deprecation warnings for --models, --model, -m (#11729) (#11739)

(cherry picked from commit 6bbcce1)

Co-authored-by: Michelle Ark <[email protected]>
Co-authored-by: Quigley Malcolm <[email protected]>

Author: 3 people

.changes/unreleased/Features-20250611-160217.yaml

@@ -0,0 +1,6 @@
+kind: Features
+body: "11561"
+time: 2025-06-11T16:02:17.334525-04:00
+custom:
+  Author: michelleark
+  Issue: deprecate --models,--model, and -m flags

core/dbt/cli/flags.py

@@ -17,7 +17,7 @@
 from dbt.config.project import read_project_flags
 from dbt.config.utils import normalize_warn_error_options
 from dbt.contracts.project import ProjectFlags
-from dbt.deprecations import fire_buffered_deprecations, renamed_env_var
+from dbt.deprecations import fire_buffered_deprecations, renamed_env_var, warn
 from dbt.events import ALL_EVENT_NAMES
 from dbt_common import ui
 from dbt_common.clients import jinja
@@ -50,6 +50,8 @@
 }
 
 
+DEPRECATED_FLAGS_TO_WARNINGS = {("--models", "--model", "-m"): "model-param-usage-deprecation"}
+
 WHICH_KEY = "which"
 
 
@@ -385,7 +387,7 @@ def _validate_event_time_configs(self) -> None:
                     "Value for `--event-time-start` must be less than `--event-time-end`"
                 )
 
-    def fire_deprecations(self):
+    def fire_deprecations(self, ctx: Optional[Context] = None):
         """Fires events for deprecated env_var usage."""
         [dep_fn() for dep_fn in self.deprecated_env_var_warnings]
         # It is necessary to remove this attr from the class so it does
@@ -394,12 +396,25 @@ def fire_deprecations(self):
 
         fire_buffered_deprecations()
 
+        # Handle firing deprecations of CLI aliases separately using argv or dbtRunner args
+        # because click doesn't make it possible to disambiguite which literal CLI option was used
+        # and only preserves the 'canonical' representation.
+        original_command_args = (
+            ctx.obj["dbt_runner_command_args"]
+            if (ctx and ctx.obj and "dbt_runner_command_args" in ctx.obj)
+            else sys.argv
+        )
+        for deprecated_flags, warning in DEPRECATED_FLAGS_TO_WARNINGS.items():
+            for deprecated_flag in deprecated_flags:
+                if deprecated_flag in original_command_args:
+                    warn(warning)
+
     @classmethod
     def from_dict(cls, command: CliCommand, args_dict: Dict[str, Any]) -> "Flags":
         command_arg_list = command_params(command, args_dict)
         ctx = args_to_context(command_arg_list)
         flags = cls(ctx=ctx)
-        flags.fire_deprecations()
+        flags.fire_deprecations(ctx=ctx)
         return flags
 
     def set_common_global_flags(self):

core/dbt/cli/main.py

@@ -56,6 +56,7 @@ def invoke(self, args: List[str], **kwargs) -> dbtRunnerResult:
             dbt_ctx.obj = {
                 "manifest": self.manifest,
                 "callbacks": self.callbacks,
+                "dbt_runner_command_args": args,
             }
 
             for key, value in kwargs.items():

core/dbt/cli/requires.py

@@ -96,7 +96,7 @@ def wrapper(*args, **kwargs):
         fire_event(MainReportArgs(args=flags_dict_str))
 
         # Deprecation warnings
-        flags.fire_deprecations()
+        flags.fire_deprecations(ctx)
 
         if active_user is not None:  # mypy appeasement, always true
             fire_event(MainTrackingUserState(user_state=active_user.state()))

core/dbt/deprecations.py

@@ -194,6 +194,11 @@ class PropertyMovedToConfigDeprecation(DBTDeprecation):
     _event = "PropertyMovedToConfigDeprecation"
 
 
+class ModelParamUsageDeprecation(DBTDeprecation):
+    _name = "model-param-usage-deprecation"
+    _event = "ModelParamUsageDeprecation"
+
+
 def renamed_env_var(old_name: str, new_name: str):
     class EnvironmentVariableRenamed(DBTDeprecation):
         _name = f"environment-variable-renamed:{old_name}"
@@ -272,6 +277,7 @@ def show_deprecations_summary() -> None:
     CustomKeyInObjectDeprecation(),
     CustomOutputPathInSourceFreshnessDeprecation(),
     PropertyMovedToConfigDeprecation(),
+    ModelParamUsageDeprecation(),
     WEOInlcudeExcludeDeprecation(),
 ]
 

core/dbt/events/types.py

@@ -700,6 +700,15 @@ def message(self) -> str:
         return line_wrap_message(deprecation_tag(description, self.__class__.__name__))
 
 
+class ModelParamUsageDeprecation(WarnLevel):
+    def code(self) -> str:
+        return "D032"
+
+    def message(self) -> str:
+        description = "Usage of `--models`, `--model`, and `-m` is deprecated in favor of `--resource-type model --select`"
+        return line_wrap_message(deprecation_tag(description))
+
+
 # =======================================================
 # I - Project parsing
 # =======================================================

core/setup.py

@@ -73,7 +73,7 @@
         # Minor versions for these are expected to be backwards-compatible
         "dbt-common>=1.22.0,<2.0",
         "dbt-adapters>=1.15.2,<2.0",
