Add public helper fns for event deferral (#364)

* add top level fire_or_defer_event fn

* add top level fire_deferred events

* add helper functions

* Add changelog

* remove warn_or_error_with_deferral

Author: ash2shukla

.changes/unreleased/Features-20260422-022544.yaml

@@ -0,0 +1,6 @@
+kind: Features
+body: Adds public helper functions for event deferral functionality
+time: 2026-04-22T02:25:44.929201+05:30
+custom:
+    Author: ash2shukla
+    Issue: "12339"

dbt_common/events/event_manager.py

@@ -171,6 +171,21 @@ def fire_event(
     ) -> None:
         ...
 
+    def fire_or_defer_event(
+        self,
+        e: BaseEvent,
+        event_group_type: EventGroupType = EventGroupType.DEFAULT,
+        level: Optional[EventLevel] = None,
+        node: Any = None,
+        force_warn_or_error_handling: bool = False,
+    ) -> None:
+        ...
+
+    def fire_deferred_events(
+        self, event_group_type: EventGroupType = EventGroupType.DEFAULT
+    ) -> None:
+        ...
+
     def add_logger(self, config: LoggerConfig) -> None:
         ...
 
@@ -197,6 +212,21 @@ def fire_event(
     ) -> None:
         self.event_history.append((e, level))
 
+    def fire_or_defer_event(
+        self,
+        e: BaseEvent,
+        event_group_type: EventGroupType = EventGroupType.DEFAULT,
+        level: Optional[EventLevel] = None,
+        node: Any = None,
+        force_warn_or_error_handling: bool = False,
+    ) -> None:
+        raise NotImplementedError()
+
+    def fire_deferred_events(
+        self, event_group_type: EventGroupType = EventGroupType.DEFAULT
+    ) -> None:
+        raise NotImplementedError()
+
     def add_logger(self, config: LoggerConfig) -> None:
         raise NotImplementedError()
 

dbt_common/events/functions.py

@@ -4,7 +4,7 @@
 from dbt_common.helper_types import WarnErrorOptions, WarnErrorOptionsV2
 from dbt_common.invocation import get_invocation_id
 from dbt_common.utils.encoding import ForgivingJSONEncoder
-from dbt_common.events.base_types import BaseEvent, EventLevel, EventMsg
+from dbt_common.events.base_types import BaseEvent, EventLevel, EventMsg, EventGroupType
 from dbt_common.events.logger import LoggerConfig, LineFormat
 from dbt_common.exceptions import scrub_secrets, env_secrets
 from dbt_common.events.types import Note
@@ -144,6 +144,28 @@ def fire_event(
     )
 
 
+def fire_or_defer_event(
+    e: BaseEvent,
+    level: Optional[EventLevel] = None,
+    node: Any = None,
+    force_warn_or_error_handling: bool = False,
+    event_group_type: EventGroupType = EventGroupType.DEFAULT,
+) -> None:
+    get_event_manager().fire_or_defer_event(
+        e,
+        level=level,
+        node=node,
+        force_warn_or_error_handling=force_warn_or_error_handling,
+        event_group_type=event_group_type,
+    )
+
+
+def fire_deferred_events(
+    event_group_type: EventGroupType = EventGroupType.DEFAULT,
+) -> None:
+    get_event_manager().fire_deferred_events(event_group_type=event_group_type)
+
+
 def get_metadata_vars() -> Dict[str, str]:
     global metadata_vars
     if metadata_vars is None: