From ecf9418a1bdaa9b9ed4d5cf1759213aa439b85c3 Mon Sep 17 00:00:00 2001 From: Alexander Tkachev Date: Sun, 24 Jul 2022 21:56:02 +0300 Subject: [PATCH] docs: explain read model Signed-off-by: Alexander Tkachev --- cloudevents/abstract/event.py | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/cloudevents/abstract/event.py b/cloudevents/abstract/event.py index 76f8858..77a099d 100644 --- a/cloudevents/abstract/event.py +++ b/cloudevents/abstract/event.py @@ -31,10 +31,19 @@ class CloudEvent(abc.ABC): @abc.abstractmethod def _attributes_read_model(self) -> typing.Dict[str, typing.Any]: """ - :return: attributes of this event + :return: Attributes of this event. - you MUST NOT mutate this dict - implementation MAY assume the dic will not be mutated + You MUST NOT mutate this dict. + Implementation MAY assume the dict will not be mutated. + + The reason this is only a read model and not a write model is + because you MAY not have an easy write access to the data. + + For example - a database row or a cached value. + + We don't wont to restrict our future selves. + + When a write model will be needed, it will be implemented """ pass @@ -42,9 +51,19 @@ class CloudEvent(abc.ABC): @abc.abstractmethod def _data_read_model(self) -> typing.Optional[typing.Any]: """ - :return: data value of the event - you MUST NOT mutate this value - implementation MAY assume the value will not be mutated + :return: Data value of the event. + You MUST NOT mutate this dict. + Implementation MAY assume the dict will not be mutated. + + The reason this is only a read model and not a write model is + because you MAY not have an easy write access to the data. + + For example - a database row or a cached value. + + We don't wont to restrict our future selves. + + When a write model will be needed, it will be implemented + """ pass