Update flow.serve and flow.deploy docstrings and docs for multipl…

…e schedules (#12131)

docs/concepts/schedules.md

@@ -143,19 +143,18 @@ 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:
 
 - 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.

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.