Skip to content

Commit 5c93053

Browse files
committed
Docs: update documentation for correlation hooks
Adds information about `register_correlation_hook_with_master_record` hook to the Modules section.
1 parent 7fa8b85 commit 5c93053

1 file changed

Lines changed: 22 additions & 2 deletions

File tree

docs/modules.md

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -334,14 +334,22 @@ on the data of the snapshot.
334334

335335
#### Snapshots Correlation Hook
336336

337+
There are two correlation hooks available:
338+
339+
- [`register_correlation_hook`][dp3.common.callback_registrar.CallbackRegistrar.register_correlation_hook]
340+
- [`register_correlation_hook_with_master_record`][dp3.common.callback_registrar.CallbackRegistrar.register_correlation_hook_with_master_record]
341+
342+
Both do the same thing, but as the naming suggests, the latter also provides a master record.
337343
The [`register_correlation_hook`][dp3.common.callback_registrar.CallbackRegistrar.register_correlation_hook]
338344
method expects a callable with the following signature:
339345
`Callable[[str, dict], Union[None, list[DataPointTask]]]`, where the first argument is the entity type, and the second is a dict
340346
containing the current values of the entity and its linked entities.
341-
The method can optionally return a list of DataPointTask objects to be inserted into the system.
347+
The [`register_correlation_hook_with_master_record`][dp3.common.callback_registrar.CallbackRegistrar.register_correlation_hook_with_master_record] method expects a callable with the following signature:
348+
`Callable[[str, dict, dict], Union[None, list[DataPointTask]]]` - the first two arguments are identical (entity type and dict with current values), but there is also a third argument: a dictionary of values stored in the master record of the entity.
349+
The method (applicable to both variants) can optionally return a list of `DataPointTask` objects to be inserted into the system.
342350

343351
As correlation hooks can depend on each other, the hook inputs and outputs must be specified
344-
using the depends_on and may_change arguments. Both arguments are lists of lists of strings,
352+
using the `depends_on` and `may_change` arguments. Both arguments are lists of lists of strings,
345353
where each list of strings is a path from the specified entity type to individual attributes (even on linked entities).
346354
For example, if the entity type is `test_entity_type`, and the hook depends on the attribute `test_attr_type1`,
347355
the path is simply `[["test_attr_type1"]]`. If the hook depends on the attribute `test_attr_type1`
@@ -351,9 +359,21 @@ of an entity linked using `test_attr_link`, the path will be `[["test_attr_link
351359
def correlation_hook(entity_type: str, values: dict):
352360
...
353361
362+
def correlation_hook_with_master_record(entity_type: str, values: dict, master_record: dict):
363+
...
364+
365+
# Without master record
354366
registrar.register_correlation_hook(
355367
correlation_hook, "test_entity_type", [["test_attr_type1"]], [["test_attr_type2"]]
356368
)
369+
370+
# Or with master record
371+
registrar.register_correlation_hook_with_master_record(
372+
correlation_hook_with_master_record,
373+
"test_entity_type",
374+
[["test_attr_type1"]],
375+
[["test_attr_type2"]]
376+
)
357377
```
358378

359379
The order of running callbacks is determined automatically, based on the dependencies.

0 commit comments

Comments
 (0)