Merge branch 'main' into deprecate-models-flag

.changes/unreleased/Features-20250523-115920.yaml

@@ -0,0 +1,6 @@
+kind: Features
+body: deprecate --models flag
+time: 2025-05-23T11:59:20.758872-04:00
+custom:
+  Author: michelleark
+  Issue: "11561"

core/dbt/cli/flags.py

@@ -17,7 +17,7 @@ from dbt.cli.types import Command as CliCommand
 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
@@ -49,6 +49,8 @@ DEPRECATED_PARAMS = {
     "deprecated_state": "state",
 }
 
+DEPRECATED_PARAM_WARNINGS = {"models": "model-param-usage-deprecation"}
+
 
 WHICH_KEY = "which"
 
@@ -125,6 +127,7 @@ class Flags:
             params_assigned_from_default: set,
             params_assigned_from_user: set,
             deprecated_env_vars: Dict[str, Callable],
+            deprecated_params: Dict[str, Callable],
         ):
             """Recursively adds all click params to flag object"""
             for param_name, param_value in ctx.params.items():
@@ -181,6 +184,12 @@ class Flags:
                     )
                 # end deprecated_params
 
+                # Warning-only deprecations
+                if param_name in DEPRECATED_PARAM_WARNINGS:
+                    if ctx.get_parameter_source(param_name) != ParameterSource.DEFAULT:
+                        deprecation_name = DEPRECATED_PARAM_WARNINGS[param_name]
+                        deprecated_params[param_name] = lambda: warn(deprecation_name)
+
                 # Set the flag value.
                 is_duplicate = (
                     hasattr(self, param_name.upper())
@@ -221,19 +230,28 @@ class Flags:
                     params_assigned_from_default,
                     params_assigned_from_user,
                     deprecated_env_vars,
+                    deprecated_params,
                 )
 
         params_assigned_from_user = set()  # type: Set[str]
         params_assigned_from_default = set()  # type: Set[str]
         deprecated_env_vars: Dict[str, Callable] = {}
+        deprecated_params: Dict[str, Callable] = {}
         _assign_params(
-            ctx, params_assigned_from_default, params_assigned_from_user, deprecated_env_vars
+            ctx,
+            params_assigned_from_default,
+            params_assigned_from_user,
+            deprecated_env_vars,
+            deprecated_params,
         )
 
         # Set deprecated_env_var_warnings to be fired later after events have been init.
         object.__setattr__(
             self, "deprecated_env_var_warnings", [x for x in deprecated_env_vars.values()]
         )
+        object.__setattr__(
+            self, "deprecated_param_warnings", [x for x in deprecated_params.values()]
+        )
 
         # Get the invoked command flags.
         invoked_subcommand_name = (
@@ -249,6 +267,7 @@ class Flags:
                 params_assigned_from_default,
                 params_assigned_from_user,
                 deprecated_env_vars,
+                deprecated_params,
             )
 
         if not project_flags:
@@ -388,9 +407,11 @@ class Flags:
     def fire_deprecations(self):
         """Fires events for deprecated env_var usage."""
         [dep_fn() for dep_fn in self.deprecated_env_var_warnings]
+        [dep_fn() for dep_fn in self.deprecated_param_warnings]
         # It is necessary to remove this attr from the class so it does
         # not get pickled when written to disk as json.
         object.__delattr__(self, "deprecated_env_var_warnings")
+        object.__delattr__(self, "deprecated_param_warnings")
 
         fire_buffered_deprecations()
 

core/dbt/cli/main.py

@@ -182,7 +182,8 @@ def cli(ctx, **kwargs):
 @p.resource_type
 @p.exclude_resource_type
 @p.sample
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.show
 @p.store_failures
@@ -250,7 +251,8 @@ def docs(ctx, **kwargs):
 @p.exclude
 @p.profiles_dir
 @p.project_dir
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.empty_catalog
 @p.static
