Deprecate Deployment class and deployment build and apply commands

src/prefect/cli/_types.py

@@ -110,18 +110,36 @@ def command(
         self,
         *args,
         aliases: List[str] = None,
+        deprecated: bool = False,
+        deprecated_start_date: Optional[str] = None,
+        deprecated_help: str = "",
+        deprecated_name: str = "",
         **kwargs,
     ):
         """
         Create a new command. If aliases are provided, the same command function
         will be registered with multiple names.
+
+        Provide `deprecated=True` to mark the command as deprecated. If `deprecated=True`,
+        `deprecated_name` and `deprecated_start_date` must be provided.
         """
 
         def wrapper(fn):
             if is_async_fn(fn):
                 fn = sync_compatible(fn)
             fn = with_cli_exception_handling(fn)
-            if self.deprecated:
+            if deprecated:
+                if not deprecated_name or not deprecated_start_date:
+                    raise ValueError(
+                        "Provide the name of the deprecated command and a deprecation start date."
+                    )
+                command_deprecated_message = generate_deprecation_message(
+                    name=f"The {deprecated_name!r} command",
+                    start_date=deprecated_start_date,
+                    help=deprecated_help,
+                )
+                fn = with_deprecated_message(command_deprecated_message)(fn)
+            elif self.deprecated:
                 fn = with_deprecated_message(self.deprecated_message)(fn)
 
             # register fn with its original name

src/prefect/cli/deployment.py