-        "dbt-protos>=1.0.312,<2.0",
+        "dbt-protos>=1.0.315,<2.0",
         # ----
         # Expect compatibility with all new versions of these packages, so lower bounds only.
         "packaging>20.9",

tests/functional/deprecations/test_deprecations.py

@@ -1,4 +1,5 @@
 import os
+import sys
 from collections import defaultdict
 from unittest import mock
 
@@ -7,6 +8,7 @@
 
 import dbt_common
 from dbt import deprecations
+from dbt.cli.main import dbtRunner
 from dbt.clients.registry import _get_cached
 from dbt.events.types import (
     CustomKeyInConfigDeprecation,
@@ -15,6 +17,7 @@
     DeprecationsSummary,
     DuplicateYAMLKeysDeprecation,
     GenericJSONSchemaValidationDeprecation,
+    ModelParamUsageDeprecation,
     PackageRedirectDeprecation,
     WEOIncludeExcludeDeprecation,
 )
@@ -491,3 +494,95 @@ def test_weo_include_exclude_deprecation(
                 assert "exclude" in event_catcher.caught_events[0].info.msg
             else:
                 assert "exclude" not in event_catcher.caught_events[0].info.msg
+
+
+class TestModelsParamUsageDeprecation:
+
+    @mock.patch.object(sys, "argv", ["dbt", "ls", "--models", "some_model"])
+    def test_models_usage(self, project):
+        event_catcher = EventCatcher(ModelParamUsageDeprecation)
+
+        assert len(event_catcher.caught_events) == 0
+        run_dbt(
+            ["ls", "--models", "some_model"],
+            callbacks=[event_catcher.catch],
+        )
+        assert len(event_catcher.caught_events) == 1
+
+
+class TestModelsParamUsageRunnerDeprecation:
+
+    def test_models_usage(self, project):
+        event_catcher = EventCatcher(ModelParamUsageDeprecation)
+
+        assert len(event_catcher.caught_events) == 0
+        dbtRunner(callbacks=[event_catcher.catch]).invoke(["ls", "--models", "some_model"])
+        assert len(event_catcher.caught_events) == 1
+
+
+class TestModelParamUsageDeprecation:
+    @mock.patch.object(sys, "argv", ["dbt", "ls", "--model", "some_model"])
+    def test_model_usage(self, project):
+        event_catcher = EventCatcher(ModelParamUsageDeprecation)
+
+        assert len(event_catcher.caught_events) == 0
+        run_dbt(
+            ["ls", "--model", "some_model"],
+            callbacks=[event_catcher.catch],
+        )
+        assert len(event_catcher.caught_events) == 1
+
+
+class TestModelParamUsageRunnerDeprecation:
+
+    def test_model_usage(self, project):
+        event_catcher = EventCatcher(ModelParamUsageDeprecation)
+
+        assert len(event_catcher.caught_events) == 0
+        dbtRunner(callbacks=[event_catcher.catch]).invoke(["ls", "--model", "some_model"])
+        assert len(event_catcher.caught_events) == 1
+
+
+class TestMParamUsageDeprecation:
+    @mock.patch.object(sys, "argv", ["dbt", "ls", "-m", "some_model"])
+    def test_m_usage(self, project):
+        event_catcher = EventCatcher(ModelParamUsageDeprecation)
+
+        assert len(event_catcher.caught_events) == 0
+        run_dbt(
+            ["ls", "-m", "some_model"],
+            callbacks=[event_catcher.catch],
+        )
+        assert len(event_catcher.caught_events) == 1
+
+
+class TestMParamUsageRunnerDeprecation:
+    def test_m_usage(self, project):
+        event_catcher = EventCatcher(ModelParamUsageDeprecation)
+
+        assert len(event_catcher.caught_events) == 0
+        dbtRunner(callbacks=[event_catcher.catch]).invoke(["ls", "-m", "some_model"])
+        assert len(event_catcher.caught_events) == 1
+
+
+class TestSelectParamNoModelUsageDeprecation:
+
+    @mock.patch.object(sys, "argv", ["dbt", "ls", "--select", "some_model"])
+    def test_select_usage(self, project):
+        event_catcher = EventCatcher(ModelParamUsageDeprecation)
+
+        assert len(event_catcher.caught_events) == 0
+        run_dbt(
+            ["ls", "--select", "some_model"],
+            callbacks=[event_catcher.catch],
+        )
+        assert len(event_catcher.caught_events) == 0
+
+
+class TestSelectParamNoModelUsageRunnerDeprecation:
+    def test_select_usage(self, project):
+        event_catcher = EventCatcher(ModelParamUsageDeprecation)
+
+        assert len(event_catcher.caught_events) == 0
+        dbtRunner(callbacks=[event_catcher.catch]).invoke(["ls", "--select", "some_model"])
+        assert len(event_catcher.caught_events) == 0

tests/unit/test_events.py

@@ -169,6 +169,7 @@ def test_event_codes(self):
     core_types.CustomOutputPathInSourceFreshnessDeprecation(path=""),
     core_types.PropertyMovedToConfigDeprecation(key="", key_path="", file=""),
     core_types.WEOIncludeExcludeDeprecation(found_include=True, found_exclude=True),
+    core_types.ModelParamUsageDeprecation(),
     # E - DB Adapter ======================
     adapter_types.AdapterEventDebug(),
     adapter_types.AdapterEventInfo(),