Topics¶
diffusion.features.topics.Topics ¶
Bases: Component
Topics component.
It is not supposed to be instantiated independently; an instance is available
on each Session
instance as session.topics
.
add_topic
async
¶
Create a new topic of the given type and properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_path |
str
|
The path to create the topic on. |
required |
specification |
DataTypeArgument
|
Data type of the topic. |
required |
add_and_set_topic
async
¶
add_and_set_topic(topic_path: str, specification: DataTypeArgument, value: Any, constraint: UpdateConstraint = None) -> TopicAddResponse
Create a new topic of the given type and properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_path |
str
|
The path to create the topic on. |
required |
specification |
DataTypeArgument
|
Data type of the topic. |
required |
value |
Any
|
Value to set when creating the topic. The value needs to
be compatible with the |
required |
constraint |
UpdateConstraint
|
optional update constraint |
None
|
set_topic
async
¶
set_topic(topic_path: str, value: Any, specification: DataTypeArgument, constraint: UpdateConstraint = None) -> None
Sets the topic to a specified value.
None
can only be passed to the value
parameter
when updating STRING
, INT64
, or DOUBLE
topics.
When a STRING
, INT64
, or DOUBLE
topic is set to None
, the
topic will be updated to have no value. If a previous value was present
subscribers will receive a notification that the new value is
None
. New subscribers will not receive a value notification.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_path |
str
|
the path of the topic |
required |
specification |
DataTypeArgument
|
Data type of the topic. |
required |
value |
Any
|
the value. |
required |
constraint |
UpdateConstraint
|
optional update constraint |
None
|
remove_topic
async
¶
Remove all the topics that match the given selector.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_selector |
str
|
The topics matching this selector will be removed from the server. |
required |
Returns:
Type | Description |
---|---|
TopicRemovalResult
|
An object detailing the results. |
add_value_stream ¶
Registers a value stream handler for a topic selector.
A value stream is a series of events associated with a registered topic. This method adds a ValueStreamHandler which can handle those events.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_selector |
str
|
The handler will react to the updates to all topics matching this selector. |
required |
stream |
ValueStreamHandler
|
A handler for incoming events of the matching data type. |
required |
add_fallback_stream ¶
Registers a fallback stream handler for a topic type.
A value stream is a series of events associated with a registered topic. This method makes it possible to register callbacks for each of those events.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
stream |
ValueStreamHandler
|
A handler for the matching data type. |
required |
subscribe
async
¶
Register the session to receive updates for the given topic.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_selector |
str
|
The selector for topics to subscribe to. |
required |
unsubscribe
async
¶
Unregister the session to stop receiving updates for the given topic.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_selector |
str
|
The selector for topics to unsubscribe from. |
required |
diffusion.features.topics.details.topic_specification ¶
WithProperties ¶
Bases: typing.Generic[T]
CompressionPolicy ¶
Bases: str
, enum.Enum
Compression Level
OFF
instance-attribute
class-attribute
¶
Disables compression completely for the topic and requires no additional CPU.
LOW
instance-attribute
class-attribute
¶
Low compression.
Generally some compression is beneficial, so the default value for this property is this.
HIGH
instance-attribute
class-attribute
¶
Compresses the topic messages to the smallest number of bytes, but has the highest CPU cost.
TopicDeliveryPriority ¶
ConflationPolicy ¶
Bases: str
, enum.Enum
Conflation Policy
OFF
instance-attribute
class-attribute
¶
Disables conflation for the topic. This policy disables all conflation for the topic, so topic updates will never be merged or discarded.
CONFLATE
instance-attribute
class-attribute
¶
Automatically conflates topic updates when back pressure is detected by the server.
UNSUBSCRIBE
instance-attribute
class-attribute
¶
Automatically unsubscribes the topic when back pressure is detected by the server. The unsubscription is not persisted to the cluster. If a session fails over to a different server it will be resubscribed to the topic.
ALWAYS
instance-attribute
class-attribute
¶
Automatically conflates topic updates as they are queued for the session. This is an eager policy that ensures only the latest update is queued for the topic, minimising the server memory and network bandwidth used by the session.
TopicSpecification ¶
Bases: typing.Generic[T]
, pydantic.generics.GenericModel
Topic specifications provide the information required to create a topic. Topics can be created from a topic specification using add_topic.
Topic specifications allow an application to introspect the type and capabilities of a topic. Topic specifications are provided to ValueStream value streams and TopicNotifications topic notification listeners
A topic specification has a topic type and a map of property settings which define the behavior of the topic. A
Topic specification types can be derived from any datatype using its with_properties member. This will return a TopicSpecification type ready for instantiation with the relevant parameters.
Topic specifications with different properties can be derived from any instance using with_properties.
Topic Properties¶
Depending on the topic type, some properties must be included in the specification when creating a topic and some properties have no effect. The required and optional properties for each the topic type are set out in the following table. Properties unsupported by the topic type are ignored.
Default when optional | STRING JSON BINARY | DOUBLE INT64 | RECORD_V2 | TIME_SERIES |
---|---|---|---|---|
COMPRESSION | CompressionPolicy.LOW | Optional | — | Optional |
CONFLATION | ConflationPolicy.CONFLATE | Optional | Optional | Optional |
DONT_RETAIN_VALUE | False |
Optional | Optional | Optional |
OWNER | Optional | Optional | Optional | Optional |
PERSISTENT | True |
Optional | Optional | Optional |
PRIORITY | TopicDeliveryPriority.DEFAULT | Optional | Optional | Optional |
PUBLISH_VALUES_ONLY | False |
Optional | — | Optional |
REMOVAL | Optional | Optional | Optional | Optional |
SCHEMA | — | — | Optional | — |
TIDY_ON_UNSUBSCRIBE | False |
Optional | Optional | Optional |
TIME_SERIES_EVENT_VALUE_TYPE | — | — | — | Required |
TIME_SERIES_RETAINED_RANGE | limit 10 |
— | — | — |
TIME_SERIES_SUBSCRIPTION_RANGE | TIME_SERIES_SUBSCRIPTION_RANGE As documented | |||
VALIDATE_VALUES | False |
Optional | Optional | Optional |
†TIME_SERIES topics have restricted values for the CONFLATION property. They are only allowed to have the values OFF or UNSUBSCRIBE.
topic_type
property
¶
The topic datatype.
Returns:
Type | Description |
---|---|
typing.Type[T]
|
The topic datatype. |
with_properties
instance-attribute
class-attribute
¶
Class property providing a TopicSpecification subtype ready for instantiation.
PUBLISH_VALUES_ONLY
instance-attribute
class-attribute
¶
Key of the topic property that specifies whether a topic should publish only values.
By default, a topic that supports delta streams will publish the difference between two values (a delta) when doing so is more efficient than publishing the complete new value. Subscribing sessions can use a ValueStream value stream to automatically apply the delta to a local copy of the topic value to calculate the new value.
Setting
PUBLISH_VALUES_ONLY
to True
disables this
behavior so that deltas are never published. Doing so is usually not
recommended because it will result in more data being transmitted, less
efficient use of network resources, and increased transmission latency.
On the other hand, calculating deltas can require significant CPU from
the server or, if update streams are used, from the updating client. The
CPU cost will be higher if there are many differences between successive
values, in which case delta streams confer fewer benefits. If successive
values are unrelated to each other, consider setting
PUBLISH_VALUES_ONLY
to True
.
Also consider setting
PUBLISH_VALUES_ONLY
to True
if the network capacity is
high and the bandwidth savings of deltas are not required.
See also: DONT_RETAIN_VALUE
VALIDATE_VALUES
instance-attribute
class-attribute
¶
Key of the topic property indicating whether a topic should validate inbound values.
By default, the server does not validate received values before sending
them on to client sessions. Invalid or corrupt values will be stored in
the topic and passed on to sessions. If this property is set to True
,
the server will perform additional validation on values to check that
they are valid instances of the data type, and if it is not then it will
return an error to the updater and not update the topic.
If this value is not set (or set to something other than True
), no
server validation of inbound values is performed. This is the recommended
setting as there is a performance overhead to validation and a session
using Topic Update cannot send invalid values anyway.
TIDY_ON_UNSUBSCRIBE
instance-attribute
class-attribute
¶
Key of the topic property that specifies the 'tidy on unsubscribe' option for a topic.
By default, if a session unsubscribes from a topic, it will receive any updates for that topic that were previously queued but not sent.
If this property is set to "True", when a session unsubscribes from the topic, any updates for the topic that are still queued for the session are removed. There is a performance overhead to using this option as the client queue must be scanned to find topic updates to remove, however it may prove useful for preventing unwanted data being sent to sessions.
Since 6.8.3
SCHEMA
instance-attribute
class-attribute
¶
Key of the topic property that specifies a schema which constrains topic values.
This property is only used by RECORD_V2 topics.
Since 6.8.3
DONT_RETAIN_VALUE
instance-attribute
class-attribute
¶
Key of the topic property that specifies a topic should not retain its last value.
By default, a topic will retain its
latest value. The latest value will be sent to new subscribers. Setting
this property to True
disables this behavior. New subscribers
will not be sent an initial value. No value will be returned for fetch
operations that select the topic. This is useful for data streams where
the values are only transiently valid.
Setting
DONT_RETAIN_VALUE to
True
also disables delta
streams, regardless of the
PUBLISH_VALUES_ONLY value. If
subsequent values are likely to be related, delta streams usually provide
performance benefits (see
PUBLISH_VALUES_ONLY). Consider leaving
DONT_RETAIN_VALUE
set to False
to benefit from delta streams, even if there is no other requirement to retain the last value.
Bearing in mind the performance trade-offs of disabling delta streams,
there are two reasons to consider setting
DONT_RETAIN_VALUE to
True
. First, it stops the server and each subscribed client from
keeping a copy of the value, reducing their memory requirements. Second,
when a topic has a high update rate and is replicated across a cluster,
it can significantly improve throughput because the values need not be
persisted to the cluster.
Time series topics ignore this property and always retain the latest value.
Since 6.8.3
PERSISTENT
instance-attribute
class-attribute
¶
Key of the topic property that can be used to prevent a topic from being persisted when the server is configured to enable persistence.
By default, a topic will be persisted if persistence is enabled at the server and the topic type supports persistence. Setting PERSISTENT to `false` will prevent the topic from being persisted. Since 6.8.3
REMOVAL
instance-attribute
class-attribute
¶
Key of the topic property that specifies a removal policy for automatic
removal of the topic (and/or other topics).
This property is specified as an expression which defines one or more
conditions that are to be satisfied before automatic removal occurs.
The expression takes the form:
when conditions [remove "selector"]
At least one condition must be supplied. If more than one is supplied,
they must be separated by logical operators (and
or or
).
The natural evaluation order of the operators may be changed by
surrounding with parentheses (e.g. (condition and
condition)).
The remove
clause is optional. It provides a
Topic Selector expression representing the topics to be removed.
If a remove
clause is specified, the topic with the removal
policy will only be removed if its path matches the selector expression.
The selector must be surrounded by either double or single quotes.
When many topics have the same removal policy, it is better to
set the
REMOVAL
property for one of them, using a remove
clause that selects all of the topics. This is more efficient because it
allows the server to avoid evaluating the same condition many times.
The permissions that are applied at the time of removal are those defined by the roles of the principal that created the topic at the time of creation. The roles of that principal may therefore change before the removal with no effect, but if the permissions given to the roles change it may have an effect upon the final removal. Only one occurrence of each of the following condition types may be included within the expression:
Condition Type | Format | Usage |
---|---|---|
time after | time after absoluteTime |
Removal should occur after a specified absolute time. Absolute time may be specified as a number of milliseconds since the epoch (00:00:00 on 1 January 1970) or as a quoted date and time formatted in RFC_1123 date time format. Either single or double quotes may be used. |
subscriptions less than |
[local] subscriptions < n for
forPeriod [after afterPeriod]
|
Removal should occur when the topic has had less than the specified
number (n) of subscriptions for a given period (forPeriod)
of time. Optionally, an initial period (afterPeriod) may be
specified by which to delay the initial checking of this condition. See
below for period formats.
The optional local keyword restricts evaluation to only count
subscriptions from sessions belonging to the local server or cluster,
ignoring subscriptions from sessions belonging to downstream remote servers that
host fanout replicas of the topic. |
no updates for | no updates for forPeriod [after afterPeriod] |
Removal should occur when the topic has had no updates for a given period (forPeriod) of time. Optionally, an initial period (afterPeriod) may be specified by which to delay the initial checking of this condition. See below for period formats. |
Multiple occurrences of the following condition types may be included within the expression:
Condition Type | Format | Usage |
---|---|---|
no session has | no [local] session has "criteria" [for forPeriod] [after afterPeriod] | Removal should occur when there are no sessions satisfying certain criteria. Optionally the criteria can be required to be satisfied for a period of time (forPeriod). Optionally, an initial period (afterPeriod) can be specified to delay the initial check of the criteria. Session selection criteria are specified as defined in session filters and must be surrounded by single or double quotes. See below for period formats. The optional local keyword restricts evaluation to sessions belonging to the local server or cluster, ignoring sessions belonging to downstream remote servers that host fanout replicas of the topic. |
this session closes | This is a shorthand form of no local session has that may be used to indicate that the topic is to be removed when the session that created it closes. |
Time periods are specified as a number followed (with no intermediate
space) by a single letter representing the time unit. The time unit may
be s
(seconds), m
(minutes), h
(hours) or
d
(days). For example, 10 minutes would be specified as 10m
.
If quotes or backslashes \
are required within quoted values
such as selectors or session criteria then they may be escaped by
preceding with \
.
The expression is validated only by the server and therefore if
an invalid expression is specified it will be reported as an
InvalidTopicSpecificationError.
** Examples: **
The topic will be removed when the date and time indicated by the specified number of milliseconds since the epoch has passed. The topic will be removed when the specified date and time has passed. The topic alpha/beta and all topics subordinate to it will be removed when the specified date and time has passed.The topic will be removed when it has had no subscriptions for a continuous period of 20 minutes.
The topic will be removed when it has had less than 2 subscriptions for a continuous period of 20 minutes after one hour has passed since its creation.
The topic will be removed when it has had no updates for a continuous period of 3 hours.
The topic will be removed when it has had no updates for a continuous period of 15 minutes after one day has passed since its creation.
The topic will be removed when the session creating it closes. The topic will be removed when there are no sessions with the principal 'Alice'. The topic will be removed when there are no sessions with the principal 'Alice' for a continuous period of 10 minutes. The topic will be removed when there have been no sessions from the Accounts department for a continuous period of 30 minutes after 2 hours have passed since its creation. The topic will be removed when the specified date and time has passed and the topic has had no subscriptions for a continuous period of 30 minutes after that time. The topic will be removed when the specified date and time has passed and the topic has had less than 2 subscriptions for a continuous period of 10 minutes after that time plus one hour. The topic will be removed when the specified date and time has passed or the topic has had less than 2 subscriptions for a continuous period of 10 minutes after one hour from its creation.when time after "Tue, 3 Jun 2018 11:05:30 GMT" and (subscriptions < 2 for 10m after 1h or no updates for 20m)
Notes and restrictions on use
The after
time periods refer to the period since the topic was
created or restored from persistence store after a server is restarted.
They are designed as a 'grace' period after the topic comes into
existence before the related condition starts to be evaluated. When not
specified the conditions start to be evaluated as soon as the topic is
created or restored.
The server will evaluate conditions on a periodic basis (every few
seconds) so the exact removal time will not be precise for low periodic
granularity.
The meaning of the for
period in a no session has
condition is subtly different from its use in other conditions. It does
not guarantee that there has been no session satisfying the condition at
some point between evaluations, only that when evaluated the given period
of time has passed since it was last evaluated and found to have no
matching sessions.
Subscriptions is the number of subscriptions to a topic.
Automatic topic removal is supported for a topic that is replicated
across the local cluster, and for a topic with with fanout replicas on
downstream remote servers. A subscriptions less than
condition
will be evaluated against the total number of subscriptions across the
cluster and on all fanout replicas on downstream remote servers. A
no session has
condition will consider all sessions hosted across
the cluster and all sessions hosted by downstream remote servers that
have a fanout replica of the topic. The local
keyword can be used
to restrict evaluation to the local cluster, ignoring fanout replicas.
Since 6.8.3
CONFLATION
instance-attribute
class-attribute
¶
The conflation policy of the topic. The policy specifies how the server manages queued topic updates. Conflation is applied individually to each session queue. Conflation is the process of merging or discarding topic updates queued for a session to reduce the server memory footprint and network data. The server will conflate sessions that have a large number of queued messages to meet configured queue size targets. The sessions with the largest queues are typically slow consumers or have been disconnected – both will benefit from conflation. This property allows conflation behavior to be tuned on a topic-by-topic basis.
The supported policies are:
The default policy used when the property is not specified and the topic type is not time series is CONFLATE. The default policy used when the property is not specified and the topic type is time series is OFF.
See ConflationPolicy for more.
The CONFLATE and UNSUBSCRIBE policies are applied when the server detects back pressure for a session. The server configuration places limits on the data queued for each session. If these limits are breached, the server will conflate the session queue to attempt to reducee its size. If the session queue still exceeds the limits after conflation, the session will be terminated. Conflation can be disabled on a session-by-session basis. If conflation is disabled for a session the policy will not be applied to topic updates queued for the session but will be for other sessions that have conflation enabled. The policies CONFLATE and ALWAYS are not supported for time series topics as they would cause missing events. Attempts to enable these policies with time series topics will cause the creation of the topic to fail, reporting that the specification is invalid.
Since 6.8.3
OWNER
instance-attribute
class-attribute
¶
Key of the topic property that allows the creator of a topic to extend
READ_TOPIC, MODIFY_TOPIC, and UPDATE_TOPIC permissions to a specific
principal, in addition to the permissions granted by the authorisation
rules in the security store.
A session that has authenticated using the principal can update and
remove the topic, so the principal can be considered the topic owner. To
fetch or subscribe to the topic, the principal must also be granted
the SELECT_TOPIC permission by the security store rules.
This may be used in the following cases:
1) A session creates a topic and makes its own principal the owner.
2) A session creates a topic and makes another principal the owner.
The format of the property value is: $Principal is name
where name is the name of the principal. Single quotes may be used
instead of double quotes and special characters can be escaped.
The purpose of this property is to allow a client to create topics on
behalf of other users. This can be used in conjunction with the
REMOVAL
property so that such topics are removed when there are
no longer any sessions for the named principal.
For example:
>>> import diffusion.datatypes
>>> specification = diffusion.datatypes.JSON
>>> specification.with_properties(OWNER="$Principal is 'myPrincipal'", REMOVAL="when no session has '$Principal is "myPrincipal"' for 5s")
Since 6.8.3
COMPRESSION
instance-attribute
class-attribute
¶
Key of the topic property that allows the compression policy to be set on a per-topic basis.
Compression reduces the bandwidth required to broadcast topic updates to subscribed sessions, at the cost of increased server CPU.
Changes to a topic's value are published to each subscribed session as a sequence of topic messages. A topic message can carry the latest value or the difference between the latest value and the previous value (a delta). The compression policy determines if and how published topic messages are compressed. Topic messages are not exposed through the client API; the client library handles decompression and decodes deltas automatically, passing reconstructed values to the application.
The compression policy for a topic is specified by setting this property to one of several values:
The policies are listed in the order of increasing compression and increasing CPU cost.
See Also
Prior to version 6.4, only two values were allowed: True
(equivalent to MEDIUM,
and the previous default policy) and
False
(equivalent to OFF). These values are still
supported.
This property is only one factor that determines whether a topic message will be compressed. Other factors include:
- Compression must be enabled in the server configuration.
- The client library must support the server's compression scheme. In this release, the server supports zlib compression, and also allows compression to be disabled on a per-connector basis. From 6.4, all client libraries are capable of zlib compression. A JavaScript client may or may not support zlib compression, depending on whether the zlib library can be loaded. The zlib library is packaged separately to reduce the download size of the core library.
Since 6.8.3
PRIORITY
instance-attribute
class-attribute
¶
Key of the topic property that specifies the topic delivery priority. The supported delivery priorities are:
The delivery priority affects the order of topic updates sent to a subscribed client session. When there are multiple topic updates for topics with different priorities in a session's outbound queue, updates for HIGH priority topics will be delivered first, followed by updates for DEFAULT priority topics, followed by updates for LOW priority topics. Topic subscription and unsubscription notifications are also delivered according to the topic delivery priority.
Using different delivery priorities is most beneficial when there is a large backlog of queued updates to deliver to a client session. On lightly loaded systems, updates typically remain in the outbound queue for a few milliseconds and so there is a lower chance of topic updates being reordered based on their priority. The backlog will be larger if the topic update rate is higher; the server or the client are more heavily loaded; the client session becomes temporarily disconnected; or if there is poor network connectivity between the server and the client.
Messages from the server to the client that are not topic updates, for example ping requests and responses, are queued with the DEFAULT delivery priority.
Since 6.8.3
new_topic_specification
classmethod
¶
Return a TopicSpecification class with datatype tp
,
ready for instantiation.
This is for internal use - to get a TopicSpecification for a given DataType you should use its with_properties member, which will return an appropriate TopicSpecification type ready for instantiation with the relevant parameters.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tp |
typing.Type[T_other]
|
the datatype |
required |
Returns:
Type | Description |
---|---|
typing.Type[TopicSpecification[T_other]]
|
A new TopicSpecification with the given type |
diffusion.features.topics.selectors ¶
Matching of topic selectors.
Selector ¶
Bases: Protocol
, Hashable
Generic protocol for all selectors.
match ¶
Compares a topic path against the selector.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_path |
str
|
The topic path to match against the selector. |
required |
Returns:
Type | Description |
---|---|
bool
|
|
TopicSelectorError ¶
Bases: DiffusionError
Error related to selector matching.
PathSelector ¶
Bases: Selector
Basic topic selector, matching the topic path exactly.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
selector |
str
|
The topic selector text. |
required |
match ¶
Compares a topic path against the selector.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_path |
str
|
The topic path to match against the selector. |
required |
Returns:
Type | Description |
---|---|
bool
|
|
PatternSelector ¶
FullPathPatternSelector ¶
Bases: PatternSelector
Selector containing a regular expression matching the entire path.
A full-path pattern topic selector returns topics for which the regular expression matches the full topic path.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
selector |
str
|
The topic selector text. |
required |
match ¶
Compares a topic path against the selector.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_path |
str
|
The topic path to match against the selector. |
required |
Returns:
Type | Description |
---|---|
bool
|
|
SplitPathPatternSelector ¶
Bases: PatternSelector
Selector containing split-path regular expression pattern.
A split-path pattern expression contains a list of regular expressions separated by the / character. Each regular expression describes a part of the topic path. The selector returns topics for which each regular expression matches the part of the topic path at the corresponding level.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
selector |
str
|
The topic selector text. |
required |
match ¶
Compares a topic path against the selector.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_path |
str
|
The topic path to match against the selector. |
required |
Returns:
Type | Description |
---|---|
bool
|
|
SelectorSet ¶
Bases: Set[Selector]
, Selector
A set of multiple path or pattern selectors.
A selector set returns topics that match any of the selectors. Its
textual form is a list of selectors separated by the separator ////
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
selectors |
Union[str, Iterable[str]]
|
Either the full list of selectors (separated by |
required |
match ¶
Compares a topic path against the selector.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
topic_path |
str
|
The topic path to match against the selector. |
required |
Returns:
Type | Description |
---|---|
bool
|
|
any_of
classmethod
¶
Helper method that accepts selectors as individual arguments to create a set.
get_selector ¶
Instantiate a selector based on the given textual value.
diffusion.features.topics.update ¶
UpdateConstraint ¶
Bases: abc.ABC
, GenericModel
The constraint to be applied to an update operation or the creation of an update stream.
Notes
Constraints describe a condition that must be satisfied for an operation to succeed. Constraints can be applied to the setting of a value or creation of an update stream. Constraints are only evaluated on the server.
The constraints are evaluated using the:
- active session locks
- existence of the topic
- current value of the topic
The value of a topic can be described in several ways. The value can be described as an exact value, a partial value or an unset value.
Constraints can be composed with one another. It is only possible to construct logical ANDs of constraints. Constraints can only be composed if the resulting constraint is satisfiable. Multiple session locks can be held but a topic can only have a single value. Constraints specifying multiple topic values can't be constructed.
Constraints can be created using a ConstraintFactory.
__and__ ¶
Creates a composed constraint that represents a logical AND of this constraint and another.
Notes
You must use the binary &
form to invoke this due to short-circuiting.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
other |
UpdateConstraint
|
The constraint that will be logically-ANDed with the current constraint. |
required |
Returns:
Type | Description |
---|---|
UpdateConstraint
|
The newly composed constraint that represents a logical AND of the current constraint and the
|
constraint_factory ¶
ConstraintFactory ¶
Bases: abc.ABC
The factory for the update constraint types.
json_value
property
¶
Gets the constraint that partially matches the current topic value.
Notes
The topic must be a diffusion.datatypes.JSON topic. The diffusion.features.topics.update.constraints.PartialJSON partially describes the structure of a diffusion.datatypes.JSON value.
Returns:
Type | Description |
---|---|
PartialJSON
|
The constraint. |
no_value
property
¶
Gets the constraint requiring the topic to have no value.
Notes
This is useful when setting the first value of a topic. This constraint is unsatisfied if no topic is present at the path, making it unsuitable for operations that try to add topics.
Returns:
Type | Description |
---|---|
NoValueConstraint
|
The constraint. |
no_topic
property
¶
Gets the constraint requiring the path to have no topic.
Notes
This is useful when setting the first value of a topic being added using Topics.add_and_set_topic without changing the value if the topic already exists. This constraint is unsatisfied if a topic is present at the path, making it unsuitable for operations that try to set topics without adding them.
Returns:
Type | Description |
---|---|
NoTopicConstraint
|
The constraint. |
value ¶
Creates a constraint requiring the current value of the topic to match the supplied value.
Notes
When a None value, the topic is set to have no value. Use the NoValueConstraint constraint to check if the topic has no value.
This is useful when changing the value of a topic. This constraint is unsatisfied if no topic is present at the path, making it unsuitable for operations that try to add topics.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
value |
typing.Union[AbstractDataType, bytes]
|
The value. |
required |
Returns:
Type | Description |
---|---|
BinaryValueConstraint
|
The update constraint. |
constraints ¶
PartialJSONType
module-attribute
¶
Instance of PartialJSON or any subclasses
Unconstrained ¶
BinaryValueConstraint ¶
NoValueConstraint ¶
LockConstraint ¶
NoTopicConstraint ¶
PartialJSON ¶
Bases: UpdateConstraint
The constraint requiring the current value of the JSON topic to match the partially described value.
with_ ¶
Requires a value at a specific position in the JSON object.
Notes
The pointer
is a JSON Pointer (https://tools.ietf.org/html/rfc6901) syntax reference
locating the value
in the JSON object.
The pointer
syntax is not being verified for correctness.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
pointer |
pydantic.StrictStr
|
The pointer expression. |
required |
value |
AbstractDataType
|
The value. |
required |
Returns:
Type | Description |
---|---|
'PartialJSONType'
|
The constraint including the specified |
without ¶
Requires a specific position in the JSON object to be empty.
Notes
The pointer
is a JSON Pointer (https://tools.ietf.org/html/rfc6901) syntax reference
that should have no value in the JSON object.
The pointer
syntax is not being verified for correctness.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
pointer |
pydantic.StrictStr
|
The pointer expression. |
required |
Returns:
Type | Description |
---|---|
'PartialJSONType'
|
The constraint including the specified |