@@ -624,7 +624,13 @@ async def clear_schedules(
         exit_with_success(f"Cleared all schedules for deployment {deployment_name}")
 
 
-@deployment_app.command("set-schedule", deprecated=True)
+@deployment_app.command(
+    "set-schedule",
+    deprecated=True,
+    deprecated_start_date="Mar 2024",
+    deprecated_help="Use 'prefect deployment schedule create' instead.",
+    deprecated_name="deployment set-schedule",
+)
 async def _set_schedule(
     name: str,
     interval: Optional[float] = typer.Option(
@@ -664,7 +670,7 @@ async def _set_schedule(
     """
     Set schedule for a given deployment.
 
-    This command is deprecated. Use `prefect deployment schedule create` instead.
+    This command is deprecated. Use 'prefect deployment schedule create' instead.
     """
     assert_deployment_name_format(name)
 
@@ -714,7 +720,13 @@ async def _set_schedule(
             )
 
 
-@deployment_app.command("pause-schedule", deprecated=True)
+@deployment_app.command(
+    "pause-schedule",
+    deprecated=True,
+    deprecated_start_date="Mar 2024",
+    deprecated_help="Use 'prefect deployment schedule pause' instead.",
+    deprecated_name="deployment pause-schedule",
+)
 async def _pause_schedule(
     name: str,
 ):
@@ -743,7 +755,13 @@ async def _pause_schedule(
         return await pause_schedule(name, deployment.schedules[0].id)
 
 
-@deployment_app.command("resume-schedule", deprecated=True)
+@deployment_app.command(
+    "resume-schedule",
+    deprecated=True,
+    deprecated_start_date="Mar 2024",
+    deprecated_help="Use 'prefect deployment schedule resume' instead.",
+    deprecated_name="deployment resume-schedule",
+)
 async def _resume_schedule(
     name: str,
 ):
@@ -1086,7 +1104,12 @@ def _load_deployments(path: Path, quietly=False) -> PrefectObjectRegistry:
     return specs
 
 
-@deployment_app.command()
+@deployment_app.command(
+    deprecated=True,
+    deprecated_start_date="Mar 2024",
+    deprecated_name="deployment apply",
+    deprecated_help="Use 'prefect deploy' to deploy flows via YAML instead.",
+)
 async def apply(
     paths: List[str] = typer.Argument(
         ...,
@@ -1253,7 +1276,12 @@ async def delete(
 ]
 
 
-@deployment_app.command()
+@deployment_app.command(
+    deprecated=True,
+    deprecated_start_date="Mar 2024",
+    deprecated_name="deployment build",
+    deprecated_help="Use 'prefect deploy' to deploy flows via YAML instead.",
+)
 async def build(
     entrypoint: str = typer.Argument(
         ...,

src/prefect/deployments/deployments.py

@@ -16,6 +16,10 @@
 import pendulum
 import yaml
 
+from prefect._internal.compatibility.deprecated import (
+    deprecated_callable,
+    deprecated_class,
+)
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
 from prefect.client.schemas.actions import DeploymentScheduleCreate
 
@@ -24,12 +28,10 @@
 else:
     from pydantic import BaseModel, Field, parse_obj_as, root_validator, validator
 
-from prefect._internal.compatibility.experimental import experimental_field
 from prefect.blocks.core import Block
 from prefect.blocks.fields import SecretDict
 from prefect.client.orchestration import PrefectClient, ServerType, get_client
 from prefect.client.schemas.objects import (
-    DEFAULT_AGENT_WORK_POOL_NAME,
     FlowRun,
     MinimalDeploymentSchedule,
 )
@@ -297,6 +299,7 @@ async def load_flow_from_flow_run(
     return flow
 
 
+@deprecated_callable(start_date="Mar 2024")
 def load_deployments_from_yaml(
     path: str,
 ) -> PrefectObjectRegistry:
@@ -320,13 +323,20 @@ def load_deployments_from_yaml(
     return registry
 
 
-@experimental_field(
-    "work_pool_name",
-    group="work_pools",
-    when=lambda x: x is not None and x != DEFAULT_AGENT_WORK_POOL_NAME,
+@deprecated_class(
+    start_date="Mar 2024",
+    help="Use `flow.deploy` to deploy your flows instead."
+    " Refer to the upgrade guide for more information:"
+    " https://docs.prefect.io/latest/guides/upgrade-guide-agents-to-workers/.",
 )
 class Deployment(BaseModel):
     """
+    DEPRECATION WARNING:
+
+    This class is deprecated as of March 2024 and will not be available after September 2024.
+    It has been replaced by `flow.deploy`, 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/.
+
     A Prefect Deployment definition, used for specifying and building deployments.
 
     Args:

tests/cli/deployment/test_deployment_build.py

@@ -164,6 +164,27 @@ async def ensure_default_agent_pool_exists(session):
     assert default_work_pool is not None
 
 
+def test_deployment_build_prints_deprecation_warning(tmp_path, patch_import):
+    invoke_and_assert(
+        [
+            "deployment",
+            "build",
+            "fake-path.py:fn",
+            "-n",
+            "TEST",
+            "-o",
+            str(tmp_path / "test.yaml"),
+            "--no-schedule",
+        ],
+        temp_dir=tmp_path,
+        expected_output_contains=(
+            "WARNING: The 'deployment build' command has been deprecated.",
+            "It will not be available after Sep 2024.",
+            "Use 'prefect deploy' to deploy flows via YAML instead.",
+        ),
+    )
+
+
 class TestSchedules:
     def test_passing_no_schedule_and_cron_schedules_to_build_exits_with_error(
         self, patch_import, tmp_path
@@ -184,7 +205,7 @@ def test_passing_no_schedule_and_cron_schedules_to_build_exits_with_error(
                 "Europe/Berlin",
             ],
             expected_code=1,
-            expected_output="Only one schedule type can be provided.",
+            expected_output_contains="Only one schedule type can be provided.",
             temp_dir=tmp_path,
         )
 
@@ -393,7 +414,7 @@ def test_providing_multiple_schedules_exits_with_error(
         invoke_and_assert(
             cmd,
             expected_code=1,
-            expected_output="Only one schedule type can be provided.",
+            expected_output_contains="Only one schedule type can be provided.",
         )
 
 
@@ -519,7 +540,7 @@ def test_not_providing_name_exits_with_error(self, patch_import, tmp_path):
         invoke_and_assert(
             cmd,
             expected_code=1,
-            expected_output=(
+            expected_output_contains=(
                 "A name for this deployment must be provided with the '--name' flag.\n"
             ),
         )
@@ -1080,7 +1101,7 @@ def test_providing_infra_block_and_infra_type_exits_with_error(
         invoke_and_assert(
             cmd,
             expected_code=1,
-            expected_output=(
+            expected_output_contains=(
                 "Only one of `infra` or `infra_block` can be provided, please choose"
                 " one."
             ),
@@ -1239,7 +1260,9 @@ def test_output_file_with_wrong_suffix_exits_with_error(
         cmd += ["-o", output_path]
 
         invoke_and_assert(
-            cmd, expected_code=1, expected_output="Output file must be a '.yaml' file."
+            cmd,
+            expected_code=1,
+            expected_output_contains="Output file must be a '.yaml' file.",
         )
 
     @pytest.mark.filterwarnings("ignore:does not have upload capabilities")

tests/cli/deployment/test_deployment_cli.py

@@ -28,6 +28,30 @@ def fn():
     return fn
 
 
+def test_deployment_apply_prints_deprecation_warning(tmp_path, patch_import):
+    Deployment.build_from_flow(
+        flow=my_flow,
+        name="TEST",
+        flow_name="my_flow",
+        output=str(tmp_path / "test.yaml"),
+        work_queue_name="prod",
+    )
+
+    invoke_and_assert(
+        [
+            "deployment",
+            "apply",
+            str(tmp_path / "test.yaml"),
+        ],
+        temp_dir=tmp_path,
+        expected_output_contains=(
+            "WARNING: The 'deployment apply' command has been deprecated.",
+            "It will not be available after Sep 2024.",
+            "Use 'prefect deploy' to deploy flows via YAML instead.",
+        ),
+    )
+
+
 class TestOutputMessages:
     def test_message_with_work_queue_name_from_python_build(
         self, patch_import, tmp_path

tests/test_deployments.py

@@ -11,6 +11,7 @@
 import yaml
 from httpx import Response
 
+from prefect._internal.compatibility.deprecated import PrefectDeprecationWarning
 from prefect._internal.compatibility.experimental import ExperimentalFeature
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
 from prefect.client.schemas.actions import DeploymentScheduleCreate
@@ -72,6 +73,19 @@ async def ensure_default_agent_pool_exists(session):
         await session.commit()
 
 
+def test_deployment_emits_deprecation_warning():
+    with pytest.warns(
+        PrefectDeprecationWarning,
+        match=(
+            "prefect.deployments.deployments.Deployment has been deprecated."
+            " It will not be available after Sep 2024."
+            " Use `flow.deploy` to deploy your flows instead."
+            " Refer to the upgrade guide for more information"
+        ),
+    ):
+        Deployment(name="foo")
+
+
 class TestDeploymentBasicInterface:
     async def test_that_name_is_required(self):
         with pytest.raises(ValidationError, match="field required"):