diff --git a/docs/concepts/schedules.md b/docs/concepts/schedules.md index d55d9c9ac859..43658dd7a8fa 100644 --- a/docs/concepts/schedules.md +++ b/docs/concepts/schedules.md @@ -143,7 +143,6 @@ schedule: Note that as a calendar-oriented standard, `RRules` 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. - ## Creating schedules There are several ways to create a schedule for a deployment: @@ -151,11 +150,11 @@ There are several ways to create a schedule for a deployment: - Through the Prefect UI - Via the `cron`, `interval`, or `rrule` parameters if building your deployment via the [`serve` method](/concepts/flows/#serving-a-flow) of the `Flow` object or [the `serve` utility](/concepts/flows/#serving-multiple-flows-at-once) for managing multiple flows simultaneously - If using [worker-based deployments](/concepts/work-pools/) - * Through the interactive `prefect deploy` command - * With the `deployments` -> `schedule` section of the `prefect.yaml` file ) + - Through the interactive `prefect deploy` command + - With the `deployments` -> `schedule` section of the `prefect.yaml` file ) - If using [block-based deployments](/concepts/deployments/#block-based-deployments) - * `Through the schedules` section of the deployment YAML file - * By passing `schedules` into the `Deployment` class or `Deployment.build_from_flow` + - `Through the schedules` section of the deployment YAML file + - By passing `schedules` into the `Deployment` class or `Deployment.build_from_flow` ### Creating schedules in the UI @@ -166,6 +165,7 @@ You can add schedules in the **Schedules** section on a **Deployment** page in t On larger displays, the **Schedules** section will appear in a sidebar on the right side of the page. On smaller displays, it will appear on the "Details" tab of the page. #### Adding a schedule + Under **Schedules**, select the **+ Schedule** button. A modal dialog will open. Choose **Interval** or **Cron** to create a schedule. ![Prefect UI with Interval button selected](/img/ui/interval-schedule.png) @@ -178,48 +178,27 @@ The new schedule will appear on the **Deployment** page where you created it. In After you create a schedule, new scheduled flow runs will be visible in the **Upcoming** tab of the **Deployment** page where you created it. #### Editing schedules -You can edit a schedule by selecting **Edit** from the three-dot menu next to a schedule on a **Deployment** page. - -### Creating schedules with the `serve` method - -As seen in the [Quickstart](/getting-started/quickstart/#step-5-add-a-schedule), you can create a schedule by passing a `cron`, `interval`, or `rrule` parameters to the `Flow.serve` method or the `serve` utility. - -### Creating schedules with the interactive `prefect deploy` command - -If you are using [worker-based deployments](/concepts/work-pools/), you can create a schedule through the interactive `prefect deploy` command. -You will be prompted to choose which type of schedule to create. - -### Creating schedules in the `prefect.yaml` file's `deployments` -> `schedule` section - -If you save the `prefect.yaml` file from the `prefect deploy` command, you will see it has a `schedules` section for your deployment. -Alternatively, you can create a `prefect.yaml` file from a recipe or from scratch and add a `schedules` section to it. -```yaml -deployments: - ... - schedules: - - cron: "0 0 * * *" - timezone: "America/Chicago" - active: false - - cron: "0 12 * * *" - timezone: "America/New_York" - active: true - - cron: "0 18 * * *" - timezone: "Europe/London" - active: true -``` +You can edit a schedule by selecting **Edit** from the three-dot menu next to a schedule on a **Deployment** page. ### Creating schedules with a Python deployment creation file -When you create a deployment in a Python file with `flow.serve()`, `serve`, `flow.deploy()`, or `deploy` you can specify the schedule. Just add the keyword argument `cron`, `interval`, or `rrule`. +When you create a deployment in a Python file with `flow.serve()`, `serve`, `flow.deploy()`, or `deploy` you can specify the schedule. Just add the keyword argument `cron`, `interval`, or `rrule`. ``` -interval: 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. -cron: A cron schedule of when to execute runs of this deployment. -rrule: An rrule schedule of when to execute runs of this deployment. +interval: 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. +cron: A cron schedule string of when to execute runs of this deployment. + Also accepts an iterable of cron schedule strings to create multiple schedules. +rrule: An rrule schedule string of when to execute runs of this deployment. + Also accepts an iterable of rrule schedule strings to create multiple schedules. +schedules: A list of schedule objects defining when to execute runs of this deployment. + Used to define multiple schedules or additional scheduling options such as `timezone`. schedule: A schedule object defining when to execute runs of this deployment. Used to - define additional scheduling options like `timezone`. + define additional scheduling options like `timezone`. + ``` Here's an example of creating a cron schedule with `serve` for a deployment flow that will run every minute of every day: @@ -238,7 +217,7 @@ my_flow.serve(name="flowing", schedule=IntervalSchedule(interval=timedelta(minut ``` 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 `schedule` parameter to the `Deployment.build_from_flow` method. +However, if you are using that deployment creation method you can create a schedule by passing a `schedule` argument to the `Deployment.build_from_flow` method. Here's how you create the equivalent schedule in a Python deployment file, with a timezone specified. @@ -254,6 +233,31 @@ cron_demo = Deployment.build_from_flow( `IntervalSchedule` and `RRuleSchedule` are the other two Python class schedule options. +### Creating schedules with the interactive `prefect deploy` command + +If you are using [worker-based deployments](/concepts/work-pools/), you can create a schedule through the interactive `prefect deploy` command. +You will be prompted to choose which type of schedule to create. + +### Creating schedules in the `prefect.yaml` file's `deployments` -> `schedule` section + +If you save the `prefect.yaml` file from the `prefect deploy` command, you will see it has a `schedules` section for your deployment. +Alternatively, you can create a `prefect.yaml` file from a recipe or from scratch and add a `schedules` section to it. + +```yaml +deployments: + ... + schedules: + - cron: "0 0 * * *" + timezone: "America/Chicago" + active: false + - cron: "0 12 * * *" + timezone: "America/New_York" + active: true + - cron: "0 18 * * *" + timezone: "Europe/London" + active: true +``` + ## The `Scheduler` service The `Scheduler` service is started automatically when `prefect server start` is run and it is a built-in service of Prefect Cloud. diff --git a/src/prefect/flows.py b/src/prefect/flows.py index bf519e968f1b..4c5c7877a487 100644 --- a/src/prefect/flows.py +++ b/src/prefect/flows.py @@ -1,6 +1,7 @@ """ Module containing the base workflow class and decorator - for most use cases, using the [`@flow` decorator][prefect.flows.flow] is preferred. """ + # This file requires type-checking with pyright because mypy does not yet support PEP612 # See https://github.com/python/mypy/issues/8645 @@ -449,9 +450,11 @@ def with_options( version=version or self.version, task_runner=task_runner or self.task_runner, retries=retries if retries is not None else self.retries, - retry_delay_seconds=retry_delay_seconds - if retry_delay_seconds is not None - else self.retry_delay_seconds, + retry_delay_seconds=( + retry_delay_seconds + if retry_delay_seconds is not None + else self.retry_delay_seconds + ), timeout_seconds=( timeout_seconds if timeout_seconds is not None else self.timeout_seconds ), @@ -618,7 +621,7 @@ async def to_deployment( rrule: An rrule schedule of when to execute runs of this deployment. paused: Whether or not to set this deployment as paused. schedules: A list of schedule objects defining when to execute runs of this deployment. - Used to define multiple schedules or additional scheduling options like `timezone`. + Used to define multiple schedules or additional scheduling options such as `timezone`. schedule: A schedule object defining when to execute runs of this deployment. is_schedule_active: 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 @@ -744,16 +747,20 @@ async def serve( Args: name: The name to give the created deployment. - interval: 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. - cron: A cron schedule of when to execute runs of this deployment. - rrule: An rrule schedule of when to execute runs of this deployment. + interval: 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. + cron: A cron schedule string of when to execute runs of this deployment. + Also accepts an iterable of cron schedule strings to create multiple schedules. + rrule: An rrule schedule string of when to execute runs of this deployment. + Also accepts an iterable of rrule schedule strings to create multiple schedules. triggers: A list of triggers that will kick off runs of this deployment. paused: Whether or not to set this deployment as paused. schedules: A list of schedule objects defining when to execute runs of this deployment. Used to define multiple schedules or additional scheduling options like `timezone`. schedule: A schedule object defining when to execute runs of this deployment. Used to - define additional scheduling options like `timezone`. + define additional scheduling options such as `timezone`. is_schedule_active: 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. @@ -970,10 +977,14 @@ async def deploy( job_variables: 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. - interval: 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. - cron: A cron schedule of when to execute runs of this deployment. - rrule: An rrule schedule of when to execute runs of this deployment. + interval: 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. + cron: A cron schedule string of when to execute runs of this deployment. + Also accepts an iterable of cron schedule strings to create multiple schedules. + rrule: An rrule schedule string of when to execute runs of this deployment. + Also accepts an iterable of rrule schedule strings to create multiple schedules. triggers: A list of triggers that will kick off runs of this deployment. paused: Whether or not to set this deployment as paused. schedules: A list of schedule objects defining when to execute runs of this deployment.