Emit an event to the event queue and distribute it to interested modules. This is how modules "return" data. The method first creates an event object by calling `self.make_event()` with the provided arguments. Then, the event is queued for outgoing distribution using `self.
(self, *args, **kwargs)
| 571 | return updated |
| 572 | |
| 573 | async def emit_event(self, *args, **kwargs): |
| 574 | """Emit an event to the event queue and distribute it to interested modules. |
| 575 | |
| 576 | This is how modules "return" data. |
| 577 | |
| 578 | The method first creates an event object by calling `self.make_event()` with the provided arguments. |
| 579 | Then, the event is queued for outgoing distribution using `self.queue_outgoing_event()`. |
| 580 | |
| 581 | Args: |
| 582 | *args: Positional arguments to be passed to `self.make_event()` for event creation. |
| 583 | **kwargs: Keyword arguments to be passed for event creation or configuration of the emit action. |
| 584 | ```markdown |
| 585 | - on_success_callback: Optional callback function to execute upon successful event emission. |
| 586 | - abort_if: Optional condition under which the event emission should be aborted. |
| 587 | - quick: Optional flag to indicate whether the event should be processed quickly. |
| 588 | ``` |
| 589 | |
| 590 | Examples: |
| 591 | >>> await self.emit_event("www.evilcorp.com", parent=event, tags=["affiliate"]) |
| 592 | |
| 593 | >>> new_event = self.make_event("1.2.3.4", parent=event) |
| 594 | >>> await self.emit_event(new_event) |
| 595 | |
| 596 | Returns: |
| 597 | None |
| 598 | |
| 599 | Raises: |
| 600 | ValidationError: If the event cannot be validated (handled in `self.make_event()`). |
| 601 | """ |
| 602 | event_kwargs = dict(kwargs) |
| 603 | emit_kwargs = {} |
| 604 | for o in ("on_success_callback", "abort_if", "quick"): |
| 605 | v = event_kwargs.pop(o, None) |
| 606 | if v is not None: |
| 607 | emit_kwargs[o] = v |
| 608 | |
| 609 | # Two entry points: |
| 610 | # - emit_event(data, ...) -> create a new event via make_event() |
| 611 | # - emit_event(existing_event, ...) -> update and re‑emit that event |
| 612 | if args and is_event(args[0]): |
| 613 | event, *rest = args |
| 614 | if rest: |
| 615 | self.warning( |
| 616 | f"emit_event() was called on {self.name} with an existing event and extra " |
| 617 | f"positional args ({rest}); extra args are ignored. " |
| 618 | "Pass only the event plus keyword arguments, or call make_event() explicitly." |
| 619 | ) |
| 620 | # Update the existing event (e.g. tags/context/module) before emitting |
| 621 | event = self.update_event(event, **event_kwargs) |
| 622 | else: |
| 623 | event = self.make_event(*args, **event_kwargs) |
| 624 | |
| 625 | if event is not None: |
| 626 | children = event.children |
| 627 | for e in [event] + children: |
| 628 | await self.queue_outgoing_event(e, **emit_kwargs) |
| 629 | return event |
| 630 |