Add Behavior Flag Framework

.changes/unreleased/Features-20240808-194933.yaml

@@ -0,0 +1,6 @@
+kind: Features
+body: Add Behavior Flag Framework
+time: 2024-08-08T19:49:33.738569-04:00
+custom:
+  Author: mikealfare
+  Issue: "178"

.gitignore

@@ -158,3 +158,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+# VSCode
+.vscode/

dbt_common/behavior_flags.py

@@ -0,0 +1,108 @@
+import inspect
+from types import SimpleNamespace
+from typing import Any, Dict, List, TypedDict
+
+try:
+    from typing import NotRequired
+except ImportError:
+    # NotRequired was introduced in Python 3.11
+    # This is the suggested way to implement a TypedDict with optional arguments
+    from typing import Optional as NotRequired
+
+from dbt_common.events.base_types import WarnLevel
+from dbt_common.events.functions import fire_event
+from dbt_common.events.types import BehaviorDeprecationEvent
+
+
+class BehaviorFlag:
+    """
+    The canonical behavior flag that gets used through dbt packages
+
+    Args:
+        name: the name of the behavior flag, e.g. enforce_quoting_on_relation_creation
+        setting: the flag setting, after accounting for user input and the default
+        deprecation_event: the event to fire if the flag evaluates to False
+    """
+
+    def __init__(self, name: str, setting: bool, deprecation_event: WarnLevel) -> None:
+        self.name = name
+        self.setting = setting
+        self.deprecation_event = deprecation_event
+
+    @property
+    def setting(self) -> bool:
+        if self._setting is False:
+            fire_event(self.deprecation_event)
+        return self._setting
+
+    @setting.setter
+    def setting(self, value: bool) -> None:
+        self._setting = value
+
+    def __bool__(self) -> bool:
+        return self.setting
+
+
+class RawBehaviorFlag(TypedDict):
+    """
+    A set of config used to create a BehaviorFlag
+
+    Args:
+        name: the name of the behavior flag
+        default:  default setting, starts as False, becomes True in the next minor release
+        deprecation_version: the version when the default will change to True
+        deprecation_message: an additional message to send when the flag evaluates to False
+        docs_url: the url to the relevant docs on docs.getdbt.com
+    """
+
+    name: str
+    default: bool
+    source: NotRequired[str]
+    deprecation_version: NotRequired[str]
+    deprecation_message: NotRequired[str]
+    docs_url: NotRequired[str]
+
+
+# this is effectively a dictionary that supports dot notation
+# it makes usage easy, e.g. adapter.behavior.my_flag
+Behavior = SimpleNamespace
+
+
+def register(
+    behavior_flags: List[RawBehaviorFlag],
+    user_flags: Dict[str, Any],
+) -> Behavior:
+    flags = {}
+    for raw_flag in behavior_flags:
+        flag = {
+            "name": raw_flag["name"],
+            "setting": raw_flag["default"],
+        }
+
+        # specifically evaluate for `None` since `False` and `None` should be treated differently
+        if user_flags.get(raw_flag["name"]) is not None:
+            flag["setting"] = user_flags.get(raw_flag["name"])
+
+        event = BehaviorDeprecationEvent(
+            flag_name=raw_flag["name"],
+            flag_source=raw_flag.get("source", _default_source()),
+            deprecation_version=raw_flag.get("deprecation_version"),
+            deprecation_message=raw_flag.get("deprecation_message"),
+            docs_url=raw_flag.get("docs_url"),
+        )
+        flag["deprecation_event"] = event
+
+        flags[flag["name"]] = BehaviorFlag(**flag)  # type: ignore
+
+    return Behavior(**flags)  # type: ignore
+
+
+def _default_source() -> str:
+    """
+    If the maintainer did not provide a source, default to the module that called `register`.
+    For adapters, this will likely be `dbt.adapters.<foo>.impl` for `dbt-foo`.
+    """
+    frame = inspect.stack()[2]
+    if module := inspect.getmodule(frame[0]):
+        return module.__name__
+    return "Unknown"

dbt_common/events/types.proto

@@ -23,6 +23,22 @@ message GenericMessage {
     EventInfo info = 1;
 }
 
+// D - Deprecations
+
+// D042
+message BehaviorDeprecationEvent {
+    string flag_name = 1;
+    string flag_source = 2;
+    string deprecation_version = 3;
+    string deprecation_message = 4;
+    string docs_url = 5;
+}
+
+message BehaviorDeprecationEventMsg {
+    EventInfo info = 1;
+    BehaviorDeprecationEvent data = 2;
+}
+
 // M - Deps generation
 
 // M020

dbt_common/events/types.py

@@ -1,7 +1,11 @@
+from typing import Optional
+
 from dbt_common.events.base_types import (
     DebugLevel,
     InfoLevel,
+    WarnLevel,
 )
+from dbt_common.ui import warning_tag
 
 
 # The classes in this file represent the data necessary to describe a
@@ -28,6 +32,41 @@
 #
 # The basic idea is that event codes roughly translate to the natural order of running a dbt task
 
+
+# =======================================================
+# D - Deprecations
+# =======================================================
+
+
+class BehaviorDeprecationEvent(WarnLevel):
+    flag_name: str
+    flag_source: str
+    deprecation_version: Optional[str]
+    deprecation_message: Optional[str]
+    docs_url: Optional[str]
+
+    def code(self) -> str:
+        return "D042"  # TODO: update this to the next unused code
+
+    def message(self) -> str:
+        msg = f"The legacy behavior controlled by `{self.flag_name}` is deprecated.\n"
+
+        if self.deprecation_version:
+            msg = (
+                f"The legacy behavior is expected to be retired in `{self.deprecation_version}`.\n"
+            )
+
+        msg += f"The new behavior can be turned on by setting `flags.{self.flag_name}` to `True` in `dbt_project.yml`.\n"
+
+        if self.deprecation_message:
+            msg += f"{self.deprecation_message}.\n"
+
+        docs_url = self.docs_url or f"https://docs.getdbt.com/search?q={self.flag_name}"
+        msg += f"Visit {docs_url} for more information."
+
+        return warning_tag(msg)
+
+
 # =======================================================
 # M - Deps generation
 # =======================================================

pyproject.toml

@@ -127,7 +127,8 @@ exclude = [
     "dbt_common/events/types_pb2.py",
     "venv",
     ".venv",
-    "env*"
+    "env*",
+    ".hatch/*",
 ]
 per-file-ignores = ["*/__init__.py: F401"]
 docstring-convention = "google"
@@ -140,6 +141,7 @@ show_error_codes = true
 disable_error_code = "attr-defined"  # TODO: revisit once other mypy errors resolved
 disallow_untyped_defs = false # TODO: add type annotations everywhere
 warn_redundant_casts = true
+ignore_missing_imports = true
 exclude = [
     "dbt_common/events/types_pb2.py",
     "env*",