From 12c8cb0a852aa31209e467aa1cda6057ae289504 Mon Sep 17 00:00:00 2001
From: Mike Alfare <mike.alfare@dbtlabs.com>
Date: Wed, 4 Sep 2024 18:52:11 -0400
Subject: [PATCH] fix the event code; update docs

---
 dbt_common/behavior_flags.py  | 25 +++++++++++++++++++------
 dbt_common/events/types.proto |  2 +-
 dbt_common/events/types.py    |  2 +-
 3 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/dbt_common/behavior_flags.py b/dbt_common/behavior_flags.py
index 04ac740..307fe5b 100644
--- a/dbt_common/behavior_flags.py
+++ b/dbt_common/behavior_flags.py
@@ -15,11 +15,11 @@
 
 class BehaviorFlag(TypedDict):
     """
-    A set of config used to create a BehaviorFlag
+    Configuration used to create a BehaviorFlagRendered instance
 
     Args:
         name: the name of the behavior flag
-        default:  default setting, starts as False, becomes True in the next minor release
+        default: default setting, starts as False, becomes True after a bake-in period
         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
@@ -35,7 +35,7 @@ class BehaviorFlag(TypedDict):
 
 class BehaviorFlagRendered:
     """
-    The canonical behavior flag that gets used through dbt packages
+    A rendered behavior flag that gets used throughout dbt packages
 
     Args:
         flag: the configuration for the behavior flag
@@ -73,7 +73,7 @@ def _deprecation_event(self, flag: BehaviorFlag) -> BehaviorDeprecationEvent:
     @staticmethod
     def _default_source() -> str:
         """
-        If the maintainer did not provide a source, default to the module that called `register`.
+        If the maintainer did not provide a source, default to the module that called this class.
         For adapters, this will likely be `dbt.adapters.<foo>.impl` for `dbt-foo`.
         """
         for frame in inspect.stack():
@@ -86,9 +86,22 @@ def __bool__(self) -> bool:
         return self.setting
 
 
-# this is effectively a dictionary that supports dot notation
-# it makes usage easy, e.g. adapter.behavior.my_flag
 class Behavior:
+    """
+    A collection of behavior flags
+
+    This is effectively a dictionary that supports dot notation for easy reference, e.g.:
+        ```python
+        if adapter.behavior.my_flag:
+            ...
+        ```
+        ```jinja
+        {% if adapter.behavior.my_flag %}
+            ...
+        {% endif %}
+        ```
+    """
+
     _flags: List[BehaviorFlagRendered]
 
     def __init__(self, flags: List[BehaviorFlag], user_overrides: Dict[str, Any]) -> None:
diff --git a/dbt_common/events/types.proto b/dbt_common/events/types.proto
index ed8d09f..d72d6b2 100644
--- a/dbt_common/events/types.proto
+++ b/dbt_common/events/types.proto
@@ -25,7 +25,7 @@ message GenericMessage {
 
 // D - Deprecations
 
-// D042
+// D018
 message BehaviorDeprecationEvent {
     string flag_name = 1;
     string flag_source = 2;
diff --git a/dbt_common/events/types.py b/dbt_common/events/types.py
index 1c73a43..02fc3ee 100644
--- a/dbt_common/events/types.py
+++ b/dbt_common/events/types.py
@@ -46,7 +46,7 @@ class BehaviorDeprecationEvent(WarnLevel):
     docs_url: Optional[str]
 
     def code(self) -> str:
-        return "D042"  # TODO: update this to the next unused code
+        return "D018"
 
     def message(self) -> str:
         msg = f"The legacy behavior controlled by `{self.flag_name}` is deprecated.\n"