@@ -319,7 +321,8 @@ def docs_serve(ctx, **kwargs):
 @p.profiles_dir
 @p.project_dir
 @p.empty
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.inline
 @p.compile_inject_ephemeral_ctes
@@ -359,7 +362,8 @@ def compile(ctx, **kwargs):
 @p.introspect
 @p.profiles_dir
 @p.project_dir
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.inline
 @p.inline_direct
@@ -497,6 +501,7 @@ def init(ctx, **kwargs):
 @p.resource_type
 @p.exclude_resource_type
 @p.raw_select
+@p.models
 @p.selector
 @p.target_path
 @p.vars
@@ -560,7 +565,8 @@ def parse(ctx, **kwargs):
 @p.event_time_start
 @p.event_time_end
 @p.sample
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.target_path
 @p.threads
@@ -627,7 +633,8 @@ def retry(ctx, **kwargs):
 @p.project_dir
 @p.resource_type
 @p.exclude_resource_type
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.target_path
 @p.threads
@@ -693,7 +700,8 @@ def run_operation(ctx, **kwargs):
 @p.full_refresh
 @p.profiles_dir
 @p.project_dir
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.show
 @p.target_path
@@ -727,7 +735,8 @@ def seed(ctx, **kwargs):
 @p.exclude
 @p.profiles_dir
 @p.project_dir
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.target_path
 @p.threads
@@ -769,7 +778,8 @@ def source(ctx, **kwargs):
 @p.output_path  # TODO: Is this ok to re-use?  We have three different output params, how much can we consolidate?
 @p.profiles_dir
 @p.project_dir
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.target_path
 @p.threads
@@ -810,7 +820,8 @@ cli.commands["source"].add_command(snapshot_freshness, "snapshot-freshness")  #
 @p.exclude_resource_type
 @p.profiles_dir
 @p.project_dir
-@p.select
+@p.raw_select
+@p.models
 @p.selector
 @p.store_failures
 @p.target_path

core/dbt/deprecations.py

@@ -189,6 +189,11 @@ class CustomOutputPathInSourceFreshnessDeprecation(DBTDeprecation):
     _event = "CustomOutputPathInSourceFreshnessDeprecation"
 
 
+class ModelParamUsageDeprecation(DBTDeprecation):
+    _name = "model-param-usage-deprecation"
+    _event = "ModelParamUsageDeprecation"
+
+
 class PropertyMovedToConfigDeprecation(DBTDeprecation):
     _name = "property-moved-to-config-deprecation"
     _event = "PropertyMovedToConfigDeprecation"
@@ -271,6 +276,7 @@ deprecations_list: List[DBTDeprecation] = [
     CustomKeyInConfigDeprecation(),
     CustomKeyInObjectDeprecation(),
     CustomOutputPathInSourceFreshnessDeprecation(),
+    ModelParamUsageDeprecation(),
     PropertyMovedToConfigDeprecation(),
     WEOInlcudeExcludeDeprecation(),
 ]

core/dbt/events/types.py

@@ -700,6 +700,15 @@ class WEOIncludeExcludeDeprecation(WarnLevel):
         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 @@ setup(
         # 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

@@ -15,6 +15,7 @@ from dbt.events.types import (
     DeprecationsSummary,
     DuplicateYAMLKeysDeprecation,
     GenericJSONSchemaValidationDeprecation,
+    ModelParamUsageDeprecation,
     PackageRedirectDeprecation,
     WEOIncludeExcludeDeprecation,
 )
@@ -432,6 +433,54 @@ class TestCustomOutputPathInSourceFreshnessDeprecation:
         assert len(event_catcher.caught_events) == 1
 
 
+class TestModelsParamUsageDeprecation:
+    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 TestModelParamUsageDeprecation:
+    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 TestMParamUsageDeprecation:
+    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 TestSelectParamNoModelUsageDeprecation:
+    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
+
+
 @pytest.mark.skip(
     reason="Skip until we have have regenerated the json schemas to account for all happy path failures"
 )