+controlpi.messagebus

+ +

Provide an asynchronous message bus.

+ +

A message is a dictionary with string keys and string, integer, float, +Boolean, dictionary, or list values, where the inner dictionaries again +have string keys and these values and the inner lists also have elements of +these types. All messages have a special key 'sender' with the name of the +sending client as string value, which is set by the constructor:

+ +

>>> m = Message('Example sender', {'key 1': 'value 1'})
+>>> m['key 2'] = 'value 2'
+>>> print(m)
+{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+

+ +

A message template is a mapping from string keys to JSON schemas as values. +A message template matches a message if all keys of the template are +contained in the message and the values in the message validate against the +respective schemas. An empty mapping therefore matches all messages.

+ +

The bus executes asynchronous callbacks for all messages to be received by +a client. We use a simple callback printing the message in all examples:

+ +

>>> def callback_for_receiver(receiver):
+...     async def callback(message):
+...         print(f"{receiver}: {message}")
+...     return callback
+

+ +

Clients can be registered at the bus with a name, lists of message templates +they want to use for sending and receiving and a callback function for +receiving. An empty list of templates means that the client does not want to +send or receive any messages, respectively. A list with an empty template +means that it wants to send arbitrary or receive all messages, respectively:

+ +

>>> async def setup(bus):
+...     bus.register('Logger', 'Test Plugin',
+...                  [],
+...                  [([MessageTemplate({})],
+...                    callback_for_receiver('Logger'))])
+...     bus.register('Client 1', 'Test Plugin',
+...                  [MessageTemplate({'k1': {'type': 'string'}})],
+...                  [([MessageTemplate({'target': {'const': 'Client 1'}})],
+...                    callback_for_receiver('Client 1'))])
+

+ +

While most clients should always use their own name for sending, this is not +enforced and debugging or management clients could send messages on behalf +of arbitrary client names.

+ +

The name of a client has to be unique and is not allowed to be empty +(otherwise registration fails).

+ +

The empty name is used to refer to the bus itself. The bus sends messages +for registrations and deregistrations of clients containing their complete +interface of send and receive templates. This can be used to allow dynamic +(debug) clients to deal with arbitrary configurations of clients. The bus +also reacts to 'get clients' command messages by sending the complete +information of all currently registered clients.

+ +

Clients can send to the bus with the send function. Each message has to +declare a sender. The send templates of that sender are checked for a +template matching the message:

+ +

>>> async def send(bus):
+...     print("Sending messages.")
+...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
+...     await bus.send({'sender': '', 'target': 'Client 1'})
+

+ +

The run function executes the message bus forever. If we want to stop it, we +have to explicitly cancel the task:

+ +

>>> async def main():
+...     bus = MessageBus()
+...     await setup(bus)
+...     bus_task = asyncio.create_task(bus.run())
+...     await send(bus)
+...     await asyncio.sleep(0)
+...     bus_task.cancel()
+...     try:
+...         await bus_task
+...     except asyncio.exceptions.CancelledError:
+...         pass
+>>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+Sending messages.
+Logger: {'sender': '', 'event': 'registered',
+         'client': 'Logger', 'plugin': 'Test Plugin',
+         'sends': [], 'receives': [{}]}
+Logger: {'sender': '', 'event': 'registered',
+         'client': 'Client 1', 'plugin': 'Test Plugin',
+         'sends': [{'k1': {'type': 'string'}}],
+         'receives': [{'target': {'const': 'Client 1'}}]}
+Logger: {'sender': 'Client 1', 'k1': 'Test'}
+Logger: {'sender': '', 'target': 'Client 1'}
+Client 1: {'sender': '', 'target': 'Client 1'}
+

+ + + + View Source + +

   1"""Provide an asynchronous message bus.
+   2
+   3A message is a dictionary with string keys and string, integer, float,
+   4Boolean, dictionary, or list values, where the inner dictionaries again
+   5have string keys and these values and the inner lists also have elements of
+   6these types. All messages have a special key 'sender' with the name of the
+   7sending client as string value, which is set by the constructor:
+   8>>> m = Message('Example sender', {'key 1': 'value 1'})
+   9>>> m['key 2'] = 'value 2'
+  10>>> print(m)
+  11{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+  12
+  13A message template is a mapping from string keys to JSON schemas as values.
+  14A message template matches a message if all keys of the template are
+  15contained in the message and the values in the message validate against the
+  16respective schemas. An empty mapping therefore matches all messages.
+  17
+  18The bus executes asynchronous callbacks for all messages to be received by
+  19a client. We use a simple callback printing the message in all examples:
+  20>>> def callback_for_receiver(receiver):
+  21...     async def callback(message):
+  22...         print(f"{receiver}: {message}")
+  23...     return callback
+  24
+  25Clients can be registered at the bus with a name, lists of message templates
+  26they want to use for sending and receiving and a callback function for
+  27receiving. An empty list of templates means that the client does not want to
+  28send or receive any messages, respectively. A list with an empty template
+  29means that it wants to send arbitrary or receive all messages, respectively:
+  30>>> async def setup(bus):
+  31...     bus.register('Logger', 'Test Plugin',
+  32...                  [],
+  33...                  [([MessageTemplate({})],
+  34...                    callback_for_receiver('Logger'))])
+  35...     bus.register('Client 1', 'Test Plugin',
+  36...                  [MessageTemplate({'k1': {'type': 'string'}})],
+  37...                  [([MessageTemplate({'target': {'const': 'Client 1'}})],
+  38...                    callback_for_receiver('Client 1'))])
+  39
+  40While most clients should always use their own name for sending, this is not
+  41enforced and debugging or management clients could send messages on behalf
+  42of arbitrary client names.
+  43
+  44The name of a client has to be unique and is not allowed to be empty
+  45(otherwise registration fails).
+  46
+  47The empty name is used to refer to the bus itself. The bus sends messages
+  48for registrations and deregistrations of clients containing their complete
+  49interface of send and receive templates. This can be used to allow dynamic
+  50(debug) clients to deal with arbitrary configurations of clients. The bus
+  51also reacts to 'get clients' command messages by sending the complete
+  52information of all currently registered clients.
+  53
+  54Clients can send to the bus with the send function. Each message has to
+  55declare a sender. The send templates of that sender are checked for a
+  56template matching the message:
+  57>>> async def send(bus):
+  58...     print("Sending messages.")
+  59...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
+  60...     await bus.send({'sender': '', 'target': 'Client 1'})
+  61
+  62The run function executes the message bus forever. If we want to stop it, we
+  63have to explicitly cancel the task:
+  64>>> async def main():
+  65...     bus = MessageBus()
+  66...     await setup(bus)
+  67...     bus_task = asyncio.create_task(bus.run())
+  68...     await send(bus)
+  69...     await asyncio.sleep(0)
+  70...     bus_task.cancel()
+  71...     try:
+  72...         await bus_task
+  73...     except asyncio.exceptions.CancelledError:
+  74...         pass
+  75>>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+  76Sending messages.
+  77Logger: {'sender': '', 'event': 'registered',
+  78         'client': 'Logger', 'plugin': 'Test Plugin',
+  79         'sends': [], 'receives': [{}]}
+  80Logger: {'sender': '', 'event': 'registered',
+  81         'client': 'Client 1', 'plugin': 'Test Plugin',
+  82         'sends': [{'k1': {'type': 'string'}}],
+  83         'receives': [{'target': {'const': 'Client 1'}}]}
+  84Logger: {'sender': 'Client 1', 'k1': 'Test'}
+  85Logger: {'sender': '', 'target': 'Client 1'}
+  86Client 1: {'sender': '', 'target': 'Client 1'}
+  87"""
+  88
+  89import asyncio
+  90import json
+  91import fastjsonschema
+  92import sys
+  93
+  94from typing import (
+  95    Union,
+  96    Dict,
+  97    List,
+  98    Any,
+  99    Callable,
+ 100    Coroutine,
+ 101    Optional,
+ 102    Iterable,
+ 103    Tuple,
+ 104)
+ 105
+ 106MessageValue = Union[None, str, int, float, bool, Dict[str, Any], List[Any]]
+ 107# Should really be:
+ 108# MessageValue = Union[None, str, int, float, bool,
+ 109#                      Dict[str, 'MessageValue'], List['MessageValue']]
+ 110# But mypy does not support recursion by now:
+ 111# https://github.com/python/mypy/issues/731
+ 112JSONSchema = Union[bool, Dict[str, MessageValue]]
+ 113# Could be even more specific.
+ 114MessageCallback = Callable[["Message"], Coroutine[Any, Any, None]]
+ 115
+ 116
+ 117# Global cache of JSON schema validation functions:
+ 118_validates: Dict[str, Callable[[MessageValue], MessageValue]] = {}
+ 119
+ 120
+ 121def register_schema(schema: JSONSchema) -> bool:
+ 122    """Register the given JSON schema in the global cache."""
+ 123    global _validates
+ 124    schema_string = json.dumps(schema)
+ 125    if schema_string not in _validates:
+ 126        if not (isinstance(schema, dict) or isinstance(schema, bool)):
+ 127            return False
+ 128        try:
+ 129            _validates[schema_string] = fastjsonschema.compile(schema)
+ 130        except fastjsonschema.JsonSchemaDefinitionException:
+ 131            return False
+ 132    return True
+ 133
+ 134
+ 135def validate(schema_string: str, value: MessageValue) -> bool:
+ 136    """Validate the given MessageValue against the given JSON schema string."""
+ 137    global _validates
+ 138    if schema_string not in _validates:
+ 139        schema = json.loads(schema_string)
+ 140        _validates[schema_string] = fastjsonschema.compile(schema)
+ 141    validate = _validates[schema_string]
+ 142    try:
+ 143        validate(value)
+ 144    except fastjsonschema.JsonSchemaException:
+ 145        return False
+ 146    return True
+ 147
+ 148
+ 149class Message(Dict[str, MessageValue]):
+ 150    """Define arbitrary message.
+ 151
+ 152    Messages are dictionaries with string keys and values that are strings,
+ 153    integers, floats, Booleans, dictionaries that recursively have string
+ 154    keys and values of any of these types, or lists with elements that have
+ 155    any of these types. These constraints are checked when setting key-value
+ 156    pairs of the message.
+ 157
+ 158    A message has to have a sender, which is set by the constructor:
+ 159    >>> m = Message('Example sender')
+ 160    >>> print(m)
+ 161    {'sender': 'Example sender'}
+ 162
+ 163    A dictionary can be given to the constructor:
+ 164    >>> m = Message('Example sender',
+ 165    ...             {'key 1': 'value 1', 'key 2': 'value 2'})
+ 166    >>> print(m)
+ 167    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+ 168
+ 169    A 'sender' set in the initial dictionary is overwritten by the explicitly
+ 170    given sender in the first argument:
+ 171    >>> m = Message('Example sender',
+ 172    ...             {'sender': 'Original sender', 'key': 'value'})
+ 173    >>> print(m)
+ 174    {'sender': 'Example sender', 'key': 'value'}
+ 175
+ 176    Or the message can be modified after construction:
+ 177    >>> m = Message('Example sender', {'key 1': 'value 1'})
+ 178    >>> m['key 2'] = 'value 2'
+ 179    >>> print(m)
+ 180    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+ 181
+ 182    The 'sender' key can be overwritten, but this should only be done in
+ 183    exceptional cases:
+ 184    >>> m = Message('Example sender', {'key': 'value'})
+ 185    >>> m['sender'] = 'New sender'
+ 186    >>> print(m)
+ 187    {'sender': 'New sender', 'key': 'value'}
+ 188    """
+ 189
+ 190    def __init__(
+ 191        self, sender: str, init: Optional[Dict[str, MessageValue]] = None
+ 192    ) -> None:
+ 193        """Initialise message.
+ 194
+ 195        Message is initialised with given sender and possibly given
+ 196        key-value pairs:
+ 197        >>> m = Message('Example sender')
+ 198        >>> print(m)
+ 199        {'sender': 'Example sender'}
+ 200        >>> m = Message('Example sender', {'key 1': 'value 1'})
+ 201        >>> print(m)
+ 202        {'sender': 'Example sender', 'key 1': 'value 1'}
+ 203        """
+ 204        if not isinstance(sender, str):
+ 205            raise TypeError(f"'{sender}' is not a valid sender name (not a string).")
+ 206        self["sender"] = ""
+ 207        if init is not None:
+ 208            self.update(init)
+ 209        self["sender"] = sender
+ 210
+ 211    @staticmethod
+ 212    def check_value(value: MessageValue) -> bool:
+ 213        """Check recursively if a given value is valid.
+ 214
+ 215        None, strings, integers, floats and Booleans are valid:
+ 216        >>> Message.check_value(None)
+ 217        True
+ 218        >>> Message.check_value('Spam')
+ 219        True
+ 220        >>> Message.check_value(42)
+ 221        True
+ 222        >>> Message.check_value(42.42)
+ 223        True
+ 224        >>> Message.check_value(False)
+ 225        True
+ 226
+ 227        Other basic types are not valid:
+ 228        >>> Message.check_value(b'bytes')
+ 229        False
+ 230        >>> Message.check_value(1j)
+ 231        False
+ 232
+ 233        Dictionaries with string keys and recursively valid values are valid:
+ 234        >>> Message.check_value({'str value': 'Spam', 'int value': 42,
+ 235        ...                      'float value': 42.42, 'bool value': False})
+ 236        True
+ 237
+ 238        Empty dictionaries are valid:
+ 239        >>> Message.check_value({})
+ 240        True
+ 241
+ 242        Dictionaries with other keys are not valid:
+ 243        >>> Message.check_value({42: 'int key'})
+ 244        False
+ 245
+ 246        Dictionaries with invalid values are not valid:
+ 247        >>> Message.check_value({'complex value': 1j})
+ 248        False
+ 249
+ 250        Lists with valid elements are valid:
+ 251        >>> Message.check_value(['Spam', 42, 42.42, False])
+ 252        True
+ 253
+ 254        Empty lists are valid:
+ 255        >>> Message.check_value([])
+ 256        True
+ 257
+ 258        Lists with invalid elements are not valid:
+ 259        >>> Message.check_value([1j])
+ 260        False
+ 261        """
+ 262        if value is None:
+ 263            return True
+ 264        elif (
+ 265            isinstance(value, str)
+ 266            or isinstance(value, int)
+ 267            or isinstance(value, float)
+ 268            or isinstance(value, bool)
+ 269        ):
+ 270            return True
+ 271        elif isinstance(value, dict):
+ 272            for key in value:
+ 273                if not isinstance(key, str):
+ 274                    return False
+ 275                if not Message.check_value(value[key]):
+ 276                    return False
+ 277            return True
+ 278        elif isinstance(value, list):
+ 279            for element in value:
+ 280                if not Message.check_value(element):
+ 281                    return False
+ 282            return True
+ 283        return False
+ 284
+ 285    def __setitem__(self, key: str, value: MessageValue) -> None:
+ 286        """Check key and value before putting pair into dict.
+ 287
+ 288        >>> m = Message('Example sender')
+ 289        >>> m['key'] = 'value'
+ 290        >>> m['dict'] = {'k1': 'v1', 'k2': 2}
+ 291        >>> print(m)  # doctest: +NORMALIZE_WHITESPACE
+ 292        {'sender': 'Example sender', 'key': 'value',
+ 293         'dict': {'k1': 'v1', 'k2': 2}}
+ 294        >>> m = Message('Example sender')
+ 295        >>> m[42] = 'int key'
+ 296        Traceback (most recent call last):
+ 297          ...
+ 298        TypeError: '42' is not a valid key in Message (not a string).
+ 299        >>> m['complex value'] = 1j
+ 300        Traceback (most recent call last):
+ 301          ...
+ 302        TypeError: '1j' is not a valid value in Message.
+ 303        """
+ 304        if not isinstance(key, str):
+ 305            raise TypeError(f"'{key}' is not a valid key in Message (not a string).")
+ 306        if not self.check_value(value):
+ 307            raise TypeError(f"'{value}' is not a valid value in Message.")
+ 308        super().__setitem__(key, value)
+ 309
+ 310    def update(self, *args, **kwargs) -> None:
+ 311        """Override update to use validity checks.
+ 312
+ 313        >>> m = Message('Example sender')
+ 314        >>> m.update({'key 1': 'value 1', 'key 2': 'value 2'})
+ 315        >>> print(m)
+ 316        {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+ 317        >>> m.update({42: 'int key'})
+ 318        Traceback (most recent call last):
+ 319          ...
+ 320        TypeError: '42' is not a valid key in Message (not a string).
+ 321        >>> m.update({'complex value': 1j})
+ 322        Traceback (most recent call last):
+ 323          ...
+ 324        TypeError: '1j' is not a valid value in Message.
+ 325
+ 326        This is also used in __init__:
+ 327        >>> m = Message('Example sender', {'key': 'value'})
+ 328        >>> print(m)
+ 329        {'sender': 'Example sender', 'key': 'value'}
+ 330        >>> m = Message('Example sender', {42: 'int key'})
+ 331        Traceback (most recent call last):
+ 332          ...
+ 333        TypeError: '42' is not a valid key in Message (not a string).
+ 334        >>> m = Message('Example sender', {'complex value': 1j})
+ 335        Traceback (most recent call last):
+ 336          ...
+ 337        TypeError: '1j' is not a valid value in Message.
+ 338        """
+ 339        if args:
+ 340            if len(args) > 1:
+ 341                raise TypeError(f"update expected at most 1 argument, got {len(args)}")
+ 342            other = dict(args[0])
+ 343            for key in other:
+ 344                self[key] = other[key]
+ 345        for key in kwargs:
+ 346            self[key] = kwargs[key]
+ 347
+ 348    def setdefault(self, key: str, value: MessageValue = None) -> MessageValue:
+ 349        """Override setdefault to use validity checks.
+ 350
+ 351        >>> m = Message('Example sender')
+ 352        >>> m.setdefault('key', 'value 1')
+ 353        'value 1'
+ 354        >>> m.setdefault('key', 'value 2')
+ 355        'value 1'
+ 356        >>> m.setdefault(42, 'int key')
+ 357        Traceback (most recent call last):
+ 358          ...
+ 359        TypeError: '42' is not a valid key in Message (not a string).
+ 360        >>> m.setdefault('complex value', 1j)
+ 361        Traceback (most recent call last):
+ 362          ...
+ 363        TypeError: '1j' is not a valid value in Message.
+ 364
+ 365        But __setitem__ is not called if the key is already present:
+ 366        >>> m.setdefault('key', 1j)
+ 367        'value 1'
+ 368        """
+ 369        if key not in self:
+ 370            self[key] = value
+ 371        return self[key]
+ 372
+ 373
+ 374class MessageTemplate(Dict[str, JSONSchema]):
+ 375    """Define a message template.
+ 376
+ 377    A message template is a mapping from string keys to JSON schemas as
+ 378    values:
+ 379    >>> t = MessageTemplate({'key 1': {'const': 'value'},
+ 380    ...                      'key 2': {'type': 'string'}})
+ 381    >>> t['key 3'] = {'type': 'object',
+ 382    ...               'properties': {'key 1': {'type': 'number'},
+ 383    ...                              'key 2': True}}
+ 384
+ 385    A message template matches a message if all keys of the template are
+ 386    contained in the message and the values in the message validate against
+ 387    the respective schemas:
+ 388    >>> t.check(Message('Example Sender',
+ 389    ...                 {'key 1': 'value', 'key 2': 'some string',
+ 390    ...                  'key 3': {'key 1': 42, 'key 2': None}}))
+ 391    True
+ 392
+ 393    An empty mapping therefore matches all messages:
+ 394    >>> t = MessageTemplate()
+ 395    >>> t.check(Message('Example Sender', {'arbitrary': 'content'}))
+ 396    True
+ 397    """
+ 398
+ 399    def __init__(self, init: Optional[Dict[str, JSONSchema]] = None) -> None:
+ 400        """Initialise message.
+ 401
+ 402        Template is initialised empty or with given key-value pairs:
+ 403        >>> t = MessageTemplate()
+ 404        >>> print(t)
+ 405        {}
+ 406        >>> t = MessageTemplate({'key': {'const': 'value'}})
+ 407        >>> print(t)
+ 408        {'key': {'const': 'value'}}
+ 409        """
+ 410        if init is not None:
+ 411            self.update(init)
+ 412
+ 413    @staticmethod
+ 414    def from_message(message: Message) -> "MessageTemplate":
+ 415        """Create template from message.
+ 416
+ 417        Template witch constant schemas is created from message:
+ 418        >>> m = Message('Example Sender', {'key': 'value'})
+ 419        >>> t = MessageTemplate.from_message(m)
+ 420        >>> print(t)
+ 421        {'sender': {'const': 'Example Sender'}, 'key': {'const': 'value'}}
+ 422        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
+ 423        ...                                'list': [None, True, 'string']})
+ 424        >>> t = MessageTemplate.from_message(m)
+ 425        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+ 426        {'sender': {'const': 'Example Sender'},
+ 427         'dict': {'type': 'object',
+ 428                  'properties': {'int': {'const': 42},
+ 429                                 'float': {'const': 42.42}}},
+ 430         'list': {'type': 'array',
+ 431                  'items': [{'const': None},
+ 432                            {'const': True},
+ 433                            {'const': 'string'}]}}
+ 434
+ 435        This is especially useful for clients that send certain fully
+ 436        predefined messages, where the message is given in the configuration
+ 437        and the template for the registration can be constructed by this
+ 438        method.
+ 439        """
+ 440
+ 441        def schema_from_value(value: MessageValue) -> JSONSchema:
+ 442            schema: JSONSchema = False
+ 443            if value is None:
+ 444                schema = {"const": None}
+ 445            elif (
+ 446                isinstance(value, str)
+ 447                or isinstance(value, int)
+ 448                or isinstance(value, float)
+ 449                or isinstance(value, bool)
+ 450            ):
+ 451                schema = {"const": value}
+ 452            elif isinstance(value, dict):
+ 453                properties = {}
+ 454                for inner_key in value:
+ 455                    inner_value: Message = value[inner_key]
+ 456                    properties[inner_key] = schema_from_value(inner_value)
+ 457                schema = {"type": "object", "properties": properties}
+ 458            elif isinstance(value, list):
+ 459                schema = {
+ 460                    "type": "array",
+ 461                    "items": [schema_from_value(element) for element in value],
+ 462                }
+ 463            return schema
+ 464
+ 465        template = MessageTemplate()
+ 466        for key in message:
+ 467            template[key] = schema_from_value(message[key])
+ 468        return template
+ 469
+ 470    def __setitem__(self, key: str, value: JSONSchema) -> None:
+ 471        """Check key and value before putting pair into dict.
+ 472
+ 473        >>> t = MessageTemplate()
+ 474        >>> t['key 1'] = {'const': 'value'}
+ 475        >>> t['key 2'] = {'type': 'string'}
+ 476        >>> t['key 3'] = {'type': 'object',
+ 477        ...               'properties': {'key 1': {'type': 'number'},
+ 478        ...                              'key 2': True}}
+ 479        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+ 480        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+ 481         'key 3': {'type': 'object',
+ 482                   'properties': {'key 1': {'type': 'number'},
+ 483                                  'key 2': True}}}
+ 484        >>> t[42] = {'const': 'int key'}
+ 485        Traceback (most recent call last):
+ 486          ...
+ 487        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+ 488        >>> t['key'] = 'schema'  # doctest: +NORMALIZE_WHITESPACE
+ 489        Traceback (most recent call last):
+ 490          ...
+ 491        TypeError: 'schema' is not a valid value in MessageTemplate
+ 492        (not a valid JSON schema).
+ 493        >>> t['key'] = True
+ 494        """
+ 495        if not isinstance(key, str):
+ 496            raise TypeError(
+ 497                f"'{key}' is not a valid key in MessageTemplate (not a string)."
+ 498            )
+ 499        if not register_schema(value):
+ 500            raise TypeError(
+ 501                f"'{value}' is not a valid value in"
+ 502                " MessageTemplate (not a valid JSON schema)."
+ 503            )
+ 504        super().__setitem__(key, value)
+ 505
+ 506    def update(self, *args, **kwargs) -> None:
+ 507        """Override update to use validity checks.
+ 508
+ 509        >>> t = MessageTemplate()
+ 510        >>> t.update({'key 1': {'const': 'value'},
+ 511        ...           'key 2': {'type': 'string'},
+ 512        ...           'key 3': {'type': 'object',
+ 513        ...                     'properties': {'key 1': {'type': 'number'},
+ 514        ...                                    'key 2': True}}})
+ 515        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+ 516        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+ 517         'key 3': {'type': 'object',
+ 518                   'properties': {'key 1': {'type': 'number'},
+ 519                                  'key 2': True}}}
+ 520        >>> t.update({42: {'const': 'int key'}})
+ 521        Traceback (most recent call last):
+ 522          ...
+ 523        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+ 524        >>> t.update({'key': 'schema'})  # doctest: +NORMALIZE_WHITESPACE
+ 525        Traceback (most recent call last):
+ 526          ...
+ 527        TypeError: 'schema' is not a valid value in MessageTemplate
+ 528        (not a valid JSON schema).
+ 529        >>> t.update({'key': True})
+ 530
+ 531        This is also used in __init__:
+ 532        >>> t = MessageTemplate({'key 1': {'const': 'value'},
+ 533        ...                      'key 2': {'type': 'string'},
+ 534        ...                      'key 3': {'type': 'object',
+ 535        ...                                'properties': {
+ 536        ...                                    'key 1': {'type': 'number'},
+ 537        ...                                    'key 2': True}}})
+ 538        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+ 539        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+ 540         'key 3': {'type': 'object',
+ 541                   'properties': {'key 1': {'type': 'number'},
+ 542                                  'key 2': True}}}
+ 543        >>> t = MessageTemplate({42: {'const': 'int key'}})
+ 544        Traceback (most recent call last):
+ 545          ...
+ 546        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+ 547        >>> t = MessageTemplate({'key': 'schema'})
+ 548        ... # doctest: +NORMALIZE_WHITESPACE
+ 549        Traceback (most recent call last):
+ 550          ...
+ 551        TypeError: 'schema' is not a valid value in MessageTemplate
+ 552        (not a valid JSON schema).
+ 553        >>> t = MessageTemplate({'key': True})
+ 554        """
+ 555        if args:
+ 556            if len(args) > 1:
+ 557                raise TypeError(f"update expected at most 1 argument, got {len(args)}")
+ 558            other = dict(args[0])
+ 559            for key in other:
+ 560                self[key] = other[key]
+ 561        for key in kwargs:
+ 562            self[key] = kwargs[key]
+ 563
+ 564    def setdefault(self, key: str, value: Optional[JSONSchema] = None) -> JSONSchema:
+ 565        """Override setdefault to use validity checks.
+ 566
+ 567        >>> t = MessageTemplate()
+ 568        >>> t.setdefault('key 1', {'const': 'value'})
+ 569        {'const': 'value'}
+ 570        >>> t.setdefault('key 2', {'type': 'string'})
+ 571        {'type': 'string'}
+ 572        >>> t.setdefault('key 3', {'type': 'object',
+ 573        ...                        'properties': {'key 1': {'type': 'number'},
+ 574        ...                                       'key 2': True}})
+ 575        ... # doctest: +NORMALIZE_WHITESPACE
+ 576        {'type': 'object',
+ 577                   'properties': {'key 1': {'type': 'number'},
+ 578                                  'key 2': True}}
+ 579        >>> t.setdefault(42, {'const': 'int key'})
+ 580        Traceback (most recent call last):
+ 581          ...
+ 582        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+ 583        >>> t.setdefault('key', 'schema')  # doctest: +NORMALIZE_WHITESPACE
+ 584        Traceback (most recent call last):
+ 585          ...
+ 586        TypeError: 'schema' is not a valid value in MessageTemplate
+ 587        (not a valid JSON schema).
+ 588
+ 589        But __setitem__ is not called if the key is already present:
+ 590        >>> t.setdefault('key 1', 'schema')
+ 591        {'const': 'value'}
+ 592        """
+ 593        if key not in self:
+ 594            if value is not None:
+ 595                self[key] = value
+ 596            else:
+ 597                self[key] = True
+ 598        return self[key]
+ 599
+ 600    def check(self, message: Message) -> bool:
+ 601        """Check message against this template.
+ 602
+ 603        Constant values have to match exactly:
+ 604        >>> t = MessageTemplate({'key': {'const': 'value'}})
+ 605        >>> t.check(Message('Example Sender', {'key': 'value'}))
+ 606        True
+ 607        >>> t.check(Message('Example Sender', {'key': 'other value'}))
+ 608        False
+ 609
+ 610        But for integers, floats with the same value are also valid:
+ 611        >>> t = MessageTemplate({'key': {'const': 42}})
+ 612        >>> t.check(Message('Example Sender', {'key': 42}))
+ 613        True
+ 614        >>> t.check(Message('Example Sender', {'key': 42.0}))
+ 615        True
+ 616
+ 617        Type integer is valid for floats with zero fractional part, but
+ 618        not by floats with non-zero fractional part:
+ 619        >>> t = MessageTemplate({'key': {'type': 'integer'}})
+ 620        >>> t.check(Message('Example Sender', {'key': 42}))
+ 621        True
+ 622        >>> t.check(Message('Example Sender', {'key': 42.0}))
+ 623        True
+ 624        >>> t.check(Message('Example Sender', {'key': 42.42}))
+ 625        False
+ 626
+ 627        Type number is valid for arbitrary ints or floats:
+ 628        >>> t = MessageTemplate({'key': {'type': 'number'}})
+ 629        >>> t.check(Message('Example Sender', {'key': 42}))
+ 630        True
+ 631        >>> t.check(Message('Example Sender', {'key': 42.42}))
+ 632        True
+ 633
+ 634        All keys in template have to be present in message:
+ 635        >>> t = MessageTemplate({'key 1': {'const': 'value'},
+ 636        ...                      'key 2': {'type': 'string'},
+ 637        ...                      'key 3': {'type': 'object',
+ 638        ...                                'properties': {
+ 639        ...                                    'key 1': {'type': 'number'},
+ 640        ...                                    'key 2': True,
+ 641        ...                                    'key 3': False}}})
+ 642        >>> t.check(Message('Example Sender',
+ 643        ...                 {'key 1': 'value', 'key 2': 'some string'}))
+ 644        False
+ 645
+ 646        But for nested objects their properties do not necessarily have
+ 647        to be present:
+ 648        >>> t.check(Message('Example Sender',
+ 649        ...                 {'key 1': 'value', 'key 2': 'some string',
+ 650        ...                  'key 3': {'key 1': 42}}))
+ 651        True
+ 652
+ 653        Schema True matches everything (even None):
+ 654        >>> t.check(Message('Example Sender',
+ 655        ...                 {'key 1': 'value', 'key 2': 'some string',
+ 656        ...                  'key 3': {'key 2': None}}))
+ 657        True
+ 658
+ 659        Schema False matches nothing:
+ 660        >>> t.check(Message('Example Sender',
+ 661        ...                 {'key 1': 'value', 'key 2': 'some string',
+ 662        ...                  'key 3': {'key 3': True}}))
+ 663        False
+ 664
+ 665        Message is valid for the constant template created from it:
+ 666        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
+ 667        ...                                'list': [None, True, 'string']})
+ 668        >>> t = MessageTemplate.from_message(m)
+ 669        >>> t.check(m)
+ 670        True
+ 671        """
+ 672        for key in self:
+ 673            if key not in message:
+ 674                return False
+ 675            else:
+ 676                schema_string = json.dumps(self[key])
+ 677                if not validate(schema_string, message[key]):
+ 678                    return False
+ 679        return True
+ 680
+ 681
+ 682class TemplateRegistry:
+ 683    """Manage a collection of message templates with registered clients.
+ 684
+ 685    A new TemplateRegistry is created by:
+ 686    >>> r = TemplateRegistry()
+ 687
+ 688    Client names (strings) can be registered for message templates, which
+ 689    are mappings from keys to JSON schemas:
+ 690    >>> r.insert({'k1': {'const': 'v1'}}, 'C 1')
+ 691
+ 692    The check function checks if the templates registered for a client
+ 693    match a given message:
+ 694    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 695    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 696    ...     print(f"{m}: {r.check('C 1', m)}")
+ 697    {'k1': 'v1', 'k2': 'v1'}: True
+ 698    {'k1': 'v1', 'k2': 2}: True
+ 699    {'k1': 'v2', 'k2': 'v1'}: False
+ 700    {'k1': 'v2', 'k2': 2}: False
+ 701
+ 702    Clients can be registered for values validating against arbitrary JSON
+ 703    schemas, e.g. all values of a certain type:
+ 704    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}, 'C 2')
+ 705    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 706    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 707    ...     print(f"{m}: {r.check('C 2', m)}")
+ 708    {'k1': 'v1', 'k2': 'v1'}: False
+ 709    {'k1': 'v1', 'k2': 2}: False
+ 710    {'k1': 'v2', 'k2': 'v1'}: True
+ 711    {'k1': 'v2', 'k2': 2}: False
+ 712    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}, 'C 3')
+ 713    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 714    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 715    ...     print(f"{m}: {r.check('C 3', m)}")
+ 716    {'k1': 'v1', 'k2': 'v1'}: False
+ 717    {'k1': 'v1', 'k2': 2}: False
+ 718    {'k1': 'v2', 'k2': 'v1'}: False
+ 719    {'k1': 'v2', 'k2': 2}: True
+ 720
+ 721    The order of key-value pairs does not have to match the order in the
+ 722    messages and keys can be left out:
+ 723    >>> r.insert({'k2': {'const': 2}}, 'C 4')
+ 724    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 725    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 726    ...     print(f"{m}: {r.check('C 4', m)}")
+ 727    {'k1': 'v1', 'k2': 'v1'}: False
+ 728    {'k1': 'v1', 'k2': 2}: True
+ 729    {'k1': 'v2', 'k2': 'v1'}: False
+ 730    {'k1': 'v2', 'k2': 2}: True
+ 731
+ 732    A registration for an empty template matches all messages:
+ 733    >>> r.insert({}, 'C 5')
+ 734    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 735    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 736    ...     print(f"{m}: {r.check('C 5', m)}")
+ 737    {'k1': 'v1', 'k2': 'v1'}: True
+ 738    {'k1': 'v1', 'k2': 2}: True
+ 739    {'k1': 'v2', 'k2': 'v1'}: True
+ 740    {'k1': 'v2', 'k2': 2}: True
+ 741
+ 742    A client can be registered for multiple templates:
+ 743    >>> r.insert({'k1': {'const': 'v1'}}, 'C 6')
+ 744    >>> r.insert({'k2': {'const': 'v1'}}, 'C 6')
+ 745    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 746    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 747    ...     print(f"{m}: {r.check('C 6', m)}")
+ 748    {'k1': 'v1', 'k2': 'v1'}: True
+ 749    {'k1': 'v1', 'k2': 2}: True
+ 750    {'k1': 'v2', 'k2': 'v1'}: True
+ 751    {'k1': 'v2', 'k2': 2}: False
+ 752
+ 753    Clients can be deregistered again (the result is False if the registry
+ 754    is empty after the deletion):
+ 755    >>> r.insert({'k1': {'const': 'v1'}}, 'C 7')
+ 756    >>> r.delete('C 7')
+ 757    True
+ 758    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 759    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 760    ...     print(f"{m}: {r.check('C 7', m)}")
+ 761    {'k1': 'v1', 'k2': 'v1'}: False
+ 762    {'k1': 'v1', 'k2': 2}: False
+ 763    {'k1': 'v2', 'k2': 'v1'}: False
+ 764    {'k1': 'v2', 'k2': 2}: False
+ 765
+ 766    The get function returns all clients with registered templates matching
+ 767    a given message:
+ 768    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 769    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 770    ...     print(f"{m}: {r.get(m)}")
+ 771    {'k1': 'v1', 'k2': 'v1'}: ['C 5', 'C 1', 'C 6']
+ 772    {'k1': 'v1', 'k2': 2}: ['C 5', 'C 1', 'C 6', 'C 4']
+ 773    {'k1': 'v2', 'k2': 'v1'}: ['C 5', 'C 2', 'C 6']
+ 774    {'k1': 'v2', 'k2': 2}: ['C 5', 'C 3', 'C 4']
+ 775
+ 776    The get_templates function returns all templates for a given client:
+ 777    >>> for c in ['C 1', 'C 2', 'C 3', 'C 4', 'C 5', 'C 6']:
+ 778    ...     print(f"{c}: {r.get_templates(c)}")
+ 779    C 1: [{'k1': {'const': 'v1'}}]
+ 780    C 2: [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
+ 781    C 3: [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
+ 782    C 4: [{'k2': {'const': 2}}]
+ 783    C 5: [{}]
+ 784    C 6: [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
+ 785    """
+ 786
+ 787    def __init__(self) -> None:
+ 788        """Initialise an empty registry.
+ 789
+ 790        >>> r = TemplateRegistry()
+ 791        """
+ 792        self._clients: List[str] = []
+ 793        self._callbacks: Dict[str, List[MessageCallback]] = {}
+ 794        self._constants: Dict[str, Dict[str, TemplateRegistry]] = {}
+ 795        # First key is the message key, second key is the constant string
+ 796        self._schemas: Dict[str, Dict[str, TemplateRegistry]] = {}
+ 797        # First key is the message key, second key is the JSON schema string
+ 798        self._templates: Dict[str, List[MessageTemplate]] = {}
+ 799
+ 800    def insert(
+ 801        self,
+ 802        template: MessageTemplate,
+ 803        client: str,
+ 804        callback: Optional[MessageCallback] = None,
+ 805    ) -> None:
+ 806        """Register a client for a template.
+ 807
+ 808        >>> r = TemplateRegistry()
+ 809        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'integer'}}, 'C 1')
+ 810        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'string'}}, 'C 2')
+ 811        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v1'}}, 'C 3')
+ 812        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v2'}}, 'C 4')
+ 813        >>> r.insert({}, 'C 5')
+ 814        """
+ 815        if client not in self._templates:
+ 816            self._templates[client] = []
+ 817        self._templates[client].append(template)
+ 818        if not template:
+ 819            self._clients.append(client)
+ 820            if callback:
+ 821                if client not in self._callbacks:
+ 822                    self._callbacks[client] = []
+ 823                self._callbacks[client].append(callback)
+ 824        else:
+ 825            key, schema = next(iter(template.items()))
+ 826            reduced_template = MessageTemplate(
+ 827                {k: template[k] for k in template if k != key}
+ 828            )
+ 829            if (
+ 830                isinstance(schema, dict)
+ 831                and len(schema) == 1
+ 832                and "const" in schema
+ 833                and isinstance(schema["const"], str)
+ 834            ):
+ 835                value = schema["const"]
+ 836                if key not in self._constants:
+ 837                    self._constants[key] = {}
+ 838                if value not in self._constants[key]:
+ 839                    self._constants[key][value] = TemplateRegistry()
+ 840                self._constants[key][value].insert(reduced_template, client, callback)
+ 841            else:
+ 842                schema_string = json.dumps(schema)
+ 843                if key not in self._schemas:
+ 844                    self._schemas[key] = {}
+ 845                if schema_string not in self._schemas[key]:
+ 846                    self._schemas[key][schema_string] = TemplateRegistry()
+ 847                self._schemas[key][schema_string].insert(
+ 848                    reduced_template, client, callback
+ 849                )
+ 850
+ 851    def delete(self, client: str) -> bool:
+ 852        """Unregister a client from all templates.
+ 853
+ 854        >>> r = TemplateRegistry()
+ 855        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'integer'}}, 'C 1')
+ 856        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'string'}}, 'C 2')
+ 857        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v1'}}, 'C 3')
+ 858        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v2'}}, 'C 4')
+ 859        >>> r.insert({}, 'C 5')
+ 860        >>> r.delete('C 3')
+ 861        True
+ 862        >>> r.delete('C 4')
+ 863        True
+ 864        """
+ 865        if client in self._templates:
+ 866            del self._templates[client]
+ 867        self._clients = [c for c in self._clients if c != client]
+ 868        if client in self._callbacks:
+ 869            del self._callbacks[client]
+ 870        new_constants: Dict[str, Dict[str, TemplateRegistry]] = {}
+ 871        for key in self._constants:
+ 872            new_constants[key] = {}
+ 873            for value in self._constants[key]:
+ 874                if self._constants[key][value].delete(client):
+ 875                    new_constants[key][value] = self._constants[key][value]
+ 876            if not new_constants[key]:
+ 877                del new_constants[key]
+ 878        self._constants = new_constants
+ 879        new_schemas: Dict[str, Dict[str, TemplateRegistry]] = {}
+ 880        for key in self._schemas:
+ 881            new_schemas[key] = {}
+ 882            for schema in self._schemas[key]:
+ 883                if self._schemas[key][schema].delete(client):
+ 884                    new_schemas[key][schema] = self._schemas[key][schema]
+ 885            if not new_schemas[key]:
+ 886                del new_schemas[key]
+ 887        self._schemas = new_schemas
+ 888        if self._clients or self._callbacks or self._constants or self._schemas:
+ 889            return True
+ 890        return False
+ 891
+ 892    def check(self, client: str, message: Message) -> bool:
+ 893        """Get if a client has a registered template matching a message.
+ 894
+ 895        >>> r = TemplateRegistry()
+ 896        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+ 897        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 898        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 899        ...     print(f"{m}: {r.check('Client 1', m)}")
+ 900        {'k1': 'v1', 'k2': 'v1'}: True
+ 901        {'k1': 'v1', 'k2': 2}: True
+ 902        {'k1': 'v2', 'k2': 'v1'}: False
+ 903        {'k1': 'v2', 'k2': 2}: False
+ 904        >>> r.insert({'k2': {'type': 'integer'}}, 'Client 2')
+ 905        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 906        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 907        ...     print(f"{m}: {r.check('Client 2', m)}")
+ 908        {'k1': 'v1', 'k2': 'v1'}: False
+ 909        {'k1': 'v1', 'k2': 2}: True
+ 910        {'k1': 'v2', 'k2': 'v1'}: False
+ 911        {'k1': 'v2', 'k2': 2}: True
+ 912        """
+ 913        if client in self._clients:
+ 914            return True
+ 915        for key in self._constants:
+ 916            if (
+ 917                key in message
+ 918                and isinstance(message[key], str)
+ 919                and message[key] in self._constants[key]
+ 920            ):
+ 921                value = message[key]
+ 922                assert isinstance(value, str)
+ 923                child = self._constants[key][value]
+ 924                if child.check(client, message):
+ 925                    return True
+ 926        for key in self._schemas:
+ 927            if key in message:
+ 928                for schema_string in self._schemas[key]:
+ 929                    if validate(schema_string, message[key]):
+ 930                        child = self._schemas[key][schema_string]
+ 931                        if child.check(client, message):
+ 932                            return True
+ 933        return False
+ 934
+ 935    def get(self, message: Message) -> List[str]:
+ 936        """Get all clients registered for templates matching a message.
+ 937
+ 938        >>> r = TemplateRegistry()
+ 939        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+ 940        >>> r.insert({'k2': {'type': 'integer'}}, 'Client 2')
+ 941        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 942        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 943        ...     print(f"{m}: {r.get(m)}")
+ 944        {'k1': 'v1', 'k2': 'v1'}: ['Client 1']
+ 945        {'k1': 'v1', 'k2': 2}: ['Client 1', 'Client 2']
+ 946        {'k1': 'v2', 'k2': 'v1'}: []
+ 947        {'k1': 'v2', 'k2': 2}: ['Client 2']
+ 948        """
+ 949        result = []
+ 950        for client in self._clients:
+ 951            if client not in result:
+ 952                result.append(client)
+ 953        for key in self._constants:
+ 954            if (
+ 955                key in message
+ 956                and isinstance(message[key], str)
+ 957                and message[key] in self._constants[key]
+ 958            ):
+ 959                value = message[key]
+ 960                assert isinstance(value, str)
+ 961                child = self._constants[key][value]
+ 962                for client in child.get(message):
+ 963                    if client not in result:
+ 964                        result.append(client)
+ 965        for key in self._schemas:
+ 966            if key in message:
+ 967                for schema_string in self._schemas[key]:
+ 968                    if validate(schema_string, message[key]):
+ 969                        child = self._schemas[key][schema_string]
+ 970                        for client in child.get(message):
+ 971                            if client not in result:
+ 972                                result.append(client)
+ 973        return result
+ 974
+ 975    def get_callbacks(self, message: Message) -> List[MessageCallback]:
+ 976        """Get all callbacks registered for templates matching a message."""
+ 977        result = []
+ 978        for client in self._callbacks:
+ 979            for callback in self._callbacks[client]:
+ 980                if callback not in result:
+ 981                    result.append(callback)
+ 982        for key in self._constants:
+ 983            if (
+ 984                key in message
+ 985                and isinstance(message[key], str)
+ 986                and message[key] in self._constants[key]
+ 987            ):
+ 988                value = message[key]
+ 989                assert isinstance(value, str)
+ 990                child = self._constants[key][value]
+ 991                for callback in child.get_callbacks(message):
+ 992                    if callback not in result:
+ 993                        result.append(callback)
+ 994        for key in self._schemas:
+ 995            if key in message:
+ 996                for schema_string in self._schemas[key]:
+ 997                    if validate(schema_string, message[key]):
+ 998                        child = self._schemas[key][schema_string]
+ 999                        for callback in child.get_callbacks(message):
+1000                            if callback not in result:
+1001                                result.append(callback)
+1002        return result
+1003
+1004    def get_templates(self, client: str) -> List[MessageTemplate]:
+1005        """Get all templates for a client.
+1006
+1007        >>> r = TemplateRegistry()
+1008        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+1009        >>> r.get_templates('Client 1')
+1010        [{'k1': {'const': 'v1'}}]
+1011        >>> r.insert({'k1': {'const': 'v2'},
+1012        ...           'k2': {'type': 'string'}}, 'Client 2')
+1013        >>> r.get_templates('Client 2')
+1014        [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
+1015        >>> r.insert({'k1': {'const': 'v2'},
+1016        ...           'k2': {'type': 'integer'}}, 'Client 3')
+1017        >>> r.get_templates('Client 3')
+1018        [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
+1019        >>> r.insert({'k2': {'const': 2}}, 'Client 4')
+1020        >>> r.get_templates('Client 4')
+1021        [{'k2': {'const': 2}}]
+1022        >>> r.insert({}, 'Client 5')
+1023        >>> r.get_templates('Client 5')
+1024        [{}]
+1025        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 6')
+1026        >>> r.insert({'k2': {'const': 'v1'}}, 'Client 6')
+1027        >>> r.get_templates('Client 6')
+1028        [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
+1029        """
+1030        if client in self._templates:
+1031            return self._templates[client]
+1032        return []
+1033
+1034
+1035class BusException(Exception):
+1036    """Raise for errors in using message bus."""
+1037
+1038
+1039class MessageBus:
+1040    """Provide an asynchronous message bus.
+1041
+1042    The bus executes asynchronous callbacks for all messages to be received
+1043    by a client. We use a simple callback printing the message in all
+1044    examples:
+1045    >>> def callback_for_receiver(receiver):
+1046    ...     print(f"Creating callback for {receiver}.")
+1047    ...     async def callback(message):
+1048    ...         print(f"{receiver}: {message}")
+1049    ...     return callback
+1050
+1051    Clients can be registered at the bus with a name, lists of message
+1052    templates they want to use for sending and receiving and a callback
+1053    function for receiving. An empty list of templates means that the
+1054    client does not want to send or receive any messages, respectively.
+1055    A list with an empty template means that it wants to send arbitrary
+1056    or receive all messages, respectively:
+1057    >>> async def setup(bus):
+1058    ...     print("Setting up.")
+1059    ...     bus.register('Logger', 'Test Plugin',
+1060    ...                  [],
+1061    ...                  [([MessageTemplate({})],
+1062    ...                    callback_for_receiver('Logger'))])
+1063    ...     bus.register('Client 1', 'Test Plugin',
+1064    ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1065    ...                  [([MessageTemplate({'target':
+1066    ...                                      {'const': 'Client 1'}})],
+1067    ...                    callback_for_receiver('Client 1'))])
+1068    ...     bus.register('Client 2', 'Test Plugin',
+1069    ...                  [MessageTemplate({})],
+1070    ...                  [([MessageTemplate({'target':
+1071    ...                                      {'const': 'Client 2'}})],
+1072    ...                    callback_for_receiver('Client 2'))])
+1073
+1074    The bus itself is addressed by the empty string. It sends messages for
+1075    each registration and deregestration of a client with a key 'event' and
+1076    a value of 'registered' or 'unregistered', a key 'client' with the
+1077    client's name as value and for registrations also keys 'sends' and
+1078    'receives' with all templates registered for the client for sending and
+1079    receiving.
+1080
+1081    Clients can send to the bus with the send function. Each message has to
+1082    declare a sender. The send templates of that sender are checked for a
+1083    template matching the message. We cannot prevent arbitrary code from
+1084    impersonating any sender, but this should only be done in debugging or
+1085    management situations.
+1086
+1087    Messages that are intended for a specific client by convention have a
+1088    key 'target' with the target client's name as value. Such messages are
+1089    often commands to the client to do something, which is by convention
+1090    indicated by a key 'command' with a value that indicates what should be
+1091    done.
+1092
+1093    The bus, for example, reacts to a message with 'target': '' and
+1094    'command': 'get clients' by sending one message for each currently
+1095    registered with complete information about its registered send and
+1096    receive templates.
+1097
+1098    >>> async def send(bus):
+1099    ...     print("Sending messages.")
+1100    ...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
+1101    ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
+1102    ...     await bus.send({'sender': '', 'target': '',
+1103    ...                     'command': 'get clients'})
+1104
+1105    The run function executes the message bus forever. If we want to stop
+1106    it, we have to explicitly cancel the task:
+1107    >>> async def main():
+1108    ...     bus = MessageBus()
+1109    ...     await setup(bus)
+1110    ...     bus_task = asyncio.create_task(bus.run())
+1111    ...     await send(bus)
+1112    ...     await asyncio.sleep(0)
+1113    ...     bus_task.cancel()
+1114    ...     try:
+1115    ...         await bus_task
+1116    ...     except asyncio.exceptions.CancelledError:
+1117    ...         pass
+1118    >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+1119    Setting up.
+1120    Creating callback for Logger.
+1121    Creating callback for Client 1.
+1122    Creating callback for Client 2.
+1123    Sending messages.
+1124    Logger: {'sender': '', 'event': 'registered',
+1125             'client': 'Logger', 'plugin': 'Test Plugin',
+1126             'sends': [], 'receives': [{}]}
+1127    Logger: {'sender': '', 'event': 'registered',
+1128             'client': 'Client 1', 'plugin': 'Test Plugin',
+1129             'sends': [{'k1': {'type': 'string'}}],
+1130             'receives': [{'target': {'const': 'Client 1'}}]}
+1131    Logger: {'sender': '', 'event': 'registered',
+1132             'client': 'Client 2', 'plugin': 'Test Plugin',
+1133             'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
+1134    Logger: {'sender': 'Client 1', 'k1': 'Test'}
+1135    Logger: {'sender': 'Client 2', 'target': 'Client 1'}
+1136    Client 1: {'sender': 'Client 2', 'target': 'Client 1'}
+1137    Logger: {'sender': '', 'target': '', 'command': 'get clients'}
+1138    Logger: {'sender': '', 'client': 'Logger', 'plugin': 'Test Plugin',
+1139             'sends': [], 'receives': [{}]}
+1140    Logger: {'sender': '', 'client': 'Client 1', 'plugin': 'Test Plugin',
+1141             'sends': [{'k1': {'type': 'string'}}],
+1142             'receives': [{'target': {'const': 'Client 1'}}]}
+1143    Logger: {'sender': '', 'client': 'Client 2', 'plugin': 'Test Plugin',
+1144             'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
+1145    """
+1146
+1147    def __init__(self) -> None:
+1148        """Initialise a new bus without clients.
+1149
+1150        >>> async def main():
+1151        ...     bus = MessageBus()
+1152        >>> asyncio.run(main())
+1153        """
+1154        self._queue: asyncio.Queue = asyncio.Queue()
+1155        self._plugins: Dict[str, str] = {}
+1156        self._send_reg: TemplateRegistry = TemplateRegistry()
+1157        self._recv_reg: TemplateRegistry = TemplateRegistry()
+1158
+1159    def register(
+1160        self,
+1161        client: str,
+1162        plugin: str,
+1163        sends: Iterable[MessageTemplate],
+1164        receives: Iterable[Tuple[Iterable[MessageTemplate], MessageCallback]],
+1165    ) -> None:
+1166        """Register a client at the message bus.
+1167
+1168        >>> async def callback(message):
+1169        ...     print(message)
+1170        >>> async def main():
+1171        ...     bus = MessageBus()
+1172        ...     bus.register('Logger', 'Test Plugin',
+1173        ...                  [],    # send nothing
+1174        ...                  [([MessageTemplate({})],  # receive everything
+1175        ...                    callback)])
+1176        ...     bus.register('Client 1', 'Test Plugin',
+1177        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1178        ...                      # send with key 'k1' and string value
+1179        ...                  [([MessageTemplate({'target':
+1180        ...                                      {'const': 'Client 1'}})],
+1181        ...                      # receive for this client
+1182        ...                    callback)])
+1183        ...     bus.register('Client 2', 'Test Plugin',
+1184        ...                  [MessageTemplate({})],  # send arbitrary
+1185        ...                  [([MessageTemplate({'target':
+1186        ...                                      {'const': 'Client 2'}})],
+1187        ...                      # receive for this client
+1188        ...                    callback)])
+1189        >>> asyncio.run(main())
+1190        """
+1191        if not client:
+1192            raise BusException("Client name is not allowed to be empty.")
+1193        if client in self._plugins:
+1194            raise BusException(f"Client '{client}' already registered at message bus.")
+1195        event = Message("")
+1196        event["event"] = "registered"
+1197        event["client"] = client
+1198        self._plugins[client] = plugin
+1199        event["plugin"] = plugin
+1200        for template in sends:
+1201            self._send_reg.insert(template, client)
+1202        event["sends"] = self._send_reg.get_templates(client)
+1203        for templates, callback in receives:
+1204            for template in templates:
+1205                self._recv_reg.insert(template, client, callback)
+1206        event["receives"] = self._recv_reg.get_templates(client)
+1207        self._queue.put_nowait(event)
+1208
+1209    def unregister(self, client: str) -> None:
+1210        """Unregister a client from the message bus.
+1211
+1212        >>> async def callback(message):
+1213        ...     print(message)
+1214        >>> async def main():
+1215        ...     bus = MessageBus()
+1216        ...     bus.register('Client 1', 'Test Plugin',
+1217        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1218        ...                  [([MessageTemplate({'target':
+1219        ...                                      {'const': 'Client 1'}})],
+1220        ...                    callback)])
+1221        ...     bus.unregister('Client 1')
+1222        >>> asyncio.run(main())
+1223        """
+1224        if client not in self._plugins:
+1225            return
+1226        event = Message("")
+1227        event["event"] = "unregistered"
+1228        event["client"] = client
+1229        del self._plugins[client]
+1230        self._send_reg.delete(client)
+1231        self._recv_reg.delete(client)
+1232        self._queue.put_nowait(event)
+1233
+1234    async def run(self) -> None:
+1235        """Run the message bus forever.
+1236
+1237        >>> async def main():
+1238        ...     bus = MessageBus()
+1239        ...     bus_task = asyncio.create_task(bus.run())
+1240        ...     bus_task.cancel()
+1241        ...     try:
+1242        ...         await bus_task
+1243        ...     except asyncio.exceptions.CancelledError:
+1244        ...         pass
+1245        >>> asyncio.run(main())
+1246        """
+1247        background_tasks = set()
+1248        while True:
+1249            message = await self._queue.get()
+1250            if "target" in message and message["target"] == "" and "command" in message:
+1251                if message["command"] == "get clients":
+1252                    for client in self._plugins:
+1253                        answer = Message("")
+1254                        answer["client"] = client
+1255                        answer["plugin"] = self._plugins[client]
+1256                        answer["sends"] = self._send_reg.get_templates(client)
+1257                        answer["receives"] = self._recv_reg.get_templates(client)
+1258                        await self._queue.put(answer)
+1259                elif message["command"] == "push conf":
+1260                    conf = {}
+1261                    try:
+1262                        with open(sys.argv[1]) as conf_file:
+1263                            conf = json.load(conf_file)
+1264                    except (
+1265                        IndexError,
+1266                        FileNotFoundError,
+1267                        json.decoder.JSONDecodeError,
+1268                    ):
+1269                        pass
+1270                    if conf == message["conf"]:
+1271                        await self._queue.put(Message("", {"event": "conf unchanged"}))
+1272                    else:
+1273                        await self._queue.put(Message("", {"event": "conf changed"}))
+1274                        with open(sys.argv[1], "w") as conf_file:
+1275                            json.dump(message["conf"], conf_file)
+1276            for callback in self._recv_reg.get_callbacks(message):
+1277                task = asyncio.create_task(callback(message))
+1278                background_tasks.add(task)
+1279                task.add_done_callback(background_tasks.discard)
+1280            self._queue.task_done()
+1281
+1282    async def send(self, message: Message) -> None:
+1283        """Send a message to the message bus.
+1284
+1285        >>> async def callback(message):
+1286        ...     print(f"Got: {message}")
+1287        >>> async def main():
+1288        ...     bus = MessageBus()
+1289        ...     bus.register('Client 1', 'Test Plugin',
+1290        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1291        ...                  [([MessageTemplate({'target':
+1292        ...                                      {'const': 'Client 1'}})],
+1293        ...                    callback)])
+1294        ...     bus.register('Client 2', 'Test Plugin',
+1295        ...                  [MessageTemplate({})],
+1296        ...                  [([MessageTemplate({'target':
+1297        ...                                      {'const': 'Client 2'}})],
+1298        ...                    callback)])
+1299        ...     bus_task = asyncio.create_task(bus.run())
+1300        ...     await bus.send({'sender': 'Client 1', 'target': 'Client 2',
+1301        ...                     'k1': 'Test'})
+1302        ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
+1303        ...     try:
+1304        ...         await bus.send({'sender': 'Client 1', 'target': 'Client 2',
+1305        ...                         'k1': 42})
+1306        ...     except BusException as e:
+1307        ...         print(e)
+1308        ...     await asyncio.sleep(0)
+1309        ...     bus_task.cancel()
+1310        ...     try:
+1311        ...         await bus_task
+1312        ...     except asyncio.exceptions.CancelledError:
+1313        ...         pass
+1314        >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+1315        Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
+1316        not allowed for sender 'Client 1'.
+1317        Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
+1318        Got: {'sender': 'Client 2', 'target': 'Client 1'}
+1319        """
+1320        assert isinstance(message["sender"], str)
+1321        sender = message["sender"]
+1322        if sender:
+1323            if not self._send_reg.check(sender, message):
+1324                raise BusException(
+1325                    f"Message '{message}' not allowed for sender '{sender}'."
+1326                )
+1327        await self._queue.put(message)
+1328
+1329    def send_nowait(self, message: Message) -> None:
+1330        """Send a message to the message bus without blocking.
+1331
+1332        >>> async def callback(message):
+1333        ...     print(f"Got: {message}")
+1334        >>> async def main():
+1335        ...     bus = MessageBus()
+1336        ...     bus.register('Client 1', 'Test Plugin',
+1337        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1338        ...                  [([MessageTemplate({'target':
+1339        ...                                      {'const': 'Client 1'}})],
+1340        ...                    callback)])
+1341        ...     bus.register('Client 2', 'Test Plugin',
+1342        ...                  [MessageTemplate({})],
+1343        ...                  [([MessageTemplate({'target':
+1344        ...                                      {'const': 'Client 2'}})],
+1345        ...                    callback)])
+1346        ...     bus_task = asyncio.create_task(bus.run())
+1347        ...     bus.send_nowait({'sender': 'Client 1', 'target': 'Client 2',
+1348        ...                      'k1': 'Test'})
+1349        ...     bus.send_nowait({'sender': 'Client 2', 'target': 'Client 1'})
+1350        ...     try:
+1351        ...         bus.send_nowait({'sender': 'Client 1',
+1352        ...                          'target': 'Client 2', 'k1': 42})
+1353        ...     except BusException as e:
+1354        ...         print(e)
+1355        ...     await asyncio.sleep(0)
+1356        ...     bus_task.cancel()
+1357        ...     try:
+1358        ...         await bus_task
+1359        ...     except asyncio.exceptions.CancelledError:
+1360        ...         pass
+1361        >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+1362        Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
+1363        not allowed for sender 'Client 1'.
+1364        Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
+1365        Got: {'sender': 'Client 2', 'target': 'Client 1'}
+1366        """
+1367        assert isinstance(message["sender"], str)
+1368        sender = message["sender"]
+1369        if sender:
+1370            if not self._send_reg.check(sender, message):
+1371                raise BusException(
+1372                    f"Message '{message}' not allowed for sender '{sender}'."
+1373                )
+1374        self._queue.put_nowait(message)
+

+ + +

+ + + + +

+ + + + +

+ MessageCallback = +typing.Callable[[ForwardRef('Message')], typing.Coroutine[typing.Any, typing.Any, NoneType]] + + +

+ + + + +

+ +

+ +

122def register_schema(schema: JSONSchema) -> bool:
+123    """Register the given JSON schema in the global cache."""
+124    global _validates
+125    schema_string = json.dumps(schema)
+126    if schema_string not in _validates:
+127        if not (isinstance(schema, dict) or isinstance(schema, bool)):
+128            return False
+129        try:
+130            _validates[schema_string] = fastjsonschema.compile(schema)
+131        except fastjsonschema.JsonSchemaDefinitionException:
+132            return False
+133    return True
+

+ + +

+ +

+ +

136def validate(schema_string: str, value: MessageValue) -> bool:
+137    """Validate the given MessageValue against the given JSON schema string."""
+138    global _validates
+139    if schema_string not in _validates:
+140        schema = json.loads(schema_string)
+141        _validates[schema_string] = fastjsonschema.compile(schema)
+142    validate = _validates[schema_string]
+143    try:
+144        validate(value)
+145    except fastjsonschema.JsonSchemaException:
+146        return False
+147    return True
+

+ + +

Validate the given MessageValue against the given JSON schema string.

+ + +

+ +

+ +

150class Message(Dict[str, MessageValue]):
+151    """Define arbitrary message.
+152
+153    Messages are dictionaries with string keys and values that are strings,
+154    integers, floats, Booleans, dictionaries that recursively have string
+155    keys and values of any of these types, or lists with elements that have
+156    any of these types. These constraints are checked when setting key-value
+157    pairs of the message.
+158
+159    A message has to have a sender, which is set by the constructor:
+160    >>> m = Message('Example sender')
+161    >>> print(m)
+162    {'sender': 'Example sender'}
+163
+164    A dictionary can be given to the constructor:
+165    >>> m = Message('Example sender',
+166    ...             {'key 1': 'value 1', 'key 2': 'value 2'})
+167    >>> print(m)
+168    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+169
+170    A 'sender' set in the initial dictionary is overwritten by the explicitly
+171    given sender in the first argument:
+172    >>> m = Message('Example sender',
+173    ...             {'sender': 'Original sender', 'key': 'value'})
+174    >>> print(m)
+175    {'sender': 'Example sender', 'key': 'value'}
+176
+177    Or the message can be modified after construction:
+178    >>> m = Message('Example sender', {'key 1': 'value 1'})
+179    >>> m['key 2'] = 'value 2'
+180    >>> print(m)
+181    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+182
+183    The 'sender' key can be overwritten, but this should only be done in
+184    exceptional cases:
+185    >>> m = Message('Example sender', {'key': 'value'})
+186    >>> m['sender'] = 'New sender'
+187    >>> print(m)
+188    {'sender': 'New sender', 'key': 'value'}
+189    """
+190
+191    def __init__(
+192        self, sender: str, init: Optional[Dict[str, MessageValue]] = None
+193    ) -> None:
+194        """Initialise message.
+195
+196        Message is initialised with given sender and possibly given
+197        key-value pairs:
+198        >>> m = Message('Example sender')
+199        >>> print(m)
+200        {'sender': 'Example sender'}
+201        >>> m = Message('Example sender', {'key 1': 'value 1'})
+202        >>> print(m)
+203        {'sender': 'Example sender', 'key 1': 'value 1'}
+204        """
+205        if not isinstance(sender, str):
+206            raise TypeError(f"'{sender}' is not a valid sender name (not a string).")
+207        self["sender"] = ""
+208        if init is not None:
+209            self.update(init)
+210        self["sender"] = sender
+211
+212    @staticmethod
+213    def check_value(value: MessageValue) -> bool:
+214        """Check recursively if a given value is valid.
+215
+216        None, strings, integers, floats and Booleans are valid:
+217        >>> Message.check_value(None)
+218        True
+219        >>> Message.check_value('Spam')
+220        True
+221        >>> Message.check_value(42)
+222        True
+223        >>> Message.check_value(42.42)
+224        True
+225        >>> Message.check_value(False)
+226        True
+227
+228        Other basic types are not valid:
+229        >>> Message.check_value(b'bytes')
+230        False
+231        >>> Message.check_value(1j)
+232        False
+233
+234        Dictionaries with string keys and recursively valid values are valid:
+235        >>> Message.check_value({'str value': 'Spam', 'int value': 42,
+236        ...                      'float value': 42.42, 'bool value': False})
+237        True
+238
+239        Empty dictionaries are valid:
+240        >>> Message.check_value({})
+241        True
+242
+243        Dictionaries with other keys are not valid:
+244        >>> Message.check_value({42: 'int key'})
+245        False
+246
+247        Dictionaries with invalid values are not valid:
+248        >>> Message.check_value({'complex value': 1j})
+249        False
+250
+251        Lists with valid elements are valid:
+252        >>> Message.check_value(['Spam', 42, 42.42, False])
+253        True
+254
+255        Empty lists are valid:
+256        >>> Message.check_value([])
+257        True
+258
+259        Lists with invalid elements are not valid:
+260        >>> Message.check_value([1j])
+261        False
+262        """
+263        if value is None:
+264            return True
+265        elif (
+266            isinstance(value, str)
+267            or isinstance(value, int)
+268            or isinstance(value, float)
+269            or isinstance(value, bool)
+270        ):
+271            return True
+272        elif isinstance(value, dict):
+273            for key in value:
+274                if not isinstance(key, str):
+275                    return False
+276                if not Message.check_value(value[key]):
+277                    return False
+278            return True
+279        elif isinstance(value, list):
+280            for element in value:
+281                if not Message.check_value(element):
+282                    return False
+283            return True
+284        return False
+285
+286    def __setitem__(self, key: str, value: MessageValue) -> None:
+287        """Check key and value before putting pair into dict.
+288
+289        >>> m = Message('Example sender')
+290        >>> m['key'] = 'value'
+291        >>> m['dict'] = {'k1': 'v1', 'k2': 2}
+292        >>> print(m)  # doctest: +NORMALIZE_WHITESPACE
+293        {'sender': 'Example sender', 'key': 'value',
+294         'dict': {'k1': 'v1', 'k2': 2}}
+295        >>> m = Message('Example sender')
+296        >>> m[42] = 'int key'
+297        Traceback (most recent call last):
+298          ...
+299        TypeError: '42' is not a valid key in Message (not a string).
+300        >>> m['complex value'] = 1j
+301        Traceback (most recent call last):
+302          ...
+303        TypeError: '1j' is not a valid value in Message.
+304        """
+305        if not isinstance(key, str):
+306            raise TypeError(f"'{key}' is not a valid key in Message (not a string).")
+307        if not self.check_value(value):
+308            raise TypeError(f"'{value}' is not a valid value in Message.")
+309        super().__setitem__(key, value)
+310
+311    def update(self, *args, **kwargs) -> None:
+312        """Override update to use validity checks.
+313
+314        >>> m = Message('Example sender')
+315        >>> m.update({'key 1': 'value 1', 'key 2': 'value 2'})
+316        >>> print(m)
+317        {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+318        >>> m.update({42: 'int key'})
+319        Traceback (most recent call last):
+320          ...
+321        TypeError: '42' is not a valid key in Message (not a string).
+322        >>> m.update({'complex value': 1j})
+323        Traceback (most recent call last):
+324          ...
+325        TypeError: '1j' is not a valid value in Message.
+326
+327        This is also used in __init__:
+328        >>> m = Message('Example sender', {'key': 'value'})
+329        >>> print(m)
+330        {'sender': 'Example sender', 'key': 'value'}
+331        >>> m = Message('Example sender', {42: 'int key'})
+332        Traceback (most recent call last):
+333          ...
+334        TypeError: '42' is not a valid key in Message (not a string).
+335        >>> m = Message('Example sender', {'complex value': 1j})
+336        Traceback (most recent call last):
+337          ...
+338        TypeError: '1j' is not a valid value in Message.
+339        """
+340        if args:
+341            if len(args) > 1:
+342                raise TypeError(f"update expected at most 1 argument, got {len(args)}")
+343            other = dict(args[0])
+344            for key in other:
+345                self[key] = other[key]
+346        for key in kwargs:
+347            self[key] = kwargs[key]
+348
+349    def setdefault(self, key: str, value: MessageValue = None) -> MessageValue:
+350        """Override setdefault to use validity checks.
+351
+352        >>> m = Message('Example sender')
+353        >>> m.setdefault('key', 'value 1')
+354        'value 1'
+355        >>> m.setdefault('key', 'value 2')
+356        'value 1'
+357        >>> m.setdefault(42, 'int key')
+358        Traceback (most recent call last):
+359          ...
+360        TypeError: '42' is not a valid key in Message (not a string).
+361        >>> m.setdefault('complex value', 1j)
+362        Traceback (most recent call last):
+363          ...
+364        TypeError: '1j' is not a valid value in Message.
+365
+366        But __setitem__ is not called if the key is already present:
+367        >>> m.setdefault('key', 1j)
+368        'value 1'
+369        """
+370        if key not in self:
+371            self[key] = value
+372        return self[key]
+

+ + +

Define arbitrary message.

+ +

Messages are dictionaries with string keys and values that are strings, +integers, floats, Booleans, dictionaries that recursively have string +keys and values of any of these types, or lists with elements that have +any of these types. These constraints are checked when setting key-value +pairs of the message.

+ +

A message has to have a sender, which is set by the constructor:

+ +

>>> m = Message('Example sender')
+>>> print(m)
+{'sender': 'Example sender'}
+

+ +

A dictionary can be given to the constructor:

+ +

>>> m = Message('Example sender',
+...             {'key 1': 'value 1', 'key 2': 'value 2'})
+>>> print(m)
+{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+

+ +

A 'sender' set in the initial dictionary is overwritten by the explicitly +given sender in the first argument:

+ +

>>> m = Message('Example sender',
+...             {'sender': 'Original sender', 'key': 'value'})
+>>> print(m)
+{'sender': 'Example sender', 'key': 'value'}
+

+ +

Or the message can be modified after construction:

+ +

>>> m = Message('Example sender', {'key 1': 'value 1'})
+>>> m['key 2'] = 'value 2'
+>>> print(m)
+{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+

+ +

The 'sender' key can be overwritten, but this should only be done in +exceptional cases:

+ +

>>> m = Message('Example sender', {'key': 'value'})
+>>> m['sender'] = 'New sender'
+>>> print(m)
+{'sender': 'New sender', 'key': 'value'}
+

+ + +

+ +

+ +

191    def __init__(
+192        self, sender: str, init: Optional[Dict[str, MessageValue]] = None
+193    ) -> None:
+194        """Initialise message.
+195
+196        Message is initialised with given sender and possibly given
+197        key-value pairs:
+198        >>> m = Message('Example sender')
+199        >>> print(m)
+200        {'sender': 'Example sender'}
+201        >>> m = Message('Example sender', {'key 1': 'value 1'})
+202        >>> print(m)
+203        {'sender': 'Example sender', 'key 1': 'value 1'}
+204        """
+205        if not isinstance(sender, str):
+206            raise TypeError(f"'{sender}' is not a valid sender name (not a string).")
+207        self["sender"] = ""
+208        if init is not None:
+209            self.update(init)
+210        self["sender"] = sender
+

+ + +

Initialise message.

+ +

Message is initialised with given sender and possibly given +key-value pairs:

+ +

>>> m = Message('Example sender')
+>>> print(m)
+{'sender': 'Example sender'}
+>>> m = Message('Example sender', {'key 1': 'value 1'})
+>>> print(m)
+{'sender': 'Example sender', 'key 1': 'value 1'}
+

+ + +

+ +

@staticmethod

+ +

212    @staticmethod
+213    def check_value(value: MessageValue) -> bool:
+214        """Check recursively if a given value is valid.
+215
+216        None, strings, integers, floats and Booleans are valid:
+217        >>> Message.check_value(None)
+218        True
+219        >>> Message.check_value('Spam')
+220        True
+221        >>> Message.check_value(42)
+222        True
+223        >>> Message.check_value(42.42)
+224        True
+225        >>> Message.check_value(False)
+226        True
+227
+228        Other basic types are not valid:
+229        >>> Message.check_value(b'bytes')
+230        False
+231        >>> Message.check_value(1j)
+232        False
+233
+234        Dictionaries with string keys and recursively valid values are valid:
+235        >>> Message.check_value({'str value': 'Spam', 'int value': 42,
+236        ...                      'float value': 42.42, 'bool value': False})
+237        True
+238
+239        Empty dictionaries are valid:
+240        >>> Message.check_value({})
+241        True
+242
+243        Dictionaries with other keys are not valid:
+244        >>> Message.check_value({42: 'int key'})
+245        False
+246
+247        Dictionaries with invalid values are not valid:
+248        >>> Message.check_value({'complex value': 1j})
+249        False
+250
+251        Lists with valid elements are valid:
+252        >>> Message.check_value(['Spam', 42, 42.42, False])
+253        True
+254
+255        Empty lists are valid:
+256        >>> Message.check_value([])
+257        True
+258
+259        Lists with invalid elements are not valid:
+260        >>> Message.check_value([1j])
+261        False
+262        """
+263        if value is None:
+264            return True
+265        elif (
+266            isinstance(value, str)
+267            or isinstance(value, int)
+268            or isinstance(value, float)
+269            or isinstance(value, bool)
+270        ):
+271            return True
+272        elif isinstance(value, dict):
+273            for key in value:
+274                if not isinstance(key, str):
+275                    return False
+276                if not Message.check_value(value[key]):
+277                    return False
+278            return True
+279        elif isinstance(value, list):
+280            for element in value:
+281                if not Message.check_value(element):
+282                    return False
+283            return True
+284        return False
+

+ + +

Check recursively if a given value is valid.

+ +

None, strings, integers, floats and Booleans are valid:

+ +

>>> Message.check_value(None)
+True
+>>> Message.check_value('Spam')
+True
+>>> Message.check_value(42)
+True
+>>> Message.check_value(42.42)
+True
+>>> Message.check_value(False)
+True
+

+ +

Other basic types are not valid:

+ +

>>> Message.check_value(b'bytes')
+False
+>>> Message.check_value(1j)
+False
+

+ +

Dictionaries with string keys and recursively valid values are valid:

+ +

>>> Message.check_value({'str value': 'Spam', 'int value': 42,
+...                      'float value': 42.42, 'bool value': False})
+True
+

+ +

Empty dictionaries are valid:

+ +

>>> Message.check_value({})
+True
+

+ +

Dictionaries with other keys are not valid:

+ +

>>> Message.check_value({42: 'int key'})
+False
+

+ +

Dictionaries with invalid values are not valid:

+ +

>>> Message.check_value({'complex value': 1j})
+False
+

+ +

Lists with valid elements are valid:

+ +

>>> Message.check_value(['Spam', 42, 42.42, False])
+True
+

+ +

Empty lists are valid:

+ +

>>> Message.check_value([])
+True
+

+ +

Lists with invalid elements are not valid:

+ +

>>> Message.check_value([1j])
+False
+

+ + +

+ +

+ + def + update(self, *args, **kwargs) -> None: + + View Source + +

+ +

311    def update(self, *args, **kwargs) -> None:
+312        """Override update to use validity checks.
+313
+314        >>> m = Message('Example sender')
+315        >>> m.update({'key 1': 'value 1', 'key 2': 'value 2'})
+316        >>> print(m)
+317        {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+318        >>> m.update({42: 'int key'})
+319        Traceback (most recent call last):
+320          ...
+321        TypeError: '42' is not a valid key in Message (not a string).
+322        >>> m.update({'complex value': 1j})
+323        Traceback (most recent call last):
+324          ...
+325        TypeError: '1j' is not a valid value in Message.
+326
+327        This is also used in __init__:
+328        >>> m = Message('Example sender', {'key': 'value'})
+329        >>> print(m)
+330        {'sender': 'Example sender', 'key': 'value'}
+331        >>> m = Message('Example sender', {42: 'int key'})
+332        Traceback (most recent call last):
+333          ...
+334        TypeError: '42' is not a valid key in Message (not a string).
+335        >>> m = Message('Example sender', {'complex value': 1j})
+336        Traceback (most recent call last):
+337          ...
+338        TypeError: '1j' is not a valid value in Message.
+339        """
+340        if args:
+341            if len(args) > 1:
+342                raise TypeError(f"update expected at most 1 argument, got {len(args)}")
+343            other = dict(args[0])
+344            for key in other:
+345                self[key] = other[key]
+346        for key in kwargs:
+347            self[key] = kwargs[key]
+

+ + +

Override update to use validity checks.

+ +

>>> m = Message('Example sender')
+>>> m.update({'key 1': 'value 1', 'key 2': 'value 2'})
+>>> print(m)
+{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
+>>> m.update({42: 'int key'})
+Traceback (most recent call last):
+  ...
+TypeError: '42' is not a valid key in Message (not a string).
+>>> m.update({'complex value': 1j})
+Traceback (most recent call last):
+  ...
+TypeError: '1j' is not a valid value in Message.
+

+ +

This is also used in __init__:

+ +

>>> m = Message('Example sender', {'key': 'value'})
+>>> print(m)
+{'sender': 'Example sender', 'key': 'value'}
+>>> m = Message('Example sender', {42: 'int key'})
+Traceback (most recent call last):
+  ...
+TypeError: '42' is not a valid key in Message (not a string).
+>>> m = Message('Example sender', {'complex value': 1j})
+Traceback (most recent call last):
+  ...
+TypeError: '1j' is not a valid value in Message.
+

+ + +

+ +

+ +

349    def setdefault(self, key: str, value: MessageValue = None) -> MessageValue:
+350        """Override setdefault to use validity checks.
+351
+352        >>> m = Message('Example sender')
+353        >>> m.setdefault('key', 'value 1')
+354        'value 1'
+355        >>> m.setdefault('key', 'value 2')
+356        'value 1'
+357        >>> m.setdefault(42, 'int key')
+358        Traceback (most recent call last):
+359          ...
+360        TypeError: '42' is not a valid key in Message (not a string).
+361        >>> m.setdefault('complex value', 1j)
+362        Traceback (most recent call last):
+363          ...
+364        TypeError: '1j' is not a valid value in Message.
+365
+366        But __setitem__ is not called if the key is already present:
+367        >>> m.setdefault('key', 1j)
+368        'value 1'
+369        """
+370        if key not in self:
+371            self[key] = value
+372        return self[key]
+

+ + +

Override setdefault to use validity checks.

+ +

>>> m = Message('Example sender')
+>>> m.setdefault('key', 'value 1')
+'value 1'
+>>> m.setdefault('key', 'value 2')
+'value 1'
+>>> m.setdefault(42, 'int key')
+Traceback (most recent call last):
+  ...
+TypeError: '42' is not a valid key in Message (not a string).
+>>> m.setdefault('complex value', 1j)
+Traceback (most recent call last):
+  ...
+TypeError: '1j' is not a valid value in Message.
+

+ +

But __setitem__ is not called if the key is already present:

+ +

>>> m.setdefault('key', 1j)
+'value 1'
+

+ + +

+ +

+ +

375class MessageTemplate(Dict[str, JSONSchema]):
+376    """Define a message template.
+377
+378    A message template is a mapping from string keys to JSON schemas as
+379    values:
+380    >>> t = MessageTemplate({'key 1': {'const': 'value'},
+381    ...                      'key 2': {'type': 'string'}})
+382    >>> t['key 3'] = {'type': 'object',
+383    ...               'properties': {'key 1': {'type': 'number'},
+384    ...                              'key 2': True}}
+385
+386    A message template matches a message if all keys of the template are
+387    contained in the message and the values in the message validate against
+388    the respective schemas:
+389    >>> t.check(Message('Example Sender',
+390    ...                 {'key 1': 'value', 'key 2': 'some string',
+391    ...                  'key 3': {'key 1': 42, 'key 2': None}}))
+392    True
+393
+394    An empty mapping therefore matches all messages:
+395    >>> t = MessageTemplate()
+396    >>> t.check(Message('Example Sender', {'arbitrary': 'content'}))
+397    True
+398    """
+399
+400    def __init__(self, init: Optional[Dict[str, JSONSchema]] = None) -> None:
+401        """Initialise message.
+402
+403        Template is initialised empty or with given key-value pairs:
+404        >>> t = MessageTemplate()
+405        >>> print(t)
+406        {}
+407        >>> t = MessageTemplate({'key': {'const': 'value'}})
+408        >>> print(t)
+409        {'key': {'const': 'value'}}
+410        """
+411        if init is not None:
+412            self.update(init)
+413
+414    @staticmethod
+415    def from_message(message: Message) -> "MessageTemplate":
+416        """Create template from message.
+417
+418        Template witch constant schemas is created from message:
+419        >>> m = Message('Example Sender', {'key': 'value'})
+420        >>> t = MessageTemplate.from_message(m)
+421        >>> print(t)
+422        {'sender': {'const': 'Example Sender'}, 'key': {'const': 'value'}}
+423        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
+424        ...                                'list': [None, True, 'string']})
+425        >>> t = MessageTemplate.from_message(m)
+426        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+427        {'sender': {'const': 'Example Sender'},
+428         'dict': {'type': 'object',
+429                  'properties': {'int': {'const': 42},
+430                                 'float': {'const': 42.42}}},
+431         'list': {'type': 'array',
+432                  'items': [{'const': None},
+433                            {'const': True},
+434                            {'const': 'string'}]}}
+435
+436        This is especially useful for clients that send certain fully
+437        predefined messages, where the message is given in the configuration
+438        and the template for the registration can be constructed by this
+439        method.
+440        """
+441
+442        def schema_from_value(value: MessageValue) -> JSONSchema:
+443            schema: JSONSchema = False
+444            if value is None:
+445                schema = {"const": None}
+446            elif (
+447                isinstance(value, str)
+448                or isinstance(value, int)
+449                or isinstance(value, float)
+450                or isinstance(value, bool)
+451            ):
+452                schema = {"const": value}
+453            elif isinstance(value, dict):
+454                properties = {}
+455                for inner_key in value:
+456                    inner_value: Message = value[inner_key]
+457                    properties[inner_key] = schema_from_value(inner_value)
+458                schema = {"type": "object", "properties": properties}
+459            elif isinstance(value, list):
+460                schema = {
+461                    "type": "array",
+462                    "items": [schema_from_value(element) for element in value],
+463                }
+464            return schema
+465
+466        template = MessageTemplate()
+467        for key in message:
+468            template[key] = schema_from_value(message[key])
+469        return template
+470
+471    def __setitem__(self, key: str, value: JSONSchema) -> None:
+472        """Check key and value before putting pair into dict.
+473
+474        >>> t = MessageTemplate()
+475        >>> t['key 1'] = {'const': 'value'}
+476        >>> t['key 2'] = {'type': 'string'}
+477        >>> t['key 3'] = {'type': 'object',
+478        ...               'properties': {'key 1': {'type': 'number'},
+479        ...                              'key 2': True}}
+480        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+481        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+482         'key 3': {'type': 'object',
+483                   'properties': {'key 1': {'type': 'number'},
+484                                  'key 2': True}}}
+485        >>> t[42] = {'const': 'int key'}
+486        Traceback (most recent call last):
+487          ...
+488        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+489        >>> t['key'] = 'schema'  # doctest: +NORMALIZE_WHITESPACE
+490        Traceback (most recent call last):
+491          ...
+492        TypeError: 'schema' is not a valid value in MessageTemplate
+493        (not a valid JSON schema).
+494        >>> t['key'] = True
+495        """
+496        if not isinstance(key, str):
+497            raise TypeError(
+498                f"'{key}' is not a valid key in MessageTemplate (not a string)."
+499            )
+500        if not register_schema(value):
+501            raise TypeError(
+502                f"'{value}' is not a valid value in"
+503                " MessageTemplate (not a valid JSON schema)."
+504            )
+505        super().__setitem__(key, value)
+506
+507    def update(self, *args, **kwargs) -> None:
+508        """Override update to use validity checks.
+509
+510        >>> t = MessageTemplate()
+511        >>> t.update({'key 1': {'const': 'value'},
+512        ...           'key 2': {'type': 'string'},
+513        ...           'key 3': {'type': 'object',
+514        ...                     'properties': {'key 1': {'type': 'number'},
+515        ...                                    'key 2': True}}})
+516        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+517        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+518         'key 3': {'type': 'object',
+519                   'properties': {'key 1': {'type': 'number'},
+520                                  'key 2': True}}}
+521        >>> t.update({42: {'const': 'int key'}})
+522        Traceback (most recent call last):
+523          ...
+524        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+525        >>> t.update({'key': 'schema'})  # doctest: +NORMALIZE_WHITESPACE
+526        Traceback (most recent call last):
+527          ...
+528        TypeError: 'schema' is not a valid value in MessageTemplate
+529        (not a valid JSON schema).
+530        >>> t.update({'key': True})
+531
+532        This is also used in __init__:
+533        >>> t = MessageTemplate({'key 1': {'const': 'value'},
+534        ...                      'key 2': {'type': 'string'},
+535        ...                      'key 3': {'type': 'object',
+536        ...                                'properties': {
+537        ...                                    'key 1': {'type': 'number'},
+538        ...                                    'key 2': True}}})
+539        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+540        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+541         'key 3': {'type': 'object',
+542                   'properties': {'key 1': {'type': 'number'},
+543                                  'key 2': True}}}
+544        >>> t = MessageTemplate({42: {'const': 'int key'}})
+545        Traceback (most recent call last):
+546          ...
+547        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+548        >>> t = MessageTemplate({'key': 'schema'})
+549        ... # doctest: +NORMALIZE_WHITESPACE
+550        Traceback (most recent call last):
+551          ...
+552        TypeError: 'schema' is not a valid value in MessageTemplate
+553        (not a valid JSON schema).
+554        >>> t = MessageTemplate({'key': True})
+555        """
+556        if args:
+557            if len(args) > 1:
+558                raise TypeError(f"update expected at most 1 argument, got {len(args)}")
+559            other = dict(args[0])
+560            for key in other:
+561                self[key] = other[key]
+562        for key in kwargs:
+563            self[key] = kwargs[key]
+564
+565    def setdefault(self, key: str, value: Optional[JSONSchema] = None) -> JSONSchema:
+566        """Override setdefault to use validity checks.
+567
+568        >>> t = MessageTemplate()
+569        >>> t.setdefault('key 1', {'const': 'value'})
+570        {'const': 'value'}
+571        >>> t.setdefault('key 2', {'type': 'string'})
+572        {'type': 'string'}
+573        >>> t.setdefault('key 3', {'type': 'object',
+574        ...                        'properties': {'key 1': {'type': 'number'},
+575        ...                                       'key 2': True}})
+576        ... # doctest: +NORMALIZE_WHITESPACE
+577        {'type': 'object',
+578                   'properties': {'key 1': {'type': 'number'},
+579                                  'key 2': True}}
+580        >>> t.setdefault(42, {'const': 'int key'})
+581        Traceback (most recent call last):
+582          ...
+583        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+584        >>> t.setdefault('key', 'schema')  # doctest: +NORMALIZE_WHITESPACE
+585        Traceback (most recent call last):
+586          ...
+587        TypeError: 'schema' is not a valid value in MessageTemplate
+588        (not a valid JSON schema).
+589
+590        But __setitem__ is not called if the key is already present:
+591        >>> t.setdefault('key 1', 'schema')
+592        {'const': 'value'}
+593        """
+594        if key not in self:
+595            if value is not None:
+596                self[key] = value
+597            else:
+598                self[key] = True
+599        return self[key]
+600
+601    def check(self, message: Message) -> bool:
+602        """Check message against this template.
+603
+604        Constant values have to match exactly:
+605        >>> t = MessageTemplate({'key': {'const': 'value'}})
+606        >>> t.check(Message('Example Sender', {'key': 'value'}))
+607        True
+608        >>> t.check(Message('Example Sender', {'key': 'other value'}))
+609        False
+610
+611        But for integers, floats with the same value are also valid:
+612        >>> t = MessageTemplate({'key': {'const': 42}})
+613        >>> t.check(Message('Example Sender', {'key': 42}))
+614        True
+615        >>> t.check(Message('Example Sender', {'key': 42.0}))
+616        True
+617
+618        Type integer is valid for floats with zero fractional part, but
+619        not by floats with non-zero fractional part:
+620        >>> t = MessageTemplate({'key': {'type': 'integer'}})
+621        >>> t.check(Message('Example Sender', {'key': 42}))
+622        True
+623        >>> t.check(Message('Example Sender', {'key': 42.0}))
+624        True
+625        >>> t.check(Message('Example Sender', {'key': 42.42}))
+626        False
+627
+628        Type number is valid for arbitrary ints or floats:
+629        >>> t = MessageTemplate({'key': {'type': 'number'}})
+630        >>> t.check(Message('Example Sender', {'key': 42}))
+631        True
+632        >>> t.check(Message('Example Sender', {'key': 42.42}))
+633        True
+634
+635        All keys in template have to be present in message:
+636        >>> t = MessageTemplate({'key 1': {'const': 'value'},
+637        ...                      'key 2': {'type': 'string'},
+638        ...                      'key 3': {'type': 'object',
+639        ...                                'properties': {
+640        ...                                    'key 1': {'type': 'number'},
+641        ...                                    'key 2': True,
+642        ...                                    'key 3': False}}})
+643        >>> t.check(Message('Example Sender',
+644        ...                 {'key 1': 'value', 'key 2': 'some string'}))
+645        False
+646
+647        But for nested objects their properties do not necessarily have
+648        to be present:
+649        >>> t.check(Message('Example Sender',
+650        ...                 {'key 1': 'value', 'key 2': 'some string',
+651        ...                  'key 3': {'key 1': 42}}))
+652        True
+653
+654        Schema True matches everything (even None):
+655        >>> t.check(Message('Example Sender',
+656        ...                 {'key 1': 'value', 'key 2': 'some string',
+657        ...                  'key 3': {'key 2': None}}))
+658        True
+659
+660        Schema False matches nothing:
+661        >>> t.check(Message('Example Sender',
+662        ...                 {'key 1': 'value', 'key 2': 'some string',
+663        ...                  'key 3': {'key 3': True}}))
+664        False
+665
+666        Message is valid for the constant template created from it:
+667        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
+668        ...                                'list': [None, True, 'string']})
+669        >>> t = MessageTemplate.from_message(m)
+670        >>> t.check(m)
+671        True
+672        """
+673        for key in self:
+674            if key not in message:
+675                return False
+676            else:
+677                schema_string = json.dumps(self[key])
+678                if not validate(schema_string, message[key]):
+679                    return False
+680        return True
+

+ + +

Define a message template.

+ +

A message template is a mapping from string keys to JSON schemas as +values:

+ +

>>> t = MessageTemplate({'key 1': {'const': 'value'},
+...                      'key 2': {'type': 'string'}})
+>>> t['key 3'] = {'type': 'object',
+...               'properties': {'key 1': {'type': 'number'},
+...                              'key 2': True}}
+

+ +

A message template matches a message if all keys of the template are +contained in the message and the values in the message validate against +the respective schemas:

+ +

>>> t.check(Message('Example Sender',
+...                 {'key 1': 'value', 'key 2': 'some string',
+...                  'key 3': {'key 1': 42, 'key 2': None}}))
+True
+

+ +

An empty mapping therefore matches all messages:

+ +

>>> t = MessageTemplate()
+>>> t.check(Message('Example Sender', {'arbitrary': 'content'}))
+True
+

+ + +

+ +

+ +

400    def __init__(self, init: Optional[Dict[str, JSONSchema]] = None) -> None:
+401        """Initialise message.
+402
+403        Template is initialised empty or with given key-value pairs:
+404        >>> t = MessageTemplate()
+405        >>> print(t)
+406        {}
+407        >>> t = MessageTemplate({'key': {'const': 'value'}})
+408        >>> print(t)
+409        {'key': {'const': 'value'}}
+410        """
+411        if init is not None:
+412            self.update(init)
+

+ + +

Initialise message.

+ +

Template is initialised empty or with given key-value pairs:

+ +

>>> t = MessageTemplate()
+>>> print(t)
+{}
+>>> t = MessageTemplate({'key': {'const': 'value'}})
+>>> print(t)
+{'key': {'const': 'value'}}
+

+ + +

+ +

@staticmethod

+ + def + from_message( message: Message) -> MessageTemplate: + + View Source + +

+ +

414    @staticmethod
+415    def from_message(message: Message) -> "MessageTemplate":
+416        """Create template from message.
+417
+418        Template witch constant schemas is created from message:
+419        >>> m = Message('Example Sender', {'key': 'value'})
+420        >>> t = MessageTemplate.from_message(m)
+421        >>> print(t)
+422        {'sender': {'const': 'Example Sender'}, 'key': {'const': 'value'}}
+423        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
+424        ...                                'list': [None, True, 'string']})
+425        >>> t = MessageTemplate.from_message(m)
+426        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+427        {'sender': {'const': 'Example Sender'},
+428         'dict': {'type': 'object',
+429                  'properties': {'int': {'const': 42},
+430                                 'float': {'const': 42.42}}},
+431         'list': {'type': 'array',
+432                  'items': [{'const': None},
+433                            {'const': True},
+434                            {'const': 'string'}]}}
+435
+436        This is especially useful for clients that send certain fully
+437        predefined messages, where the message is given in the configuration
+438        and the template for the registration can be constructed by this
+439        method.
+440        """
+441
+442        def schema_from_value(value: MessageValue) -> JSONSchema:
+443            schema: JSONSchema = False
+444            if value is None:
+445                schema = {"const": None}
+446            elif (
+447                isinstance(value, str)
+448                or isinstance(value, int)
+449                or isinstance(value, float)
+450                or isinstance(value, bool)
+451            ):
+452                schema = {"const": value}
+453            elif isinstance(value, dict):
+454                properties = {}
+455                for inner_key in value:
+456                    inner_value: Message = value[inner_key]
+457                    properties[inner_key] = schema_from_value(inner_value)
+458                schema = {"type": "object", "properties": properties}
+459            elif isinstance(value, list):
+460                schema = {
+461                    "type": "array",
+462                    "items": [schema_from_value(element) for element in value],
+463                }
+464            return schema
+465
+466        template = MessageTemplate()
+467        for key in message:
+468            template[key] = schema_from_value(message[key])
+469        return template
+

+ + +

Create template from message.

+ +

Template witch constant schemas is created from message:

+ +

>>> m = Message('Example Sender', {'key': 'value'})
+>>> t = MessageTemplate.from_message(m)
+>>> print(t)
+{'sender': {'const': 'Example Sender'}, 'key': {'const': 'value'}}
+>>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
+...                                'list': [None, True, 'string']})
+>>> t = MessageTemplate.from_message(m)
+>>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+{'sender': {'const': 'Example Sender'},
+ 'dict': {'type': 'object',
+          'properties': {'int': {'const': 42},
+                         'float': {'const': 42.42}}},
+ 'list': {'type': 'array',
+          'items': [{'const': None},
+                    {'const': True},
+                    {'const': 'string'}]}}
+

+ +

This is especially useful for clients that send certain fully +predefined messages, where the message is given in the configuration +and the template for the registration can be constructed by this +method.

+ + +

+ +

+ + def + update(self, *args, **kwargs) -> None: + + View Source + +

+ +

507    def update(self, *args, **kwargs) -> None:
+508        """Override update to use validity checks.
+509
+510        >>> t = MessageTemplate()
+511        >>> t.update({'key 1': {'const': 'value'},
+512        ...           'key 2': {'type': 'string'},
+513        ...           'key 3': {'type': 'object',
+514        ...                     'properties': {'key 1': {'type': 'number'},
+515        ...                                    'key 2': True}}})
+516        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+517        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+518         'key 3': {'type': 'object',
+519                   'properties': {'key 1': {'type': 'number'},
+520                                  'key 2': True}}}
+521        >>> t.update({42: {'const': 'int key'}})
+522        Traceback (most recent call last):
+523          ...
+524        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+525        >>> t.update({'key': 'schema'})  # doctest: +NORMALIZE_WHITESPACE
+526        Traceback (most recent call last):
+527          ...
+528        TypeError: 'schema' is not a valid value in MessageTemplate
+529        (not a valid JSON schema).
+530        >>> t.update({'key': True})
+531
+532        This is also used in __init__:
+533        >>> t = MessageTemplate({'key 1': {'const': 'value'},
+534        ...                      'key 2': {'type': 'string'},
+535        ...                      'key 3': {'type': 'object',
+536        ...                                'properties': {
+537        ...                                    'key 1': {'type': 'number'},
+538        ...                                    'key 2': True}}})
+539        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+540        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+541         'key 3': {'type': 'object',
+542                   'properties': {'key 1': {'type': 'number'},
+543                                  'key 2': True}}}
+544        >>> t = MessageTemplate({42: {'const': 'int key'}})
+545        Traceback (most recent call last):
+546          ...
+547        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+548        >>> t = MessageTemplate({'key': 'schema'})
+549        ... # doctest: +NORMALIZE_WHITESPACE
+550        Traceback (most recent call last):
+551          ...
+552        TypeError: 'schema' is not a valid value in MessageTemplate
+553        (not a valid JSON schema).
+554        >>> t = MessageTemplate({'key': True})
+555        """
+556        if args:
+557            if len(args) > 1:
+558                raise TypeError(f"update expected at most 1 argument, got {len(args)}")
+559            other = dict(args[0])
+560            for key in other:
+561                self[key] = other[key]
+562        for key in kwargs:
+563            self[key] = kwargs[key]
+

+ + +

Override update to use validity checks.

+ +

>>> t = MessageTemplate()
+>>> t.update({'key 1': {'const': 'value'},
+...           'key 2': {'type': 'string'},
+...           'key 3': {'type': 'object',
+...                     'properties': {'key 1': {'type': 'number'},
+...                                    'key 2': True}}})
+>>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+{'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+ 'key 3': {'type': 'object',
+           'properties': {'key 1': {'type': 'number'},
+                          'key 2': True}}}
+>>> t.update({42: {'const': 'int key'}})
+Traceback (most recent call last):
+  ...
+TypeError: '42' is not a valid key in MessageTemplate (not a string).
+>>> t.update({'key': 'schema'})  # doctest: +NORMALIZE_WHITESPACE
+Traceback (most recent call last):
+  ...
+TypeError: 'schema' is not a valid value in MessageTemplate
+(not a valid JSON schema).
+>>> t.update({'key': True})
+

+ +

This is also used in __init__:

+ +

>>> t = MessageTemplate({'key 1': {'const': 'value'},
+...                      'key 2': {'type': 'string'},
+...                      'key 3': {'type': 'object',
+...                                'properties': {
+...                                    'key 1': {'type': 'number'},
+...                                    'key 2': True}}})
+>>> print(t)  # doctest: +NORMALIZE_WHITESPACE
+{'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
+ 'key 3': {'type': 'object',
+           'properties': {'key 1': {'type': 'number'},
+                          'key 2': True}}}
+>>> t = MessageTemplate({42: {'const': 'int key'}})
+Traceback (most recent call last):
+  ...
+TypeError: '42' is not a valid key in MessageTemplate (not a string).
+>>> t = MessageTemplate({'key': 'schema'})
+... # doctest: +NORMALIZE_WHITESPACE
+Traceback (most recent call last):
+  ...
+TypeError: 'schema' is not a valid value in MessageTemplate
+(not a valid JSON schema).
+>>> t = MessageTemplate({'key': True})
+

+ + +

+ +

+ +

565    def setdefault(self, key: str, value: Optional[JSONSchema] = None) -> JSONSchema:
+566        """Override setdefault to use validity checks.
+567
+568        >>> t = MessageTemplate()
+569        >>> t.setdefault('key 1', {'const': 'value'})
+570        {'const': 'value'}
+571        >>> t.setdefault('key 2', {'type': 'string'})
+572        {'type': 'string'}
+573        >>> t.setdefault('key 3', {'type': 'object',
+574        ...                        'properties': {'key 1': {'type': 'number'},
+575        ...                                       'key 2': True}})
+576        ... # doctest: +NORMALIZE_WHITESPACE
+577        {'type': 'object',
+578                   'properties': {'key 1': {'type': 'number'},
+579                                  'key 2': True}}
+580        >>> t.setdefault(42, {'const': 'int key'})
+581        Traceback (most recent call last):
+582          ...
+583        TypeError: '42' is not a valid key in MessageTemplate (not a string).
+584        >>> t.setdefault('key', 'schema')  # doctest: +NORMALIZE_WHITESPACE
+585        Traceback (most recent call last):
+586          ...
+587        TypeError: 'schema' is not a valid value in MessageTemplate
+588        (not a valid JSON schema).
+589
+590        But __setitem__ is not called if the key is already present:
+591        >>> t.setdefault('key 1', 'schema')
+592        {'const': 'value'}
+593        """
+594        if key not in self:
+595            if value is not None:
+596                self[key] = value
+597            else:
+598                self[key] = True
+599        return self[key]
+

+ + +

Override setdefault to use validity checks.

+ +

>>> t = MessageTemplate()
+>>> t.setdefault('key 1', {'const': 'value'})
+{'const': 'value'}
+>>> t.setdefault('key 2', {'type': 'string'})
+{'type': 'string'}
+>>> t.setdefault('key 3', {'type': 'object',
+...                        'properties': {'key 1': {'type': 'number'},
+...                                       'key 2': True}})
+... # doctest: +NORMALIZE_WHITESPACE
+{'type': 'object',
+           'properties': {'key 1': {'type': 'number'},
+                          'key 2': True}}
+>>> t.setdefault(42, {'const': 'int key'})
+Traceback (most recent call last):
+  ...
+TypeError: '42' is not a valid key in MessageTemplate (not a string).
+>>> t.setdefault('key', 'schema')  # doctest: +NORMALIZE_WHITESPACE
+Traceback (most recent call last):
+  ...
+TypeError: 'schema' is not a valid value in MessageTemplate
+(not a valid JSON schema).
+

+ +

But __setitem__ is not called if the key is already present:

+ +

>>> t.setdefault('key 1', 'schema')
+{'const': 'value'}
+

+ + +

+ +

+ + def + check(self, message: Message) -> bool: + + View Source + +

+ +

601    def check(self, message: Message) -> bool:
+602        """Check message against this template.
+603
+604        Constant values have to match exactly:
+605        >>> t = MessageTemplate({'key': {'const': 'value'}})
+606        >>> t.check(Message('Example Sender', {'key': 'value'}))
+607        True
+608        >>> t.check(Message('Example Sender', {'key': 'other value'}))
+609        False
+610
+611        But for integers, floats with the same value are also valid:
+612        >>> t = MessageTemplate({'key': {'const': 42}})
+613        >>> t.check(Message('Example Sender', {'key': 42}))
+614        True
+615        >>> t.check(Message('Example Sender', {'key': 42.0}))
+616        True
+617
+618        Type integer is valid for floats with zero fractional part, but
+619        not by floats with non-zero fractional part:
+620        >>> t = MessageTemplate({'key': {'type': 'integer'}})
+621        >>> t.check(Message('Example Sender', {'key': 42}))
+622        True
+623        >>> t.check(Message('Example Sender', {'key': 42.0}))
+624        True
+625        >>> t.check(Message('Example Sender', {'key': 42.42}))
+626        False
+627
+628        Type number is valid for arbitrary ints or floats:
+629        >>> t = MessageTemplate({'key': {'type': 'number'}})
+630        >>> t.check(Message('Example Sender', {'key': 42}))
+631        True
+632        >>> t.check(Message('Example Sender', {'key': 42.42}))
+633        True
+634
+635        All keys in template have to be present in message:
+636        >>> t = MessageTemplate({'key 1': {'const': 'value'},
+637        ...                      'key 2': {'type': 'string'},
+638        ...                      'key 3': {'type': 'object',
+639        ...                                'properties': {
+640        ...                                    'key 1': {'type': 'number'},
+641        ...                                    'key 2': True,
+642        ...                                    'key 3': False}}})
+643        >>> t.check(Message('Example Sender',
+644        ...                 {'key 1': 'value', 'key 2': 'some string'}))
+645        False
+646
+647        But for nested objects their properties do not necessarily have
+648        to be present:
+649        >>> t.check(Message('Example Sender',
+650        ...                 {'key 1': 'value', 'key 2': 'some string',
+651        ...                  'key 3': {'key 1': 42}}))
+652        True
+653
+654        Schema True matches everything (even None):
+655        >>> t.check(Message('Example Sender',
+656        ...                 {'key 1': 'value', 'key 2': 'some string',
+657        ...                  'key 3': {'key 2': None}}))
+658        True
+659
+660        Schema False matches nothing:
+661        >>> t.check(Message('Example Sender',
+662        ...                 {'key 1': 'value', 'key 2': 'some string',
+663        ...                  'key 3': {'key 3': True}}))
+664        False
+665
+666        Message is valid for the constant template created from it:
+667        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
+668        ...                                'list': [None, True, 'string']})
+669        >>> t = MessageTemplate.from_message(m)
+670        >>> t.check(m)
+671        True
+672        """
+673        for key in self:
+674            if key not in message:
+675                return False
+676            else:
+677                schema_string = json.dumps(self[key])
+678                if not validate(schema_string, message[key]):
+679                    return False
+680        return True
+

+ + +

Check message against this template.

+ +

Constant values have to match exactly:

+ +

>>> t = MessageTemplate({'key': {'const': 'value'}})
+>>> t.check(Message('Example Sender', {'key': 'value'}))
+True
+>>> t.check(Message('Example Sender', {'key': 'other value'}))
+False
+

+ +

But for integers, floats with the same value are also valid:

+ +

>>> t = MessageTemplate({'key': {'const': 42}})
+>>> t.check(Message('Example Sender', {'key': 42}))
+True
+>>> t.check(Message('Example Sender', {'key': 42.0}))
+True
+

+ +

Type integer is valid for floats with zero fractional part, but +not by floats with non-zero fractional part:

+ +

>>> t = MessageTemplate({'key': {'type': 'integer'}})
+>>> t.check(Message('Example Sender', {'key': 42}))
+True
+>>> t.check(Message('Example Sender', {'key': 42.0}))
+True
+>>> t.check(Message('Example Sender', {'key': 42.42}))
+False
+

+ +

Type number is valid for arbitrary ints or floats:

+ +

>>> t = MessageTemplate({'key': {'type': 'number'}})
+>>> t.check(Message('Example Sender', {'key': 42}))
+True
+>>> t.check(Message('Example Sender', {'key': 42.42}))
+True
+

+ +

All keys in template have to be present in message:

+ +

>>> t = MessageTemplate({'key 1': {'const': 'value'},
+...                      'key 2': {'type': 'string'},
+...                      'key 3': {'type': 'object',
+...                                'properties': {
+...                                    'key 1': {'type': 'number'},
+...                                    'key 2': True,
+...                                    'key 3': False}}})
+>>> t.check(Message('Example Sender',
+...                 {'key 1': 'value', 'key 2': 'some string'}))
+False
+

+ +

But for nested objects their properties do not necessarily have +to be present:

+ +

>>> t.check(Message('Example Sender',
+...                 {'key 1': 'value', 'key 2': 'some string',
+...                  'key 3': {'key 1': 42}}))
+True
+

+ +

Schema True matches everything (even None):

+ +

>>> t.check(Message('Example Sender',
+...                 {'key 1': 'value', 'key 2': 'some string',
+...                  'key 3': {'key 2': None}}))
+True
+

+ +

Schema False matches nothing:

+ +

>>> t.check(Message('Example Sender',
+...                 {'key 1': 'value', 'key 2': 'some string',
+...                  'key 3': {'key 3': True}}))
+False
+

+ +

Message is valid for the constant template created from it:

+ +

>>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
+...                                'list': [None, True, 'string']})
+>>> t = MessageTemplate.from_message(m)
+>>> t.check(m)
+True
+

+ + +

+ +

+ + class + TemplateRegistry: + + View Source + +

+ +

 683class TemplateRegistry:
+ 684    """Manage a collection of message templates with registered clients.
+ 685
+ 686    A new TemplateRegistry is created by:
+ 687    >>> r = TemplateRegistry()
+ 688
+ 689    Client names (strings) can be registered for message templates, which
+ 690    are mappings from keys to JSON schemas:
+ 691    >>> r.insert({'k1': {'const': 'v1'}}, 'C 1')
+ 692
+ 693    The check function checks if the templates registered for a client
+ 694    match a given message:
+ 695    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 696    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 697    ...     print(f"{m}: {r.check('C 1', m)}")
+ 698    {'k1': 'v1', 'k2': 'v1'}: True
+ 699    {'k1': 'v1', 'k2': 2}: True
+ 700    {'k1': 'v2', 'k2': 'v1'}: False
+ 701    {'k1': 'v2', 'k2': 2}: False
+ 702
+ 703    Clients can be registered for values validating against arbitrary JSON
+ 704    schemas, e.g. all values of a certain type:
+ 705    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}, 'C 2')
+ 706    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 707    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 708    ...     print(f"{m}: {r.check('C 2', m)}")
+ 709    {'k1': 'v1', 'k2': 'v1'}: False
+ 710    {'k1': 'v1', 'k2': 2}: False
+ 711    {'k1': 'v2', 'k2': 'v1'}: True
+ 712    {'k1': 'v2', 'k2': 2}: False
+ 713    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}, 'C 3')
+ 714    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 715    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 716    ...     print(f"{m}: {r.check('C 3', m)}")
+ 717    {'k1': 'v1', 'k2': 'v1'}: False
+ 718    {'k1': 'v1', 'k2': 2}: False
+ 719    {'k1': 'v2', 'k2': 'v1'}: False
+ 720    {'k1': 'v2', 'k2': 2}: True
+ 721
+ 722    The order of key-value pairs does not have to match the order in the
+ 723    messages and keys can be left out:
+ 724    >>> r.insert({'k2': {'const': 2}}, 'C 4')
+ 725    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 726    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 727    ...     print(f"{m}: {r.check('C 4', m)}")
+ 728    {'k1': 'v1', 'k2': 'v1'}: False
+ 729    {'k1': 'v1', 'k2': 2}: True
+ 730    {'k1': 'v2', 'k2': 'v1'}: False
+ 731    {'k1': 'v2', 'k2': 2}: True
+ 732
+ 733    A registration for an empty template matches all messages:
+ 734    >>> r.insert({}, 'C 5')
+ 735    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 736    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 737    ...     print(f"{m}: {r.check('C 5', m)}")
+ 738    {'k1': 'v1', 'k2': 'v1'}: True
+ 739    {'k1': 'v1', 'k2': 2}: True
+ 740    {'k1': 'v2', 'k2': 'v1'}: True
+ 741    {'k1': 'v2', 'k2': 2}: True
+ 742
+ 743    A client can be registered for multiple templates:
+ 744    >>> r.insert({'k1': {'const': 'v1'}}, 'C 6')
+ 745    >>> r.insert({'k2': {'const': 'v1'}}, 'C 6')
+ 746    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 747    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 748    ...     print(f"{m}: {r.check('C 6', m)}")
+ 749    {'k1': 'v1', 'k2': 'v1'}: True
+ 750    {'k1': 'v1', 'k2': 2}: True
+ 751    {'k1': 'v2', 'k2': 'v1'}: True
+ 752    {'k1': 'v2', 'k2': 2}: False
+ 753
+ 754    Clients can be deregistered again (the result is False if the registry
+ 755    is empty after the deletion):
+ 756    >>> r.insert({'k1': {'const': 'v1'}}, 'C 7')
+ 757    >>> r.delete('C 7')
+ 758    True
+ 759    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 760    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 761    ...     print(f"{m}: {r.check('C 7', m)}")
+ 762    {'k1': 'v1', 'k2': 'v1'}: False
+ 763    {'k1': 'v1', 'k2': 2}: False
+ 764    {'k1': 'v2', 'k2': 'v1'}: False
+ 765    {'k1': 'v2', 'k2': 2}: False
+ 766
+ 767    The get function returns all clients with registered templates matching
+ 768    a given message:
+ 769    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 770    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 771    ...     print(f"{m}: {r.get(m)}")
+ 772    {'k1': 'v1', 'k2': 'v1'}: ['C 5', 'C 1', 'C 6']
+ 773    {'k1': 'v1', 'k2': 2}: ['C 5', 'C 1', 'C 6', 'C 4']
+ 774    {'k1': 'v2', 'k2': 'v1'}: ['C 5', 'C 2', 'C 6']
+ 775    {'k1': 'v2', 'k2': 2}: ['C 5', 'C 3', 'C 4']
+ 776
+ 777    The get_templates function returns all templates for a given client:
+ 778    >>> for c in ['C 1', 'C 2', 'C 3', 'C 4', 'C 5', 'C 6']:
+ 779    ...     print(f"{c}: {r.get_templates(c)}")
+ 780    C 1: [{'k1': {'const': 'v1'}}]
+ 781    C 2: [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
+ 782    C 3: [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
+ 783    C 4: [{'k2': {'const': 2}}]
+ 784    C 5: [{}]
+ 785    C 6: [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
+ 786    """
+ 787
+ 788    def __init__(self) -> None:
+ 789        """Initialise an empty registry.
+ 790
+ 791        >>> r = TemplateRegistry()
+ 792        """
+ 793        self._clients: List[str] = []
+ 794        self._callbacks: Dict[str, List[MessageCallback]] = {}
+ 795        self._constants: Dict[str, Dict[str, TemplateRegistry]] = {}
+ 796        # First key is the message key, second key is the constant string
+ 797        self._schemas: Dict[str, Dict[str, TemplateRegistry]] = {}
+ 798        # First key is the message key, second key is the JSON schema string
+ 799        self._templates: Dict[str, List[MessageTemplate]] = {}
+ 800
+ 801    def insert(
+ 802        self,
+ 803        template: MessageTemplate,
+ 804        client: str,
+ 805        callback: Optional[MessageCallback] = None,
+ 806    ) -> None:
+ 807        """Register a client for a template.
+ 808
+ 809        >>> r = TemplateRegistry()
+ 810        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'integer'}}, 'C 1')
+ 811        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'string'}}, 'C 2')
+ 812        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v1'}}, 'C 3')
+ 813        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v2'}}, 'C 4')
+ 814        >>> r.insert({}, 'C 5')
+ 815        """
+ 816        if client not in self._templates:
+ 817            self._templates[client] = []
+ 818        self._templates[client].append(template)
+ 819        if not template:
+ 820            self._clients.append(client)
+ 821            if callback:
+ 822                if client not in self._callbacks:
+ 823                    self._callbacks[client] = []
+ 824                self._callbacks[client].append(callback)
+ 825        else:
+ 826            key, schema = next(iter(template.items()))
+ 827            reduced_template = MessageTemplate(
+ 828                {k: template[k] for k in template if k != key}
+ 829            )
+ 830            if (
+ 831                isinstance(schema, dict)
+ 832                and len(schema) == 1
+ 833                and "const" in schema
+ 834                and isinstance(schema["const"], str)
+ 835            ):
+ 836                value = schema["const"]
+ 837                if key not in self._constants:
+ 838                    self._constants[key] = {}
+ 839                if value not in self._constants[key]:
+ 840                    self._constants[key][value] = TemplateRegistry()
+ 841                self._constants[key][value].insert(reduced_template, client, callback)
+ 842            else:
+ 843                schema_string = json.dumps(schema)
+ 844                if key not in self._schemas:
+ 845                    self._schemas[key] = {}
+ 846                if schema_string not in self._schemas[key]:
+ 847                    self._schemas[key][schema_string] = TemplateRegistry()
+ 848                self._schemas[key][schema_string].insert(
+ 849                    reduced_template, client, callback
+ 850                )
+ 851
+ 852    def delete(self, client: str) -> bool:
+ 853        """Unregister a client from all templates.
+ 854
+ 855        >>> r = TemplateRegistry()
+ 856        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'integer'}}, 'C 1')
+ 857        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'string'}}, 'C 2')
+ 858        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v1'}}, 'C 3')
+ 859        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v2'}}, 'C 4')
+ 860        >>> r.insert({}, 'C 5')
+ 861        >>> r.delete('C 3')
+ 862        True
+ 863        >>> r.delete('C 4')
+ 864        True
+ 865        """
+ 866        if client in self._templates:
+ 867            del self._templates[client]
+ 868        self._clients = [c for c in self._clients if c != client]
+ 869        if client in self._callbacks:
+ 870            del self._callbacks[client]
+ 871        new_constants: Dict[str, Dict[str, TemplateRegistry]] = {}
+ 872        for key in self._constants:
+ 873            new_constants[key] = {}
+ 874            for value in self._constants[key]:
+ 875                if self._constants[key][value].delete(client):
+ 876                    new_constants[key][value] = self._constants[key][value]
+ 877            if not new_constants[key]:
+ 878                del new_constants[key]
+ 879        self._constants = new_constants
+ 880        new_schemas: Dict[str, Dict[str, TemplateRegistry]] = {}
+ 881        for key in self._schemas:
+ 882            new_schemas[key] = {}
+ 883            for schema in self._schemas[key]:
+ 884                if self._schemas[key][schema].delete(client):
+ 885                    new_schemas[key][schema] = self._schemas[key][schema]
+ 886            if not new_schemas[key]:
+ 887                del new_schemas[key]
+ 888        self._schemas = new_schemas
+ 889        if self._clients or self._callbacks or self._constants or self._schemas:
+ 890            return True
+ 891        return False
+ 892
+ 893    def check(self, client: str, message: Message) -> bool:
+ 894        """Get if a client has a registered template matching a message.
+ 895
+ 896        >>> r = TemplateRegistry()
+ 897        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+ 898        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 899        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 900        ...     print(f"{m}: {r.check('Client 1', m)}")
+ 901        {'k1': 'v1', 'k2': 'v1'}: True
+ 902        {'k1': 'v1', 'k2': 2}: True
+ 903        {'k1': 'v2', 'k2': 'v1'}: False
+ 904        {'k1': 'v2', 'k2': 2}: False
+ 905        >>> r.insert({'k2': {'type': 'integer'}}, 'Client 2')
+ 906        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 907        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 908        ...     print(f"{m}: {r.check('Client 2', m)}")
+ 909        {'k1': 'v1', 'k2': 'v1'}: False
+ 910        {'k1': 'v1', 'k2': 2}: True
+ 911        {'k1': 'v2', 'k2': 'v1'}: False
+ 912        {'k1': 'v2', 'k2': 2}: True
+ 913        """
+ 914        if client in self._clients:
+ 915            return True
+ 916        for key in self._constants:
+ 917            if (
+ 918                key in message
+ 919                and isinstance(message[key], str)
+ 920                and message[key] in self._constants[key]
+ 921            ):
+ 922                value = message[key]
+ 923                assert isinstance(value, str)
+ 924                child = self._constants[key][value]
+ 925                if child.check(client, message):
+ 926                    return True
+ 927        for key in self._schemas:
+ 928            if key in message:
+ 929                for schema_string in self._schemas[key]:
+ 930                    if validate(schema_string, message[key]):
+ 931                        child = self._schemas[key][schema_string]
+ 932                        if child.check(client, message):
+ 933                            return True
+ 934        return False
+ 935
+ 936    def get(self, message: Message) -> List[str]:
+ 937        """Get all clients registered for templates matching a message.
+ 938
+ 939        >>> r = TemplateRegistry()
+ 940        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+ 941        >>> r.insert({'k2': {'type': 'integer'}}, 'Client 2')
+ 942        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+ 943        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+ 944        ...     print(f"{m}: {r.get(m)}")
+ 945        {'k1': 'v1', 'k2': 'v1'}: ['Client 1']
+ 946        {'k1': 'v1', 'k2': 2}: ['Client 1', 'Client 2']
+ 947        {'k1': 'v2', 'k2': 'v1'}: []
+ 948        {'k1': 'v2', 'k2': 2}: ['Client 2']
+ 949        """
+ 950        result = []
+ 951        for client in self._clients:
+ 952            if client not in result:
+ 953                result.append(client)
+ 954        for key in self._constants:
+ 955            if (
+ 956                key in message
+ 957                and isinstance(message[key], str)
+ 958                and message[key] in self._constants[key]
+ 959            ):
+ 960                value = message[key]
+ 961                assert isinstance(value, str)
+ 962                child = self._constants[key][value]
+ 963                for client in child.get(message):
+ 964                    if client not in result:
+ 965                        result.append(client)
+ 966        for key in self._schemas:
+ 967            if key in message:
+ 968                for schema_string in self._schemas[key]:
+ 969                    if validate(schema_string, message[key]):
+ 970                        child = self._schemas[key][schema_string]
+ 971                        for client in child.get(message):
+ 972                            if client not in result:
+ 973                                result.append(client)
+ 974        return result
+ 975
+ 976    def get_callbacks(self, message: Message) -> List[MessageCallback]:
+ 977        """Get all callbacks registered for templates matching a message."""
+ 978        result = []
+ 979        for client in self._callbacks:
+ 980            for callback in self._callbacks[client]:
+ 981                if callback not in result:
+ 982                    result.append(callback)
+ 983        for key in self._constants:
+ 984            if (
+ 985                key in message
+ 986                and isinstance(message[key], str)
+ 987                and message[key] in self._constants[key]
+ 988            ):
+ 989                value = message[key]
+ 990                assert isinstance(value, str)
+ 991                child = self._constants[key][value]
+ 992                for callback in child.get_callbacks(message):
+ 993                    if callback not in result:
+ 994                        result.append(callback)
+ 995        for key in self._schemas:
+ 996            if key in message:
+ 997                for schema_string in self._schemas[key]:
+ 998                    if validate(schema_string, message[key]):
+ 999                        child = self._schemas[key][schema_string]
+1000                        for callback in child.get_callbacks(message):
+1001                            if callback not in result:
+1002                                result.append(callback)
+1003        return result
+1004
+1005    def get_templates(self, client: str) -> List[MessageTemplate]:
+1006        """Get all templates for a client.
+1007
+1008        >>> r = TemplateRegistry()
+1009        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+1010        >>> r.get_templates('Client 1')
+1011        [{'k1': {'const': 'v1'}}]
+1012        >>> r.insert({'k1': {'const': 'v2'},
+1013        ...           'k2': {'type': 'string'}}, 'Client 2')
+1014        >>> r.get_templates('Client 2')
+1015        [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
+1016        >>> r.insert({'k1': {'const': 'v2'},
+1017        ...           'k2': {'type': 'integer'}}, 'Client 3')
+1018        >>> r.get_templates('Client 3')
+1019        [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
+1020        >>> r.insert({'k2': {'const': 2}}, 'Client 4')
+1021        >>> r.get_templates('Client 4')
+1022        [{'k2': {'const': 2}}]
+1023        >>> r.insert({}, 'Client 5')
+1024        >>> r.get_templates('Client 5')
+1025        [{}]
+1026        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 6')
+1027        >>> r.insert({'k2': {'const': 'v1'}}, 'Client 6')
+1028        >>> r.get_templates('Client 6')
+1029        [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
+1030        """
+1031        if client in self._templates:
+1032            return self._templates[client]
+1033        return []
+

+ + +

Manage a collection of message templates with registered clients.

+ +

A new TemplateRegistry is created by:

+ +

>>> r = TemplateRegistry()
+

+ +

Client names (strings) can be registered for message templates, which +are mappings from keys to JSON schemas:

+ +

>>> r.insert({'k1': {'const': 'v1'}}, 'C 1')
+

+ +

The check function checks if the templates registered for a client +match a given message:

+ +

>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('C 1', m)}")
+{'k1': 'v1', 'k2': 'v1'}: True
+{'k1': 'v1', 'k2': 2}: True
+{'k1': 'v2', 'k2': 'v1'}: False
+{'k1': 'v2', 'k2': 2}: False
+

+ +

Clients can be registered for values validating against arbitrary JSON +schemas, e.g. all values of a certain type:

+ +

>>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}, 'C 2')
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('C 2', m)}")
+{'k1': 'v1', 'k2': 'v1'}: False
+{'k1': 'v1', 'k2': 2}: False
+{'k1': 'v2', 'k2': 'v1'}: True
+{'k1': 'v2', 'k2': 2}: False
+>>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}, 'C 3')
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('C 3', m)}")
+{'k1': 'v1', 'k2': 'v1'}: False
+{'k1': 'v1', 'k2': 2}: False
+{'k1': 'v2', 'k2': 'v1'}: False
+{'k1': 'v2', 'k2': 2}: True
+

+ +

The order of key-value pairs does not have to match the order in the +messages and keys can be left out:

+ +

>>> r.insert({'k2': {'const': 2}}, 'C 4')
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('C 4', m)}")
+{'k1': 'v1', 'k2': 'v1'}: False
+{'k1': 'v1', 'k2': 2}: True
+{'k1': 'v2', 'k2': 'v1'}: False
+{'k1': 'v2', 'k2': 2}: True
+

+ +

A registration for an empty template matches all messages:

+ +

>>> r.insert({}, 'C 5')
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('C 5', m)}")
+{'k1': 'v1', 'k2': 'v1'}: True
+{'k1': 'v1', 'k2': 2}: True
+{'k1': 'v2', 'k2': 'v1'}: True
+{'k1': 'v2', 'k2': 2}: True
+

+ +

A client can be registered for multiple templates:

+ +

>>> r.insert({'k1': {'const': 'v1'}}, 'C 6')
+>>> r.insert({'k2': {'const': 'v1'}}, 'C 6')
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('C 6', m)}")
+{'k1': 'v1', 'k2': 'v1'}: True
+{'k1': 'v1', 'k2': 2}: True
+{'k1': 'v2', 'k2': 'v1'}: True
+{'k1': 'v2', 'k2': 2}: False
+

+ +

Clients can be deregistered again (the result is False if the registry +is empty after the deletion):

+ +

>>> r.insert({'k1': {'const': 'v1'}}, 'C 7')
+>>> r.delete('C 7')
+True
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('C 7', m)}")
+{'k1': 'v1', 'k2': 'v1'}: False
+{'k1': 'v1', 'k2': 2}: False
+{'k1': 'v2', 'k2': 'v1'}: False
+{'k1': 'v2', 'k2': 2}: False
+

+ +

The get function returns all clients with registered templates matching +a given message:

+ +

>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.get(m)}")
+{'k1': 'v1', 'k2': 'v1'}: ['C 5', 'C 1', 'C 6']
+{'k1': 'v1', 'k2': 2}: ['C 5', 'C 1', 'C 6', 'C 4']
+{'k1': 'v2', 'k2': 'v1'}: ['C 5', 'C 2', 'C 6']
+{'k1': 'v2', 'k2': 2}: ['C 5', 'C 3', 'C 4']
+

+ +

The get_templates function returns all templates for a given client:

+ +

>>> for c in ['C 1', 'C 2', 'C 3', 'C 4', 'C 5', 'C 6']:
+...     print(f"{c}: {r.get_templates(c)}")
+C 1: [{'k1': {'const': 'v1'}}]
+C 2: [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
+C 3: [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
+C 4: [{'k2': {'const': 2}}]
+C 5: [{}]
+C 6: [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
+

+ + +

+ +

+ + TemplateRegistry() + + View Source + +

+ +

788    def __init__(self) -> None:
+789        """Initialise an empty registry.
+790
+791        >>> r = TemplateRegistry()
+792        """
+793        self._clients: List[str] = []
+794        self._callbacks: Dict[str, List[MessageCallback]] = {}
+795        self._constants: Dict[str, Dict[str, TemplateRegistry]] = {}
+796        # First key is the message key, second key is the constant string
+797        self._schemas: Dict[str, Dict[str, TemplateRegistry]] = {}
+798        # First key is the message key, second key is the JSON schema string
+799        self._templates: Dict[str, List[MessageTemplate]] = {}
+

+ + +

Initialise an empty registry.

+ +

>>> r = TemplateRegistry()
+

+ + +

+ +

+ + def + insert( self, template: MessageTemplate, client: str, callback: Callable[[Message], Coroutine[Any, Any, NoneType]] | None = None) -> None: + + View Source + +

+ +

801    def insert(
+802        self,
+803        template: MessageTemplate,
+804        client: str,
+805        callback: Optional[MessageCallback] = None,
+806    ) -> None:
+807        """Register a client for a template.
+808
+809        >>> r = TemplateRegistry()
+810        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'integer'}}, 'C 1')
+811        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'string'}}, 'C 2')
+812        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v1'}}, 'C 3')
+813        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v2'}}, 'C 4')
+814        >>> r.insert({}, 'C 5')
+815        """
+816        if client not in self._templates:
+817            self._templates[client] = []
+818        self._templates[client].append(template)
+819        if not template:
+820            self._clients.append(client)
+821            if callback:
+822                if client not in self._callbacks:
+823                    self._callbacks[client] = []
+824                self._callbacks[client].append(callback)
+825        else:
+826            key, schema = next(iter(template.items()))
+827            reduced_template = MessageTemplate(
+828                {k: template[k] for k in template if k != key}
+829            )
+830            if (
+831                isinstance(schema, dict)
+832                and len(schema) == 1
+833                and "const" in schema
+834                and isinstance(schema["const"], str)
+835            ):
+836                value = schema["const"]
+837                if key not in self._constants:
+838                    self._constants[key] = {}
+839                if value not in self._constants[key]:
+840                    self._constants[key][value] = TemplateRegistry()
+841                self._constants[key][value].insert(reduced_template, client, callback)
+842            else:
+843                schema_string = json.dumps(schema)
+844                if key not in self._schemas:
+845                    self._schemas[key] = {}
+846                if schema_string not in self._schemas[key]:
+847                    self._schemas[key][schema_string] = TemplateRegistry()
+848                self._schemas[key][schema_string].insert(
+849                    reduced_template, client, callback
+850                )
+

+ + +

+ +

>>> r = TemplateRegistry()
+>>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'integer'}}, 'C 1')
+>>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'string'}}, 'C 2')
+>>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v1'}}, 'C 3')
+>>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v2'}}, 'C 4')
+>>> r.insert({}, 'C 5')
+

+ + +

+ +

+ + def + delete(self, client: str) -> bool: + + View Source + +

+ +

852    def delete(self, client: str) -> bool:
+853        """Unregister a client from all templates.
+854
+855        >>> r = TemplateRegistry()
+856        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'integer'}}, 'C 1')
+857        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'string'}}, 'C 2')
+858        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v1'}}, 'C 3')
+859        >>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v2'}}, 'C 4')
+860        >>> r.insert({}, 'C 5')
+861        >>> r.delete('C 3')
+862        True
+863        >>> r.delete('C 4')
+864        True
+865        """
+866        if client in self._templates:
+867            del self._templates[client]
+868        self._clients = [c for c in self._clients if c != client]
+869        if client in self._callbacks:
+870            del self._callbacks[client]
+871        new_constants: Dict[str, Dict[str, TemplateRegistry]] = {}
+872        for key in self._constants:
+873            new_constants[key] = {}
+874            for value in self._constants[key]:
+875                if self._constants[key][value].delete(client):
+876                    new_constants[key][value] = self._constants[key][value]
+877            if not new_constants[key]:
+878                del new_constants[key]
+879        self._constants = new_constants
+880        new_schemas: Dict[str, Dict[str, TemplateRegistry]] = {}
+881        for key in self._schemas:
+882            new_schemas[key] = {}
+883            for schema in self._schemas[key]:
+884                if self._schemas[key][schema].delete(client):
+885                    new_schemas[key][schema] = self._schemas[key][schema]
+886            if not new_schemas[key]:
+887                del new_schemas[key]
+888        self._schemas = new_schemas
+889        if self._clients or self._callbacks or self._constants or self._schemas:
+890            return True
+891        return False
+

+ + +

Unregister a client from all templates.

+ +

>>> r = TemplateRegistry()
+>>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'integer'}}, 'C 1')
+>>> r.insert({'k1': {'const': 'v1'}, 'k2': {'type': 'string'}}, 'C 2')
+>>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v1'}}, 'C 3')
+>>> r.insert({'k1': {'type': 'integer'}, 'k2': {'const': 'v2'}}, 'C 4')
+>>> r.insert({}, 'C 5')
+>>> r.delete('C 3')
+True
+>>> r.delete('C 4')
+True
+

+ + +

+ +

+ + def + check(self, client: str, message: Message) -> bool: + + View Source + +

+ +

893    def check(self, client: str, message: Message) -> bool:
+894        """Get if a client has a registered template matching a message.
+895
+896        >>> r = TemplateRegistry()
+897        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+898        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+899        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+900        ...     print(f"{m}: {r.check('Client 1', m)}")
+901        {'k1': 'v1', 'k2': 'v1'}: True
+902        {'k1': 'v1', 'k2': 2}: True
+903        {'k1': 'v2', 'k2': 'v1'}: False
+904        {'k1': 'v2', 'k2': 2}: False
+905        >>> r.insert({'k2': {'type': 'integer'}}, 'Client 2')
+906        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+907        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+908        ...     print(f"{m}: {r.check('Client 2', m)}")
+909        {'k1': 'v1', 'k2': 'v1'}: False
+910        {'k1': 'v1', 'k2': 2}: True
+911        {'k1': 'v2', 'k2': 'v1'}: False
+912        {'k1': 'v2', 'k2': 2}: True
+913        """
+914        if client in self._clients:
+915            return True
+916        for key in self._constants:
+917            if (
+918                key in message
+919                and isinstance(message[key], str)
+920                and message[key] in self._constants[key]
+921            ):
+922                value = message[key]
+923                assert isinstance(value, str)
+924                child = self._constants[key][value]
+925                if child.check(client, message):
+926                    return True
+927        for key in self._schemas:
+928            if key in message:
+929                for schema_string in self._schemas[key]:
+930                    if validate(schema_string, message[key]):
+931                        child = self._schemas[key][schema_string]
+932                        if child.check(client, message):
+933                            return True
+934        return False
+

+ + +

Get if a client has a registered template matching a message.

+ +

>>> r = TemplateRegistry()
+>>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('Client 1', m)}")
+{'k1': 'v1', 'k2': 'v1'}: True
+{'k1': 'v1', 'k2': 2}: True
+{'k1': 'v2', 'k2': 'v1'}: False
+{'k1': 'v2', 'k2': 2}: False
+>>> r.insert({'k2': {'type': 'integer'}}, 'Client 2')
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.check('Client 2', m)}")
+{'k1': 'v1', 'k2': 'v1'}: False
+{'k1': 'v1', 'k2': 2}: True
+{'k1': 'v2', 'k2': 'v1'}: False
+{'k1': 'v2', 'k2': 2}: True
+

+ + +

+ +

+ + def + get(self, message: Message) -> List[str]: + + View Source + +

+ +

936    def get(self, message: Message) -> List[str]:
+937        """Get all clients registered for templates matching a message.
+938
+939        >>> r = TemplateRegistry()
+940        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+941        >>> r.insert({'k2': {'type': 'integer'}}, 'Client 2')
+942        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+943        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+944        ...     print(f"{m}: {r.get(m)}")
+945        {'k1': 'v1', 'k2': 'v1'}: ['Client 1']
+946        {'k1': 'v1', 'k2': 2}: ['Client 1', 'Client 2']
+947        {'k1': 'v2', 'k2': 'v1'}: []
+948        {'k1': 'v2', 'k2': 2}: ['Client 2']
+949        """
+950        result = []
+951        for client in self._clients:
+952            if client not in result:
+953                result.append(client)
+954        for key in self._constants:
+955            if (
+956                key in message
+957                and isinstance(message[key], str)
+958                and message[key] in self._constants[key]
+959            ):
+960                value = message[key]
+961                assert isinstance(value, str)
+962                child = self._constants[key][value]
+963                for client in child.get(message):
+964                    if client not in result:
+965                        result.append(client)
+966        for key in self._schemas:
+967            if key in message:
+968                for schema_string in self._schemas[key]:
+969                    if validate(schema_string, message[key]):
+970                        child = self._schemas[key][schema_string]
+971                        for client in child.get(message):
+972                            if client not in result:
+973                                result.append(client)
+974        return result
+

+ + +

Get all clients registered for templates matching a message.

+ +

>>> r = TemplateRegistry()
+>>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+>>> r.insert({'k2': {'type': 'integer'}}, 'Client 2')
+>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
+...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
+...     print(f"{m}: {r.get(m)}")
+{'k1': 'v1', 'k2': 'v1'}: ['Client 1']
+{'k1': 'v1', 'k2': 2}: ['Client 1', 'Client 2']
+{'k1': 'v2', 'k2': 'v1'}: []
+{'k1': 'v2', 'k2': 2}: ['Client 2']
+

+ + +

+ +

+ + def + get_callbacks( self, message: Message) -> List[Callable[[Message], Coroutine[Any, Any, NoneType]]]: + + View Source + +

+ +

 976    def get_callbacks(self, message: Message) -> List[MessageCallback]:
+ 977        """Get all callbacks registered for templates matching a message."""
+ 978        result = []
+ 979        for client in self._callbacks:
+ 980            for callback in self._callbacks[client]:
+ 981                if callback not in result:
+ 982                    result.append(callback)
+ 983        for key in self._constants:
+ 984            if (
+ 985                key in message
+ 986                and isinstance(message[key], str)
+ 987                and message[key] in self._constants[key]
+ 988            ):
+ 989                value = message[key]
+ 990                assert isinstance(value, str)
+ 991                child = self._constants[key][value]
+ 992                for callback in child.get_callbacks(message):
+ 993                    if callback not in result:
+ 994                        result.append(callback)
+ 995        for key in self._schemas:
+ 996            if key in message:
+ 997                for schema_string in self._schemas[key]:
+ 998                    if validate(schema_string, message[key]):
+ 999                        child = self._schemas[key][schema_string]
+1000                        for callback in child.get_callbacks(message):
+1001                            if callback not in result:
+1002                                result.append(callback)
+1003        return result
+

+ + +

Get all callbacks registered for templates matching a message.

+ + +

+ +

+ + def + get_templates(self, client: str) -> List[MessageTemplate]: + + View Source + +

+ +

1005    def get_templates(self, client: str) -> List[MessageTemplate]:
+1006        """Get all templates for a client.
+1007
+1008        >>> r = TemplateRegistry()
+1009        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+1010        >>> r.get_templates('Client 1')
+1011        [{'k1': {'const': 'v1'}}]
+1012        >>> r.insert({'k1': {'const': 'v2'},
+1013        ...           'k2': {'type': 'string'}}, 'Client 2')
+1014        >>> r.get_templates('Client 2')
+1015        [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
+1016        >>> r.insert({'k1': {'const': 'v2'},
+1017        ...           'k2': {'type': 'integer'}}, 'Client 3')
+1018        >>> r.get_templates('Client 3')
+1019        [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
+1020        >>> r.insert({'k2': {'const': 2}}, 'Client 4')
+1021        >>> r.get_templates('Client 4')
+1022        [{'k2': {'const': 2}}]
+1023        >>> r.insert({}, 'Client 5')
+1024        >>> r.get_templates('Client 5')
+1025        [{}]
+1026        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 6')
+1027        >>> r.insert({'k2': {'const': 'v1'}}, 'Client 6')
+1028        >>> r.get_templates('Client 6')
+1029        [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
+1030        """
+1031        if client in self._templates:
+1032            return self._templates[client]
+1033        return []
+

+ + +

Get all templates for a client.

+ +

>>> r = TemplateRegistry()
+>>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
+>>> r.get_templates('Client 1')
+[{'k1': {'const': 'v1'}}]
+>>> r.insert({'k1': {'const': 'v2'},
+...           'k2': {'type': 'string'}}, 'Client 2')
+>>> r.get_templates('Client 2')
+[{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
+>>> r.insert({'k1': {'const': 'v2'},
+...           'k2': {'type': 'integer'}}, 'Client 3')
+>>> r.get_templates('Client 3')
+[{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
+>>> r.insert({'k2': {'const': 2}}, 'Client 4')
+>>> r.get_templates('Client 4')
+[{'k2': {'const': 2}}]
+>>> r.insert({}, 'Client 5')
+>>> r.get_templates('Client 5')
+[{}]
+>>> r.insert({'k1': {'const': 'v1'}}, 'Client 6')
+>>> r.insert({'k2': {'const': 'v1'}}, 'Client 6')
+>>> r.get_templates('Client 6')
+[{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
+

+ + +

+ +

+ + class + BusException(builtins.Exception): + + View Source + +

+ +

1036class BusException(Exception):
+1037    """Raise for errors in using message bus."""
+

+ + +

Raise for errors in using message bus.

+ + +

+ +

+ + class + MessageBus: + + View Source + +

+ +

1040class MessageBus:
+1041    """Provide an asynchronous message bus.
+1042
+1043    The bus executes asynchronous callbacks for all messages to be received
+1044    by a client. We use a simple callback printing the message in all
+1045    examples:
+1046    >>> def callback_for_receiver(receiver):
+1047    ...     print(f"Creating callback for {receiver}.")
+1048    ...     async def callback(message):
+1049    ...         print(f"{receiver}: {message}")
+1050    ...     return callback
+1051
+1052    Clients can be registered at the bus with a name, lists of message
+1053    templates they want to use for sending and receiving and a callback
+1054    function for receiving. An empty list of templates means that the
+1055    client does not want to send or receive any messages, respectively.
+1056    A list with an empty template means that it wants to send arbitrary
+1057    or receive all messages, respectively:
+1058    >>> async def setup(bus):
+1059    ...     print("Setting up.")
+1060    ...     bus.register('Logger', 'Test Plugin',
+1061    ...                  [],
+1062    ...                  [([MessageTemplate({})],
+1063    ...                    callback_for_receiver('Logger'))])
+1064    ...     bus.register('Client 1', 'Test Plugin',
+1065    ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1066    ...                  [([MessageTemplate({'target':
+1067    ...                                      {'const': 'Client 1'}})],
+1068    ...                    callback_for_receiver('Client 1'))])
+1069    ...     bus.register('Client 2', 'Test Plugin',
+1070    ...                  [MessageTemplate({})],
+1071    ...                  [([MessageTemplate({'target':
+1072    ...                                      {'const': 'Client 2'}})],
+1073    ...                    callback_for_receiver('Client 2'))])
+1074
+1075    The bus itself is addressed by the empty string. It sends messages for
+1076    each registration and deregestration of a client with a key 'event' and
+1077    a value of 'registered' or 'unregistered', a key 'client' with the
+1078    client's name as value and for registrations also keys 'sends' and
+1079    'receives' with all templates registered for the client for sending and
+1080    receiving.
+1081
+1082    Clients can send to the bus with the send function. Each message has to
+1083    declare a sender. The send templates of that sender are checked for a
+1084    template matching the message. We cannot prevent arbitrary code from
+1085    impersonating any sender, but this should only be done in debugging or
+1086    management situations.
+1087
+1088    Messages that are intended for a specific client by convention have a
+1089    key 'target' with the target client's name as value. Such messages are
+1090    often commands to the client to do something, which is by convention
+1091    indicated by a key 'command' with a value that indicates what should be
+1092    done.
+1093
+1094    The bus, for example, reacts to a message with 'target': '' and
+1095    'command': 'get clients' by sending one message for each currently
+1096    registered with complete information about its registered send and
+1097    receive templates.
+1098
+1099    >>> async def send(bus):
+1100    ...     print("Sending messages.")
+1101    ...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
+1102    ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
+1103    ...     await bus.send({'sender': '', 'target': '',
+1104    ...                     'command': 'get clients'})
+1105
+1106    The run function executes the message bus forever. If we want to stop
+1107    it, we have to explicitly cancel the task:
+1108    >>> async def main():
+1109    ...     bus = MessageBus()
+1110    ...     await setup(bus)
+1111    ...     bus_task = asyncio.create_task(bus.run())
+1112    ...     await send(bus)
+1113    ...     await asyncio.sleep(0)
+1114    ...     bus_task.cancel()
+1115    ...     try:
+1116    ...         await bus_task
+1117    ...     except asyncio.exceptions.CancelledError:
+1118    ...         pass
+1119    >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+1120    Setting up.
+1121    Creating callback for Logger.
+1122    Creating callback for Client 1.
+1123    Creating callback for Client 2.
+1124    Sending messages.
+1125    Logger: {'sender': '', 'event': 'registered',
+1126             'client': 'Logger', 'plugin': 'Test Plugin',
+1127             'sends': [], 'receives': [{}]}
+1128    Logger: {'sender': '', 'event': 'registered',
+1129             'client': 'Client 1', 'plugin': 'Test Plugin',
+1130             'sends': [{'k1': {'type': 'string'}}],
+1131             'receives': [{'target': {'const': 'Client 1'}}]}
+1132    Logger: {'sender': '', 'event': 'registered',
+1133             'client': 'Client 2', 'plugin': 'Test Plugin',
+1134             'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
+1135    Logger: {'sender': 'Client 1', 'k1': 'Test'}
+1136    Logger: {'sender': 'Client 2', 'target': 'Client 1'}
+1137    Client 1: {'sender': 'Client 2', 'target': 'Client 1'}
+1138    Logger: {'sender': '', 'target': '', 'command': 'get clients'}
+1139    Logger: {'sender': '', 'client': 'Logger', 'plugin': 'Test Plugin',
+1140             'sends': [], 'receives': [{}]}
+1141    Logger: {'sender': '', 'client': 'Client 1', 'plugin': 'Test Plugin',
+1142             'sends': [{'k1': {'type': 'string'}}],
+1143             'receives': [{'target': {'const': 'Client 1'}}]}
+1144    Logger: {'sender': '', 'client': 'Client 2', 'plugin': 'Test Plugin',
+1145             'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
+1146    """
+1147
+1148    def __init__(self) -> None:
+1149        """Initialise a new bus without clients.
+1150
+1151        >>> async def main():
+1152        ...     bus = MessageBus()
+1153        >>> asyncio.run(main())
+1154        """
+1155        self._queue: asyncio.Queue = asyncio.Queue()
+1156        self._plugins: Dict[str, str] = {}
+1157        self._send_reg: TemplateRegistry = TemplateRegistry()
+1158        self._recv_reg: TemplateRegistry = TemplateRegistry()
+1159
+1160    def register(
+1161        self,
+1162        client: str,
+1163        plugin: str,
+1164        sends: Iterable[MessageTemplate],
+1165        receives: Iterable[Tuple[Iterable[MessageTemplate], MessageCallback]],
+1166    ) -> None:
+1167        """Register a client at the message bus.
+1168
+1169        >>> async def callback(message):
+1170        ...     print(message)
+1171        >>> async def main():
+1172        ...     bus = MessageBus()
+1173        ...     bus.register('Logger', 'Test Plugin',
+1174        ...                  [],    # send nothing
+1175        ...                  [([MessageTemplate({})],  # receive everything
+1176        ...                    callback)])
+1177        ...     bus.register('Client 1', 'Test Plugin',
+1178        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1179        ...                      # send with key 'k1' and string value
+1180        ...                  [([MessageTemplate({'target':
+1181        ...                                      {'const': 'Client 1'}})],
+1182        ...                      # receive for this client
+1183        ...                    callback)])
+1184        ...     bus.register('Client 2', 'Test Plugin',
+1185        ...                  [MessageTemplate({})],  # send arbitrary
+1186        ...                  [([MessageTemplate({'target':
+1187        ...                                      {'const': 'Client 2'}})],
+1188        ...                      # receive for this client
+1189        ...                    callback)])
+1190        >>> asyncio.run(main())
+1191        """
+1192        if not client:
+1193            raise BusException("Client name is not allowed to be empty.")
+1194        if client in self._plugins:
+1195            raise BusException(f"Client '{client}' already registered at message bus.")
+1196        event = Message("")
+1197        event["event"] = "registered"
+1198        event["client"] = client
+1199        self._plugins[client] = plugin
+1200        event["plugin"] = plugin
+1201        for template in sends:
+1202            self._send_reg.insert(template, client)
+1203        event["sends"] = self._send_reg.get_templates(client)
+1204        for templates, callback in receives:
+1205            for template in templates:
+1206                self._recv_reg.insert(template, client, callback)
+1207        event["receives"] = self._recv_reg.get_templates(client)
+1208        self._queue.put_nowait(event)
+1209
+1210    def unregister(self, client: str) -> None:
+1211        """Unregister a client from the message bus.
+1212
+1213        >>> async def callback(message):
+1214        ...     print(message)
+1215        >>> async def main():
+1216        ...     bus = MessageBus()
+1217        ...     bus.register('Client 1', 'Test Plugin',
+1218        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1219        ...                  [([MessageTemplate({'target':
+1220        ...                                      {'const': 'Client 1'}})],
+1221        ...                    callback)])
+1222        ...     bus.unregister('Client 1')
+1223        >>> asyncio.run(main())
+1224        """
+1225        if client not in self._plugins:
+1226            return
+1227        event = Message("")
+1228        event["event"] = "unregistered"
+1229        event["client"] = client
+1230        del self._plugins[client]
+1231        self._send_reg.delete(client)
+1232        self._recv_reg.delete(client)
+1233        self._queue.put_nowait(event)
+1234
+1235    async def run(self) -> None:
+1236        """Run the message bus forever.
+1237
+1238        >>> async def main():
+1239        ...     bus = MessageBus()
+1240        ...     bus_task = asyncio.create_task(bus.run())
+1241        ...     bus_task.cancel()
+1242        ...     try:
+1243        ...         await bus_task
+1244        ...     except asyncio.exceptions.CancelledError:
+1245        ...         pass
+1246        >>> asyncio.run(main())
+1247        """
+1248        background_tasks = set()
+1249        while True:
+1250            message = await self._queue.get()
+1251            if "target" in message and message["target"] == "" and "command" in message:
+1252                if message["command"] == "get clients":
+1253                    for client in self._plugins:
+1254                        answer = Message("")
+1255                        answer["client"] = client
+1256                        answer["plugin"] = self._plugins[client]
+1257                        answer["sends"] = self._send_reg.get_templates(client)
+1258                        answer["receives"] = self._recv_reg.get_templates(client)
+1259                        await self._queue.put(answer)
+1260                elif message["command"] == "push conf":
+1261                    conf = {}
+1262                    try:
+1263                        with open(sys.argv[1]) as conf_file:
+1264                            conf = json.load(conf_file)
+1265                    except (
+1266                        IndexError,
+1267                        FileNotFoundError,
+1268                        json.decoder.JSONDecodeError,
+1269                    ):
+1270                        pass
+1271                    if conf == message["conf"]:
+1272                        await self._queue.put(Message("", {"event": "conf unchanged"}))
+1273                    else:
+1274                        await self._queue.put(Message("", {"event": "conf changed"}))
+1275                        with open(sys.argv[1], "w") as conf_file:
+1276                            json.dump(message["conf"], conf_file)
+1277            for callback in self._recv_reg.get_callbacks(message):
+1278                task = asyncio.create_task(callback(message))
+1279                background_tasks.add(task)
+1280                task.add_done_callback(background_tasks.discard)
+1281            self._queue.task_done()
+1282
+1283    async def send(self, message: Message) -> None:
+1284        """Send a message to the message bus.
+1285
+1286        >>> async def callback(message):
+1287        ...     print(f"Got: {message}")
+1288        >>> async def main():
+1289        ...     bus = MessageBus()
+1290        ...     bus.register('Client 1', 'Test Plugin',
+1291        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1292        ...                  [([MessageTemplate({'target':
+1293        ...                                      {'const': 'Client 1'}})],
+1294        ...                    callback)])
+1295        ...     bus.register('Client 2', 'Test Plugin',
+1296        ...                  [MessageTemplate({})],
+1297        ...                  [([MessageTemplate({'target':
+1298        ...                                      {'const': 'Client 2'}})],
+1299        ...                    callback)])
+1300        ...     bus_task = asyncio.create_task(bus.run())
+1301        ...     await bus.send({'sender': 'Client 1', 'target': 'Client 2',
+1302        ...                     'k1': 'Test'})
+1303        ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
+1304        ...     try:
+1305        ...         await bus.send({'sender': 'Client 1', 'target': 'Client 2',
+1306        ...                         'k1': 42})
+1307        ...     except BusException as e:
+1308        ...         print(e)
+1309        ...     await asyncio.sleep(0)
+1310        ...     bus_task.cancel()
+1311        ...     try:
+1312        ...         await bus_task
+1313        ...     except asyncio.exceptions.CancelledError:
+1314        ...         pass
+1315        >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+1316        Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
+1317        not allowed for sender 'Client 1'.
+1318        Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
+1319        Got: {'sender': 'Client 2', 'target': 'Client 1'}
+1320        """
+1321        assert isinstance(message["sender"], str)
+1322        sender = message["sender"]
+1323        if sender:
+1324            if not self._send_reg.check(sender, message):
+1325                raise BusException(
+1326                    f"Message '{message}' not allowed for sender '{sender}'."
+1327                )
+1328        await self._queue.put(message)
+1329
+1330    def send_nowait(self, message: Message) -> None:
+1331        """Send a message to the message bus without blocking.
+1332
+1333        >>> async def callback(message):
+1334        ...     print(f"Got: {message}")
+1335        >>> async def main():
+1336        ...     bus = MessageBus()
+1337        ...     bus.register('Client 1', 'Test Plugin',
+1338        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1339        ...                  [([MessageTemplate({'target':
+1340        ...                                      {'const': 'Client 1'}})],
+1341        ...                    callback)])
+1342        ...     bus.register('Client 2', 'Test Plugin',
+1343        ...                  [MessageTemplate({})],
+1344        ...                  [([MessageTemplate({'target':
+1345        ...                                      {'const': 'Client 2'}})],
+1346        ...                    callback)])
+1347        ...     bus_task = asyncio.create_task(bus.run())
+1348        ...     bus.send_nowait({'sender': 'Client 1', 'target': 'Client 2',
+1349        ...                      'k1': 'Test'})
+1350        ...     bus.send_nowait({'sender': 'Client 2', 'target': 'Client 1'})
+1351        ...     try:
+1352        ...         bus.send_nowait({'sender': 'Client 1',
+1353        ...                          'target': 'Client 2', 'k1': 42})
+1354        ...     except BusException as e:
+1355        ...         print(e)
+1356        ...     await asyncio.sleep(0)
+1357        ...     bus_task.cancel()
+1358        ...     try:
+1359        ...         await bus_task
+1360        ...     except asyncio.exceptions.CancelledError:
+1361        ...         pass
+1362        >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+1363        Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
+1364        not allowed for sender 'Client 1'.
+1365        Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
+1366        Got: {'sender': 'Client 2', 'target': 'Client 1'}
+1367        """
+1368        assert isinstance(message["sender"], str)
+1369        sender = message["sender"]
+1370        if sender:
+1371            if not self._send_reg.check(sender, message):
+1372                raise BusException(
+1373                    f"Message '{message}' not allowed for sender '{sender}'."
+1374                )
+1375        self._queue.put_nowait(message)
+

+ + +

Provide an asynchronous message bus.

+ +

The bus executes asynchronous callbacks for all messages to be received +by a client. We use a simple callback printing the message in all +examples:

+ +

>>> def callback_for_receiver(receiver):
+...     print(f"Creating callback for {receiver}.")
+...     async def callback(message):
+...         print(f"{receiver}: {message}")
+...     return callback
+

+ +

Clients can be registered at the bus with a name, lists of message +templates they want to use for sending and receiving and a callback +function for receiving. An empty list of templates means that the +client does not want to send or receive any messages, respectively. +A list with an empty template means that it wants to send arbitrary +or receive all messages, respectively:

+ +

>>> async def setup(bus):
+...     print("Setting up.")
+...     bus.register('Logger', 'Test Plugin',
+...                  [],
+...                  [([MessageTemplate({})],
+...                    callback_for_receiver('Logger'))])
+...     bus.register('Client 1', 'Test Plugin',
+...                  [MessageTemplate({'k1': {'type': 'string'}})],
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 1'}})],
+...                    callback_for_receiver('Client 1'))])
+...     bus.register('Client 2', 'Test Plugin',
+...                  [MessageTemplate({})],
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 2'}})],
+...                    callback_for_receiver('Client 2'))])
+

+ +

The bus itself is addressed by the empty string. It sends messages for +each registration and deregestration of a client with a key 'event' and +a value of 'registered' or 'unregistered', a key 'client' with the +client's name as value and for registrations also keys 'sends' and +'receives' with all templates registered for the client for sending and +receiving.

+ +

Clients can send to the bus with the send function. Each message has to +declare a sender. The send templates of that sender are checked for a +template matching the message. We cannot prevent arbitrary code from +impersonating any sender, but this should only be done in debugging or +management situations.

+ +

Messages that are intended for a specific client by convention have a +key 'target' with the target client's name as value. Such messages are +often commands to the client to do something, which is by convention +indicated by a key 'command' with a value that indicates what should be +done.

+ +

The bus, for example, reacts to a message with 'target': '' and +'command': 'get clients' by sending one message for each currently +registered with complete information about its registered send and +receive templates.

+ +

>>> async def send(bus):
+...     print("Sending messages.")
+...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
+...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
+...     await bus.send({'sender': '', 'target': '',
+...                     'command': 'get clients'})
+

+ +

The run function executes the message bus forever. If we want to stop +it, we have to explicitly cancel the task:

+ +

>>> async def main():
+...     bus = MessageBus()
+...     await setup(bus)
+...     bus_task = asyncio.create_task(bus.run())
+...     await send(bus)
+...     await asyncio.sleep(0)
+...     bus_task.cancel()
+...     try:
+...         await bus_task
+...     except asyncio.exceptions.CancelledError:
+...         pass
+>>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+Setting up.
+Creating callback for Logger.
+Creating callback for Client 1.
+Creating callback for Client 2.
+Sending messages.
+Logger: {'sender': '', 'event': 'registered',
+         'client': 'Logger', 'plugin': 'Test Plugin',
+         'sends': [], 'receives': [{}]}
+Logger: {'sender': '', 'event': 'registered',
+         'client': 'Client 1', 'plugin': 'Test Plugin',
+         'sends': [{'k1': {'type': 'string'}}],
+         'receives': [{'target': {'const': 'Client 1'}}]}
+Logger: {'sender': '', 'event': 'registered',
+         'client': 'Client 2', 'plugin': 'Test Plugin',
+         'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
+Logger: {'sender': 'Client 1', 'k1': 'Test'}
+Logger: {'sender': 'Client 2', 'target': 'Client 1'}
+Client 1: {'sender': 'Client 2', 'target': 'Client 1'}
+Logger: {'sender': '', 'target': '', 'command': 'get clients'}
+Logger: {'sender': '', 'client': 'Logger', 'plugin': 'Test Plugin',
+         'sends': [], 'receives': [{}]}
+Logger: {'sender': '', 'client': 'Client 1', 'plugin': 'Test Plugin',
+         'sends': [{'k1': {'type': 'string'}}],
+         'receives': [{'target': {'const': 'Client 1'}}]}
+Logger: {'sender': '', 'client': 'Client 2', 'plugin': 'Test Plugin',
+         'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
+

+ + +

+ +

+ + MessageBus() + + View Source + +

+ +

1148    def __init__(self) -> None:
+1149        """Initialise a new bus without clients.
+1150
+1151        >>> async def main():
+1152        ...     bus = MessageBus()
+1153        >>> asyncio.run(main())
+1154        """
+1155        self._queue: asyncio.Queue = asyncio.Queue()
+1156        self._plugins: Dict[str, str] = {}
+1157        self._send_reg: TemplateRegistry = TemplateRegistry()
+1158        self._recv_reg: TemplateRegistry = TemplateRegistry()
+

+ + +

Initialise a new bus without clients.

+ +

>>> async def main():
+...     bus = MessageBus()
+>>> asyncio.run(main())
+

+ + +

+ +

+ + def + register( self, client: str, plugin: str, sends: Iterable[MessageTemplate], receives: Iterable[Tuple[Iterable[MessageTemplate], Callable[[Message], Coroutine[Any, Any, NoneType]]]]) -> None: + + View Source + +

+ +

1160    def register(
+1161        self,
+1162        client: str,
+1163        plugin: str,
+1164        sends: Iterable[MessageTemplate],
+1165        receives: Iterable[Tuple[Iterable[MessageTemplate], MessageCallback]],
+1166    ) -> None:
+1167        """Register a client at the message bus.
+1168
+1169        >>> async def callback(message):
+1170        ...     print(message)
+1171        >>> async def main():
+1172        ...     bus = MessageBus()
+1173        ...     bus.register('Logger', 'Test Plugin',
+1174        ...                  [],    # send nothing
+1175        ...                  [([MessageTemplate({})],  # receive everything
+1176        ...                    callback)])
+1177        ...     bus.register('Client 1', 'Test Plugin',
+1178        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1179        ...                      # send with key 'k1' and string value
+1180        ...                  [([MessageTemplate({'target':
+1181        ...                                      {'const': 'Client 1'}})],
+1182        ...                      # receive for this client
+1183        ...                    callback)])
+1184        ...     bus.register('Client 2', 'Test Plugin',
+1185        ...                  [MessageTemplate({})],  # send arbitrary
+1186        ...                  [([MessageTemplate({'target':
+1187        ...                                      {'const': 'Client 2'}})],
+1188        ...                      # receive for this client
+1189        ...                    callback)])
+1190        >>> asyncio.run(main())
+1191        """
+1192        if not client:
+1193            raise BusException("Client name is not allowed to be empty.")
+1194        if client in self._plugins:
+1195            raise BusException(f"Client '{client}' already registered at message bus.")
+1196        event = Message("")
+1197        event["event"] = "registered"
+1198        event["client"] = client
+1199        self._plugins[client] = plugin
+1200        event["plugin"] = plugin
+1201        for template in sends:
+1202            self._send_reg.insert(template, client)
+1203        event["sends"] = self._send_reg.get_templates(client)
+1204        for templates, callback in receives:
+1205            for template in templates:
+1206                self._recv_reg.insert(template, client, callback)
+1207        event["receives"] = self._recv_reg.get_templates(client)
+1208        self._queue.put_nowait(event)
+

+ + +

+ +

>>> async def callback(message):
+...     print(message)
+>>> async def main():
+...     bus = MessageBus()
+...     bus.register('Logger', 'Test Plugin',
+...                  [],    # send nothing
+...                  [([MessageTemplate({})],  # receive everything
+...                    callback)])
+...     bus.register('Client 1', 'Test Plugin',
+...                  [MessageTemplate({'k1': {'type': 'string'}})],
+...                      # send with key 'k1' and string value
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 1'}})],
+...                      # receive for this client
+...                    callback)])
+...     bus.register('Client 2', 'Test Plugin',
+...                  [MessageTemplate({})],  # send arbitrary
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 2'}})],
+...                      # receive for this client
+...                    callback)])
+>>> asyncio.run(main())
+

+ + +

+ +

+ + def + unregister(self, client: str) -> None: + + View Source + +

+ +

1210    def unregister(self, client: str) -> None:
+1211        """Unregister a client from the message bus.
+1212
+1213        >>> async def callback(message):
+1214        ...     print(message)
+1215        >>> async def main():
+1216        ...     bus = MessageBus()
+1217        ...     bus.register('Client 1', 'Test Plugin',
+1218        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1219        ...                  [([MessageTemplate({'target':
+1220        ...                                      {'const': 'Client 1'}})],
+1221        ...                    callback)])
+1222        ...     bus.unregister('Client 1')
+1223        >>> asyncio.run(main())
+1224        """
+1225        if client not in self._plugins:
+1226            return
+1227        event = Message("")
+1228        event["event"] = "unregistered"
+1229        event["client"] = client
+1230        del self._plugins[client]
+1231        self._send_reg.delete(client)
+1232        self._recv_reg.delete(client)
+1233        self._queue.put_nowait(event)
+

+ + +

Unregister a client from the message bus.

+ +

>>> async def callback(message):
+...     print(message)
+>>> async def main():
+...     bus = MessageBus()
+...     bus.register('Client 1', 'Test Plugin',
+...                  [MessageTemplate({'k1': {'type': 'string'}})],
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 1'}})],
+...                    callback)])
+...     bus.unregister('Client 1')
+>>> asyncio.run(main())
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

1235    async def run(self) -> None:
+1236        """Run the message bus forever.
+1237
+1238        >>> async def main():
+1239        ...     bus = MessageBus()
+1240        ...     bus_task = asyncio.create_task(bus.run())
+1241        ...     bus_task.cancel()
+1242        ...     try:
+1243        ...         await bus_task
+1244        ...     except asyncio.exceptions.CancelledError:
+1245        ...         pass
+1246        >>> asyncio.run(main())
+1247        """
+1248        background_tasks = set()
+1249        while True:
+1250            message = await self._queue.get()
+1251            if "target" in message and message["target"] == "" and "command" in message:
+1252                if message["command"] == "get clients":
+1253                    for client in self._plugins:
+1254                        answer = Message("")
+1255                        answer["client"] = client
+1256                        answer["plugin"] = self._plugins[client]
+1257                        answer["sends"] = self._send_reg.get_templates(client)
+1258                        answer["receives"] = self._recv_reg.get_templates(client)
+1259                        await self._queue.put(answer)
+1260                elif message["command"] == "push conf":
+1261                    conf = {}
+1262                    try:
+1263                        with open(sys.argv[1]) as conf_file:
+1264                            conf = json.load(conf_file)
+1265                    except (
+1266                        IndexError,
+1267                        FileNotFoundError,
+1268                        json.decoder.JSONDecodeError,
+1269                    ):
+1270                        pass
+1271                    if conf == message["conf"]:
+1272                        await self._queue.put(Message("", {"event": "conf unchanged"}))
+1273                    else:
+1274                        await self._queue.put(Message("", {"event": "conf changed"}))
+1275                        with open(sys.argv[1], "w") as conf_file:
+1276                            json.dump(message["conf"], conf_file)
+1277            for callback in self._recv_reg.get_callbacks(message):
+1278                task = asyncio.create_task(callback(message))
+1279                background_tasks.add(task)
+1280                task.add_done_callback(background_tasks.discard)
+1281            self._queue.task_done()
+

+ + +

Run the message bus forever.

+ +

>>> async def main():
+...     bus = MessageBus()
+...     bus_task = asyncio.create_task(bus.run())
+...     bus_task.cancel()
+...     try:
+...         await bus_task
+...     except asyncio.exceptions.CancelledError:
+...         pass
+>>> asyncio.run(main())
+

+ + +

+ +

+ + async def + send(self, message: Message) -> None: + + View Source + +

+ +

1283    async def send(self, message: Message) -> None:
+1284        """Send a message to the message bus.
+1285
+1286        >>> async def callback(message):
+1287        ...     print(f"Got: {message}")
+1288        >>> async def main():
+1289        ...     bus = MessageBus()
+1290        ...     bus.register('Client 1', 'Test Plugin',
+1291        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1292        ...                  [([MessageTemplate({'target':
+1293        ...                                      {'const': 'Client 1'}})],
+1294        ...                    callback)])
+1295        ...     bus.register('Client 2', 'Test Plugin',
+1296        ...                  [MessageTemplate({})],
+1297        ...                  [([MessageTemplate({'target':
+1298        ...                                      {'const': 'Client 2'}})],
+1299        ...                    callback)])
+1300        ...     bus_task = asyncio.create_task(bus.run())
+1301        ...     await bus.send({'sender': 'Client 1', 'target': 'Client 2',
+1302        ...                     'k1': 'Test'})
+1303        ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
+1304        ...     try:
+1305        ...         await bus.send({'sender': 'Client 1', 'target': 'Client 2',
+1306        ...                         'k1': 42})
+1307        ...     except BusException as e:
+1308        ...         print(e)
+1309        ...     await asyncio.sleep(0)
+1310        ...     bus_task.cancel()
+1311        ...     try:
+1312        ...         await bus_task
+1313        ...     except asyncio.exceptions.CancelledError:
+1314        ...         pass
+1315        >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+1316        Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
+1317        not allowed for sender 'Client 1'.
+1318        Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
+1319        Got: {'sender': 'Client 2', 'target': 'Client 1'}
+1320        """
+1321        assert isinstance(message["sender"], str)
+1322        sender = message["sender"]
+1323        if sender:
+1324            if not self._send_reg.check(sender, message):
+1325                raise BusException(
+1326                    f"Message '{message}' not allowed for sender '{sender}'."
+1327                )
+1328        await self._queue.put(message)
+

+ + +

Send a message to the message bus.

+ +

>>> async def callback(message):
+...     print(f"Got: {message}")
+>>> async def main():
+...     bus = MessageBus()
+...     bus.register('Client 1', 'Test Plugin',
+...                  [MessageTemplate({'k1': {'type': 'string'}})],
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 1'}})],
+...                    callback)])
+...     bus.register('Client 2', 'Test Plugin',
+...                  [MessageTemplate({})],
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 2'}})],
+...                    callback)])
+...     bus_task = asyncio.create_task(bus.run())
+...     await bus.send({'sender': 'Client 1', 'target': 'Client 2',
+...                     'k1': 'Test'})
+...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
+...     try:
+...         await bus.send({'sender': 'Client 1', 'target': 'Client 2',
+...                         'k1': 42})
+...     except BusException as e:
+...         print(e)
+...     await asyncio.sleep(0)
+...     bus_task.cancel()
+...     try:
+...         await bus_task
+...     except asyncio.exceptions.CancelledError:
+...         pass
+>>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
+not allowed for sender 'Client 1'.
+Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
+Got: {'sender': 'Client 2', 'target': 'Client 1'}
+

+ + +

+ +

+ + def + send_nowait(self, message: Message) -> None: + + View Source + +

+ +

1330    def send_nowait(self, message: Message) -> None:
+1331        """Send a message to the message bus without blocking.
+1332
+1333        >>> async def callback(message):
+1334        ...     print(f"Got: {message}")
+1335        >>> async def main():
+1336        ...     bus = MessageBus()
+1337        ...     bus.register('Client 1', 'Test Plugin',
+1338        ...                  [MessageTemplate({'k1': {'type': 'string'}})],
+1339        ...                  [([MessageTemplate({'target':
+1340        ...                                      {'const': 'Client 1'}})],
+1341        ...                    callback)])
+1342        ...     bus.register('Client 2', 'Test Plugin',
+1343        ...                  [MessageTemplate({})],
+1344        ...                  [([MessageTemplate({'target':
+1345        ...                                      {'const': 'Client 2'}})],
+1346        ...                    callback)])
+1347        ...     bus_task = asyncio.create_task(bus.run())
+1348        ...     bus.send_nowait({'sender': 'Client 1', 'target': 'Client 2',
+1349        ...                      'k1': 'Test'})
+1350        ...     bus.send_nowait({'sender': 'Client 2', 'target': 'Client 1'})
+1351        ...     try:
+1352        ...         bus.send_nowait({'sender': 'Client 1',
+1353        ...                          'target': 'Client 2', 'k1': 42})
+1354        ...     except BusException as e:
+1355        ...         print(e)
+1356        ...     await asyncio.sleep(0)
+1357        ...     bus_task.cancel()
+1358        ...     try:
+1359        ...         await bus_task
+1360        ...     except asyncio.exceptions.CancelledError:
+1361        ...         pass
+1362        >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+1363        Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
+1364        not allowed for sender 'Client 1'.
+1365        Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
+1366        Got: {'sender': 'Client 2', 'target': 'Client 1'}
+1367        """
+1368        assert isinstance(message["sender"], str)
+1369        sender = message["sender"]
+1370        if sender:
+1371            if not self._send_reg.check(sender, message):
+1372                raise BusException(
+1373                    f"Message '{message}' not allowed for sender '{sender}'."
+1374                )
+1375        self._queue.put_nowait(message)
+

+ + +

Send a message to the message bus without blocking.

+ +

>>> async def callback(message):
+...     print(f"Got: {message}")
+>>> async def main():
+...     bus = MessageBus()
+...     bus.register('Client 1', 'Test Plugin',
+...                  [MessageTemplate({'k1': {'type': 'string'}})],
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 1'}})],
+...                    callback)])
+...     bus.register('Client 2', 'Test Plugin',
+...                  [MessageTemplate({})],
+...                  [([MessageTemplate({'target':
+...                                      {'const': 'Client 2'}})],
+...                    callback)])
+...     bus_task = asyncio.create_task(bus.run())
+...     bus.send_nowait({'sender': 'Client 1', 'target': 'Client 2',
+...                      'k1': 'Test'})
+...     bus.send_nowait({'sender': 'Client 2', 'target': 'Client 1'})
+...     try:
+...         bus.send_nowait({'sender': 'Client 1',
+...                          'target': 'Client 2', 'k1': 42})
+...     except BusException as e:
+...         print(e)
+...     await asyncio.sleep(0)
+...     bus_task.cancel()
+...     try:
+...         await bus_task
+...     except asyncio.exceptions.CancelledError:
+...         pass
+>>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
+Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
+not allowed for sender 'Client 1'.
+Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
+Got: {'sender': 'Client 2', 'target': 'Client 1'}
+

+ + +

+controlpi.pluginregistry

+ +

Provide a generic plugin system.

+ +

The class PluginRegistry is initialised with the name of a namespace +package and a base class.

+ +

All modules in the namespace package are loaded. These modules can be +included in different distribution packages, which allows to dynamically +add plugins to the system without changing any code.

+ +

Afterwards, all (direct and indirect) subclasses of the base class are +registered as plugins under their class name. Class names should be unique, +which cannot be programmatically enforced.

+ +

>>> class BasePlugin:
+...     pass
+>>> class Plugin1(BasePlugin):
+...     pass
+>>> class Plugin2(BasePlugin):
+...     pass
+>>> registry = PluginRegistry('importlib', BasePlugin)
+

+ +

The registry provides a generic mapping interface with the class names as +keys and the classes as values.

+ +

>>> print(len(registry))
+2
+>>> for name in registry:
+...     print(f"{name}: {registry[name]}")
+Plugin1: <class 'pluginregistry.Plugin1'>
+Plugin2: <class 'pluginregistry.Plugin2'>
+>>> if 'Plugin1' in registry:
+...     print(f"'Plugin1' is in registry.")
+'Plugin1' is in registry.
+>>> p1 = registry['Plugin1']
+>>> i1 = p1()
+

+ + + + View Source + +

  1"""Provide a generic plugin system.
+  2
+  3The class PluginRegistry is initialised with the name of a namespace
+  4package and a base class.
+  5
+  6All modules in the namespace package are loaded. These modules can be
+  7included in different distribution packages, which allows to dynamically
+  8add plugins to the system without changing any code.
+  9
+ 10Afterwards, all (direct and indirect) subclasses of the base class are
+ 11registered as plugins under their class name. Class names should be unique,
+ 12which cannot be programmatically enforced.
+ 13
+ 14>>> class BasePlugin:
+ 15...     pass
+ 16>>> class Plugin1(BasePlugin):
+ 17...     pass
+ 18>>> class Plugin2(BasePlugin):
+ 19...     pass
+ 20>>> registry = PluginRegistry('importlib', BasePlugin)
+ 21
+ 22The registry provides a generic mapping interface with the class names as
+ 23keys and the classes as values.
+ 24
+ 25>>> print(len(registry))
+ 262
+ 27>>> for name in registry:
+ 28...     print(f"{name}: {registry[name]}")
+ 29Plugin1: <class 'pluginregistry.Plugin1'>
+ 30Plugin2: <class 'pluginregistry.Plugin2'>
+ 31>>> if 'Plugin1' in registry:
+ 32...     print(f"'Plugin1' is in registry.")
+ 33'Plugin1' is in registry.
+ 34>>> p1 = registry['Plugin1']
+ 35>>> i1 = p1()
+ 36"""
+ 37
+ 38import importlib
+ 39import pkgutil
+ 40import collections.abc
+ 41
+ 42
+ 43class PluginRegistry(collections.abc.Mapping):
+ 44    """Provide a registry for plugins.
+ 45
+ 46    Initialise the registry by loading all modules in the given namespace
+ 47    package and then registering all subclasses of the given base class as
+ 48    plugins (only simulated here â the code for Plugin1 and Plugin2 should
+ 49    be in modules in the given namespace package in real applications):
+ 50    >>> class BasePlugin:
+ 51    ...     pass
+ 52    >>> class Plugin1(BasePlugin):
+ 53    ...     pass
+ 54    >>> class Plugin2(BasePlugin):
+ 55    ...     pass
+ 56    >>> registry = PluginRegistry('importlib', BasePlugin)
+ 57
+ 58    After initialisation, provide a mapping interface to the plugins:
+ 59    >>> print(len(registry))
+ 60    2
+ 61    >>> for name in registry:
+ 62    ...     print(f"{name}: {registry[name]}")
+ 63    Plugin1: <class 'pluginregistry.Plugin1'>
+ 64    Plugin2: <class 'pluginregistry.Plugin2'>
+ 65    >>> if 'Plugin1' in registry:
+ 66    ...     print(f"'Plugin1' is in registry.")
+ 67    'Plugin1' is in registry.
+ 68    """
+ 69
+ 70    def __init__(self, namespace_package: str, base_class: type) -> None:
+ 71        """Initialise registry.
+ 72
+ 73        Import all modules defined in the given namespace package (in any
+ 74        distribution package currently installed in the path). Then register
+ 75        all subclasses of the given base class as plugins.
+ 76
+ 77        >>> class BasePlugin:
+ 78        ...     pass
+ 79        >>> class Plugin1(BasePlugin):
+ 80        ...     pass
+ 81        >>> class Plugin2(BasePlugin):
+ 82        ...     pass
+ 83        >>> registry = PluginRegistry('importlib', BasePlugin)
+ 84        >>> for name in registry._plugins:
+ 85        ...     print(f"{name}: {registry._plugins[name]}")
+ 86        Plugin1: <class 'pluginregistry.Plugin1'>
+ 87        Plugin2: <class 'pluginregistry.Plugin2'>
+ 88        """
+ 89        ns_mod = importlib.import_module(namespace_package)
+ 90        ns_path = ns_mod.__path__
+ 91        ns_name = ns_mod.__name__
+ 92        for _, mod_name, _ in pkgutil.iter_modules(ns_path):
+ 93            importlib.import_module(f"{ns_name}.{mod_name}")
+ 94
+ 95        def all_subclasses(cls):
+ 96            result = []
+ 97            for subcls in cls.__subclasses__():
+ 98                result.append(subcls)
+ 99                result.extend(all_subclasses(subcls))
+100            return result
+101
+102        self._plugins = {cls.__name__: cls for cls in all_subclasses(base_class)}
+103
+104    def __len__(self) -> int:
+105        """Get number of registered plugins.
+106
+107        >>> class BasePlugin:
+108        ...     pass
+109        >>> class Plugin1(BasePlugin):
+110        ...     pass
+111        >>> class Plugin2(BasePlugin):
+112        ...     pass
+113        >>> registry = PluginRegistry('importlib', BasePlugin)
+114        >>> print(registry.__len__())
+115        2
+116        """
+117        return len(self._plugins)
+118
+119    def __iter__(self):
+120        """Get an iterator of the registered plugins.
+121
+122        >>> class BasePlugin:
+123        ...     pass
+124        >>> class Plugin1(BasePlugin):
+125        ...     pass
+126        >>> class Plugin2(BasePlugin):
+127        ...     pass
+128        >>> registry = PluginRegistry('importlib', BasePlugin)
+129        >>> print(type(registry.__iter__()))
+130        <class 'dict_keyiterator'>
+131        >>> for name in registry:
+132        ...     print(name)
+133        Plugin1
+134        Plugin2
+135        """
+136        return iter(self._plugins)
+137
+138    def __getitem__(self, plugin_name: str) -> type:
+139        """Get a registered plugin given its name.
+140
+141        >>> class BasePlugin:
+142        ...     pass
+143        >>> class Plugin1(BasePlugin):
+144        ...     pass
+145        >>> class Plugin2(BasePlugin):
+146        ...     pass
+147        >>> registry = PluginRegistry('importlib', BasePlugin)
+148        >>> print(registry.__getitem__('Plugin1'))
+149        <class 'pluginregistry.Plugin1'>
+150        >>> print(registry.__getitem__('Plugin2'))
+151        <class 'pluginregistry.Plugin2'>
+152        >>> for name in registry:
+153        ...     print(registry[name])
+154        <class 'pluginregistry.Plugin1'>
+155        <class 'pluginregistry.Plugin2'>
+156        """
+157        return self._plugins[plugin_name]
+

+ + +

+ +

+ + class + PluginRegistry(collections.abc.Mapping): + + View Source + +

+ +

 44class PluginRegistry(collections.abc.Mapping):
+ 45    """Provide a registry for plugins.
+ 46
+ 47    Initialise the registry by loading all modules in the given namespace
+ 48    package and then registering all subclasses of the given base class as
+ 49    plugins (only simulated here â the code for Plugin1 and Plugin2 should
+ 50    be in modules in the given namespace package in real applications):
+ 51    >>> class BasePlugin:
+ 52    ...     pass
+ 53    >>> class Plugin1(BasePlugin):
+ 54    ...     pass
+ 55    >>> class Plugin2(BasePlugin):
+ 56    ...     pass
+ 57    >>> registry = PluginRegistry('importlib', BasePlugin)
+ 58
+ 59    After initialisation, provide a mapping interface to the plugins:
+ 60    >>> print(len(registry))
+ 61    2
+ 62    >>> for name in registry:
+ 63    ...     print(f"{name}: {registry[name]}")
+ 64    Plugin1: <class 'pluginregistry.Plugin1'>
+ 65    Plugin2: <class 'pluginregistry.Plugin2'>
+ 66    >>> if 'Plugin1' in registry:
+ 67    ...     print(f"'Plugin1' is in registry.")
+ 68    'Plugin1' is in registry.
+ 69    """
+ 70
+ 71    def __init__(self, namespace_package: str, base_class: type) -> None:
+ 72        """Initialise registry.
+ 73
+ 74        Import all modules defined in the given namespace package (in any
+ 75        distribution package currently installed in the path). Then register
+ 76        all subclasses of the given base class as plugins.
+ 77
+ 78        >>> class BasePlugin:
+ 79        ...     pass
+ 80        >>> class Plugin1(BasePlugin):
+ 81        ...     pass
+ 82        >>> class Plugin2(BasePlugin):
+ 83        ...     pass
+ 84        >>> registry = PluginRegistry('importlib', BasePlugin)
+ 85        >>> for name in registry._plugins:
+ 86        ...     print(f"{name}: {registry._plugins[name]}")
+ 87        Plugin1: <class 'pluginregistry.Plugin1'>
+ 88        Plugin2: <class 'pluginregistry.Plugin2'>
+ 89        """
+ 90        ns_mod = importlib.import_module(namespace_package)
+ 91        ns_path = ns_mod.__path__
+ 92        ns_name = ns_mod.__name__
+ 93        for _, mod_name, _ in pkgutil.iter_modules(ns_path):
+ 94            importlib.import_module(f"{ns_name}.{mod_name}")
+ 95
+ 96        def all_subclasses(cls):
+ 97            result = []
+ 98            for subcls in cls.__subclasses__():
+ 99                result.append(subcls)
+100                result.extend(all_subclasses(subcls))
+101            return result
+102
+103        self._plugins = {cls.__name__: cls for cls in all_subclasses(base_class)}
+104
+105    def __len__(self) -> int:
+106        """Get number of registered plugins.
+107
+108        >>> class BasePlugin:
+109        ...     pass
+110        >>> class Plugin1(BasePlugin):
+111        ...     pass
+112        >>> class Plugin2(BasePlugin):
+113        ...     pass
+114        >>> registry = PluginRegistry('importlib', BasePlugin)
+115        >>> print(registry.__len__())
+116        2
+117        """
+118        return len(self._plugins)
+119
+120    def __iter__(self):
+121        """Get an iterator of the registered plugins.
+122
+123        >>> class BasePlugin:
+124        ...     pass
+125        >>> class Plugin1(BasePlugin):
+126        ...     pass
+127        >>> class Plugin2(BasePlugin):
+128        ...     pass
+129        >>> registry = PluginRegistry('importlib', BasePlugin)
+130        >>> print(type(registry.__iter__()))
+131        <class 'dict_keyiterator'>
+132        >>> for name in registry:
+133        ...     print(name)
+134        Plugin1
+135        Plugin2
+136        """
+137        return iter(self._plugins)
+138
+139    def __getitem__(self, plugin_name: str) -> type:
+140        """Get a registered plugin given its name.
+141
+142        >>> class BasePlugin:
+143        ...     pass
+144        >>> class Plugin1(BasePlugin):
+145        ...     pass
+146        >>> class Plugin2(BasePlugin):
+147        ...     pass
+148        >>> registry = PluginRegistry('importlib', BasePlugin)
+149        >>> print(registry.__getitem__('Plugin1'))
+150        <class 'pluginregistry.Plugin1'>
+151        >>> print(registry.__getitem__('Plugin2'))
+152        <class 'pluginregistry.Plugin2'>
+153        >>> for name in registry:
+154        ...     print(registry[name])
+155        <class 'pluginregistry.Plugin1'>
+156        <class 'pluginregistry.Plugin2'>
+157        """
+158        return self._plugins[plugin_name]
+

+ + +

Provide a registry for plugins.

+ +

Initialise the registry by loading all modules in the given namespace +package and then registering all subclasses of the given base class as +plugins (only simulated here â the code for Plugin1 and Plugin2 should +be in modules in the given namespace package in real applications):

+ +

>>> class BasePlugin:
+...     pass
+>>> class Plugin1(BasePlugin):
+...     pass
+>>> class Plugin2(BasePlugin):
+...     pass
+>>> registry = PluginRegistry('importlib', BasePlugin)
+

+ +

After initialisation, provide a mapping interface to the plugins:

+ +

>>> print(len(registry))
+2
+>>> for name in registry:
+...     print(f"{name}: {registry[name]}")
+Plugin1: <class 'pluginregistry.Plugin1'>
+Plugin2: <class 'pluginregistry.Plugin2'>
+>>> if 'Plugin1' in registry:
+...     print(f"'Plugin1' is in registry.")
+'Plugin1' is in registry.
+

+ + +

+ +

+ + PluginRegistry(namespace_package: str, base_class: type) + + View Source + +

+ +

 71    def __init__(self, namespace_package: str, base_class: type) -> None:
+ 72        """Initialise registry.
+ 73
+ 74        Import all modules defined in the given namespace package (in any
+ 75        distribution package currently installed in the path). Then register
+ 76        all subclasses of the given base class as plugins.
+ 77
+ 78        >>> class BasePlugin:
+ 79        ...     pass
+ 80        >>> class Plugin1(BasePlugin):
+ 81        ...     pass
+ 82        >>> class Plugin2(BasePlugin):
+ 83        ...     pass
+ 84        >>> registry = PluginRegistry('importlib', BasePlugin)
+ 85        >>> for name in registry._plugins:
+ 86        ...     print(f"{name}: {registry._plugins[name]}")
+ 87        Plugin1: <class 'pluginregistry.Plugin1'>
+ 88        Plugin2: <class 'pluginregistry.Plugin2'>
+ 89        """
+ 90        ns_mod = importlib.import_module(namespace_package)
+ 91        ns_path = ns_mod.__path__
+ 92        ns_name = ns_mod.__name__
+ 93        for _, mod_name, _ in pkgutil.iter_modules(ns_path):
+ 94            importlib.import_module(f"{ns_name}.{mod_name}")
+ 95
+ 96        def all_subclasses(cls):
+ 97            result = []
+ 98            for subcls in cls.__subclasses__():
+ 99                result.append(subcls)
+100                result.extend(all_subclasses(subcls))
+101            return result
+102
+103        self._plugins = {cls.__name__: cls for cls in all_subclasses(base_class)}
+

+ + +

Initialise registry.

+ +

Import all modules defined in the given namespace package (in any +distribution package currently installed in the path). Then register +all subclasses of the given base class as plugins.

+ +

>>> class BasePlugin:
+...     pass
+>>> class Plugin1(BasePlugin):
+...     pass
+>>> class Plugin2(BasePlugin):
+...     pass
+>>> registry = PluginRegistry('importlib', BasePlugin)
+>>> for name in registry._plugins:
+...     print(f"{name}: {registry._plugins[name]}")
+Plugin1: <class 'pluginregistry.Plugin1'>
+Plugin2: <class 'pluginregistry.Plugin2'>
+

+ + +

+controlpi_plugins

+ + + + + +

+controlpi_plugins.state

+ +

Provide state plugins for all kinds of systems.

+ +

State represents a Boolean state.
StateAlias translates to another state-like client.
AndState combines several state-like clients by conjunction.
OrState combines several state-like clients by disjunction.
AndSet sets a state due to a conjunction of other state-like clients.
OrSet sets a state due to a disjunction of other state-like clients.

+ +

All these plugins use the following conventions:

+ +

If their state changes they send a message containing "event": "changed" +and "state": NEW STATE.
If their state is reported due to a message, but did not change they send +a message containing just "state": CURRENT STATE.
If they receive a message containing "target": NAME and +"command": "get state" they report their current state.
If State (or any other settable state using these conventions) receives +a message containing "target": NAME, "command": "set state" and +"new state": STATE TO SET it changes the state accordingly. If this +was really a change the corresponding event is sent. If it was already in +this state a report message without "event": "changed" is sent.
StateAlias can alias any message bus client using these conventions, not +just State instances. It translates all messages described here in both +directions.
AndState and OrState instances cannot be set.
AndState and OrState can combine any message bus clients using these +conventions, not just State instances. They only react to messages +containing "state" information.

+ +

>>> import asyncio
+>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test State": {"plugin": "State"},
+...      "Test State 2": {"plugin": "State"},
+...      "Test State 3": {"plugin": "State"},
+...      "Test State 4": {"plugin": "State"},
+...      "Test StateAlias": {"plugin": "StateAlias",
+...                          "alias for": "Test State 2"},
+...      "Test AndState": {"plugin": "AndState",
+...                        "states": ["Test State", "Test StateAlias"]},
+...      "Test OrState": {"plugin": "OrState",
+...                       "states": ["Test State", "Test StateAlias"]},
+...      "Test AndSet": {"plugin": "AndSet",
+...                      "input states": ["Test State", "Test StateAlias"],
+...                      "output state": "Test State 3"},
+...      "Test OrSet": {"plugin": "OrSet",
+...                      "input states": ["Test State", "Test StateAlias"],
+...                      "output state": "Test State 4"}},
+...     [{"target": "Test AndState",
+...       "command": "get state"},
+...      {"target": "Test OrState",
+...       "command": "get state"},
+...      {"target": "Test State",
+...       "command": "set state", "new state": True},
+...      {"target": "Test StateAlias",
+...       "command": "set state", "new state": True},
+...      {"target": "Test State",
+...       "command": "set state", "new state": False}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered', ...
+test(): {'sender': 'test()', 'target': 'Test AndState', 'command': 'get state'}
+test(): {'sender': 'test()', 'target': 'Test OrState', 'command': 'get state'}
+test(): {'sender': 'Test AndState', 'state': False}
+test(): {'sender': 'test()', 'target': 'Test State',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test OrState', 'state': False}
+test(): {'sender': 'test()', 'target': 'Test StateAlias',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test State', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test State',
+         'command': 'set state', 'new state': False}
+test(): {'sender': 'Test StateAlias', 'target': 'Test State 2',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test OrState', 'event': 'changed', 'state': True}
+test(): {'sender': 'Test OrSet', 'target': 'Test State 4',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test State', 'event': 'changed', 'state': False}
+test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+test(): {'sender': 'Test State 4', 'event': 'changed', 'state': True}
+

+ + + + View Source + +

  1"""Provide state plugins for all kinds of systems.
+  2
+  3- State represents a Boolean state.
+  4- StateAlias translates to another state-like client.
+  5- AndState combines several state-like clients by conjunction.
+  6- OrState combines several state-like clients by disjunction.
+  7- AndSet sets a state due to a conjunction of other state-like clients.
+  8- OrSet sets a state due to a disjunction of other state-like clients.
+  9
+ 10All these plugins use the following conventions:
+ 11
+ 12- If their state changes they send a message containing "event": "changed"
+ 13  and "state": NEW STATE.
+ 14- If their state is reported due to a message, but did not change they send
+ 15  a message containing just "state": CURRENT STATE.
+ 16- If they receive a message containing "target": NAME and
+ 17  "command": "get state" they report their current state.
+ 18- If State (or any other settable state using these conventions) receives
+ 19  a message containing "target": NAME, "command": "set state" and
+ 20  "new state": STATE TO SET it changes the state accordingly. If this
+ 21  was really a change the corresponding event is sent. If it was already in
+ 22  this state a report message without "event": "changed" is sent.
+ 23- StateAlias can alias any message bus client using these conventions, not
+ 24  just State instances. It translates all messages described here in both
+ 25  directions.
+ 26- AndState and OrState instances cannot be set.
+ 27- AndState and OrState can combine any message bus clients using these
+ 28  conventions, not just State instances. They only react to messages
+ 29  containing "state" information.
+ 30
+ 31>>> import asyncio
+ 32>>> import controlpi
+ 33>>> asyncio.run(controlpi.test(
+ 34...     {"Test State": {"plugin": "State"},
+ 35...      "Test State 2": {"plugin": "State"},
+ 36...      "Test State 3": {"plugin": "State"},
+ 37...      "Test State 4": {"plugin": "State"},
+ 38...      "Test StateAlias": {"plugin": "StateAlias",
+ 39...                          "alias for": "Test State 2"},
+ 40...      "Test AndState": {"plugin": "AndState",
+ 41...                        "states": ["Test State", "Test StateAlias"]},
+ 42...      "Test OrState": {"plugin": "OrState",
+ 43...                       "states": ["Test State", "Test StateAlias"]},
+ 44...      "Test AndSet": {"plugin": "AndSet",
+ 45...                      "input states": ["Test State", "Test StateAlias"],
+ 46...                      "output state": "Test State 3"},
+ 47...      "Test OrSet": {"plugin": "OrSet",
+ 48...                      "input states": ["Test State", "Test StateAlias"],
+ 49...                      "output state": "Test State 4"}},
+ 50...     [{"target": "Test AndState",
+ 51...       "command": "get state"},
+ 52...      {"target": "Test OrState",
+ 53...       "command": "get state"},
+ 54...      {"target": "Test State",
+ 55...       "command": "set state", "new state": True},
+ 56...      {"target": "Test StateAlias",
+ 57...       "command": "set state", "new state": True},
+ 58...      {"target": "Test State",
+ 59...       "command": "set state", "new state": False}]))
+ 60... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+ 61test(): {'sender': '', 'event': 'registered', ...
+ 62test(): {'sender': 'test()', 'target': 'Test AndState', 'command': 'get state'}
+ 63test(): {'sender': 'test()', 'target': 'Test OrState', 'command': 'get state'}
+ 64test(): {'sender': 'Test AndState', 'state': False}
+ 65test(): {'sender': 'test()', 'target': 'Test State',
+ 66         'command': 'set state', 'new state': True}
+ 67test(): {'sender': 'Test OrState', 'state': False}
+ 68test(): {'sender': 'test()', 'target': 'Test StateAlias',
+ 69         'command': 'set state', 'new state': True}
+ 70test(): {'sender': 'Test State', 'event': 'changed', 'state': True}
+ 71test(): {'sender': 'test()', 'target': 'Test State',
+ 72         'command': 'set state', 'new state': False}
+ 73test(): {'sender': 'Test StateAlias', 'target': 'Test State 2',
+ 74         'command': 'set state', 'new state': True}
+ 75test(): {'sender': 'Test OrState', 'event': 'changed', 'state': True}
+ 76test(): {'sender': 'Test OrSet', 'target': 'Test State 4',
+ 77         'command': 'set state', 'new state': True}
+ 78test(): {'sender': 'Test State', 'event': 'changed', 'state': False}
+ 79test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+ 80test(): {'sender': 'Test State 4', 'event': 'changed', 'state': True}
+ 81"""
+ 82
+ 83from controlpi import BasePlugin, Message, MessageTemplate
+ 84
+ 85from typing import Dict, List
+ 86
+ 87
+ 88class State(BasePlugin):
+ 89    """Provide a Boolean state.
+ 90
+ 91    The state of a State plugin instance can be queried with the "get state"
+ 92    command and set with the "set state" command to the new state given by
+ 93    the "new state" key:
+ 94    >>> import asyncio
+ 95    >>> import controlpi
+ 96    >>> asyncio.run(controlpi.test(
+ 97    ...     {"Test State": {"plugin": "State"}},
+ 98    ...     [{"target": "Test State", "command": "get state"},
+ 99    ...      {"target": "Test State", "command": "set state",
+100    ...       "new state": True},
+101    ...      {"target": "Test State", "command": "set state",
+102    ...       "new state": True},
+103    ...      {"target": "Test State", "command": "get state"}]))
+104    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+105    test(): {'sender': '', 'event': 'registered', ...
+106    test(): {'sender': 'test()', 'target': 'Test State',
+107             'command': 'get state'}
+108    test(): {'sender': 'test()', 'target': 'Test State',
+109             'command': 'set state', 'new state': True}
+110    test(): {'sender': 'Test State', 'state': False}
+111    test(): {'sender': 'test()', 'target': 'Test State',
+112             'command': 'set state', 'new state': True}
+113    test(): {'sender': 'Test State', 'event': 'changed', 'state': True}
+114    test(): {'sender': 'test()', 'target': 'Test State',
+115             'command': 'get state'}
+116    test(): {'sender': 'Test State', 'state': True}
+117    test(): {'sender': 'Test State', 'state': True}
+118    """
+119
+120    CONF_SCHEMA = True
+121    """Schema for State plugin configuration.
+122
+123    There are no required or optional configuration keys.
+124    """
+125
+126    def process_conf(self) -> None:
+127        """Register plugin as bus client."""
+128        self.state: bool = False
+129        self.bus.register(
+130            self.name,
+131            "State",
+132            [
+133                MessageTemplate(
+134                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+135                ),
+136                MessageTemplate({"state": {"type": "boolean"}}),
+137            ],
+138            [
+139                (
+140                    [
+141                        MessageTemplate(
+142                            {
+143                                "target": {"const": self.name},
+144                                "command": {"const": "get state"},
+145                            }
+146                        )
+147                    ],
+148                    self._get_state,
+149                ),
+150                (
+151                    [
+152                        MessageTemplate(
+153                            {
+154                                "target": {"const": self.name},
+155                                "command": {"const": "set state"},
+156                                "new state": {"type": "boolean"},
+157                            }
+158                        )
+159                    ],
+160                    self._set_state,
+161                ),
+162            ],
+163        )
+164
+165    async def _get_state(self, message: Message) -> None:
+166        await self.bus.send(Message(self.name, {"state": self.state}))
+167
+168    async def _set_state(self, message: Message) -> None:
+169        if self.state != message["new state"]:
+170            assert isinstance(message["new state"], bool)
+171            self.state = message["new state"]
+172            await self.bus.send(
+173                Message(self.name, {"event": "changed", "state": self.state})
+174            )
+175        else:
+176            await self.bus.send(Message(self.name, {"state": self.state}))
+177
+178    async def run(self) -> None:
+179        """Run no code proactively."""
+180        pass
+181
+182
+183class StateAlias(BasePlugin):
+184    """Define an alias for another state.
+185
+186    The "alias for" configuration key gets the name for the other state that
+187    is aliased by the StateAlias plugin instance.
+188
+189    The "get state" and "set state" commands are forwarded to and the
+190    "changed" events and "state" messages are forwarded from this other
+191    state:
+192    >>> import asyncio
+193    >>> import controlpi
+194    >>> asyncio.run(controlpi.test(
+195    ...     {"Test State": {"plugin": "State"},
+196    ...      "Test StateAlias": {"plugin": "StateAlias",
+197    ...                          "alias for": "Test State"}},
+198    ...     [{"target": "Test State", "command": "get state"},
+199    ...      {"target": "Test StateAlias", "command": "set state",
+200    ...       "new state": True},
+201    ...      {"target": "Test State", "command": "set state",
+202    ...       "new state": True},
+203    ...      {"target": "Test StateAlias", "command": "get state"}]))
+204    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+205    test(): {'sender': '', 'event': 'registered', ...
+206    test(): {'sender': 'test()', 'target': 'Test State',
+207             'command': 'get state'}
+208    test(): {'sender': 'test()', 'target': 'Test StateAlias',
+209             'command': 'set state', 'new state': True}
+210    test(): {'sender': 'Test State', 'state': False}
+211    test(): {'sender': 'test()', 'target': 'Test State',
+212             'command': 'set state', 'new state': True}
+213    test(): {'sender': 'Test StateAlias', 'target': 'Test State',
+214             'command': 'set state', 'new state': True}
+215    test(): {'sender': 'Test StateAlias', 'state': False}
+216    test(): {'sender': 'test()', 'target': 'Test StateAlias',
+217             'command': 'get state'}
+218    test(): {'sender': 'Test State', 'event': 'changed', 'state': True}
+219    test(): {'sender': 'Test State', 'state': True}
+220    test(): {'sender': 'Test StateAlias', 'target': 'Test State',
+221             'command': 'get state'}
+222    test(): {'sender': 'Test StateAlias', 'event': 'changed', 'state': True}
+223    test(): {'sender': 'Test StateAlias', 'state': True}
+224    """
+225
+226    CONF_SCHEMA = {
+227        "properties": {"alias for": {"type": "string"}},
+228        "required": ["alias for"],
+229    }
+230    """Schema for StateAlias plugin configuration.
+231
+232    Required configuration key:
+233
+234    - 'alias for': name of aliased state.
+235    """
+236
+237    def process_conf(self) -> None:
+238        """Register plugin as bus client."""
+239        self.bus.register(
+240            self.name,
+241            "StateAlias",
+242            [
+243                MessageTemplate(
+244                    {
+245                        "target": {"const": self.conf["alias for"]},
+246                        "command": {"const": "get state"},
+247                    }
+248                ),
+249                MessageTemplate(
+250                    {
+251                        "target": {"const": self.conf["alias for"]},
+252                        "command": {"const": "set state"},
+253                        "new state": {"type": "boolean"},
+254                    }
+255                ),
+256                MessageTemplate(
+257                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+258                ),
+259                MessageTemplate({"state": {"type": "boolean"}}),
+260            ],
+261            [
+262                (
+263                    [
+264                        MessageTemplate(
+265                            {
+266                                "target": {"const": self.name},
+267                                "command": {"const": "get state"},
+268                            }
+269                        )
+270                    ],
+271                    self._get_state,
+272                ),
+273                (
+274                    [
+275                        MessageTemplate(
+276                            {
+277                                "target": {"const": self.name},
+278                                "command": {"const": "set state"},
+279                                "new state": {"type": "boolean"},
+280                            }
+281                        )
+282                    ],
+283                    self._set_state,
+284                ),
+285                (
+286                    [
+287                        MessageTemplate(
+288                            {
+289                                "sender": {"const": self.conf["alias for"]},
+290                                "state": {"type": "boolean"},
+291                            }
+292                        )
+293                    ],
+294                    self._translate,
+295                ),
+296            ],
+297        )
+298
+299    async def _get_state(self, message: Message) -> None:
+300        await self.bus.send(
+301            Message(
+302                self.name, {"target": self.conf["alias for"], "command": "get state"}
+303            )
+304        )
+305
+306    async def _set_state(self, message: Message) -> None:
+307        await self.bus.send(
+308            Message(
+309                self.name,
+310                {
+311                    "target": self.conf["alias for"],
+312                    "command": "set state",
+313                    "new state": message["new state"],
+314                },
+315            )
+316        )
+317
+318    async def _translate(self, message: Message) -> None:
+319        alias_message = Message(self.name)
+320        if "event" in message and message["event"] == "changed":
+321            alias_message["event"] = "changed"
+322        alias_message["state"] = message["state"]
+323        await self.bus.send(alias_message)
+324
+325    async def run(self) -> None:
+326        """Run no code proactively."""
+327        pass
+328
+329
+330class AndState(BasePlugin):
+331    """Define conjunction of states.
+332
+333    The "states" configuration key gets an array of states to be combined.
+334    An AndState plugin client reacts to "get state" commands and sends
+335    "changed" events when a change in one of the combined states leads to
+336    a change for the conjunction:
+337    >>> import asyncio
+338    >>> import controlpi
+339    >>> asyncio.run(controlpi.test(
+340    ...     {"Test State 1": {"plugin": "State"},
+341    ...      "Test State 2": {"plugin": "State"},
+342    ...      "Test AndState": {"plugin": "AndState",
+343    ...                        "states": ["Test State 1", "Test State 2"]}},
+344    ...     [{"target": "Test State 1", "command": "set state",
+345    ...       "new state": True},
+346    ...      {"target": "Test State 2", "command": "set state",
+347    ...       "new state": True},
+348    ...      {"target": "Test State 1", "command": "set state",
+349    ...       "new state": False},
+350    ...      {"target": "Test AndState", "command": "get state"},
+351    ...      {"target": "Test AndState", "command": "get sources"}]))
+352    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+353    test(): {'sender': '', 'event': 'registered', ...
+354    test(): {'sender': 'test()', 'target': 'Test State 1',
+355             'command': 'set state', 'new state': True}
+356    test(): {'sender': 'test()', 'target': 'Test State 2',
+357             'command': 'set state', 'new state': True}
+358    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+359    test(): {'sender': 'test()', 'target': 'Test State 1',
+360             'command': 'set state', 'new state': False}
+361    test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+362    test(): {'sender': 'test()', 'target': 'Test AndState',
+363             'command': 'get state'}
+364    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+365    test(): {'sender': 'Test AndState', 'event': 'changed', 'state': True}
+366    test(): {'sender': 'test()', 'target': 'Test AndState',
+367             'command': 'get sources'}
+368    test(): {'sender': 'Test AndState', 'state': True}
+369    test(): {'sender': 'Test AndState', 'event': 'changed', 'state': False}
+370    test(): {'sender': 'Test AndState',
+371             'states': ['Test State 1', 'Test State 2']}
+372    """
+373
+374    CONF_SCHEMA = {
+375        "properties": {"states": {"type": "array", "items": {"type": "string"}}},
+376        "required": ["states"],
+377    }
+378    """Schema for AndState plugin configuration.
+379
+380    Required configuration key:
+381
+382    - 'states': list of names of combined states.
+383    """
+384
+385    def process_conf(self) -> None:
+386        """Register plugin as bus client."""
+387        updates: List[MessageTemplate] = []
+388        self.states: Dict[str, bool] = {}
+389        for state in self.conf["states"]:
+390            updates.append(
+391                MessageTemplate(
+392                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+393                )
+394            )
+395            self.states[state] = False
+396        self.state: bool = all(self.states.values())
+397        self.bus.register(
+398            self.name,
+399            "AndState",
+400            [
+401                MessageTemplate(
+402                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+403                ),
+404                MessageTemplate({"state": {"type": "boolean"}}),
+405                MessageTemplate(
+406                    {"states": {"type": "array", "items": {"type": "string"}}}
+407                ),
+408            ],
+409            [
+410                (
+411                    [
+412                        MessageTemplate(
+413                            {
+414                                "target": {"const": self.name},
+415                                "command": {"const": "get state"},
+416                            }
+417                        )
+418                    ],
+419                    self._get_state,
+420                ),
+421                (
+422                    [
+423                        MessageTemplate(
+424                            {
+425                                "target": {"const": self.name},
+426                                "command": {"const": "get sources"},
+427                            }
+428                        )
+429                    ],
+430                    self._get_sources,
+431                ),
+432                (updates, self._update),
+433            ],
+434        )
+435
+436    async def _get_state(self, message: Message) -> None:
+437        await self.bus.send(Message(self.name, {"state": self.state}))
+438
+439    async def _get_sources(self, message: Message) -> None:
+440        source_states = list(self.states.keys())
+441        await self.bus.send(Message(self.name, {"states": source_states}))
+442
+443    async def _update(self, message: Message) -> None:
+444        assert isinstance(message["sender"], str)
+445        assert isinstance(message["state"], bool)
+446        self.states[message["sender"]] = message["state"]
+447        new_state = all(self.states.values())
+448        if self.state != new_state:
+449            self.state = new_state
+450            await self.bus.send(
+451                Message(self.name, {"event": "changed", "state": self.state})
+452            )
+453
+454    async def run(self) -> None:
+455        """Run no code proactively."""
+456        pass
+457
+458
+459class OrState(BasePlugin):
+460    """Define disjunction of states.
+461
+462    The "states" configuration key gets an array of states to be combined.
+463    An OrState plugin client reacts to "get state" commands and sends
+464    "changed" events when a change in one of the combined states leads to
+465    a change for the disjunction:
+466    >>> import asyncio
+467    >>> import controlpi
+468    >>> asyncio.run(controlpi.test(
+469    ...     {"Test State 1": {"plugin": "State"},
+470    ...      "Test State 2": {"plugin": "State"},
+471    ...      "Test OrState": {"plugin": "OrState",
+472    ...                       "states": ["Test State 1", "Test State 2"]}},
+473    ...     [{"target": "Test State 1", "command": "set state",
+474    ...       "new state": True},
+475    ...      {"target": "Test State 2", "command": "set state",
+476    ...       "new state": True},
+477    ...      {"target": "Test State 1", "command": "set state",
+478    ...       "new state": False},
+479    ...      {"target": "Test OrState", "command": "get state"},
+480    ...      {"target": "Test OrState", "command": "get sources"}]))
+481    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+482    test(): {'sender': '', 'event': 'registered', ...
+483    test(): {'sender': 'test()', 'target': 'Test State 1',
+484             'command': 'set state', 'new state': True}
+485    test(): {'sender': 'test()', 'target': 'Test State 2',
+486             'command': 'set state', 'new state': True}
+487    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+488    test(): {'sender': 'test()', 'target': 'Test State 1',
+489             'command': 'set state', 'new state': False}
+490    test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+491    test(): {'sender': 'Test OrState', 'event': 'changed', 'state': True}
+492    test(): {'sender': 'test()', 'target': 'Test OrState',
+493             'command': 'get state'}
+494    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+495    test(): {'sender': 'test()', 'target': 'Test OrState',
+496             'command': 'get sources'}
+497    test(): {'sender': 'Test OrState', 'state': True}
+498    test(): {'sender': 'Test OrState',
+499             'states': ['Test State 1', 'Test State 2']}
+500    """
+501
+502    CONF_SCHEMA = {
+503        "properties": {"states": {"type": "array", "items": {"type": "string"}}},
+504        "required": ["states"],
+505    }
+506    """Schema for OrState plugin configuration.
+507
+508    Required configuration key:
+509
+510    - 'states': list of names of combined states.
+511    """
+512
+513    def process_conf(self) -> None:
+514        """Register plugin as bus client."""
+515        updates: List[MessageTemplate] = []
+516        self.states: Dict[str, bool] = {}
+517        for state in self.conf["states"]:
+518            updates.append(
+519                MessageTemplate(
+520                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+521                )
+522            )
+523            self.states[state] = False
+524        self.state: bool = any(self.states.values())
+525        self.bus.register(
+526            self.name,
+527            "OrState",
+528            [
+529                MessageTemplate(
+530                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+531                ),
+532                MessageTemplate({"state": {"type": "boolean"}}),
+533                MessageTemplate(
+534                    {"states": {"type": "array", "items": {"type": "string"}}}
+535                ),
+536            ],
+537            [
+538                (
+539                    [
+540                        MessageTemplate(
+541                            {
+542                                "target": {"const": self.name},
+543                                "command": {"const": "get state"},
+544                            }
+545                        )
+546                    ],
+547                    self._get_state,
+548                ),
+549                (
+550                    [
+551                        MessageTemplate(
+552                            {
+553                                "target": {"const": self.name},
+554                                "command": {"const": "get sources"},
+555                            }
+556                        )
+557                    ],
+558                    self._get_sources,
+559                ),
+560                (updates, self._update),
+561            ],
+562        )
+563
+564    async def _get_state(self, message: Message) -> None:
+565        await self.bus.send(Message(self.name, {"state": self.state}))
+566
+567    async def _get_sources(self, message: Message) -> None:
+568        source_states = list(self.states.keys())
+569        await self.bus.send(Message(self.name, {"states": source_states}))
+570
+571    async def _update(self, message: Message) -> None:
+572        assert isinstance(message["sender"], str)
+573        assert isinstance(message["state"], bool)
+574        self.states[message["sender"]] = message["state"]
+575        new_state = any(self.states.values())
+576        if self.state != new_state:
+577            self.state = new_state
+578            await self.bus.send(
+579                Message(self.name, {"event": "changed", "state": self.state})
+580            )
+581
+582    async def run(self) -> None:
+583        """Run no code proactively."""
+584        pass
+585
+586
+587class AndSet(BasePlugin):
+588    """Set state based on conjunction of other states.
+589
+590    The "input states" configuration key gets an array of states used to
+591    determine the state in the "output state" configuration key:
+592    >>> import asyncio
+593    >>> import controlpi
+594    >>> asyncio.run(controlpi.test(
+595    ...     {"Test State 1": {"plugin": "State"},
+596    ...      "Test State 2": {"plugin": "State"},
+597    ...      "Test State 3": {"plugin": "State"},
+598    ...      "Test AndSet": {"plugin": "AndSet",
+599    ...                      "input states": ["Test State 1",
+600    ...                                       "Test State 2"],
+601    ...                      "output state": "Test State 3"}},
+602    ...     [{"target": "Test State 1", "command": "set state",
+603    ...       "new state": True},
+604    ...      {"target": "Test State 2", "command": "set state",
+605    ...       "new state": True},
+606    ...      {"target": "Test AndSet", "command": "get state"},
+607    ...      {"target": "Test State 1", "command": "set state",
+608    ...       "new state": False},
+609    ...      {"target": "Test AndSet", "command": "get state"},
+610    ...      {"target": "Test AndSet", "command": "get sources"}]))
+611    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+612    test(): {'sender': '', 'event': 'registered', ...
+613    test(): {'sender': 'test()', 'target': 'Test State 1',
+614             'command': 'set state', 'new state': True}
+615    test(): {'sender': 'test()', 'target': 'Test State 2',
+616             'command': 'set state', 'new state': True}
+617    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+618    test(): {'sender': 'test()', 'target': 'Test AndSet',
+619             'command': 'get state'}
+620    test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+621    test(): {'sender': 'test()', 'target': 'Test State 1',
+622             'command': 'set state', 'new state': False}
+623    test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+624             'command': 'set state', 'new state': False}
+625    test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+626             'command': 'set state', 'new state': True}
+627    test(): {'sender': 'test()', 'target': 'Test AndSet',
+628             'command': 'get state'}
+629    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+630    test(): {'sender': 'Test State 3', 'state': False}
+631    test(): {'sender': 'Test State 3', 'event': 'changed', 'state': True}
+632    test(): {'sender': 'test()', 'target': 'Test AndSet',
+633             'command': 'get sources'}
+634    test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+635             'command': 'set state', 'new state': True}
+636    test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+637             'command': 'set state', 'new state': False}
+638    test(): {'sender': 'Test AndSet',
+639             'states': ['Test State 1', 'Test State 2']}
+640    test(): {'sender': 'Test State 3', 'state': True}
+641    test(): {'sender': 'Test State 3', 'event': 'changed', 'state': False}
+642    """
+643
+644    CONF_SCHEMA = {
+645        "properties": {
+646            "input states": {"type": "array", "items": {"type": "string"}},
+647            "output state": {"type": "string"},
+648        },
+649        "required": ["input states", "output state"],
+650    }
+651    """Schema for AndSet plugin configuration.
+652
+653    Required configuration keys:
+654
+655    - 'input states': list of names of combined states.
+656    - 'output state': name of state to be set.
+657    """
+658
+659    def process_conf(self) -> None:
+660        """Register plugin as bus client."""
+661        updates: List[MessageTemplate] = []
+662        self.states: Dict[str, bool] = {}
+663        for state in self.conf["input states"]:
+664            updates.append(
+665                MessageTemplate(
+666                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+667                )
+668            )
+669            self.states[state] = False
+670        self.state: bool = all(self.states.values())
+671        self.bus.register(
+672            self.name,
+673            "AndSet",
+674            [
+675                MessageTemplate(
+676                    {
+677                        "target": {"const": self.conf["output state"]},
+678                        "command": {"const": "set state"},
+679                        "new state": {"type": "boolean"},
+680                    }
+681                ),
+682                MessageTemplate(
+683                    {"states": {"type": "array", "items": {"type": "string"}}}
+684                ),
+685            ],
+686            [
+687                (
+688                    [
+689                        MessageTemplate(
+690                            {
+691                                "target": {"const": self.name},
+692                                "command": {"const": "get state"},
+693                            }
+694                        )
+695                    ],
+696                    self._get_state,
+697                ),
+698                (
+699                    [
+700                        MessageTemplate(
+701                            {
+702                                "target": {"const": self.name},
+703                                "command": {"const": "get sources"},
+704                            }
+705                        )
+706                    ],
+707                    self._get_sources,
+708                ),
+709                (updates, self._update),
+710            ],
+711        )
+712
+713    async def _get_state(self, message: Message) -> None:
+714        await self.bus.send(
+715            Message(
+716                self.name,
+717                {
+718                    "target": self.conf["output state"],
+719                    "command": "set state",
+720                    "new state": self.state,
+721                },
+722            )
+723        )
+724
+725    async def _get_sources(self, message: Message) -> None:
+726        source_states = list(self.states.keys())
+727        await self.bus.send(Message(self.name, {"states": source_states}))
+728
+729    async def _update(self, message: Message) -> None:
+730        assert isinstance(message["sender"], str)
+731        assert isinstance(message["state"], bool)
+732        self.states[message["sender"]] = message["state"]
+733        new_state = all(self.states.values())
+734        if self.state != new_state:
+735            self.state = new_state
+736            await self.bus.send(
+737                Message(
+738                    self.name,
+739                    {
+740                        "target": self.conf["output state"],
+741                        "command": "set state",
+742                        "new state": self.state,
+743                    },
+744                )
+745            )
+746
+747    async def run(self) -> None:
+748        """Run no code proactively."""
+749        pass
+750
+751
+752class OrSet(BasePlugin):
+753    """Set state based on disjunction of other states.
+754
+755    The "input states" configuration key gets an array of states used to
+756    determine the state in the "output state" configuration key:
+757    >>> import asyncio
+758    >>> import controlpi
+759    >>> asyncio.run(controlpi.test(
+760    ...     {"Test State 1": {"plugin": "State"},
+761    ...      "Test State 2": {"plugin": "State"},
+762    ...      "Test State 3": {"plugin": "State"},
+763    ...      "Test OrSet": {"plugin": "OrSet",
+764    ...                      "input states": ["Test State 1",
+765    ...                                       "Test State 2"],
+766    ...                      "output state": "Test State 3"}},
+767    ...     [{"target": "Test State 1", "command": "set state",
+768    ...       "new state": True},
+769    ...      {"target": "Test OrSet", "command": "get state"},
+770    ...      {"target": "Test State 2", "command": "set state",
+771    ...       "new state": True},
+772    ...      {"target": "Test State 1", "command": "set state",
+773    ...       "new state": False},
+774    ...      {"target": "Test OrSet", "command": "get sources"}]))
+775    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+776    test(): {'sender': '', 'event': 'registered', ...
+777    test(): {'sender': 'test()', 'target': 'Test State 1',
+778             'command': 'set state', 'new state': True}
+779    test(): {'sender': 'test()', 'target': 'Test OrSet',
+780             'command': 'get state'}
+781    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+782    test(): {'sender': 'test()', 'target': 'Test State 2',
+783             'command': 'set state', 'new state': True}
+784    test(): {'sender': 'Test OrSet', 'target': 'Test State 3',
+785             'command': 'set state', 'new state': False}
+786    test(): {'sender': 'Test OrSet', 'target': 'Test State 3',
+787             'command': 'set state', 'new state': True}
+788    test(): {'sender': 'test()', 'target': 'Test State 1',
+789             'command': 'set state', 'new state': False}
+790    test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+791    test(): {'sender': 'Test State 3', 'state': False}
+792    test(): {'sender': 'Test State 3', 'event': 'changed', 'state': True}
+793    test(): {'sender': 'test()', 'target': 'Test OrSet',
+794             'command': 'get sources'}
+795    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+796    test(): {'sender': 'Test OrSet',
+797             'states': ['Test State 1', 'Test State 2']}
+798    """
+799
+800    CONF_SCHEMA = {
+801        "properties": {
+802            "input states": {"type": "array", "items": {"type": "string"}},
+803            "output state": {"type": "string"},
+804        },
+805        "required": ["input states", "output state"],
+806    }
+807    """Schema for OrSet plugin configuration.
+808
+809    Required configuration keys:
+810
+811    - 'input states': list of names of combined states.
+812    - 'output state': name of state to be set.
+813    """
+814
+815    def process_conf(self) -> None:
+816        """Register plugin as bus client."""
+817        updates: List[MessageTemplate] = []
+818        self.states: Dict[str, bool] = {}
+819        for state in self.conf["input states"]:
+820            updates.append(
+821                MessageTemplate(
+822                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+823                )
+824            )
+825            self.states[state] = False
+826        self.state: bool = any(self.states.values())
+827        self.bus.register(
+828            self.name,
+829            "AndSet",
+830            [
+831                MessageTemplate(
+832                    {
+833                        "target": {"const": self.conf["output state"]},
+834                        "command": {"const": "set state"},
+835                        "new state": {"type": "boolean"},
+836                    }
+837                ),
+838                MessageTemplate(
+839                    {"states": {"type": "array", "items": {"type": "string"}}}
+840                ),
+841            ],
+842            [
+843                (
+844                    [
+845                        MessageTemplate(
+846                            {
+847                                "target": {"const": self.name},
+848                                "command": {"const": "get state"},
+849                            }
+850                        )
+851                    ],
+852                    self._get_state,
+853                ),
+854                (
+855                    [
+856                        MessageTemplate(
+857                            {
+858                                "target": {"const": self.name},
+859                                "command": {"const": "get sources"},
+860                            }
+861                        )
+862                    ],
+863                    self._get_sources,
+864                ),
+865                (updates, self._update),
+866            ],
+867        )
+868
+869    async def _get_state(self, message: Message) -> None:
+870        await self.bus.send(
+871            Message(
+872                self.name,
+873                {
+874                    "target": self.conf["output state"],
+875                    "command": "set state",
+876                    "new state": self.state,
+877                },
+878            )
+879        )
+880
+881    async def _get_sources(self, message: Message) -> None:
+882        source_states = list(self.states.keys())
+883        await self.bus.send(Message(self.name, {"states": source_states}))
+884
+885    async def _update(self, message: Message) -> None:
+886        assert isinstance(message["sender"], str)
+887        assert isinstance(message["state"], bool)
+888        self.states[message["sender"]] = message["state"]
+889        new_state = any(self.states.values())
+890        if self.state != new_state:
+891            self.state = new_state
+892            await self.bus.send(
+893                Message(
+894                    self.name,
+895                    {
+896                        "target": self.conf["output state"],
+897                        "command": "set state",
+898                        "new state": self.state,
+899                    },
+900                )
+901            )
+902
+903    async def run(self) -> None:
+904        """Run no code proactively."""
+905        pass
+

+ + +

+ +

+ + class + State(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

 89class State(BasePlugin):
+ 90    """Provide a Boolean state.
+ 91
+ 92    The state of a State plugin instance can be queried with the "get state"
+ 93    command and set with the "set state" command to the new state given by
+ 94    the "new state" key:
+ 95    >>> import asyncio
+ 96    >>> import controlpi
+ 97    >>> asyncio.run(controlpi.test(
+ 98    ...     {"Test State": {"plugin": "State"}},
+ 99    ...     [{"target": "Test State", "command": "get state"},
+100    ...      {"target": "Test State", "command": "set state",
+101    ...       "new state": True},
+102    ...      {"target": "Test State", "command": "set state",
+103    ...       "new state": True},
+104    ...      {"target": "Test State", "command": "get state"}]))
+105    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+106    test(): {'sender': '', 'event': 'registered', ...
+107    test(): {'sender': 'test()', 'target': 'Test State',
+108             'command': 'get state'}
+109    test(): {'sender': 'test()', 'target': 'Test State',
+110             'command': 'set state', 'new state': True}
+111    test(): {'sender': 'Test State', 'state': False}
+112    test(): {'sender': 'test()', 'target': 'Test State',
+113             'command': 'set state', 'new state': True}
+114    test(): {'sender': 'Test State', 'event': 'changed', 'state': True}
+115    test(): {'sender': 'test()', 'target': 'Test State',
+116             'command': 'get state'}
+117    test(): {'sender': 'Test State', 'state': True}
+118    test(): {'sender': 'Test State', 'state': True}
+119    """
+120
+121    CONF_SCHEMA = True
+122    """Schema for State plugin configuration.
+123
+124    There are no required or optional configuration keys.
+125    """
+126
+127    def process_conf(self) -> None:
+128        """Register plugin as bus client."""
+129        self.state: bool = False
+130        self.bus.register(
+131            self.name,
+132            "State",
+133            [
+134                MessageTemplate(
+135                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+136                ),
+137                MessageTemplate({"state": {"type": "boolean"}}),
+138            ],
+139            [
+140                (
+141                    [
+142                        MessageTemplate(
+143                            {
+144                                "target": {"const": self.name},
+145                                "command": {"const": "get state"},
+146                            }
+147                        )
+148                    ],
+149                    self._get_state,
+150                ),
+151                (
+152                    [
+153                        MessageTemplate(
+154                            {
+155                                "target": {"const": self.name},
+156                                "command": {"const": "set state"},
+157                                "new state": {"type": "boolean"},
+158                            }
+159                        )
+160                    ],
+161                    self._set_state,
+162                ),
+163            ],
+164        )
+165
+166    async def _get_state(self, message: Message) -> None:
+167        await self.bus.send(Message(self.name, {"state": self.state}))
+168
+169    async def _set_state(self, message: Message) -> None:
+170        if self.state != message["new state"]:
+171            assert isinstance(message["new state"], bool)
+172            self.state = message["new state"]
+173            await self.bus.send(
+174                Message(self.name, {"event": "changed", "state": self.state})
+175            )
+176        else:
+177            await self.bus.send(Message(self.name, {"state": self.state}))
+178
+179    async def run(self) -> None:
+180        """Run no code proactively."""
+181        pass
+

+ + +

Provide a Boolean state.

+ +

The state of a State plugin instance can be queried with the "get state" +command and set with the "set state" command to the new state given by +the "new state" key:

+ +

>>> import asyncio
+>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test State": {"plugin": "State"}},
+...     [{"target": "Test State", "command": "get state"},
+...      {"target": "Test State", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State", "command": "get state"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered', ...
+test(): {'sender': 'test()', 'target': 'Test State',
+         'command': 'get state'}
+test(): {'sender': 'test()', 'target': 'Test State',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test State', 'state': False}
+test(): {'sender': 'test()', 'target': 'Test State',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test State', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test State',
+         'command': 'get state'}
+test(): {'sender': 'Test State', 'state': True}
+test(): {'sender': 'Test State', 'state': True}
+

+ + +

+ CONF_SCHEMA = +True + + +

+ + +

Schema for State plugin configuration.

+ +

There are no required or optional configuration keys.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

127    def process_conf(self) -> None:
+128        """Register plugin as bus client."""
+129        self.state: bool = False
+130        self.bus.register(
+131            self.name,
+132            "State",
+133            [
+134                MessageTemplate(
+135                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+136                ),
+137                MessageTemplate({"state": {"type": "boolean"}}),
+138            ],
+139            [
+140                (
+141                    [
+142                        MessageTemplate(
+143                            {
+144                                "target": {"const": self.name},
+145                                "command": {"const": "get state"},
+146                            }
+147                        )
+148                    ],
+149                    self._get_state,
+150                ),
+151                (
+152                    [
+153                        MessageTemplate(
+154                            {
+155                                "target": {"const": self.name},
+156                                "command": {"const": "set state"},
+157                                "new state": {"type": "boolean"},
+158                            }
+159                        )
+160                    ],
+161                    self._set_state,
+162                ),
+163            ],
+164        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

179    async def run(self) -> None:
+180        """Run no code proactively."""
+181        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + StateAlias(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

184class StateAlias(BasePlugin):
+185    """Define an alias for another state.
+186
+187    The "alias for" configuration key gets the name for the other state that
+188    is aliased by the StateAlias plugin instance.
+189
+190    The "get state" and "set state" commands are forwarded to and the
+191    "changed" events and "state" messages are forwarded from this other
+192    state:
+193    >>> import asyncio
+194    >>> import controlpi
+195    >>> asyncio.run(controlpi.test(
+196    ...     {"Test State": {"plugin": "State"},
+197    ...      "Test StateAlias": {"plugin": "StateAlias",
+198    ...                          "alias for": "Test State"}},
+199    ...     [{"target": "Test State", "command": "get state"},
+200    ...      {"target": "Test StateAlias", "command": "set state",
+201    ...       "new state": True},
+202    ...      {"target": "Test State", "command": "set state",
+203    ...       "new state": True},
+204    ...      {"target": "Test StateAlias", "command": "get state"}]))
+205    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+206    test(): {'sender': '', 'event': 'registered', ...
+207    test(): {'sender': 'test()', 'target': 'Test State',
+208             'command': 'get state'}
+209    test(): {'sender': 'test()', 'target': 'Test StateAlias',
+210             'command': 'set state', 'new state': True}
+211    test(): {'sender': 'Test State', 'state': False}
+212    test(): {'sender': 'test()', 'target': 'Test State',
+213             'command': 'set state', 'new state': True}
+214    test(): {'sender': 'Test StateAlias', 'target': 'Test State',
+215             'command': 'set state', 'new state': True}
+216    test(): {'sender': 'Test StateAlias', 'state': False}
+217    test(): {'sender': 'test()', 'target': 'Test StateAlias',
+218             'command': 'get state'}
+219    test(): {'sender': 'Test State', 'event': 'changed', 'state': True}
+220    test(): {'sender': 'Test State', 'state': True}
+221    test(): {'sender': 'Test StateAlias', 'target': 'Test State',
+222             'command': 'get state'}
+223    test(): {'sender': 'Test StateAlias', 'event': 'changed', 'state': True}
+224    test(): {'sender': 'Test StateAlias', 'state': True}
+225    """
+226
+227    CONF_SCHEMA = {
+228        "properties": {"alias for": {"type": "string"}},
+229        "required": ["alias for"],
+230    }
+231    """Schema for StateAlias plugin configuration.
+232
+233    Required configuration key:
+234
+235    - 'alias for': name of aliased state.
+236    """
+237
+238    def process_conf(self) -> None:
+239        """Register plugin as bus client."""
+240        self.bus.register(
+241            self.name,
+242            "StateAlias",
+243            [
+244                MessageTemplate(
+245                    {
+246                        "target": {"const": self.conf["alias for"]},
+247                        "command": {"const": "get state"},
+248                    }
+249                ),
+250                MessageTemplate(
+251                    {
+252                        "target": {"const": self.conf["alias for"]},
+253                        "command": {"const": "set state"},
+254                        "new state": {"type": "boolean"},
+255                    }
+256                ),
+257                MessageTemplate(
+258                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+259                ),
+260                MessageTemplate({"state": {"type": "boolean"}}),
+261            ],
+262            [
+263                (
+264                    [
+265                        MessageTemplate(
+266                            {
+267                                "target": {"const": self.name},
+268                                "command": {"const": "get state"},
+269                            }
+270                        )
+271                    ],
+272                    self._get_state,
+273                ),
+274                (
+275                    [
+276                        MessageTemplate(
+277                            {
+278                                "target": {"const": self.name},
+279                                "command": {"const": "set state"},
+280                                "new state": {"type": "boolean"},
+281                            }
+282                        )
+283                    ],
+284                    self._set_state,
+285                ),
+286                (
+287                    [
+288                        MessageTemplate(
+289                            {
+290                                "sender": {"const": self.conf["alias for"]},
+291                                "state": {"type": "boolean"},
+292                            }
+293                        )
+294                    ],
+295                    self._translate,
+296                ),
+297            ],
+298        )
+299
+300    async def _get_state(self, message: Message) -> None:
+301        await self.bus.send(
+302            Message(
+303                self.name, {"target": self.conf["alias for"], "command": "get state"}
+304            )
+305        )
+306
+307    async def _set_state(self, message: Message) -> None:
+308        await self.bus.send(
+309            Message(
+310                self.name,
+311                {
+312                    "target": self.conf["alias for"],
+313                    "command": "set state",
+314                    "new state": message["new state"],
+315                },
+316            )
+317        )
+318
+319    async def _translate(self, message: Message) -> None:
+320        alias_message = Message(self.name)
+321        if "event" in message and message["event"] == "changed":
+322            alias_message["event"] = "changed"
+323        alias_message["state"] = message["state"]
+324        await self.bus.send(alias_message)
+325
+326    async def run(self) -> None:
+327        """Run no code proactively."""
+328        pass
+

+ + +

Define an alias for another state.

+ +

The "alias for" configuration key gets the name for the other state that +is aliased by the StateAlias plugin instance.

+ +

The "get state" and "set state" commands are forwarded to and the +"changed" events and "state" messages are forwarded from this other +state:

+ +

>>> import asyncio
+>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test State": {"plugin": "State"},
+...      "Test StateAlias": {"plugin": "StateAlias",
+...                          "alias for": "Test State"}},
+...     [{"target": "Test State", "command": "get state"},
+...      {"target": "Test StateAlias", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State", "command": "set state",
+...       "new state": True},
+...      {"target": "Test StateAlias", "command": "get state"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered', ...
+test(): {'sender': 'test()', 'target': 'Test State',
+         'command': 'get state'}
+test(): {'sender': 'test()', 'target': 'Test StateAlias',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test State', 'state': False}
+test(): {'sender': 'test()', 'target': 'Test State',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test StateAlias', 'target': 'Test State',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test StateAlias', 'state': False}
+test(): {'sender': 'test()', 'target': 'Test StateAlias',
+         'command': 'get state'}
+test(): {'sender': 'Test State', 'event': 'changed', 'state': True}
+test(): {'sender': 'Test State', 'state': True}
+test(): {'sender': 'Test StateAlias', 'target': 'Test State',
+         'command': 'get state'}
+test(): {'sender': 'Test StateAlias', 'event': 'changed', 'state': True}
+test(): {'sender': 'Test StateAlias', 'state': True}
+

+ + +

+ CONF_SCHEMA = +{'properties': {'alias for': {'type': 'string'}}, 'required': ['alias for']} + + +

+ + +

Schema for StateAlias plugin configuration.

+ +

Required configuration key:

+ +

'alias for': name of aliased state.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

238    def process_conf(self) -> None:
+239        """Register plugin as bus client."""
+240        self.bus.register(
+241            self.name,
+242            "StateAlias",
+243            [
+244                MessageTemplate(
+245                    {
+246                        "target": {"const": self.conf["alias for"]},
+247                        "command": {"const": "get state"},
+248                    }
+249                ),
+250                MessageTemplate(
+251                    {
+252                        "target": {"const": self.conf["alias for"]},
+253                        "command": {"const": "set state"},
+254                        "new state": {"type": "boolean"},
+255                    }
+256                ),
+257                MessageTemplate(
+258                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+259                ),
+260                MessageTemplate({"state": {"type": "boolean"}}),
+261            ],
+262            [
+263                (
+264                    [
+265                        MessageTemplate(
+266                            {
+267                                "target": {"const": self.name},
+268                                "command": {"const": "get state"},
+269                            }
+270                        )
+271                    ],
+272                    self._get_state,
+273                ),
+274                (
+275                    [
+276                        MessageTemplate(
+277                            {
+278                                "target": {"const": self.name},
+279                                "command": {"const": "set state"},
+280                                "new state": {"type": "boolean"},
+281                            }
+282                        )
+283                    ],
+284                    self._set_state,
+285                ),
+286                (
+287                    [
+288                        MessageTemplate(
+289                            {
+290                                "sender": {"const": self.conf["alias for"]},
+291                                "state": {"type": "boolean"},
+292                            }
+293                        )
+294                    ],
+295                    self._translate,
+296                ),
+297            ],
+298        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

326    async def run(self) -> None:
+327        """Run no code proactively."""
+328        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + AndState(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

331class AndState(BasePlugin):
+332    """Define conjunction of states.
+333
+334    The "states" configuration key gets an array of states to be combined.
+335    An AndState plugin client reacts to "get state" commands and sends
+336    "changed" events when a change in one of the combined states leads to
+337    a change for the conjunction:
+338    >>> import asyncio
+339    >>> import controlpi
+340    >>> asyncio.run(controlpi.test(
+341    ...     {"Test State 1": {"plugin": "State"},
+342    ...      "Test State 2": {"plugin": "State"},
+343    ...      "Test AndState": {"plugin": "AndState",
+344    ...                        "states": ["Test State 1", "Test State 2"]}},
+345    ...     [{"target": "Test State 1", "command": "set state",
+346    ...       "new state": True},
+347    ...      {"target": "Test State 2", "command": "set state",
+348    ...       "new state": True},
+349    ...      {"target": "Test State 1", "command": "set state",
+350    ...       "new state": False},
+351    ...      {"target": "Test AndState", "command": "get state"},
+352    ...      {"target": "Test AndState", "command": "get sources"}]))
+353    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+354    test(): {'sender': '', 'event': 'registered', ...
+355    test(): {'sender': 'test()', 'target': 'Test State 1',
+356             'command': 'set state', 'new state': True}
+357    test(): {'sender': 'test()', 'target': 'Test State 2',
+358             'command': 'set state', 'new state': True}
+359    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+360    test(): {'sender': 'test()', 'target': 'Test State 1',
+361             'command': 'set state', 'new state': False}
+362    test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+363    test(): {'sender': 'test()', 'target': 'Test AndState',
+364             'command': 'get state'}
+365    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+366    test(): {'sender': 'Test AndState', 'event': 'changed', 'state': True}
+367    test(): {'sender': 'test()', 'target': 'Test AndState',
+368             'command': 'get sources'}
+369    test(): {'sender': 'Test AndState', 'state': True}
+370    test(): {'sender': 'Test AndState', 'event': 'changed', 'state': False}
+371    test(): {'sender': 'Test AndState',
+372             'states': ['Test State 1', 'Test State 2']}
+373    """
+374
+375    CONF_SCHEMA = {
+376        "properties": {"states": {"type": "array", "items": {"type": "string"}}},
+377        "required": ["states"],
+378    }
+379    """Schema for AndState plugin configuration.
+380
+381    Required configuration key:
+382
+383    - 'states': list of names of combined states.
+384    """
+385
+386    def process_conf(self) -> None:
+387        """Register plugin as bus client."""
+388        updates: List[MessageTemplate] = []
+389        self.states: Dict[str, bool] = {}
+390        for state in self.conf["states"]:
+391            updates.append(
+392                MessageTemplate(
+393                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+394                )
+395            )
+396            self.states[state] = False
+397        self.state: bool = all(self.states.values())
+398        self.bus.register(
+399            self.name,
+400            "AndState",
+401            [
+402                MessageTemplate(
+403                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+404                ),
+405                MessageTemplate({"state": {"type": "boolean"}}),
+406                MessageTemplate(
+407                    {"states": {"type": "array", "items": {"type": "string"}}}
+408                ),
+409            ],
+410            [
+411                (
+412                    [
+413                        MessageTemplate(
+414                            {
+415                                "target": {"const": self.name},
+416                                "command": {"const": "get state"},
+417                            }
+418                        )
+419                    ],
+420                    self._get_state,
+421                ),
+422                (
+423                    [
+424                        MessageTemplate(
+425                            {
+426                                "target": {"const": self.name},
+427                                "command": {"const": "get sources"},
+428                            }
+429                        )
+430                    ],
+431                    self._get_sources,
+432                ),
+433                (updates, self._update),
+434            ],
+435        )
+436
+437    async def _get_state(self, message: Message) -> None:
+438        await self.bus.send(Message(self.name, {"state": self.state}))
+439
+440    async def _get_sources(self, message: Message) -> None:
+441        source_states = list(self.states.keys())
+442        await self.bus.send(Message(self.name, {"states": source_states}))
+443
+444    async def _update(self, message: Message) -> None:
+445        assert isinstance(message["sender"], str)
+446        assert isinstance(message["state"], bool)
+447        self.states[message["sender"]] = message["state"]
+448        new_state = all(self.states.values())
+449        if self.state != new_state:
+450            self.state = new_state
+451            await self.bus.send(
+452                Message(self.name, {"event": "changed", "state": self.state})
+453            )
+454
+455    async def run(self) -> None:
+456        """Run no code proactively."""
+457        pass
+

+ + +

Define conjunction of states.

+ +

The "states" configuration key gets an array of states to be combined. +An AndState plugin client reacts to "get state" commands and sends +"changed" events when a change in one of the combined states leads to +a change for the conjunction:

+ +

>>> import asyncio
+>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test State 1": {"plugin": "State"},
+...      "Test State 2": {"plugin": "State"},
+...      "Test AndState": {"plugin": "AndState",
+...                        "states": ["Test State 1", "Test State 2"]}},
+...     [{"target": "Test State 1", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State 2", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State 1", "command": "set state",
+...       "new state": False},
+...      {"target": "Test AndState", "command": "get state"},
+...      {"target": "Test AndState", "command": "get sources"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered', ...
+test(): {'sender': 'test()', 'target': 'Test State 1',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'test()', 'target': 'Test State 2',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test State 1',
+         'command': 'set state', 'new state': False}
+test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test AndState',
+         'command': 'get state'}
+test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+test(): {'sender': 'Test AndState', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test AndState',
+         'command': 'get sources'}
+test(): {'sender': 'Test AndState', 'state': True}
+test(): {'sender': 'Test AndState', 'event': 'changed', 'state': False}
+test(): {'sender': 'Test AndState',
+         'states': ['Test State 1', 'Test State 2']}
+

+ + +

+ CONF_SCHEMA = +{'properties': {'states': {'type': 'array', 'items': {'type': 'string'}}}, 'required': ['states']} + + +

+ + +

Schema for AndState plugin configuration.

+ +

Required configuration key:

+ +

'states': list of names of combined states.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

386    def process_conf(self) -> None:
+387        """Register plugin as bus client."""
+388        updates: List[MessageTemplate] = []
+389        self.states: Dict[str, bool] = {}
+390        for state in self.conf["states"]:
+391            updates.append(
+392                MessageTemplate(
+393                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+394                )
+395            )
+396            self.states[state] = False
+397        self.state: bool = all(self.states.values())
+398        self.bus.register(
+399            self.name,
+400            "AndState",
+401            [
+402                MessageTemplate(
+403                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+404                ),
+405                MessageTemplate({"state": {"type": "boolean"}}),
+406                MessageTemplate(
+407                    {"states": {"type": "array", "items": {"type": "string"}}}
+408                ),
+409            ],
+410            [
+411                (
+412                    [
+413                        MessageTemplate(
+414                            {
+415                                "target": {"const": self.name},
+416                                "command": {"const": "get state"},
+417                            }
+418                        )
+419                    ],
+420                    self._get_state,
+421                ),
+422                (
+423                    [
+424                        MessageTemplate(
+425                            {
+426                                "target": {"const": self.name},
+427                                "command": {"const": "get sources"},
+428                            }
+429                        )
+430                    ],
+431                    self._get_sources,
+432                ),
+433                (updates, self._update),
+434            ],
+435        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

455    async def run(self) -> None:
+456        """Run no code proactively."""
+457        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + OrState(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

460class OrState(BasePlugin):
+461    """Define disjunction of states.
+462
+463    The "states" configuration key gets an array of states to be combined.
+464    An OrState plugin client reacts to "get state" commands and sends
+465    "changed" events when a change in one of the combined states leads to
+466    a change for the disjunction:
+467    >>> import asyncio
+468    >>> import controlpi
+469    >>> asyncio.run(controlpi.test(
+470    ...     {"Test State 1": {"plugin": "State"},
+471    ...      "Test State 2": {"plugin": "State"},
+472    ...      "Test OrState": {"plugin": "OrState",
+473    ...                       "states": ["Test State 1", "Test State 2"]}},
+474    ...     [{"target": "Test State 1", "command": "set state",
+475    ...       "new state": True},
+476    ...      {"target": "Test State 2", "command": "set state",
+477    ...       "new state": True},
+478    ...      {"target": "Test State 1", "command": "set state",
+479    ...       "new state": False},
+480    ...      {"target": "Test OrState", "command": "get state"},
+481    ...      {"target": "Test OrState", "command": "get sources"}]))
+482    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+483    test(): {'sender': '', 'event': 'registered', ...
+484    test(): {'sender': 'test()', 'target': 'Test State 1',
+485             'command': 'set state', 'new state': True}
+486    test(): {'sender': 'test()', 'target': 'Test State 2',
+487             'command': 'set state', 'new state': True}
+488    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+489    test(): {'sender': 'test()', 'target': 'Test State 1',
+490             'command': 'set state', 'new state': False}
+491    test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+492    test(): {'sender': 'Test OrState', 'event': 'changed', 'state': True}
+493    test(): {'sender': 'test()', 'target': 'Test OrState',
+494             'command': 'get state'}
+495    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+496    test(): {'sender': 'test()', 'target': 'Test OrState',
+497             'command': 'get sources'}
+498    test(): {'sender': 'Test OrState', 'state': True}
+499    test(): {'sender': 'Test OrState',
+500             'states': ['Test State 1', 'Test State 2']}
+501    """
+502
+503    CONF_SCHEMA = {
+504        "properties": {"states": {"type": "array", "items": {"type": "string"}}},
+505        "required": ["states"],
+506    }
+507    """Schema for OrState plugin configuration.
+508
+509    Required configuration key:
+510
+511    - 'states': list of names of combined states.
+512    """
+513
+514    def process_conf(self) -> None:
+515        """Register plugin as bus client."""
+516        updates: List[MessageTemplate] = []
+517        self.states: Dict[str, bool] = {}
+518        for state in self.conf["states"]:
+519            updates.append(
+520                MessageTemplate(
+521                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+522                )
+523            )
+524            self.states[state] = False
+525        self.state: bool = any(self.states.values())
+526        self.bus.register(
+527            self.name,
+528            "OrState",
+529            [
+530                MessageTemplate(
+531                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+532                ),
+533                MessageTemplate({"state": {"type": "boolean"}}),
+534                MessageTemplate(
+535                    {"states": {"type": "array", "items": {"type": "string"}}}
+536                ),
+537            ],
+538            [
+539                (
+540                    [
+541                        MessageTemplate(
+542                            {
+543                                "target": {"const": self.name},
+544                                "command": {"const": "get state"},
+545                            }
+546                        )
+547                    ],
+548                    self._get_state,
+549                ),
+550                (
+551                    [
+552                        MessageTemplate(
+553                            {
+554                                "target": {"const": self.name},
+555                                "command": {"const": "get sources"},
+556                            }
+557                        )
+558                    ],
+559                    self._get_sources,
+560                ),
+561                (updates, self._update),
+562            ],
+563        )
+564
+565    async def _get_state(self, message: Message) -> None:
+566        await self.bus.send(Message(self.name, {"state": self.state}))
+567
+568    async def _get_sources(self, message: Message) -> None:
+569        source_states = list(self.states.keys())
+570        await self.bus.send(Message(self.name, {"states": source_states}))
+571
+572    async def _update(self, message: Message) -> None:
+573        assert isinstance(message["sender"], str)
+574        assert isinstance(message["state"], bool)
+575        self.states[message["sender"]] = message["state"]
+576        new_state = any(self.states.values())
+577        if self.state != new_state:
+578            self.state = new_state
+579            await self.bus.send(
+580                Message(self.name, {"event": "changed", "state": self.state})
+581            )
+582
+583    async def run(self) -> None:
+584        """Run no code proactively."""
+585        pass
+

+ + +

Define disjunction of states.

+ +

The "states" configuration key gets an array of states to be combined. +An OrState plugin client reacts to "get state" commands and sends +"changed" events when a change in one of the combined states leads to +a change for the disjunction:

+ +

>>> import asyncio
+>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test State 1": {"plugin": "State"},
+...      "Test State 2": {"plugin": "State"},
+...      "Test OrState": {"plugin": "OrState",
+...                       "states": ["Test State 1", "Test State 2"]}},
+...     [{"target": "Test State 1", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State 2", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State 1", "command": "set state",
+...       "new state": False},
+...      {"target": "Test OrState", "command": "get state"},
+...      {"target": "Test OrState", "command": "get sources"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered', ...
+test(): {'sender': 'test()', 'target': 'Test State 1',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'test()', 'target': 'Test State 2',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test State 1',
+         'command': 'set state', 'new state': False}
+test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+test(): {'sender': 'Test OrState', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test OrState',
+         'command': 'get state'}
+test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+test(): {'sender': 'test()', 'target': 'Test OrState',
+         'command': 'get sources'}
+test(): {'sender': 'Test OrState', 'state': True}
+test(): {'sender': 'Test OrState',
+         'states': ['Test State 1', 'Test State 2']}
+

+ + +

+ CONF_SCHEMA = +{'properties': {'states': {'type': 'array', 'items': {'type': 'string'}}}, 'required': ['states']} + + +

+ + +

Schema for OrState plugin configuration.

+ +

Required configuration key:

+ +

'states': list of names of combined states.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

514    def process_conf(self) -> None:
+515        """Register plugin as bus client."""
+516        updates: List[MessageTemplate] = []
+517        self.states: Dict[str, bool] = {}
+518        for state in self.conf["states"]:
+519            updates.append(
+520                MessageTemplate(
+521                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+522                )
+523            )
+524            self.states[state] = False
+525        self.state: bool = any(self.states.values())
+526        self.bus.register(
+527            self.name,
+528            "OrState",
+529            [
+530                MessageTemplate(
+531                    {"event": {"const": "changed"}, "state": {"type": "boolean"}}
+532                ),
+533                MessageTemplate({"state": {"type": "boolean"}}),
+534                MessageTemplate(
+535                    {"states": {"type": "array", "items": {"type": "string"}}}
+536                ),
+537            ],
+538            [
+539                (
+540                    [
+541                        MessageTemplate(
+542                            {
+543                                "target": {"const": self.name},
+544                                "command": {"const": "get state"},
+545                            }
+546                        )
+547                    ],
+548                    self._get_state,
+549                ),
+550                (
+551                    [
+552                        MessageTemplate(
+553                            {
+554                                "target": {"const": self.name},
+555                                "command": {"const": "get sources"},
+556                            }
+557                        )
+558                    ],
+559                    self._get_sources,
+560                ),
+561                (updates, self._update),
+562            ],
+563        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

583    async def run(self) -> None:
+584        """Run no code proactively."""
+585        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + AndSet(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

588class AndSet(BasePlugin):
+589    """Set state based on conjunction of other states.
+590
+591    The "input states" configuration key gets an array of states used to
+592    determine the state in the "output state" configuration key:
+593    >>> import asyncio
+594    >>> import controlpi
+595    >>> asyncio.run(controlpi.test(
+596    ...     {"Test State 1": {"plugin": "State"},
+597    ...      "Test State 2": {"plugin": "State"},
+598    ...      "Test State 3": {"plugin": "State"},
+599    ...      "Test AndSet": {"plugin": "AndSet",
+600    ...                      "input states": ["Test State 1",
+601    ...                                       "Test State 2"],
+602    ...                      "output state": "Test State 3"}},
+603    ...     [{"target": "Test State 1", "command": "set state",
+604    ...       "new state": True},
+605    ...      {"target": "Test State 2", "command": "set state",
+606    ...       "new state": True},
+607    ...      {"target": "Test AndSet", "command": "get state"},
+608    ...      {"target": "Test State 1", "command": "set state",
+609    ...       "new state": False},
+610    ...      {"target": "Test AndSet", "command": "get state"},
+611    ...      {"target": "Test AndSet", "command": "get sources"}]))
+612    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+613    test(): {'sender': '', 'event': 'registered', ...
+614    test(): {'sender': 'test()', 'target': 'Test State 1',
+615             'command': 'set state', 'new state': True}
+616    test(): {'sender': 'test()', 'target': 'Test State 2',
+617             'command': 'set state', 'new state': True}
+618    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+619    test(): {'sender': 'test()', 'target': 'Test AndSet',
+620             'command': 'get state'}
+621    test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+622    test(): {'sender': 'test()', 'target': 'Test State 1',
+623             'command': 'set state', 'new state': False}
+624    test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+625             'command': 'set state', 'new state': False}
+626    test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+627             'command': 'set state', 'new state': True}
+628    test(): {'sender': 'test()', 'target': 'Test AndSet',
+629             'command': 'get state'}
+630    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+631    test(): {'sender': 'Test State 3', 'state': False}
+632    test(): {'sender': 'Test State 3', 'event': 'changed', 'state': True}
+633    test(): {'sender': 'test()', 'target': 'Test AndSet',
+634             'command': 'get sources'}
+635    test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+636             'command': 'set state', 'new state': True}
+637    test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+638             'command': 'set state', 'new state': False}
+639    test(): {'sender': 'Test AndSet',
+640             'states': ['Test State 1', 'Test State 2']}
+641    test(): {'sender': 'Test State 3', 'state': True}
+642    test(): {'sender': 'Test State 3', 'event': 'changed', 'state': False}
+643    """
+644
+645    CONF_SCHEMA = {
+646        "properties": {
+647            "input states": {"type": "array", "items": {"type": "string"}},
+648            "output state": {"type": "string"},
+649        },
+650        "required": ["input states", "output state"],
+651    }
+652    """Schema for AndSet plugin configuration.
+653
+654    Required configuration keys:
+655
+656    - 'input states': list of names of combined states.
+657    - 'output state': name of state to be set.
+658    """
+659
+660    def process_conf(self) -> None:
+661        """Register plugin as bus client."""
+662        updates: List[MessageTemplate] = []
+663        self.states: Dict[str, bool] = {}
+664        for state in self.conf["input states"]:
+665            updates.append(
+666                MessageTemplate(
+667                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+668                )
+669            )
+670            self.states[state] = False
+671        self.state: bool = all(self.states.values())
+672        self.bus.register(
+673            self.name,
+674            "AndSet",
+675            [
+676                MessageTemplate(
+677                    {
+678                        "target": {"const": self.conf["output state"]},
+679                        "command": {"const": "set state"},
+680                        "new state": {"type": "boolean"},
+681                    }
+682                ),
+683                MessageTemplate(
+684                    {"states": {"type": "array", "items": {"type": "string"}}}
+685                ),
+686            ],
+687            [
+688                (
+689                    [
+690                        MessageTemplate(
+691                            {
+692                                "target": {"const": self.name},
+693                                "command": {"const": "get state"},
+694                            }
+695                        )
+696                    ],
+697                    self._get_state,
+698                ),
+699                (
+700                    [
+701                        MessageTemplate(
+702                            {
+703                                "target": {"const": self.name},
+704                                "command": {"const": "get sources"},
+705                            }
+706                        )
+707                    ],
+708                    self._get_sources,
+709                ),
+710                (updates, self._update),
+711            ],
+712        )
+713
+714    async def _get_state(self, message: Message) -> None:
+715        await self.bus.send(
+716            Message(
+717                self.name,
+718                {
+719                    "target": self.conf["output state"],
+720                    "command": "set state",
+721                    "new state": self.state,
+722                },
+723            )
+724        )
+725
+726    async def _get_sources(self, message: Message) -> None:
+727        source_states = list(self.states.keys())
+728        await self.bus.send(Message(self.name, {"states": source_states}))
+729
+730    async def _update(self, message: Message) -> None:
+731        assert isinstance(message["sender"], str)
+732        assert isinstance(message["state"], bool)
+733        self.states[message["sender"]] = message["state"]
+734        new_state = all(self.states.values())
+735        if self.state != new_state:
+736            self.state = new_state
+737            await self.bus.send(
+738                Message(
+739                    self.name,
+740                    {
+741                        "target": self.conf["output state"],
+742                        "command": "set state",
+743                        "new state": self.state,
+744                    },
+745                )
+746            )
+747
+748    async def run(self) -> None:
+749        """Run no code proactively."""
+750        pass
+

+ + +

Set state based on conjunction of other states.

+ +

The "input states" configuration key gets an array of states used to +determine the state in the "output state" configuration key:

+ +

>>> import asyncio
+>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test State 1": {"plugin": "State"},
+...      "Test State 2": {"plugin": "State"},
+...      "Test State 3": {"plugin": "State"},
+...      "Test AndSet": {"plugin": "AndSet",
+...                      "input states": ["Test State 1",
+...                                       "Test State 2"],
+...                      "output state": "Test State 3"}},
+...     [{"target": "Test State 1", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State 2", "command": "set state",
+...       "new state": True},
+...      {"target": "Test AndSet", "command": "get state"},
+...      {"target": "Test State 1", "command": "set state",
+...       "new state": False},
+...      {"target": "Test AndSet", "command": "get state"},
+...      {"target": "Test AndSet", "command": "get sources"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered', ...
+test(): {'sender': 'test()', 'target': 'Test State 1',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'test()', 'target': 'Test State 2',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test AndSet',
+         'command': 'get state'}
+test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test State 1',
+         'command': 'set state', 'new state': False}
+test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+         'command': 'set state', 'new state': False}
+test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'test()', 'target': 'Test AndSet',
+         'command': 'get state'}
+test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+test(): {'sender': 'Test State 3', 'state': False}
+test(): {'sender': 'Test State 3', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test AndSet',
+         'command': 'get sources'}
+test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test AndSet', 'target': 'Test State 3',
+         'command': 'set state', 'new state': False}
+test(): {'sender': 'Test AndSet',
+         'states': ['Test State 1', 'Test State 2']}
+test(): {'sender': 'Test State 3', 'state': True}
+test(): {'sender': 'Test State 3', 'event': 'changed', 'state': False}
+

+ + +

+ CONF_SCHEMA = + + {'properties': {'input states': {'type': 'array', 'items': {'type': 'string'}}, 'output state': {'type': 'string'}}, 'required': ['input states', 'output state']} + + +

+ + +

Schema for AndSet plugin configuration.

+ +

Required configuration keys:

+ +

'input states': list of names of combined states.
'output state': name of state to be set.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

660    def process_conf(self) -> None:
+661        """Register plugin as bus client."""
+662        updates: List[MessageTemplate] = []
+663        self.states: Dict[str, bool] = {}
+664        for state in self.conf["input states"]:
+665            updates.append(
+666                MessageTemplate(
+667                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+668                )
+669            )
+670            self.states[state] = False
+671        self.state: bool = all(self.states.values())
+672        self.bus.register(
+673            self.name,
+674            "AndSet",
+675            [
+676                MessageTemplate(
+677                    {
+678                        "target": {"const": self.conf["output state"]},
+679                        "command": {"const": "set state"},
+680                        "new state": {"type": "boolean"},
+681                    }
+682                ),
+683                MessageTemplate(
+684                    {"states": {"type": "array", "items": {"type": "string"}}}
+685                ),
+686            ],
+687            [
+688                (
+689                    [
+690                        MessageTemplate(
+691                            {
+692                                "target": {"const": self.name},
+693                                "command": {"const": "get state"},
+694                            }
+695                        )
+696                    ],
+697                    self._get_state,
+698                ),
+699                (
+700                    [
+701                        MessageTemplate(
+702                            {
+703                                "target": {"const": self.name},
+704                                "command": {"const": "get sources"},
+705                            }
+706                        )
+707                    ],
+708                    self._get_sources,
+709                ),
+710                (updates, self._update),
+711            ],
+712        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

748    async def run(self) -> None:
+749        """Run no code proactively."""
+750        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + OrSet(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

753class OrSet(BasePlugin):
+754    """Set state based on disjunction of other states.
+755
+756    The "input states" configuration key gets an array of states used to
+757    determine the state in the "output state" configuration key:
+758    >>> import asyncio
+759    >>> import controlpi
+760    >>> asyncio.run(controlpi.test(
+761    ...     {"Test State 1": {"plugin": "State"},
+762    ...      "Test State 2": {"plugin": "State"},
+763    ...      "Test State 3": {"plugin": "State"},
+764    ...      "Test OrSet": {"plugin": "OrSet",
+765    ...                      "input states": ["Test State 1",
+766    ...                                       "Test State 2"],
+767    ...                      "output state": "Test State 3"}},
+768    ...     [{"target": "Test State 1", "command": "set state",
+769    ...       "new state": True},
+770    ...      {"target": "Test OrSet", "command": "get state"},
+771    ...      {"target": "Test State 2", "command": "set state",
+772    ...       "new state": True},
+773    ...      {"target": "Test State 1", "command": "set state",
+774    ...       "new state": False},
+775    ...      {"target": "Test OrSet", "command": "get sources"}]))
+776    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+777    test(): {'sender': '', 'event': 'registered', ...
+778    test(): {'sender': 'test()', 'target': 'Test State 1',
+779             'command': 'set state', 'new state': True}
+780    test(): {'sender': 'test()', 'target': 'Test OrSet',
+781             'command': 'get state'}
+782    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+783    test(): {'sender': 'test()', 'target': 'Test State 2',
+784             'command': 'set state', 'new state': True}
+785    test(): {'sender': 'Test OrSet', 'target': 'Test State 3',
+786             'command': 'set state', 'new state': False}
+787    test(): {'sender': 'Test OrSet', 'target': 'Test State 3',
+788             'command': 'set state', 'new state': True}
+789    test(): {'sender': 'test()', 'target': 'Test State 1',
+790             'command': 'set state', 'new state': False}
+791    test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+792    test(): {'sender': 'Test State 3', 'state': False}
+793    test(): {'sender': 'Test State 3', 'event': 'changed', 'state': True}
+794    test(): {'sender': 'test()', 'target': 'Test OrSet',
+795             'command': 'get sources'}
+796    test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+797    test(): {'sender': 'Test OrSet',
+798             'states': ['Test State 1', 'Test State 2']}
+799    """
+800
+801    CONF_SCHEMA = {
+802        "properties": {
+803            "input states": {"type": "array", "items": {"type": "string"}},
+804            "output state": {"type": "string"},
+805        },
+806        "required": ["input states", "output state"],
+807    }
+808    """Schema for OrSet plugin configuration.
+809
+810    Required configuration keys:
+811
+812    - 'input states': list of names of combined states.
+813    - 'output state': name of state to be set.
+814    """
+815
+816    def process_conf(self) -> None:
+817        """Register plugin as bus client."""
+818        updates: List[MessageTemplate] = []
+819        self.states: Dict[str, bool] = {}
+820        for state in self.conf["input states"]:
+821            updates.append(
+822                MessageTemplate(
+823                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+824                )
+825            )
+826            self.states[state] = False
+827        self.state: bool = any(self.states.values())
+828        self.bus.register(
+829            self.name,
+830            "AndSet",
+831            [
+832                MessageTemplate(
+833                    {
+834                        "target": {"const": self.conf["output state"]},
+835                        "command": {"const": "set state"},
+836                        "new state": {"type": "boolean"},
+837                    }
+838                ),
+839                MessageTemplate(
+840                    {"states": {"type": "array", "items": {"type": "string"}}}
+841                ),
+842            ],
+843            [
+844                (
+845                    [
+846                        MessageTemplate(
+847                            {
+848                                "target": {"const": self.name},
+849                                "command": {"const": "get state"},
+850                            }
+851                        )
+852                    ],
+853                    self._get_state,
+854                ),
+855                (
+856                    [
+857                        MessageTemplate(
+858                            {
+859                                "target": {"const": self.name},
+860                                "command": {"const": "get sources"},
+861                            }
+862                        )
+863                    ],
+864                    self._get_sources,
+865                ),
+866                (updates, self._update),
+867            ],
+868        )
+869
+870    async def _get_state(self, message: Message) -> None:
+871        await self.bus.send(
+872            Message(
+873                self.name,
+874                {
+875                    "target": self.conf["output state"],
+876                    "command": "set state",
+877                    "new state": self.state,
+878                },
+879            )
+880        )
+881
+882    async def _get_sources(self, message: Message) -> None:
+883        source_states = list(self.states.keys())
+884        await self.bus.send(Message(self.name, {"states": source_states}))
+885
+886    async def _update(self, message: Message) -> None:
+887        assert isinstance(message["sender"], str)
+888        assert isinstance(message["state"], bool)
+889        self.states[message["sender"]] = message["state"]
+890        new_state = any(self.states.values())
+891        if self.state != new_state:
+892            self.state = new_state
+893            await self.bus.send(
+894                Message(
+895                    self.name,
+896                    {
+897                        "target": self.conf["output state"],
+898                        "command": "set state",
+899                        "new state": self.state,
+900                    },
+901                )
+902            )
+903
+904    async def run(self) -> None:
+905        """Run no code proactively."""
+906        pass
+

+ + +

Set state based on disjunction of other states.

+ +

The "input states" configuration key gets an array of states used to +determine the state in the "output state" configuration key:

+ +

>>> import asyncio
+>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test State 1": {"plugin": "State"},
+...      "Test State 2": {"plugin": "State"},
+...      "Test State 3": {"plugin": "State"},
+...      "Test OrSet": {"plugin": "OrSet",
+...                      "input states": ["Test State 1",
+...                                       "Test State 2"],
+...                      "output state": "Test State 3"}},
+...     [{"target": "Test State 1", "command": "set state",
+...       "new state": True},
+...      {"target": "Test OrSet", "command": "get state"},
+...      {"target": "Test State 2", "command": "set state",
+...       "new state": True},
+...      {"target": "Test State 1", "command": "set state",
+...       "new state": False},
+...      {"target": "Test OrSet", "command": "get sources"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered', ...
+test(): {'sender': 'test()', 'target': 'Test State 1',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'test()', 'target': 'Test OrSet',
+         'command': 'get state'}
+test(): {'sender': 'Test State 1', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test State 2',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'Test OrSet', 'target': 'Test State 3',
+         'command': 'set state', 'new state': False}
+test(): {'sender': 'Test OrSet', 'target': 'Test State 3',
+         'command': 'set state', 'new state': True}
+test(): {'sender': 'test()', 'target': 'Test State 1',
+         'command': 'set state', 'new state': False}
+test(): {'sender': 'Test State 2', 'event': 'changed', 'state': True}
+test(): {'sender': 'Test State 3', 'state': False}
+test(): {'sender': 'Test State 3', 'event': 'changed', 'state': True}
+test(): {'sender': 'test()', 'target': 'Test OrSet',
+         'command': 'get sources'}
+test(): {'sender': 'Test State 1', 'event': 'changed', 'state': False}
+test(): {'sender': 'Test OrSet',
+         'states': ['Test State 1', 'Test State 2']}
+

+ + +

+ CONF_SCHEMA = + + {'properties': {'input states': {'type': 'array', 'items': {'type': 'string'}}, 'output state': {'type': 'string'}}, 'required': ['input states', 'output state']} + + +

+ + +

Schema for OrSet plugin configuration.

+ +

Required configuration keys:

+ +

'input states': list of names of combined states.
'output state': name of state to be set.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

816    def process_conf(self) -> None:
+817        """Register plugin as bus client."""
+818        updates: List[MessageTemplate] = []
+819        self.states: Dict[str, bool] = {}
+820        for state in self.conf["input states"]:
+821            updates.append(
+822                MessageTemplate(
+823                    {"sender": {"const": state}, "state": {"type": "boolean"}}
+824                )
+825            )
+826            self.states[state] = False
+827        self.state: bool = any(self.states.values())
+828        self.bus.register(
+829            self.name,
+830            "AndSet",
+831            [
+832                MessageTemplate(
+833                    {
+834                        "target": {"const": self.conf["output state"]},
+835                        "command": {"const": "set state"},
+836                        "new state": {"type": "boolean"},
+837                    }
+838                ),
+839                MessageTemplate(
+840                    {"states": {"type": "array", "items": {"type": "string"}}}
+841                ),
+842            ],
+843            [
+844                (
+845                    [
+846                        MessageTemplate(
+847                            {
+848                                "target": {"const": self.name},
+849                                "command": {"const": "get state"},
+850                            }
+851                        )
+852                    ],
+853                    self._get_state,
+854                ),
+855                (
+856                    [
+857                        MessageTemplate(
+858                            {
+859                                "target": {"const": self.name},
+860                                "command": {"const": "get sources"},
+861                            }
+862                        )
+863                    ],
+864                    self._get_sources,
+865                ),
+866                (updates, self._update),
+867            ],
+868        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

904    async def run(self) -> None:
+905        """Run no code proactively."""
+906        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+controlpi_plugins.util

+ +

Provide utility plugins for all kinds of systems.

+ +

Log logs messages on stdout.
Init sends list of messages on startup and on demand.
Execute sends configurable list of messages on demand.
Alias translates messages to an alias.

+ +

>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test Log": {"plugin": "Log",
+...                   "filter": [{"sender": {"const": "Test Alias"}}]},
+...      "Test Init": {"plugin": "Init",
+...                    "messages": [{"id": 42, "content": "Test Message"}]},
+...      "Test Alias": {"plugin": "Alias",
+...                     "from": {"sender": {"const": "Test Init"},
+...                              "id": {"const": 42}},
+...                     "to": {"id": "translated"}}}, []))
+... # doctest: +NORMALIZE_WHITESPACE
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Log', 'plugin': 'Log',
+         'sends': [], 'receives': [{'sender': {'const': 'Test Alias'}}]}
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Init', 'plugin': 'Init',
+         'sends': [{'id': {'const': 42},
+                    'content': {'const': 'Test Message'}}],
+         'receives': [{'target': {'const': 'Test Init'},
+                       'command': {'const': 'execute'}}]}
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Alias', 'plugin': 'Alias',
+         'sends': [{'id': {'const': 'translated'}}],
+         'receives': [{'sender': {'const': 'Test Init'},
+                       'id': {'const': 42}}]}
+test(): {'sender': 'Test Init', 'id': 42,
+         'content': 'Test Message'}
+test(): {'sender': 'Test Alias', 'id': 'translated',
+         'content': 'Test Message'}
+Test Log: {'sender': 'Test Alias', 'id': 'translated',
+           'content': 'Test Message'}
+

+ + + + View Source + +

  1"""Provide utility plugins for all kinds of systems.
+  2
+  3- Log logs messages on stdout.
+  4- Init sends list of messages on startup and on demand.
+  5- Execute sends configurable list of messages on demand.
+  6- Alias translates messages to an alias.
+  7
+  8>>> import controlpi
+  9>>> asyncio.run(controlpi.test(
+ 10...     {"Test Log": {"plugin": "Log",
+ 11...                   "filter": [{"sender": {"const": "Test Alias"}}]},
+ 12...      "Test Init": {"plugin": "Init",
+ 13...                    "messages": [{"id": 42, "content": "Test Message"}]},
+ 14...      "Test Alias": {"plugin": "Alias",
+ 15...                     "from": {"sender": {"const": "Test Init"},
+ 16...                              "id": {"const": 42}},
+ 17...                     "to": {"id": "translated"}}}, []))
+ 18... # doctest: +NORMALIZE_WHITESPACE
+ 19test(): {'sender': '', 'event': 'registered',
+ 20         'client': 'Test Log', 'plugin': 'Log',
+ 21         'sends': [], 'receives': [{'sender': {'const': 'Test Alias'}}]}
+ 22test(): {'sender': '', 'event': 'registered',
+ 23         'client': 'Test Init', 'plugin': 'Init',
+ 24         'sends': [{'id': {'const': 42},
+ 25                    'content': {'const': 'Test Message'}}],
+ 26         'receives': [{'target': {'const': 'Test Init'},
+ 27                       'command': {'const': 'execute'}}]}
+ 28test(): {'sender': '', 'event': 'registered',
+ 29         'client': 'Test Alias', 'plugin': 'Alias',
+ 30         'sends': [{'id': {'const': 'translated'}}],
+ 31         'receives': [{'sender': {'const': 'Test Init'},
+ 32                       'id': {'const': 42}}]}
+ 33test(): {'sender': 'Test Init', 'id': 42,
+ 34         'content': 'Test Message'}
+ 35test(): {'sender': 'Test Alias', 'id': 'translated',
+ 36         'content': 'Test Message'}
+ 37Test Log: {'sender': 'Test Alias', 'id': 'translated',
+ 38           'content': 'Test Message'}
+ 39"""
+ 40
+ 41import asyncio
+ 42from datetime import datetime
+ 43
+ 44from controlpi import BasePlugin, Message, MessageTemplate
+ 45
+ 46from typing import List
+ 47
+ 48
+ 49class Log(BasePlugin):
+ 50    """Log messages on stdout.
+ 51
+ 52    The "filter" configuration key gets a list of message templates defining
+ 53    the messages that should be logged by the plugin instance.
+ 54
+ 55    In the following example the first and third message match the given
+ 56    template and are logged by the instance "Test Log", while the second
+ 57    message does not match and is only logged by the test, but not by the
+ 58    Log instance:
+ 59    >>> import controlpi
+ 60    >>> asyncio.run(controlpi.test(
+ 61    ...     {"Test Log": {"plugin": "Log",
+ 62    ...                   "filter": [{"id": {"const": 42}}]}},
+ 63    ...     [{"id": 42, "message": "Test Message"},
+ 64    ...      {"id": 42.42, "message": "Second Message"},
+ 65    ...      {"id": 42, "message": "Third Message"}]))
+ 66    ... # doctest: +NORMALIZE_WHITESPACE
+ 67    test(): {'sender': '', 'event': 'registered',
+ 68             'client': 'Test Log', 'plugin': 'Log',
+ 69             'sends': [], 'receives': [{'id': {'const': 42}}]}
+ 70    test(): {'sender': 'test()', 'id': 42, 'message': 'Test Message'}
+ 71    Test Log: {'sender': 'test()', 'id': 42, 'message': 'Test Message'}
+ 72    test(): {'sender': 'test()', 'id': 42.42, 'message': 'Second Message'}
+ 73    test(): {'sender': 'test()', 'id': 42, 'message': 'Third Message'}
+ 74    Test Log: {'sender': 'test()', 'id': 42, 'message': 'Third Message'}
+ 75
+ 76    The "filter" key is required:
+ 77    >>> asyncio.run(controlpi.test(
+ 78    ...     {"Test Log": {"plugin": "Log"}}, []))
+ 79    data must contain ['filter'] properties
+ 80    Configuration for 'Test Log' is not valid.
+ 81
+ 82    The "filter" key has to contain a list of message templates, i.e.,
+ 83    JSON objects:
+ 84    >>> asyncio.run(controlpi.test(
+ 85    ...     {"Test Log": {"plugin": "Log",
+ 86    ...                   "filter": [42]}}, []))
+ 87    data.filter[0] must be object
+ 88    Configuration for 'Test Log' is not valid.
+ 89    """
+ 90
+ 91    CONF_SCHEMA = {
+ 92        "properties": {"filter": {"type": "array", "items": {"type": "object"}}},
+ 93        "required": ["filter"],
+ 94    }
+ 95    """Schema for Log plugin configuration.
+ 96
+ 97    Required configuration key:
+ 98
+ 99    - 'filter': list of message templates to be logged.
+100    """
+101
+102    def process_conf(self) -> None:
+103        """Register plugin as bus client."""
+104        self.bus.register(self.name, "Log", [], [(self.conf["filter"], self._log)])
+105
+106    async def _log(self, message: Message) -> None:
+107        print(f"{self.name}: {message}")
+108
+109    async def run(self) -> None:
+110        """Run no code proactively."""
+111        pass
+112
+113
+114class Init(BasePlugin):
+115    """Send list of messages on startup and on demand.
+116
+117    The "messages" configuration key gets a list of messages to be sent on
+118    startup. The same list is sent in reaction to a message with
+119    "target": NAME and "command": "execute".
+120
+121    In the example, the two configured messages are sent twice, once at
+122    startup and a second time in reaction to the "execute" command sent by
+123    the test:
+124    >>> import controlpi
+125    >>> asyncio.run(controlpi.test(
+126    ...     {"Test Init": {"plugin": "Init",
+127    ...                    "messages": [{"id": 42,
+128    ...                                  "content": "Test Message"},
+129    ...                                 {"id": 42.42,
+130    ...                                  "content": "Second Message"}]}},
+131    ...     [{"target": "Test Init", "command": "execute"}]))
+132    ... # doctest: +NORMALIZE_WHITESPACE
+133    test(): {'sender': '', 'event': 'registered',
+134             'client': 'Test Init', 'plugin': 'Init',
+135             'sends': [{'id': {'const': 42},
+136                        'content': {'const': 'Test Message'}},
+137                       {'id': {'const': 42.42},
+138                        'content': {'const': 'Second Message'}}],
+139             'receives': [{'target': {'const': 'Test Init'},
+140                           'command': {'const': 'execute'}}]}
+141    test(): {'sender': 'Test Init', 'id': 42, 'content': 'Test Message'}
+142    test(): {'sender': 'Test Init', 'id': 42.42, 'content': 'Second Message'}
+143    test(): {'sender': 'test()', 'target': 'Test Init', 'command': 'execute'}
+144    test(): {'sender': 'Test Init', 'id': 42, 'content': 'Test Message'}
+145    test(): {'sender': 'Test Init', 'id': 42.42, 'content': 'Second Message'}
+146
+147    The "messages" key is required:
+148    >>> asyncio.run(controlpi.test(
+149    ...     {"Test Init": {"plugin": "Init"}}, []))
+150    data must contain ['messages'] properties
+151    Configuration for 'Test Init' is not valid.
+152
+153    The "messages" key has to contain a list of (partial) messages, i.e.,
+154    JSON objects:
+155    >>> asyncio.run(controlpi.test(
+156    ...     {"Test Init": {"plugin": "Init",
+157    ...                    "messages": [42]}}, []))
+158    data.messages[0] must be object
+159    Configuration for 'Test Init' is not valid.
+160    """
+161
+162    CONF_SCHEMA = {
+163        "properties": {"messages": {"type": "array", "items": {"type": "object"}}},
+164        "required": ["messages"],
+165    }
+166    """Schema for Init plugin configuration.
+167
+168    Required configuration key:
+169
+170    - 'messages': list of messages to be sent.
+171    """
+172
+173    def process_conf(self) -> None:
+174        """Register plugin as bus client."""
+175        self.bus.register(
+176            self.name,
+177            "Init",
+178            [
+179                MessageTemplate.from_message(message)
+180                for message in self.conf["messages"]
+181            ],
+182            [
+183                (
+184                    [
+185                        MessageTemplate(
+186                            {
+187                                "target": {"const": self.name},
+188                                "command": {"const": "execute"},
+189                            }
+190                        )
+191                    ],
+192                    self._execute,
+193                )
+194            ],
+195        )
+196
+197    async def _execute(self, message: Message) -> None:
+198        for message in self.conf["messages"]:
+199            await self.bus.send(Message(self.name, message))
+200            # Give immediate reactions to messages opportunity to happen:
+201            await asyncio.sleep(0)
+202
+203    async def run(self) -> None:
+204        """Send configured messages on startup."""
+205        for message in self.conf["messages"]:
+206            await self.bus.send(Message(self.name, message))
+207
+208
+209class Execute(BasePlugin):
+210    """Send configurable list of messages on demand.
+211
+212    An Execute plugin instance receives two kinds of commands.
+213    The "set messages" command has a "messages" key with a list of (partial)
+214    messages, which are sent by the Execute instance in reaction to an
+215    "execute" command.
+216
+217    In the example, the first command sent by the test sets two messages,
+218    which are then sent in reaction to the second command sent by the test:
+219    >>> import controlpi
+220    >>> asyncio.run(controlpi.test(
+221    ...     {"Test Execute": {"plugin": "Execute"}},
+222    ...     [{"target": "Test Execute", "command": "set messages",
+223    ...       "messages": [{"id": 42, "content": "Test Message"},
+224    ...                    {"id": 42.42, "content": "Second Message"}]},
+225    ...      {"target": "Test Execute", "command": "execute"}]))
+226    ... # doctest: +NORMALIZE_WHITESPACE
+227    test(): {'sender': '', 'event': 'registered',
+228             'client': 'Test Execute', 'plugin': 'Execute',
+229             'sends': [{}],
+230             'receives': [{'target': {'const': 'Test Execute'},
+231                           'command': {'const': 'set messages'},
+232                           'messages': {'type': 'array',
+233                                        'items': {'type': 'object'}}},
+234                          {'target': {'const': 'Test Execute'},
+235                           'command': {'const': 'execute'}}]}
+236    test(): {'sender': 'test()', 'target': 'Test Execute',
+237             'command': 'set messages',
+238             'messages': [{'id': 42, 'content': 'Test Message'},
+239                          {'id': 42.42, 'content': 'Second Message'}]}
+240    test(): {'sender': 'test()', 'target': 'Test Execute',
+241             'command': 'execute'}
+242    test(): {'sender': 'Test Execute', 'id': 42,
+243             'content': 'Test Message'}
+244    test(): {'sender': 'Test Execute', 'id': 42.42,
+245             'content': 'Second Message'}
+246    """
+247
+248    CONF_SCHEMA = True
+249    """Schema for Execute plugin configuration.
+250
+251    There are no required or optional configuration keys.
+252    """
+253
+254    def process_conf(self) -> None:
+255        """Register plugin as bus client."""
+256        self.messages: List[Message] = []
+257        self.bus.register(
+258            self.name,
+259            "Execute",
+260            [MessageTemplate()],
+261            [
+262                (
+263                    [
+264                        MessageTemplate(
+265                            {
+266                                "target": {"const": self.name},
+267                                "command": {"const": "set messages"},
+268                                "messages": {
+269                                    "type": "array",
+270                                    "items": {"type": "object"},
+271                                },
+272                            }
+273                        )
+274                    ],
+275                    self._set_messages,
+276                ),
+277                (
+278                    [
+279                        MessageTemplate(
+280                            {
+281                                "target": {"const": self.name},
+282                                "command": {"const": "execute"},
+283                            }
+284                        )
+285                    ],
+286                    self._execute,
+287                ),
+288            ],
+289        )
+290
+291    async def _set_messages(self, message: Message) -> None:
+292        assert isinstance(message["messages"], list)
+293        self.messages = list(message["messages"])
+294
+295    async def _execute(self, message: Message) -> None:
+296        for message in self.messages:
+297            await self.bus.send(Message(self.name, message))
+298            # Give immediate reactions to messages opportunity to happen:
+299            await asyncio.sleep(0)
+300
+301    async def run(self) -> None:
+302        """Run no code proactively."""
+303        pass
+304
+305
+306class Alias(BasePlugin):
+307    """Translate messages to an alias.
+308
+309    The "from" configuration key gets a message template and the
+310    configuration key "to" a (partial) message. The "translate"
+311    configuration key contains pairs of message keys, where the "from"
+312    message key is translated to the "to" message key if present in the
+313    message.
+314
+315    All messages matching the "from" template are received by the Alias
+316    instance and a message translated by adding the keys and values of the
+317    "to" message and the translated key-value pairs according to
+318    "translate" is sent. Keys that are not "sender" and not modified by
+319    "to" or "translate" are retained.
+320
+321    In the example, the two messages sent by the test are translated by the
+322    Alias instance and the translated messages are sent by it preserving
+323    the "content" keys:
+324    >>> import controlpi
+325    >>> asyncio.run(controlpi.test(
+326    ...     {"Test Alias": {"plugin": "Alias",
+327    ...                     "from": {"id": {"const": 42}},
+328    ...                     "to": {"id": "translated"},
+329    ...                     "translate": [{'from': "old", "to": "new"}]}},
+330    ...     [{"id": 42, "content": "Test Message", "old": "content"},
+331    ...      {"id": 42, "content": "Second Message", "old": "content"}]))
+332    ... # doctest: +NORMALIZE_WHITESPACE
+333    test(): {'sender': '', 'event': 'registered',
+334             'client': 'Test Alias', 'plugin': 'Alias',
+335             'sends': [{'id': {'const': 'translated'}}],
+336             'receives': [{'id': {'const': 42}}]}
+337    test(): {'sender': 'test()', 'id': 42,
+338             'content': 'Test Message', 'old': 'content'}
+339    test(): {'sender': 'test()', 'id': 42,
+340             'content': 'Second Message', 'old': 'content'}
+341    test(): {'sender': 'Test Alias', 'id': 'translated',
+342             'content': 'Test Message', 'old': 'content', 'new': 'content'}
+343    test(): {'sender': 'Test Alias', 'id': 'translated',
+344             'content': 'Second Message', 'old': 'content', 'new': 'content'}
+345
+346    An Alias instance can also translate to a list of messages instead of
+347    a single message:
+348    >>> asyncio.run(controlpi.test(
+349    ...     {"Test Alias": {"plugin": "Alias",
+350    ...                     "from": {"id": {"const": 42}},
+351    ...                     "to": [{"id": "first"}, {"id": "second"}],
+352    ...                     "translate": [{'from': "old", "to": "new"}]}},
+353    ...     [{"id": 42, "content": "Test Message", "old": "content"}]))
+354    ... # doctest: +NORMALIZE_WHITESPACE
+355    test(): {'sender': '', 'event': 'registered',
+356             'client': 'Test Alias', 'plugin': 'Alias',
+357             'sends': [{'id': {'const': 'first'}},
+358                       {'id': {'const': 'second'}}],
+359             'receives': [{'id': {'const': 42}}]}
+360    test(): {'sender': 'test()', 'id': 42,
+361             'content': 'Test Message', 'old': 'content'}
+362    test(): {'sender': 'Test Alias', 'id': 'first',
+363             'content': 'Test Message', 'old': 'content', 'new': 'content'}
+364    test(): {'sender': 'Test Alias', 'id': 'second',
+365             'content': 'Test Message', 'old': 'content', 'new': 'content'}
+366
+367    The "from" key is required:
+368    >>> asyncio.run(controlpi.test(
+369    ...     {"Test Alias": {"plugin": "Alias"}}, []))
+370    data must contain ['from'] properties
+371    Configuration for 'Test Alias' is not valid.
+372
+373    The "from" key has to contain a message template and the "to" key a
+374    (partial) message, i.e., both have to be JSON objects:
+375    >>> asyncio.run(controlpi.test(
+376    ...     {"Test Alias": {"plugin": "Alias",
+377    ...                     "from": 42,
+378    ...                     "to": 42}}, []))
+379    data.from must be object
+380    Configuration for 'Test Alias' is not valid.
+381    >>> asyncio.run(controlpi.test(
+382    ...     {"Test Alias": {"plugin": "Alias",
+383    ...                     "from": {"id": {"const": 42}},
+384    ...                     "to": 42}}, []))
+385    data.to cannot be validated by any definition
+386    Configuration for 'Test Alias' is not valid.
+387    """
+388
+389    CONF_SCHEMA = {
+390        "properties": {
+391            "from": {"type": "object"},
+392            "to": {
+393                "anyOf": [
+394                    {"type": "object"},
+395                    {"type": "array", "items": {"type": "object"}},
+396                ]
+397            },
+398            "translate": {
+399                "type": "array",
+400                "items": {
+401                    "type": "object",
+402                    "properties": {
+403                        "from": {"type": "string"},
+404                        "to": {"type": "string"},
+405                    },
+406                },
+407            },
+408        },
+409        "required": ["from"],
+410    }
+411    """Schema for Alias plugin configuration.
+412
+413    Required configuration keys:
+414
+415    - 'from': template of messages to be translated.
+416
+417    Optional configuration keys:
+418
+419    - 'to': translated message(s) to be sent.
+420    - 'translate': array of pairs of keys to be translated.
+421    """
+422
+423    def process_conf(self) -> None:
+424        """Register plugin as bus client."""
+425        sends = []
+426        self._to = []
+427        if "to" in self.conf:
+428            if isinstance(self.conf["to"], list):
+429                self._to = self.conf["to"]
+430                for to in self.conf["to"]:
+431                    sends.append(MessageTemplate.from_message(to))
+432            else:
+433                self._to = [self.conf["to"]]
+434                sends.append(MessageTemplate.from_message(self.conf["to"]))
+435        self._translate = {}
+436        if "translate" in self.conf:
+437            for pair in self.conf["translate"]:
+438                self._translate[pair["from"]] = pair["to"]
+439        self.bus.register(
+440            self.name, "Alias", sends, [([self.conf["from"]], self._alias)]
+441        )
+442
+443    async def _alias(self, message: Message) -> None:
+444        # Prevent endless loop:
+445        if message["sender"] != self.name:
+446            for to in self._to:
+447                alias_message = Message(self.name, message)
+448                alias_message.update(to)
+449                for key in self._translate:
+450                    if key in message:
+451                        alias_message[self._translate[key]] = message[key]
+452                await self.bus.send(alias_message)
+453
+454    async def run(self) -> None:
+455        """Run no code proactively."""
+456        pass
+457
+458
+459class Counter(BasePlugin):
+460    """Count messages confirming to a given template.
+461
+462    The plugin counts messages confirming to the given template. The
+463    counter can be queried and reset by commands. The 'reset' command also
+464    queries the last count before the reset:
+465    >>> import controlpi
+466    >>> asyncio.run(controlpi.test(
+467    ...     {"Test Counter": {"plugin": "Counter",
+468    ...                       "count": {"id": {"const": 42}}}},
+469    ...     [{"target": "Test Counter", "command": "get count"},
+470    ...      {"id": 42}, {"id": 42}, {"id": 49},
+471    ...      {"target": "Test Counter", "command": "get count"},
+472    ...      {"id": 42}, {"id": 42}, {"id": 42},
+473    ...      {"target": "Test Counter", "command": "reset"},
+474    ...      {"target": "Test Counter", "command": "get count"},
+475    ...      {"id": 42}, {"id": 42}, {"id": 42},
+476    ...      {"target": "Test Counter", "command": "get count"}]))
+477    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+478    test(): {'sender': '', 'event': 'registered',
+479             'client': 'Test Counter', 'plugin': 'Counter',
+480             'sends': [{'count': {'type': 'integer'}}],
+481             'receives': [{'id': {'const': 42}},
+482                          {'target': {'const': 'Test Counter'},
+483                           'command': {'const': 'get count'}},
+484                          {'target': {'const': 'Test Counter'},
+485                           'command': {'const': 'reset'}}]}
+486    test(): {'sender': 'test()', 'target': 'Test Counter',
+487             'command': 'get count'}
+488    test(): {'sender': 'test()', 'id': 42}
+489    test(): {'sender': 'Test Counter', 'count': 0,
+490             'since': ..., 'until': ...}
+491    test(): {'sender': 'test()', 'id': 42}
+492    test(): {'sender': 'test()', 'id': 49}
+493    test(): {'sender': 'test()', 'target': 'Test Counter',
+494             'command': 'get count'}
+495    test(): {'sender': 'test()', 'id': 42}
+496    test(): {'sender': 'Test Counter', 'count': 2,
+497             'since': ..., 'until': ...}
+498    test(): {'sender': 'test()', 'id': 42}
+499    test(): {'sender': 'test()', 'id': 42}
+500    test(): {'sender': 'test()', 'target': 'Test Counter',
+501             'command': 'reset'}
+502    test(): {'sender': 'test()', 'target': 'Test Counter',
+503             'command': 'get count'}
+504    test(): {'sender': 'Test Counter', 'count': 5,
+505             'since': ..., 'until': ...}
+506    test(): {'sender': 'test()', 'id': 42}
+507    test(): {'sender': 'Test Counter', 'count': 0,
+508             'since': ..., 'until': ...}
+509    test(): {'sender': 'test()', 'id': 42}
+510    test(): {'sender': 'test()', 'id': 42}
+511    test(): {'sender': 'test()', 'target': 'Test Counter',
+512             'command': 'get count'}
+513    test(): {'sender': 'Test Counter', 'count': 3,
+514             'since': ..., 'until': ...}
+515    """
+516
+517    CONF_SCHEMA = {
+518        "properties": {
+519            "count": {"type": "object"},
+520            "date format": {"type": "string", "default": "%Y-%m-%d %H:%M:%S"},
+521        },
+522        "required": ["count"],
+523    }
+524    """Schema for Counter plugin configuration.
+525
+526    Required configuration key:
+527
+528    - 'count': template of messages to be counted.
+529    """
+530
+531    def process_conf(self) -> None:
+532        """Register plugin as bus client."""
+533        self._since = datetime.now().strftime(self.conf["date format"])
+534        self._counter = 0
+535        self.bus.register(
+536            self.name,
+537            "Counter",
+538            [MessageTemplate({"count": {"type": "integer"}})],
+539            [
+540                ([MessageTemplate(self.conf["count"])], self._count),
+541                (
+542                    [
+543                        MessageTemplate(
+544                            {
+545                                "target": {"const": self.name},
+546                                "command": {"const": "get count"},
+547                            }
+548                        )
+549                    ],
+550                    self._get_count,
+551                ),
+552                (
+553                    [
+554                        MessageTemplate(
+555                            {
+556                                "target": {"const": self.name},
+557                                "command": {"const": "reset"},
+558                            }
+559                        )
+560                    ],
+561                    self._reset,
+562                ),
+563            ],
+564        )
+565
+566    async def _count(self, message: Message) -> None:
+567        self._counter += 1
+568
+569    async def _get_count(self, message: Message) -> None:
+570        now = datetime.now().strftime(self.conf["date format"])
+571        await self.bus.send(
+572            Message(
+573                self.name, {"count": self._counter, "since": self._since, "until": now}
+574            )
+575        )
+576
+577    async def _reset(self, message: Message) -> None:
+578        now = datetime.now().strftime(self.conf["date format"])
+579        counter = self._counter
+580        self._counter = 0
+581        await self.bus.send(
+582            Message(self.name, {"count": counter, "since": self._since, "until": now})
+583        )
+584        self._since = now
+585
+586    async def run(self) -> None:
+587        """Run no code proactively."""
+588        pass
+589
+590
+591class Date(BasePlugin):
+592    """Send message with current date.
+593
+594    The plugin reacts to 'get date' commands by sending messages with
+595    a 'date' key:
+596    >>> import controlpi
+597    >>> asyncio.run(controlpi.test(
+598    ...     {"Test Date": {"plugin": "Date"}},
+599    ...     [{"target": "Test Date", "command": "get date"}]))
+600    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+601    test(): {'sender': '', 'event': 'registered',
+602             'client': 'Test Date', 'plugin': 'Date',
+603             'sends': [{'date': {'type': 'string'}}],
+604             'receives': [{'target': {'const': 'Test Date'},
+605                           'command': {'const': 'get date'}}]}
+606    test(): {'sender': 'test()', 'target': 'Test Date',
+607             'command': 'get date'}
+608    test(): {'sender': 'Test Date', 'date': ...}
+609
+610    The format of the date can be configured with the 'format'
+611    configuration key:
+612    >>> asyncio.run(controlpi.test(
+613    ...     {"Test Date": {"plugin": "Date",
+614    ...                    "format": "%Y%m%d%H%M%S%f"}},
+615    ...     [{"target": "Test Date", "command": "get date"}]))
+616    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+617    test(): {'sender': '', 'event': 'registered',
+618             'client': 'Test Date', 'plugin': 'Date',
+619             'sends': [{'date': {'type': 'string'}}],
+620             'receives': [{'target': {'const': 'Test Date'},
+621                           'command': {'const': 'get date'}}]}
+622    test(): {'sender': 'test()', 'target': 'Test Date',
+623             'command': 'get date'}
+624    test(): {'sender': 'Test Date', 'date': ...}
+625    """
+626
+627    CONF_SCHEMA = {
+628        "properties": {"format": {"type": "string", "default": "%Y-%m-%d %H:%M:%S"}}
+629    }
+630    """Schema for Date plugin configuration.
+631
+632    Optional configuration key:
+633
+634    - 'format': format for the sent datetime string.
+635                Default: '%Y-%m-%d %H:%M:%S'
+636    """
+637
+638    def process_conf(self) -> None:
+639        """Register plugin as bus client."""
+640        self.bus.register(
+641            self.name,
+642            "Date",
+643            [MessageTemplate({"date": {"type": "string"}})],
+644            [
+645                (
+646                    [
+647                        MessageTemplate(
+648                            {
+649                                "target": {"const": self.name},
+650                                "command": {"const": "get date"},
+651                            }
+652                        )
+653                    ],
+654                    self._date,
+655                )
+656            ],
+657        )
+658
+659    async def _date(self, message: Message) -> None:
+660        date = datetime.now().strftime(self.conf["format"])
+661        await self.bus.send(Message(self.name, {"date": date}))
+662
+663    async def run(self) -> None:
+664        """Run no code proactively."""
+665        pass
+

+ + +

+ +

+ + class + Log(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

 50class Log(BasePlugin):
+ 51    """Log messages on stdout.
+ 52
+ 53    The "filter" configuration key gets a list of message templates defining
+ 54    the messages that should be logged by the plugin instance.
+ 55
+ 56    In the following example the first and third message match the given
+ 57    template and are logged by the instance "Test Log", while the second
+ 58    message does not match and is only logged by the test, but not by the
+ 59    Log instance:
+ 60    >>> import controlpi
+ 61    >>> asyncio.run(controlpi.test(
+ 62    ...     {"Test Log": {"plugin": "Log",
+ 63    ...                   "filter": [{"id": {"const": 42}}]}},
+ 64    ...     [{"id": 42, "message": "Test Message"},
+ 65    ...      {"id": 42.42, "message": "Second Message"},
+ 66    ...      {"id": 42, "message": "Third Message"}]))
+ 67    ... # doctest: +NORMALIZE_WHITESPACE
+ 68    test(): {'sender': '', 'event': 'registered',
+ 69             'client': 'Test Log', 'plugin': 'Log',
+ 70             'sends': [], 'receives': [{'id': {'const': 42}}]}
+ 71    test(): {'sender': 'test()', 'id': 42, 'message': 'Test Message'}
+ 72    Test Log: {'sender': 'test()', 'id': 42, 'message': 'Test Message'}
+ 73    test(): {'sender': 'test()', 'id': 42.42, 'message': 'Second Message'}
+ 74    test(): {'sender': 'test()', 'id': 42, 'message': 'Third Message'}
+ 75    Test Log: {'sender': 'test()', 'id': 42, 'message': 'Third Message'}
+ 76
+ 77    The "filter" key is required:
+ 78    >>> asyncio.run(controlpi.test(
+ 79    ...     {"Test Log": {"plugin": "Log"}}, []))
+ 80    data must contain ['filter'] properties
+ 81    Configuration for 'Test Log' is not valid.
+ 82
+ 83    The "filter" key has to contain a list of message templates, i.e.,
+ 84    JSON objects:
+ 85    >>> asyncio.run(controlpi.test(
+ 86    ...     {"Test Log": {"plugin": "Log",
+ 87    ...                   "filter": [42]}}, []))
+ 88    data.filter[0] must be object
+ 89    Configuration for 'Test Log' is not valid.
+ 90    """
+ 91
+ 92    CONF_SCHEMA = {
+ 93        "properties": {"filter": {"type": "array", "items": {"type": "object"}}},
+ 94        "required": ["filter"],
+ 95    }
+ 96    """Schema for Log plugin configuration.
+ 97
+ 98    Required configuration key:
+ 99
+100    - 'filter': list of message templates to be logged.
+101    """
+102
+103    def process_conf(self) -> None:
+104        """Register plugin as bus client."""
+105        self.bus.register(self.name, "Log", [], [(self.conf["filter"], self._log)])
+106
+107    async def _log(self, message: Message) -> None:
+108        print(f"{self.name}: {message}")
+109
+110    async def run(self) -> None:
+111        """Run no code proactively."""
+112        pass
+

+ + +

Log messages on stdout.

+ +

The "filter" configuration key gets a list of message templates defining +the messages that should be logged by the plugin instance.

+ +

In the following example the first and third message match the given +template and are logged by the instance "Test Log", while the second +message does not match and is only logged by the test, but not by the +Log instance:

+ +

>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test Log": {"plugin": "Log",
+...                   "filter": [{"id": {"const": 42}}]}},
+...     [{"id": 42, "message": "Test Message"},
+...      {"id": 42.42, "message": "Second Message"},
+...      {"id": 42, "message": "Third Message"}]))
+... # doctest: +NORMALIZE_WHITESPACE
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Log', 'plugin': 'Log',
+         'sends': [], 'receives': [{'id': {'const': 42}}]}
+test(): {'sender': 'test()', 'id': 42, 'message': 'Test Message'}
+Test Log: {'sender': 'test()', 'id': 42, 'message': 'Test Message'}
+test(): {'sender': 'test()', 'id': 42.42, 'message': 'Second Message'}
+test(): {'sender': 'test()', 'id': 42, 'message': 'Third Message'}
+Test Log: {'sender': 'test()', 'id': 42, 'message': 'Third Message'}
+

+ +

The "filter" key is required:

+ +

>>> asyncio.run(controlpi.test(
+...     {"Test Log": {"plugin": "Log"}}, []))
+data must contain ['filter'] properties
+Configuration for 'Test Log' is not valid.
+

+ +

The "filter" key has to contain a list of message templates, i.e., +JSON objects:

+ +

>>> asyncio.run(controlpi.test(
+...     {"Test Log": {"plugin": "Log",
+...                   "filter": [42]}}, []))
+data.filter[0] must be object
+Configuration for 'Test Log' is not valid.
+

+ + +

+ CONF_SCHEMA = +{'properties': {'filter': {'type': 'array', 'items': {'type': 'object'}}}, 'required': ['filter']} + + +

+ + +

Schema for Log plugin configuration.

+ +

Required configuration key:

+ +

'filter': list of message templates to be logged.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

103    def process_conf(self) -> None:
+104        """Register plugin as bus client."""
+105        self.bus.register(self.name, "Log", [], [(self.conf["filter"], self._log)])
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

110    async def run(self) -> None:
+111        """Run no code proactively."""
+112        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + Init(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

115class Init(BasePlugin):
+116    """Send list of messages on startup and on demand.
+117
+118    The "messages" configuration key gets a list of messages to be sent on
+119    startup. The same list is sent in reaction to a message with
+120    "target": NAME and "command": "execute".
+121
+122    In the example, the two configured messages are sent twice, once at
+123    startup and a second time in reaction to the "execute" command sent by
+124    the test:
+125    >>> import controlpi
+126    >>> asyncio.run(controlpi.test(
+127    ...     {"Test Init": {"plugin": "Init",
+128    ...                    "messages": [{"id": 42,
+129    ...                                  "content": "Test Message"},
+130    ...                                 {"id": 42.42,
+131    ...                                  "content": "Second Message"}]}},
+132    ...     [{"target": "Test Init", "command": "execute"}]))
+133    ... # doctest: +NORMALIZE_WHITESPACE
+134    test(): {'sender': '', 'event': 'registered',
+135             'client': 'Test Init', 'plugin': 'Init',
+136             'sends': [{'id': {'const': 42},
+137                        'content': {'const': 'Test Message'}},
+138                       {'id': {'const': 42.42},
+139                        'content': {'const': 'Second Message'}}],
+140             'receives': [{'target': {'const': 'Test Init'},
+141                           'command': {'const': 'execute'}}]}
+142    test(): {'sender': 'Test Init', 'id': 42, 'content': 'Test Message'}
+143    test(): {'sender': 'Test Init', 'id': 42.42, 'content': 'Second Message'}
+144    test(): {'sender': 'test()', 'target': 'Test Init', 'command': 'execute'}
+145    test(): {'sender': 'Test Init', 'id': 42, 'content': 'Test Message'}
+146    test(): {'sender': 'Test Init', 'id': 42.42, 'content': 'Second Message'}
+147
+148    The "messages" key is required:
+149    >>> asyncio.run(controlpi.test(
+150    ...     {"Test Init": {"plugin": "Init"}}, []))
+151    data must contain ['messages'] properties
+152    Configuration for 'Test Init' is not valid.
+153
+154    The "messages" key has to contain a list of (partial) messages, i.e.,
+155    JSON objects:
+156    >>> asyncio.run(controlpi.test(
+157    ...     {"Test Init": {"plugin": "Init",
+158    ...                    "messages": [42]}}, []))
+159    data.messages[0] must be object
+160    Configuration for 'Test Init' is not valid.
+161    """
+162
+163    CONF_SCHEMA = {
+164        "properties": {"messages": {"type": "array", "items": {"type": "object"}}},
+165        "required": ["messages"],
+166    }
+167    """Schema for Init plugin configuration.
+168
+169    Required configuration key:
+170
+171    - 'messages': list of messages to be sent.
+172    """
+173
+174    def process_conf(self) -> None:
+175        """Register plugin as bus client."""
+176        self.bus.register(
+177            self.name,
+178            "Init",
+179            [
+180                MessageTemplate.from_message(message)
+181                for message in self.conf["messages"]
+182            ],
+183            [
+184                (
+185                    [
+186                        MessageTemplate(
+187                            {
+188                                "target": {"const": self.name},
+189                                "command": {"const": "execute"},
+190                            }
+191                        )
+192                    ],
+193                    self._execute,
+194                )
+195            ],
+196        )
+197
+198    async def _execute(self, message: Message) -> None:
+199        for message in self.conf["messages"]:
+200            await self.bus.send(Message(self.name, message))
+201            # Give immediate reactions to messages opportunity to happen:
+202            await asyncio.sleep(0)
+203
+204    async def run(self) -> None:
+205        """Send configured messages on startup."""
+206        for message in self.conf["messages"]:
+207            await self.bus.send(Message(self.name, message))
+

+ + +

Send list of messages on startup and on demand.

+ +

The "messages" configuration key gets a list of messages to be sent on +startup. The same list is sent in reaction to a message with +"target": NAME and "command": "execute".

+ +

In the example, the two configured messages are sent twice, once at +startup and a second time in reaction to the "execute" command sent by +the test:

+ +

>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test Init": {"plugin": "Init",
+...                    "messages": [{"id": 42,
+...                                  "content": "Test Message"},
+...                                 {"id": 42.42,
+...                                  "content": "Second Message"}]}},
+...     [{"target": "Test Init", "command": "execute"}]))
+... # doctest: +NORMALIZE_WHITESPACE
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Init', 'plugin': 'Init',
+         'sends': [{'id': {'const': 42},
+                    'content': {'const': 'Test Message'}},
+                   {'id': {'const': 42.42},
+                    'content': {'const': 'Second Message'}}],
+         'receives': [{'target': {'const': 'Test Init'},
+                       'command': {'const': 'execute'}}]}
+test(): {'sender': 'Test Init', 'id': 42, 'content': 'Test Message'}
+test(): {'sender': 'Test Init', 'id': 42.42, 'content': 'Second Message'}
+test(): {'sender': 'test()', 'target': 'Test Init', 'command': 'execute'}
+test(): {'sender': 'Test Init', 'id': 42, 'content': 'Test Message'}
+test(): {'sender': 'Test Init', 'id': 42.42, 'content': 'Second Message'}
+

+ +

The "messages" key is required:

+ +

>>> asyncio.run(controlpi.test(
+...     {"Test Init": {"plugin": "Init"}}, []))
+data must contain ['messages'] properties
+Configuration for 'Test Init' is not valid.
+

+ +

The "messages" key has to contain a list of (partial) messages, i.e., +JSON objects:

+ +

>>> asyncio.run(controlpi.test(
+...     {"Test Init": {"plugin": "Init",
+...                    "messages": [42]}}, []))
+data.messages[0] must be object
+Configuration for 'Test Init' is not valid.
+

+ + +

+ CONF_SCHEMA = + + {'properties': {'messages': {'type': 'array', 'items': {'type': 'object'}}}, 'required': ['messages']} + + +

+ + +

Schema for Init plugin configuration.

+ +

Required configuration key:

+ +

'messages': list of messages to be sent.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

174    def process_conf(self) -> None:
+175        """Register plugin as bus client."""
+176        self.bus.register(
+177            self.name,
+178            "Init",
+179            [
+180                MessageTemplate.from_message(message)
+181                for message in self.conf["messages"]
+182            ],
+183            [
+184                (
+185                    [
+186                        MessageTemplate(
+187                            {
+188                                "target": {"const": self.name},
+189                                "command": {"const": "execute"},
+190                            }
+191                        )
+192                    ],
+193                    self._execute,
+194                )
+195            ],
+196        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

204    async def run(self) -> None:
+205        """Send configured messages on startup."""
+206        for message in self.conf["messages"]:
+207            await self.bus.send(Message(self.name, message))
+

+ + +

Send configured messages on startup.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + Execute(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

210class Execute(BasePlugin):
+211    """Send configurable list of messages on demand.
+212
+213    An Execute plugin instance receives two kinds of commands.
+214    The "set messages" command has a "messages" key with a list of (partial)
+215    messages, which are sent by the Execute instance in reaction to an
+216    "execute" command.
+217
+218    In the example, the first command sent by the test sets two messages,
+219    which are then sent in reaction to the second command sent by the test:
+220    >>> import controlpi
+221    >>> asyncio.run(controlpi.test(
+222    ...     {"Test Execute": {"plugin": "Execute"}},
+223    ...     [{"target": "Test Execute", "command": "set messages",
+224    ...       "messages": [{"id": 42, "content": "Test Message"},
+225    ...                    {"id": 42.42, "content": "Second Message"}]},
+226    ...      {"target": "Test Execute", "command": "execute"}]))
+227    ... # doctest: +NORMALIZE_WHITESPACE
+228    test(): {'sender': '', 'event': 'registered',
+229             'client': 'Test Execute', 'plugin': 'Execute',
+230             'sends': [{}],
+231             'receives': [{'target': {'const': 'Test Execute'},
+232                           'command': {'const': 'set messages'},
+233                           'messages': {'type': 'array',
+234                                        'items': {'type': 'object'}}},
+235                          {'target': {'const': 'Test Execute'},
+236                           'command': {'const': 'execute'}}]}
+237    test(): {'sender': 'test()', 'target': 'Test Execute',
+238             'command': 'set messages',
+239             'messages': [{'id': 42, 'content': 'Test Message'},
+240                          {'id': 42.42, 'content': 'Second Message'}]}
+241    test(): {'sender': 'test()', 'target': 'Test Execute',
+242             'command': 'execute'}
+243    test(): {'sender': 'Test Execute', 'id': 42,
+244             'content': 'Test Message'}
+245    test(): {'sender': 'Test Execute', 'id': 42.42,
+246             'content': 'Second Message'}
+247    """
+248
+249    CONF_SCHEMA = True
+250    """Schema for Execute plugin configuration.
+251
+252    There are no required or optional configuration keys.
+253    """
+254
+255    def process_conf(self) -> None:
+256        """Register plugin as bus client."""
+257        self.messages: List[Message] = []
+258        self.bus.register(
+259            self.name,
+260            "Execute",
+261            [MessageTemplate()],
+262            [
+263                (
+264                    [
+265                        MessageTemplate(
+266                            {
+267                                "target": {"const": self.name},
+268                                "command": {"const": "set messages"},
+269                                "messages": {
+270                                    "type": "array",
+271                                    "items": {"type": "object"},
+272                                },
+273                            }
+274                        )
+275                    ],
+276                    self._set_messages,
+277                ),
+278                (
+279                    [
+280                        MessageTemplate(
+281                            {
+282                                "target": {"const": self.name},
+283                                "command": {"const": "execute"},
+284                            }
+285                        )
+286                    ],
+287                    self._execute,
+288                ),
+289            ],
+290        )
+291
+292    async def _set_messages(self, message: Message) -> None:
+293        assert isinstance(message["messages"], list)
+294        self.messages = list(message["messages"])
+295
+296    async def _execute(self, message: Message) -> None:
+297        for message in self.messages:
+298            await self.bus.send(Message(self.name, message))
+299            # Give immediate reactions to messages opportunity to happen:
+300            await asyncio.sleep(0)
+301
+302    async def run(self) -> None:
+303        """Run no code proactively."""
+304        pass
+

+ + +

Send configurable list of messages on demand.

+ +

An Execute plugin instance receives two kinds of commands. +The "set messages" command has a "messages" key with a list of (partial) +messages, which are sent by the Execute instance in reaction to an +"execute" command.

+ +

In the example, the first command sent by the test sets two messages, +which are then sent in reaction to the second command sent by the test:

+ +

>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test Execute": {"plugin": "Execute"}},
+...     [{"target": "Test Execute", "command": "set messages",
+...       "messages": [{"id": 42, "content": "Test Message"},
+...                    {"id": 42.42, "content": "Second Message"}]},
+...      {"target": "Test Execute", "command": "execute"}]))
+... # doctest: +NORMALIZE_WHITESPACE
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Execute', 'plugin': 'Execute',
+         'sends': [{}],
+         'receives': [{'target': {'const': 'Test Execute'},
+                       'command': {'const': 'set messages'},
+                       'messages': {'type': 'array',
+                                    'items': {'type': 'object'}}},
+                      {'target': {'const': 'Test Execute'},
+                       'command': {'const': 'execute'}}]}
+test(): {'sender': 'test()', 'target': 'Test Execute',
+         'command': 'set messages',
+         'messages': [{'id': 42, 'content': 'Test Message'},
+                      {'id': 42.42, 'content': 'Second Message'}]}
+test(): {'sender': 'test()', 'target': 'Test Execute',
+         'command': 'execute'}
+test(): {'sender': 'Test Execute', 'id': 42,
+         'content': 'Test Message'}
+test(): {'sender': 'Test Execute', 'id': 42.42,
+         'content': 'Second Message'}
+

+ + +

+ CONF_SCHEMA = +True + + +

+ + +

Schema for Execute plugin configuration.

+ +

There are no required or optional configuration keys.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

255    def process_conf(self) -> None:
+256        """Register plugin as bus client."""
+257        self.messages: List[Message] = []
+258        self.bus.register(
+259            self.name,
+260            "Execute",
+261            [MessageTemplate()],
+262            [
+263                (
+264                    [
+265                        MessageTemplate(
+266                            {
+267                                "target": {"const": self.name},
+268                                "command": {"const": "set messages"},
+269                                "messages": {
+270                                    "type": "array",
+271                                    "items": {"type": "object"},
+272                                },
+273                            }
+274                        )
+275                    ],
+276                    self._set_messages,
+277                ),
+278                (
+279                    [
+280                        MessageTemplate(
+281                            {
+282                                "target": {"const": self.name},
+283                                "command": {"const": "execute"},
+284                            }
+285                        )
+286                    ],
+287                    self._execute,
+288                ),
+289            ],
+290        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

302    async def run(self) -> None:
+303        """Run no code proactively."""
+304        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + Alias(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

307class Alias(BasePlugin):
+308    """Translate messages to an alias.
+309
+310    The "from" configuration key gets a message template and the
+311    configuration key "to" a (partial) message. The "translate"
+312    configuration key contains pairs of message keys, where the "from"
+313    message key is translated to the "to" message key if present in the
+314    message.
+315
+316    All messages matching the "from" template are received by the Alias
+317    instance and a message translated by adding the keys and values of the
+318    "to" message and the translated key-value pairs according to
+319    "translate" is sent. Keys that are not "sender" and not modified by
+320    "to" or "translate" are retained.
+321
+322    In the example, the two messages sent by the test are translated by the
+323    Alias instance and the translated messages are sent by it preserving
+324    the "content" keys:
+325    >>> import controlpi
+326    >>> asyncio.run(controlpi.test(
+327    ...     {"Test Alias": {"plugin": "Alias",
+328    ...                     "from": {"id": {"const": 42}},
+329    ...                     "to": {"id": "translated"},
+330    ...                     "translate": [{'from': "old", "to": "new"}]}},
+331    ...     [{"id": 42, "content": "Test Message", "old": "content"},
+332    ...      {"id": 42, "content": "Second Message", "old": "content"}]))
+333    ... # doctest: +NORMALIZE_WHITESPACE
+334    test(): {'sender': '', 'event': 'registered',
+335             'client': 'Test Alias', 'plugin': 'Alias',
+336             'sends': [{'id': {'const': 'translated'}}],
+337             'receives': [{'id': {'const': 42}}]}
+338    test(): {'sender': 'test()', 'id': 42,
+339             'content': 'Test Message', 'old': 'content'}
+340    test(): {'sender': 'test()', 'id': 42,
+341             'content': 'Second Message', 'old': 'content'}
+342    test(): {'sender': 'Test Alias', 'id': 'translated',
+343             'content': 'Test Message', 'old': 'content', 'new': 'content'}
+344    test(): {'sender': 'Test Alias', 'id': 'translated',
+345             'content': 'Second Message', 'old': 'content', 'new': 'content'}
+346
+347    An Alias instance can also translate to a list of messages instead of
+348    a single message:
+349    >>> asyncio.run(controlpi.test(
+350    ...     {"Test Alias": {"plugin": "Alias",
+351    ...                     "from": {"id": {"const": 42}},
+352    ...                     "to": [{"id": "first"}, {"id": "second"}],
+353    ...                     "translate": [{'from': "old", "to": "new"}]}},
+354    ...     [{"id": 42, "content": "Test Message", "old": "content"}]))
+355    ... # doctest: +NORMALIZE_WHITESPACE
+356    test(): {'sender': '', 'event': 'registered',
+357             'client': 'Test Alias', 'plugin': 'Alias',
+358             'sends': [{'id': {'const': 'first'}},
+359                       {'id': {'const': 'second'}}],
+360             'receives': [{'id': {'const': 42}}]}
+361    test(): {'sender': 'test()', 'id': 42,
+362             'content': 'Test Message', 'old': 'content'}
+363    test(): {'sender': 'Test Alias', 'id': 'first',
+364             'content': 'Test Message', 'old': 'content', 'new': 'content'}
+365    test(): {'sender': 'Test Alias', 'id': 'second',
+366             'content': 'Test Message', 'old': 'content', 'new': 'content'}
+367
+368    The "from" key is required:
+369    >>> asyncio.run(controlpi.test(
+370    ...     {"Test Alias": {"plugin": "Alias"}}, []))
+371    data must contain ['from'] properties
+372    Configuration for 'Test Alias' is not valid.
+373
+374    The "from" key has to contain a message template and the "to" key a
+375    (partial) message, i.e., both have to be JSON objects:
+376    >>> asyncio.run(controlpi.test(
+377    ...     {"Test Alias": {"plugin": "Alias",
+378    ...                     "from": 42,
+379    ...                     "to": 42}}, []))
+380    data.from must be object
+381    Configuration for 'Test Alias' is not valid.
+382    >>> asyncio.run(controlpi.test(
+383    ...     {"Test Alias": {"plugin": "Alias",
+384    ...                     "from": {"id": {"const": 42}},
+385    ...                     "to": 42}}, []))
+386    data.to cannot be validated by any definition
+387    Configuration for 'Test Alias' is not valid.
+388    """
+389
+390    CONF_SCHEMA = {
+391        "properties": {
+392            "from": {"type": "object"},
+393            "to": {
+394                "anyOf": [
+395                    {"type": "object"},
+396                    {"type": "array", "items": {"type": "object"}},
+397                ]
+398            },
+399            "translate": {
+400                "type": "array",
+401                "items": {
+402                    "type": "object",
+403                    "properties": {
+404                        "from": {"type": "string"},
+405                        "to": {"type": "string"},
+406                    },
+407                },
+408            },
+409        },
+410        "required": ["from"],
+411    }
+412    """Schema for Alias plugin configuration.
+413
+414    Required configuration keys:
+415
+416    - 'from': template of messages to be translated.
+417
+418    Optional configuration keys:
+419
+420    - 'to': translated message(s) to be sent.
+421    - 'translate': array of pairs of keys to be translated.
+422    """
+423
+424    def process_conf(self) -> None:
+425        """Register plugin as bus client."""
+426        sends = []
+427        self._to = []
+428        if "to" in self.conf:
+429            if isinstance(self.conf["to"], list):
+430                self._to = self.conf["to"]
+431                for to in self.conf["to"]:
+432                    sends.append(MessageTemplate.from_message(to))
+433            else:
+434                self._to = [self.conf["to"]]
+435                sends.append(MessageTemplate.from_message(self.conf["to"]))
+436        self._translate = {}
+437        if "translate" in self.conf:
+438            for pair in self.conf["translate"]:
+439                self._translate[pair["from"]] = pair["to"]
+440        self.bus.register(
+441            self.name, "Alias", sends, [([self.conf["from"]], self._alias)]
+442        )
+443
+444    async def _alias(self, message: Message) -> None:
+445        # Prevent endless loop:
+446        if message["sender"] != self.name:
+447            for to in self._to:
+448                alias_message = Message(self.name, message)
+449                alias_message.update(to)
+450                for key in self._translate:
+451                    if key in message:
+452                        alias_message[self._translate[key]] = message[key]
+453                await self.bus.send(alias_message)
+454
+455    async def run(self) -> None:
+456        """Run no code proactively."""
+457        pass
+

+ + +

Translate messages to an alias.

+ +

The "from" configuration key gets a message template and the +configuration key "to" a (partial) message. The "translate" +configuration key contains pairs of message keys, where the "from" +message key is translated to the "to" message key if present in the +message.

+ +

All messages matching the "from" template are received by the Alias +instance and a message translated by adding the keys and values of the +"to" message and the translated key-value pairs according to +"translate" is sent. Keys that are not "sender" and not modified by +"to" or "translate" are retained.

+ +

In the example, the two messages sent by the test are translated by the +Alias instance and the translated messages are sent by it preserving +the "content" keys:

+ +

>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test Alias": {"plugin": "Alias",
+...                     "from": {"id": {"const": 42}},
+...                     "to": {"id": "translated"},
+...                     "translate": [{'from': "old", "to": "new"}]}},
+...     [{"id": 42, "content": "Test Message", "old": "content"},
+...      {"id": 42, "content": "Second Message", "old": "content"}]))
+... # doctest: +NORMALIZE_WHITESPACE
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Alias', 'plugin': 'Alias',
+         'sends': [{'id': {'const': 'translated'}}],
+         'receives': [{'id': {'const': 42}}]}
+test(): {'sender': 'test()', 'id': 42,
+         'content': 'Test Message', 'old': 'content'}
+test(): {'sender': 'test()', 'id': 42,
+         'content': 'Second Message', 'old': 'content'}
+test(): {'sender': 'Test Alias', 'id': 'translated',
+         'content': 'Test Message', 'old': 'content', 'new': 'content'}
+test(): {'sender': 'Test Alias', 'id': 'translated',
+         'content': 'Second Message', 'old': 'content', 'new': 'content'}
+

+ +

An Alias instance can also translate to a list of messages instead of +a single message:

+ +

>>> asyncio.run(controlpi.test(
+...     {"Test Alias": {"plugin": "Alias",
+...                     "from": {"id": {"const": 42}},
+...                     "to": [{"id": "first"}, {"id": "second"}],
+...                     "translate": [{'from': "old", "to": "new"}]}},
+...     [{"id": 42, "content": "Test Message", "old": "content"}]))
+... # doctest: +NORMALIZE_WHITESPACE
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Alias', 'plugin': 'Alias',
+         'sends': [{'id': {'const': 'first'}},
+                   {'id': {'const': 'second'}}],
+         'receives': [{'id': {'const': 42}}]}
+test(): {'sender': 'test()', 'id': 42,
+         'content': 'Test Message', 'old': 'content'}
+test(): {'sender': 'Test Alias', 'id': 'first',
+         'content': 'Test Message', 'old': 'content', 'new': 'content'}
+test(): {'sender': 'Test Alias', 'id': 'second',
+         'content': 'Test Message', 'old': 'content', 'new': 'content'}
+

+ +

The "from" key is required:

+ +

>>> asyncio.run(controlpi.test(
+...     {"Test Alias": {"plugin": "Alias"}}, []))
+data must contain ['from'] properties
+Configuration for 'Test Alias' is not valid.
+

+ +

The "from" key has to contain a message template and the "to" key a +(partial) message, i.e., both have to be JSON objects:

+ +

>>> asyncio.run(controlpi.test(
+...     {"Test Alias": {"plugin": "Alias",
+...                     "from": 42,
+...                     "to": 42}}, []))
+data.from must be object
+Configuration for 'Test Alias' is not valid.
+>>> asyncio.run(controlpi.test(
+...     {"Test Alias": {"plugin": "Alias",
+...                     "from": {"id": {"const": 42}},
+...                     "to": 42}}, []))
+data.to cannot be validated by any definition
+Configuration for 'Test Alias' is not valid.
+

+ + +

+ CONF_SCHEMA = + + {'properties': {'from': {'type': 'object'}, 'to': {'anyOf': [{'type': 'object'}, {'type': 'array', 'items': {'type': 'object'}}]}, 'translate': {'type': 'array', 'items': {'type': 'object', 'properties': {'from': {'type': 'string'}, 'to': {'type': 'string'}}}}}, 'required': ['from']} + + +

+ + +

Schema for Alias plugin configuration.

+ +

Required configuration keys:

+ +

'from': template of messages to be translated.

+ +

Optional configuration keys:

+ +

'to': translated message(s) to be sent.
'translate': array of pairs of keys to be translated.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

424    def process_conf(self) -> None:
+425        """Register plugin as bus client."""
+426        sends = []
+427        self._to = []
+428        if "to" in self.conf:
+429            if isinstance(self.conf["to"], list):
+430                self._to = self.conf["to"]
+431                for to in self.conf["to"]:
+432                    sends.append(MessageTemplate.from_message(to))
+433            else:
+434                self._to = [self.conf["to"]]
+435                sends.append(MessageTemplate.from_message(self.conf["to"]))
+436        self._translate = {}
+437        if "translate" in self.conf:
+438            for pair in self.conf["translate"]:
+439                self._translate[pair["from"]] = pair["to"]
+440        self.bus.register(
+441            self.name, "Alias", sends, [([self.conf["from"]], self._alias)]
+442        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

455    async def run(self) -> None:
+456        """Run no code proactively."""
+457        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + Counter(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

460class Counter(BasePlugin):
+461    """Count messages confirming to a given template.
+462
+463    The plugin counts messages confirming to the given template. The
+464    counter can be queried and reset by commands. The 'reset' command also
+465    queries the last count before the reset:
+466    >>> import controlpi
+467    >>> asyncio.run(controlpi.test(
+468    ...     {"Test Counter": {"plugin": "Counter",
+469    ...                       "count": {"id": {"const": 42}}}},
+470    ...     [{"target": "Test Counter", "command": "get count"},
+471    ...      {"id": 42}, {"id": 42}, {"id": 49},
+472    ...      {"target": "Test Counter", "command": "get count"},
+473    ...      {"id": 42}, {"id": 42}, {"id": 42},
+474    ...      {"target": "Test Counter", "command": "reset"},
+475    ...      {"target": "Test Counter", "command": "get count"},
+476    ...      {"id": 42}, {"id": 42}, {"id": 42},
+477    ...      {"target": "Test Counter", "command": "get count"}]))
+478    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+479    test(): {'sender': '', 'event': 'registered',
+480             'client': 'Test Counter', 'plugin': 'Counter',
+481             'sends': [{'count': {'type': 'integer'}}],
+482             'receives': [{'id': {'const': 42}},
+483                          {'target': {'const': 'Test Counter'},
+484                           'command': {'const': 'get count'}},
+485                          {'target': {'const': 'Test Counter'},
+486                           'command': {'const': 'reset'}}]}
+487    test(): {'sender': 'test()', 'target': 'Test Counter',
+488             'command': 'get count'}
+489    test(): {'sender': 'test()', 'id': 42}
+490    test(): {'sender': 'Test Counter', 'count': 0,
+491             'since': ..., 'until': ...}
+492    test(): {'sender': 'test()', 'id': 42}
+493    test(): {'sender': 'test()', 'id': 49}
+494    test(): {'sender': 'test()', 'target': 'Test Counter',
+495             'command': 'get count'}
+496    test(): {'sender': 'test()', 'id': 42}
+497    test(): {'sender': 'Test Counter', 'count': 2,
+498             'since': ..., 'until': ...}
+499    test(): {'sender': 'test()', 'id': 42}
+500    test(): {'sender': 'test()', 'id': 42}
+501    test(): {'sender': 'test()', 'target': 'Test Counter',
+502             'command': 'reset'}
+503    test(): {'sender': 'test()', 'target': 'Test Counter',
+504             'command': 'get count'}
+505    test(): {'sender': 'Test Counter', 'count': 5,
+506             'since': ..., 'until': ...}
+507    test(): {'sender': 'test()', 'id': 42}
+508    test(): {'sender': 'Test Counter', 'count': 0,
+509             'since': ..., 'until': ...}
+510    test(): {'sender': 'test()', 'id': 42}
+511    test(): {'sender': 'test()', 'id': 42}
+512    test(): {'sender': 'test()', 'target': 'Test Counter',
+513             'command': 'get count'}
+514    test(): {'sender': 'Test Counter', 'count': 3,
+515             'since': ..., 'until': ...}
+516    """
+517
+518    CONF_SCHEMA = {
+519        "properties": {
+520            "count": {"type": "object"},
+521            "date format": {"type": "string", "default": "%Y-%m-%d %H:%M:%S"},
+522        },
+523        "required": ["count"],
+524    }
+525    """Schema for Counter plugin configuration.
+526
+527    Required configuration key:
+528
+529    - 'count': template of messages to be counted.
+530    """
+531
+532    def process_conf(self) -> None:
+533        """Register plugin as bus client."""
+534        self._since = datetime.now().strftime(self.conf["date format"])
+535        self._counter = 0
+536        self.bus.register(
+537            self.name,
+538            "Counter",
+539            [MessageTemplate({"count": {"type": "integer"}})],
+540            [
+541                ([MessageTemplate(self.conf["count"])], self._count),
+542                (
+543                    [
+544                        MessageTemplate(
+545                            {
+546                                "target": {"const": self.name},
+547                                "command": {"const": "get count"},
+548                            }
+549                        )
+550                    ],
+551                    self._get_count,
+552                ),
+553                (
+554                    [
+555                        MessageTemplate(
+556                            {
+557                                "target": {"const": self.name},
+558                                "command": {"const": "reset"},
+559                            }
+560                        )
+561                    ],
+562                    self._reset,
+563                ),
+564            ],
+565        )
+566
+567    async def _count(self, message: Message) -> None:
+568        self._counter += 1
+569
+570    async def _get_count(self, message: Message) -> None:
+571        now = datetime.now().strftime(self.conf["date format"])
+572        await self.bus.send(
+573            Message(
+574                self.name, {"count": self._counter, "since": self._since, "until": now}
+575            )
+576        )
+577
+578    async def _reset(self, message: Message) -> None:
+579        now = datetime.now().strftime(self.conf["date format"])
+580        counter = self._counter
+581        self._counter = 0
+582        await self.bus.send(
+583            Message(self.name, {"count": counter, "since": self._since, "until": now})
+584        )
+585        self._since = now
+586
+587    async def run(self) -> None:
+588        """Run no code proactively."""
+589        pass
+

+ + +

Count messages confirming to a given template.

+ +

The plugin counts messages confirming to the given template. The +counter can be queried and reset by commands. The 'reset' command also +queries the last count before the reset:

+ +

>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test Counter": {"plugin": "Counter",
+...                       "count": {"id": {"const": 42}}}},
+...     [{"target": "Test Counter", "command": "get count"},
+...      {"id": 42}, {"id": 42}, {"id": 49},
+...      {"target": "Test Counter", "command": "get count"},
+...      {"id": 42}, {"id": 42}, {"id": 42},
+...      {"target": "Test Counter", "command": "reset"},
+...      {"target": "Test Counter", "command": "get count"},
+...      {"id": 42}, {"id": 42}, {"id": 42},
+...      {"target": "Test Counter", "command": "get count"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Counter', 'plugin': 'Counter',
+         'sends': [{'count': {'type': 'integer'}}],
+         'receives': [{'id': {'const': 42}},
+                      {'target': {'const': 'Test Counter'},
+                       'command': {'const': 'get count'}},
+                      {'target': {'const': 'Test Counter'},
+                       'command': {'const': 'reset'}}]}
+test(): {'sender': 'test()', 'target': 'Test Counter',
+         'command': 'get count'}
+test(): {'sender': 'test()', 'id': 42}
+test(): {'sender': 'Test Counter', 'count': 0,
+         'since': ..., 'until': ...}
+test(): {'sender': 'test()', 'id': 42}
+test(): {'sender': 'test()', 'id': 49}
+test(): {'sender': 'test()', 'target': 'Test Counter',
+         'command': 'get count'}
+test(): {'sender': 'test()', 'id': 42}
+test(): {'sender': 'Test Counter', 'count': 2,
+         'since': ..., 'until': ...}
+test(): {'sender': 'test()', 'id': 42}
+test(): {'sender': 'test()', 'id': 42}
+test(): {'sender': 'test()', 'target': 'Test Counter',
+         'command': 'reset'}
+test(): {'sender': 'test()', 'target': 'Test Counter',
+         'command': 'get count'}
+test(): {'sender': 'Test Counter', 'count': 5,
+         'since': ..., 'until': ...}
+test(): {'sender': 'test()', 'id': 42}
+test(): {'sender': 'Test Counter', 'count': 0,
+         'since': ..., 'until': ...}
+test(): {'sender': 'test()', 'id': 42}
+test(): {'sender': 'test()', 'id': 42}
+test(): {'sender': 'test()', 'target': 'Test Counter',
+         'command': 'get count'}
+test(): {'sender': 'Test Counter', 'count': 3,
+         'since': ..., 'until': ...}
+

+ + +

+ CONF_SCHEMA = + + {'properties': {'count': {'type': 'object'}, 'date format': {'type': 'string', 'default': '%Y-%m-%d %H:%M:%S'}}, 'required': ['count']} + + +

+ + +

Schema for Counter plugin configuration.

+ +

Required configuration key:

+ +

'count': template of messages to be counted.

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

532    def process_conf(self) -> None:
+533        """Register plugin as bus client."""
+534        self._since = datetime.now().strftime(self.conf["date format"])
+535        self._counter = 0
+536        self.bus.register(
+537            self.name,
+538            "Counter",
+539            [MessageTemplate({"count": {"type": "integer"}})],
+540            [
+541                ([MessageTemplate(self.conf["count"])], self._count),
+542                (
+543                    [
+544                        MessageTemplate(
+545                            {
+546                                "target": {"const": self.name},
+547                                "command": {"const": "get count"},
+548                            }
+549                        )
+550                    ],
+551                    self._get_count,
+552                ),
+553                (
+554                    [
+555                        MessageTemplate(
+556                            {
+557                                "target": {"const": self.name},
+558                                "command": {"const": "reset"},
+559                            }
+560                        )
+561                    ],
+562                    self._reset,
+563                ),
+564            ],
+565        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

587    async def run(self) -> None:
+588        """Run no code proactively."""
+589        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

+ +

+ + class + Date(controlpi.baseplugin.BasePlugin): + + View Source + +

+ +

592class Date(BasePlugin):
+593    """Send message with current date.
+594
+595    The plugin reacts to 'get date' commands by sending messages with
+596    a 'date' key:
+597    >>> import controlpi
+598    >>> asyncio.run(controlpi.test(
+599    ...     {"Test Date": {"plugin": "Date"}},
+600    ...     [{"target": "Test Date", "command": "get date"}]))
+601    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+602    test(): {'sender': '', 'event': 'registered',
+603             'client': 'Test Date', 'plugin': 'Date',
+604             'sends': [{'date': {'type': 'string'}}],
+605             'receives': [{'target': {'const': 'Test Date'},
+606                           'command': {'const': 'get date'}}]}
+607    test(): {'sender': 'test()', 'target': 'Test Date',
+608             'command': 'get date'}
+609    test(): {'sender': 'Test Date', 'date': ...}
+610
+611    The format of the date can be configured with the 'format'
+612    configuration key:
+613    >>> asyncio.run(controlpi.test(
+614    ...     {"Test Date": {"plugin": "Date",
+615    ...                    "format": "%Y%m%d%H%M%S%f"}},
+616    ...     [{"target": "Test Date", "command": "get date"}]))
+617    ... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+618    test(): {'sender': '', 'event': 'registered',
+619             'client': 'Test Date', 'plugin': 'Date',
+620             'sends': [{'date': {'type': 'string'}}],
+621             'receives': [{'target': {'const': 'Test Date'},
+622                           'command': {'const': 'get date'}}]}
+623    test(): {'sender': 'test()', 'target': 'Test Date',
+624             'command': 'get date'}
+625    test(): {'sender': 'Test Date', 'date': ...}
+626    """
+627
+628    CONF_SCHEMA = {
+629        "properties": {"format": {"type": "string", "default": "%Y-%m-%d %H:%M:%S"}}
+630    }
+631    """Schema for Date plugin configuration.
+632
+633    Optional configuration key:
+634
+635    - 'format': format for the sent datetime string.
+636                Default: '%Y-%m-%d %H:%M:%S'
+637    """
+638
+639    def process_conf(self) -> None:
+640        """Register plugin as bus client."""
+641        self.bus.register(
+642            self.name,
+643            "Date",
+644            [MessageTemplate({"date": {"type": "string"}})],
+645            [
+646                (
+647                    [
+648                        MessageTemplate(
+649                            {
+650                                "target": {"const": self.name},
+651                                "command": {"const": "get date"},
+652                            }
+653                        )
+654                    ],
+655                    self._date,
+656                )
+657            ],
+658        )
+659
+660    async def _date(self, message: Message) -> None:
+661        date = datetime.now().strftime(self.conf["format"])
+662        await self.bus.send(Message(self.name, {"date": date}))
+663
+664    async def run(self) -> None:
+665        """Run no code proactively."""
+666        pass
+

+ + +

Send message with current date.

+ +

The plugin reacts to 'get date' commands by sending messages with +a 'date' key:

+ +

>>> import controlpi
+>>> asyncio.run(controlpi.test(
+...     {"Test Date": {"plugin": "Date"}},
+...     [{"target": "Test Date", "command": "get date"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Date', 'plugin': 'Date',
+         'sends': [{'date': {'type': 'string'}}],
+         'receives': [{'target': {'const': 'Test Date'},
+                       'command': {'const': 'get date'}}]}
+test(): {'sender': 'test()', 'target': 'Test Date',
+         'command': 'get date'}
+test(): {'sender': 'Test Date', 'date': ...}
+

+ +

The format of the date can be configured with the 'format' +configuration key:

+ +

>>> asyncio.run(controlpi.test(
+...     {"Test Date": {"plugin": "Date",
+...                    "format": "%Y%m%d%H%M%S%f"}},
+...     [{"target": "Test Date", "command": "get date"}]))
+... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+test(): {'sender': '', 'event': 'registered',
+         'client': 'Test Date', 'plugin': 'Date',
+         'sends': [{'date': {'type': 'string'}}],
+         'receives': [{'target': {'const': 'Test Date'},
+                       'command': {'const': 'get date'}}]}
+test(): {'sender': 'test()', 'target': 'Test Date',
+         'command': 'get date'}
+test(): {'sender': 'Test Date', 'date': ...}
+

+ + +

+ CONF_SCHEMA = +{'properties': {'format': {'type': 'string', 'default': '%Y-%m-%d %H:%M:%S'}}} + + +

+ + +

Schema for Date plugin configuration.

+ +

Optional configuration key:

+ +

'format': format for the sent datetime string. +Default: '%Y-%m-%d %H:%M:%S'

+ + +

+ +

+ + def + process_conf(self) -> None: + + View Source + +

+ +

639    def process_conf(self) -> None:
+640        """Register plugin as bus client."""
+641        self.bus.register(
+642            self.name,
+643            "Date",
+644            [MessageTemplate({"date": {"type": "string"}})],
+645            [
+646                (
+647                    [
+648                        MessageTemplate(
+649                            {
+650                                "target": {"const": self.name},
+651                                "command": {"const": "get date"},
+652                            }
+653                        )
+654                    ],
+655                    self._date,
+656                )
+657            ],
+658        )
+

+ + +

+ +

+ + async def + run(self) -> None: + + View Source + +

+ +

664    async def run(self) -> None:
+665        """Run no code proactively."""
+666        pass
+

+ + +

Run no code proactively.

+ + +

Inherited Members

controlpi.baseplugin.BasePlugin: BasePlugin; bus; name; conf

Module `controlpi.messagebus`

Provide an asynchronous message bus.

A message is a dictionary with string keys and string, integer, float, -Boolean, dictionary, or list values, where the inner dictionaries again -have string keys and these values and the inner lists also have elements of -these types. All messages have a special key 'sender' with the name of the -sending client as string value, which is set by the constructor:

>>> m = Message('Example sender', {'key 1': 'value 1'})
->>> m['key 2'] = 'value 2'
->>> print(m)
-{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-

A message template is a mapping from string keys to JSON schemas as values. -A message template matches a message if all keys of the template are -contained in the message and the values in the message validate against the -respective schemas. An empty mapping therefore matches all messages.

The bus executes asynchronous callbacks for all messages to be received by -a client. We use a simple callback printing the message in all examples:

>>> def callback_for_receiver(receiver):
-...     async def callback(message):
-...         print(f"{receiver}: {message}")
-...     return callback
-

Clients can be registered at the bus with a name, lists of message templates -they want to use for sending and receiving and a callback function for -receiving. An empty list of templates means that the client does not want to -send or receive any messages, respectively. A list with an empty template -means that it wants to send arbitrary or receive all messages, respectively:

>>> async def setup(bus):
-...     bus.register('Logger', 'Test Plugin',
-...                  [],
-...                  [{}],
-...                  callback_for_receiver('Logger'))
-...     bus.register('Client 1', 'Test Plugin',
-...                  [{'k1': {'type': 'string'}}],
-...                  [{'target': {'const': 'Client 1'}}],
-...                  callback_for_receiver('Client 1'))
-

While most clients should always use their own name for sending, this is not -enforced and debugging or management clients could send messages on behalf -of arbitrary client names.

The name of a client has to be unique and is not allowed to be empty -(otherwise registration fails).

The empty name is used to refer to the bus itself. The bus sends messages -for registrations and deregistrations of clients containing their complete -interface of send and receive templates. This can be used to allow dynamic -(debug) clients to deal with arbitrary configurations of clients. The bus -also reacts to 'get clients' command messages by sending the complete -information of all currently registered clients.

Clients can send to the bus with the send function. Each message has to -declare a sender. The send templates of that sender are checked for a -template matching the message:

>>> async def send(bus):
-...     print("Sending messages.")
-...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
-...     await bus.send({'sender': '', 'target': 'Client 1'})
-

The run function executes the message bus forever. If we want to stop it, we -have to explicitly cancel the task:

>>> async def main():
-...     bus = MessageBus()
-...     await setup(bus)
-...     bus_task = asyncio.create_task(bus.run())
-...     await send(bus)
-...     await asyncio.sleep(0)
-...     bus_task.cancel()
->>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-Sending messages.
-Logger: {'sender': '', 'event': 'registered',
-         'client': 'Logger', 'plugin': 'Test Plugin',
-         'sends': [], 'receives': [{}]}
-Logger: {'sender': '', 'event': 'registered',
-         'client': 'Client 1', 'plugin': 'Test Plugin',
-         'sends': [{'k1': {'type': 'string'}}],
-         'receives': [{'target': {'const': 'Client 1'}}]}
-Logger: {'sender': 'Client 1', 'k1': 'Test'}
-Logger: {'sender': '', 'target': 'Client 1'}
-Client 1: {'sender': '', 'target': 'Client 1'}
-

-Expand source code -

"""Provide an asynchronous message bus.
-
-A message is a dictionary with string keys and string, integer, float,
-Boolean, dictionary, or list values, where the inner dictionaries again
-have string keys and these values and the inner lists also have elements of
-these types. All messages have a special key 'sender' with the name of the
-sending client as string value, which is set by the constructor:
->>> m = Message('Example sender', {'key 1': 'value 1'})
->>> m['key 2'] = 'value 2'
->>> print(m)
-{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-
-A message template is a mapping from string keys to JSON schemas as values.
-A message template matches a message if all keys of the template are
-contained in the message and the values in the message validate against the
-respective schemas. An empty mapping therefore matches all messages.
-
-The bus executes asynchronous callbacks for all messages to be received by
-a client. We use a simple callback printing the message in all examples:
->>> def callback_for_receiver(receiver):
-...     async def callback(message):
-...         print(f"{receiver}: {message}")
-...     return callback
-
-Clients can be registered at the bus with a name, lists of message templates
-they want to use for sending and receiving and a callback function for
-receiving. An empty list of templates means that the client does not want to
-send or receive any messages, respectively. A list with an empty template
-means that it wants to send arbitrary or receive all messages, respectively:
->>> async def setup(bus):
-...     bus.register('Logger', 'Test Plugin',
-...                  [],
-...                  [{}],
-...                  callback_for_receiver('Logger'))
-...     bus.register('Client 1', 'Test Plugin',
-...                  [{'k1': {'type': 'string'}}],
-...                  [{'target': {'const': 'Client 1'}}],
-...                  callback_for_receiver('Client 1'))
-
-While most clients should always use their own name for sending, this is not
-enforced and debugging or management clients could send messages on behalf
-of arbitrary client names.
-
-The name of a client has to be unique and is not allowed to be empty
-(otherwise registration fails).
-
-The empty name is used to refer to the bus itself. The bus sends messages
-for registrations and deregistrations of clients containing their complete
-interface of send and receive templates. This can be used to allow dynamic
-(debug) clients to deal with arbitrary configurations of clients. The bus
-also reacts to 'get clients' command messages by sending the complete
-information of all currently registered clients.
-
-Clients can send to the bus with the send function. Each message has to
-declare a sender. The send templates of that sender are checked for a
-template matching the message:
->>> async def send(bus):
-...     print("Sending messages.")
-...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
-...     await bus.send({'sender': '', 'target': 'Client 1'})
-
-The run function executes the message bus forever. If we want to stop it, we
-have to explicitly cancel the task:
->>> async def main():
-...     bus = MessageBus()
-...     await setup(bus)
-...     bus_task = asyncio.create_task(bus.run())
-...     await send(bus)
-...     await asyncio.sleep(0)
-...     bus_task.cancel()
->>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-Sending messages.
-Logger: {'sender': '', 'event': 'registered',
-         'client': 'Logger', 'plugin': 'Test Plugin',
-         'sends': [], 'receives': [{}]}
-Logger: {'sender': '', 'event': 'registered',
-         'client': 'Client 1', 'plugin': 'Test Plugin',
-         'sends': [{'k1': {'type': 'string'}}],
-         'receives': [{'target': {'const': 'Client 1'}}]}
-Logger: {'sender': 'Client 1', 'k1': 'Test'}
-Logger: {'sender': '', 'target': 'Client 1'}
-Client 1: {'sender': '', 'target': 'Client 1'}
-"""
-import asyncio
-import json
-import jsonschema  # type: ignore
-
-from typing import Union, Dict, List, Any, Iterable, Callable, Coroutine
-MessageValue = Union[None, str, int, float, bool, Dict[str, Any], List[Any]]
-# Should really be:
-# MessageValue = Union[None, str, int, float, bool,
-#                      Dict[str, 'MessageValue'], List['MessageValue']]
-# But mypy does not support recursion by now:
-# https://github.com/python/mypy/issues/731
-JSONSchema = Union[bool, Dict[str, MessageValue]]
-# Could be even more specific.
-MessageCallback = Callable[['Message'], Coroutine[Any, Any, None]]
-
-
-class Message(Dict[str, MessageValue]):
-    """Define arbitrary message.
-
-    Messages are dictionaries with string keys and values that are strings,
-    integers, floats, Booleans, dictionaries that recursively have string
-    keys and values of any of these types, or lists with elements that have
-    any of these types. These constraints are checked when setting key-value
-    pairs of the message.
-
-    A message has to have a sender, which is set by the constructor:
-    >>> m = Message('Example sender')
-    >>> print(m)
-    {'sender': 'Example sender'}
-
-    A dictionary can be given to the constructor:
-    >>> m = Message('Example sender', {'key 1': 'value 1', 'key 2': 'value 2'})
-    >>> print(m)
-    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-
-    Or the message can be modified after construction:
-    >>> m = Message('Example sender', {'key 1': 'value 1'})
-    >>> m['key 2'] = 'value 2'
-    >>> print(m)
-    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-    """
-
-    def __init__(self, sender: str,
-                 init: Dict[str, MessageValue] = None) -> None:
-        """Initialise message.
-
-        Message is initialised with given sender and possibly given
-        key-value pairs:
-        >>> m = Message('Example sender')
-        >>> print(m)
-        {'sender': 'Example sender'}
-        >>> m = Message('Example sender', {'key 1': 'value 1'})
-        >>> print(m)
-        {'sender': 'Example sender', 'key 1': 'value 1'}
-
-        The sender can be overwritten by the key-value pairs:
-        >>> m = Message('Example sender', {'sender': 'Another sender'})
-        >>> print(m)
-        {'sender': 'Another sender'}
-        """
-        if not isinstance(sender, str):
-            raise TypeError(f"'{sender}' is not a valid sender name"
-                            " (not a string).")
-        self['sender'] = sender
-        if init is not None:
-            self.update(init)
-
-    @staticmethod
-    def check_value(value: MessageValue) -> bool:
-        """Check recursively if a given value is valid.
-
-        None, strings, integers, floats and Booleans are valid:
-        >>> Message.check_value(None)
-        True
-        >>> Message.check_value('Spam')
-        True
-        >>> Message.check_value(42)
-        True
-        >>> Message.check_value(42.42)
-        True
-        >>> Message.check_value(False)
-        True
-
-        Other basic types are not valid:
-        >>> Message.check_value(b'bytes')
-        False
-        >>> Message.check_value(1j)
-        False
-
-        Dictionaries with string keys and recursively valid values are valid:
-        >>> Message.check_value({'str value': 'Spam', 'int value': 42,
-        ...                      'float value': 42.42, 'bool value': False})
-        True
-
-        Empty dictionaries are valid:
-        >>> Message.check_value({})
-        True
-
-        Dictionaries with other keys are not valid:
-        >>> Message.check_value({42: 'int key'})
-        False
-
-        Dictionaries with invalid values are not valid:
-        >>> Message.check_value({'complex value': 1j})
-        False
-
-        Lists with valid elements are valid:
-        >>> Message.check_value(['Spam', 42, 42.42, False])
-        True
-
-        Empty lists are valid:
-        >>> Message.check_value([])
-        True
-
-        Lists with invalid elements are not valid:
-        >>> Message.check_value([1j])
-        False
-        """
-        if value is None:
-            return True
-        elif (isinstance(value, str) or isinstance(value, int) or
-                isinstance(value, float) or isinstance(value, bool)):
-            return True
-        elif isinstance(value, dict):
-            for key in value:
-                if not isinstance(key, str):
-                    return False
-                if not Message.check_value(value[key]):
-                    return False
-            return True
-        elif isinstance(value, list):
-            for element in value:
-                if not Message.check_value(element):
-                    return False
-            return True
-        return False
-
-    def __setitem__(self, key: str, value: MessageValue) -> None:
-        """Check key and value before putting pair into dict.
-
-        >>> m = Message('Example sender')
-        >>> m['key'] = 'value'
-        >>> m['dict'] = {'k1': 'v1', 'k2': 2}
-        >>> print(m)  # doctest: +NORMALIZE_WHITESPACE
-        {'sender': 'Example sender', 'key': 'value',
-         'dict': {'k1': 'v1', 'k2': 2}}
-        >>> m = Message('Example sender')
-        >>> m[42] = 'int key'
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in Message (not a string).
-        >>> m['complex value'] = 1j
-        Traceback (most recent call last):
-          ...
-        TypeError: '1j' is not a valid value in Message.
-        """
-        if not isinstance(key, str):
-            raise TypeError(f"'{key}' is not a valid key in Message"
-                            " (not a string).")
-        if not self.check_value(value):
-            raise TypeError(f"'{value}' is not a valid value in Message.")
-        super().__setitem__(key, value)
-
-    def update(self, *args, **kwargs) -> None:
-        """Override update to use validity checks.
-
-        >>> m = Message('Example sender')
-        >>> m.update({'key 1': 'value 1', 'key 2': 'value 2'})
-        >>> print(m)
-        {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-        >>> m.update({42: 'int key'})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in Message (not a string).
-        >>> m.update({'complex value': 1j})
-        Traceback (most recent call last):
-          ...
-        TypeError: '1j' is not a valid value in Message.
-
-        This is also used in __init__:
-        >>> m = Message('Example sender', {'key': 'value'})
-        >>> print(m)
-        {'sender': 'Example sender', 'key': 'value'}
-        >>> m = Message('Example sender', {42: 'int key'})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in Message (not a string).
-        >>> m = Message('Example sender', {'complex value': 1j})
-        Traceback (most recent call last):
-          ...
-        TypeError: '1j' is not a valid value in Message.
-        """
-        if args:
-            if len(args) > 1:
-                raise TypeError("update expected at most 1 argument,"
-                                f" got {len(args)}")
-            other = dict(args[0])
-            for key in other:
-                self[key] = other[key]
-        for key in kwargs:
-            self[key] = kwargs[key]
-
-    def setdefault(self, key: str, value: MessageValue = None) -> MessageValue:
-        """Override setdefault to use validity checks.
-
-        >>> m = Message('Example sender')
-        >>> m.setdefault('key', 'value 1')
-        'value 1'
-        >>> m.setdefault('key', 'value 2')
-        'value 1'
-        >>> m.setdefault(42, 'int key')
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in Message (not a string).
-        >>> m.setdefault('complex value', 1j)
-        Traceback (most recent call last):
-          ...
-        TypeError: '1j' is not a valid value in Message.
-
-        But __setitem__ is not called if the key is already present:
-        >>> m.setdefault('key', 1j)
-        'value 1'
-        """
-        if key not in self:
-            self[key] = value
-        return self[key]
-
-
-class MessageTemplate(Dict[str, JSONSchema]):
-    """Define a message template.
-
-    A message template is a mapping from string keys to JSON schemas as
-    values:
-    >>> t = MessageTemplate({'key 1': {'const': 'value'},
-    ...                      'key 2': {'type': 'string'}})
-    >>> t['key 3'] = {'type': 'object',
-    ...               'properties': {'key 1': {'type': 'number'},
-    ...                              'key 2': True}}
-
-    A message template matches a message if all keys of the template are
-    contained in the message and the values in the message validate against
-    the respective schemas:
-    >>> t.check(Message('Example Sender',
-    ...                 {'key 1': 'value', 'key 2': 'some string',
-    ...                  'key 3': {'key 1': 42, 'key 2': None}}))
-    True
-
-    An empty mapping therefore matches all messages:
-    >>> t = MessageTemplate()
-    >>> t.check(Message('Example Sender', {'arbitrary': 'content'}))
-    True
-    """
-
-    def __init__(self, init: Dict[str, JSONSchema] = None) -> None:
-        """Initialise message.
-
-        Template is initialised empty or with given key-value pairs:
-        >>> t = MessageTemplate()
-        >>> print(t)
-        {}
-        >>> t = MessageTemplate({'key': {'const': 'value'}})
-        >>> print(t)
-        {'key': {'const': 'value'}}
-        """
-        if init is not None:
-            self.update(init)
-
-    @staticmethod
-    def from_message(message: Message) -> 'MessageTemplate':
-        """Create template from message.
-
-        Template witch constant schemas is created from message:
-        >>> m = Message('Example Sender', {'key': 'value'})
-        >>> t = MessageTemplate.from_message(m)
-        >>> print(t)
-        {'sender': {'const': 'Example Sender'}, 'key': {'const': 'value'}}
-        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
-        ...                                'list': [None, True, 'string']})
-        >>> t = MessageTemplate.from_message(m)
-        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-        {'sender': {'const': 'Example Sender'},
-         'dict': {'type': 'object',
-                  'properties': {'int': {'const': 42},
-                                 'float': {'const': 42.42}}},
-         'list': {'type': 'array',
-                  'items': [{'const': None},
-                            {'const': True},
-                            {'const': 'string'}]}}
-
-        This is especially useful for clients that send certain fully
-        predefined messages, where the message is given in the configuration
-        and the template for the registration can be constructed by this
-        method.
-        """
-        def schema_from_value(value: MessageValue) -> JSONSchema:
-            schema: JSONSchema = False
-            if value is None:
-                schema = {'const': None}
-            elif (isinstance(value, str) or isinstance(value, int) or
-                    isinstance(value, float) or isinstance(value, bool)):
-                schema = {'const': value}
-            elif isinstance(value, dict):
-                properties = {}
-                for inner_key in value:
-                    inner_value: Message = value[inner_key]
-                    properties[inner_key] = schema_from_value(inner_value)
-                schema = {'type': 'object',
-                          'properties': properties}
-            elif isinstance(value, list):
-                schema = {'type': 'array',
-                          'items': [schema_from_value(element)
-                                    for element in value]}
-            return schema
-        template = MessageTemplate()
-        for key in message:
-            template[key] = schema_from_value(message[key])
-        return template
-
-    def __setitem__(self, key: str, value: JSONSchema) -> None:
-        """Check key and value before putting pair into dict.
-
-        >>> t = MessageTemplate()
-        >>> t['key 1'] = {'const': 'value'}
-        >>> t['key 2'] = {'type': 'string'}
-        >>> t['key 3'] = {'type': 'object',
-        ...               'properties': {'key 1': {'type': 'number'},
-        ...                              'key 2': True}}
-        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
-         'key 3': {'type': 'object',
-                   'properties': {'key 1': {'type': 'number'},
-                                  'key 2': True}}}
-        >>> t[42] = {'const': 'int key'}
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in MessageTemplate (not a string).
-        >>> t['key'] = 'schema'  # doctest: +NORMALIZE_WHITESPACE
-        Traceback (most recent call last):
-          ...
-        TypeError: 'schema' is not a valid value in MessageTemplate
-        (not a valid JSON schema).
-        """
-        if not isinstance(key, str):
-            raise TypeError(f"'{key}' is not a valid key in MessageTemplate"
-                            " (not a string).")
-        try:
-            jsonschema.Draft7Validator.check_schema(value)
-            # Draft7Validator is hardcoded, because _LATEST_VERSION is
-            # non-public in jsonschema and we also perhaps do not want to
-            # upgrade automatically.
-        except jsonschema.exceptions.SchemaError:
-            raise TypeError(f"'{value}' is not a valid value in"
-                            " MessageTemplate (not a valid JSON schema).")
-        super().__setitem__(key, value)
-
-    def update(self, *args, **kwargs) -> None:
-        """Override update to use validity checks.
-
-        >>> t = MessageTemplate()
-        >>> t.update({'key 1': {'const': 'value'},
-        ...           'key 2': {'type': 'string'},
-        ...           'key 3': {'type': 'object',
-        ...                     'properties': {'key 1': {'type': 'number'},
-        ...                                    'key 2': True}}})
-        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
-         'key 3': {'type': 'object',
-                   'properties': {'key 1': {'type': 'number'},
-                                  'key 2': True}}}
-        >>> t.update({42: {'const': 'int key'}})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in MessageTemplate (not a string).
-        >>> t.update({'key': 'schema'})  # doctest: +NORMALIZE_WHITESPACE
-        Traceback (most recent call last):
-          ...
-        TypeError: 'schema' is not a valid value in MessageTemplate
-        (not a valid JSON schema).
-
-        This is also used in __init__:
-        >>> t = MessageTemplate({'key 1': {'const': 'value'},
-        ...                      'key 2': {'type': 'string'},
-        ...                      'key 3': {'type': 'object',
-        ...                                'properties': {
-        ...                                    'key 1': {'type': 'number'},
-        ...                                    'key 2': True}}})
-        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
-         'key 3': {'type': 'object',
-                   'properties': {'key 1': {'type': 'number'},
-                                  'key 2': True}}}
-        >>> t = MessageTemplate({42: {'const': 'int key'}})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in MessageTemplate (not a string).
-        >>> t = MessageTemplate({'key': 'schema'})
-        ... # doctest: +NORMALIZE_WHITESPACE
-        Traceback (most recent call last):
-          ...
-        TypeError: 'schema' is not a valid value in MessageTemplate
-        (not a valid JSON schema).
-        """
-        if args:
-            if len(args) > 1:
-                raise TypeError("update expected at most 1 argument,"
-                                f" got {len(args)}")
-            other = dict(args[0])
-            for key in other:
-                self[key] = other[key]
-        for key in kwargs:
-            self[key] = kwargs[key]
-
-    def setdefault(self, key: str, value: JSONSchema = None) -> JSONSchema:
-        """Override setdefault to use validity checks.
-
-        >>> t = MessageTemplate()
-        >>> t.setdefault('key 1', {'const': 'value'})
-        {'const': 'value'}
-        >>> t.setdefault('key 2', {'type': 'string'})
-        {'type': 'string'}
-        >>> t.setdefault('key 3', {'type': 'object',
-        ...                        'properties': {'key 1': {'type': 'number'},
-        ...                                       'key 2': True}})
-        ... # doctest: +NORMALIZE_WHITESPACE
-        {'type': 'object',
-                   'properties': {'key 1': {'type': 'number'},
-                                  'key 2': True}}
-        >>> t.setdefault(42, {'const': 'int key'})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in MessageTemplate (not a string).
-        >>> t.setdefault('key', 'schema')  # doctest: +NORMALIZE_WHITESPACE
-        Traceback (most recent call last):
-          ...
-        TypeError: 'schema' is not a valid value in MessageTemplate
-        (not a valid JSON schema).
-
-        But __setitem__ is not called if the key is already present:
-        >>> t.setdefault('key 1', 'schema')
-        {'const': 'value'}
-        """
-        if key not in self:
-            if value is not None:
-                self[key] = value
-            else:
-                self[key] = True
-        return self[key]
-
-    def check(self, message: Message) -> bool:
-        """Check message against this template.
-
-        Constant values have to match exactly:
-        >>> t = MessageTemplate({'key': {'const': 'value'}})
-        >>> t.check(Message('Example Sender', {'key': 'value'}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 'other value'}))
-        False
-
-        But for integers, floats with the same value are also valid:
-        >>> t = MessageTemplate({'key': {'const': 42}})
-        >>> t.check(Message('Example Sender', {'key': 42}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 42.0}))
-        True
-
-        Type integer is valid for floats with zero fractional part, but
-        not by floats with non-zero fractional part:
-        >>> t = MessageTemplate({'key': {'type': 'integer'}})
-        >>> t.check(Message('Example Sender', {'key': 42}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 42.0}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 42.42}))
-        False
-
-        Type number is valid for arbitrary ints or floats:
-        >>> t = MessageTemplate({'key': {'type': 'number'}})
-        >>> t.check(Message('Example Sender', {'key': 42}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 42.42}))
-        True
-
-        All keys in template have to be present in message:
-        >>> t = MessageTemplate({'key 1': {'const': 'value'},
-        ...                      'key 2': {'type': 'string'},
-        ...                      'key 3': {'type': 'object',
-        ...                                'properties': {
-        ...                                    'key 1': {'type': 'number'},
-        ...                                    'key 2': True,
-        ...                                    'key 3': False}}})
-        >>> t.check(Message('Example Sender',
-        ...                 {'key 1': 'value', 'key 2': 'some string'}))
-        False
-
-        But for nested objects their properties do not necessarily have
-        to be present:
-        >>> t.check(Message('Example Sender',
-        ...                 {'key 1': 'value', 'key 2': 'some string',
-        ...                  'key 3': {'key 1': 42}}))
-        True
-
-        Schema True matches everything (even None):
-        >>> t.check(Message('Example Sender',
-        ...                 {'key 1': 'value', 'key 2': 'some string',
-        ...                  'key 3': {'key 2': None}}))
-        True
-
-        Schema False matches nothing:
-        >>> t.check(Message('Example Sender',
-        ...                 {'key 1': 'value', 'key 2': 'some string',
-        ...                  'key 3': {'key 3': True}}))
-        False
-
-        Message is valid for the constant template created from it:
-        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
-        ...                                'list': [None, True, 'string']})
-        >>> t = MessageTemplate.from_message(m)
-        >>> t.check(m)
-        True
-        """
-        for key in self:
-            if key not in message:
-                return False
-            else:
-                validator = jsonschema.Draft7Validator(self[key])
-                for error in validator.iter_errors(message[key]):
-                    return False
-        return True
-
-
-class MessageTemplateRegistry:
-    """Manage a collection of message templates with registered clients.
-
-    A new MessageTemplateRegistry is created by:
-    >>> r = MessageTemplateRegistry()
-
-    Client names (strings) can be registered for message templates, which
-    are mappings from keys to JSON schemas:
-    >>> r.insert({'k1': {'const': 'v1'}}, 'C 1')
-
-    The check function checks if the templates registered for a client
-    match a given message:
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 1', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: True
-    {'k1': 'v1', 'k2': 2}: True
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 2}: False
-
-    Clients can be registered for values validating against arbitrary JSON
-    schemas, e.g. all values of a certain type:
-    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}, 'C 2')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 2', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 2}: False
-    {'k1': 'v2', 'k2': 'v1'}: True
-    {'k1': 'v2', 'k2': 2}: False
-    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}, 'C 3')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 3', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 2}: False
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 2}: True
-
-    The order of key-value pairs does not have to match the order in the
-    messages and keys can be left out:
-    >>> r.insert({'k2': {'const': 2}}, 'C 4')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 4', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 2}: True
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 2}: True
-
-    A registration for an empty template matches all messages:
-    >>> r.insert({}, 'C 5')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 5', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: True
-    {'k1': 'v1', 'k2': 2}: True
-    {'k1': 'v2', 'k2': 'v1'}: True
-    {'k1': 'v2', 'k2': 2}: True
-
-    A client can be registered for multiple templates:
-    >>> r.insert({'k1': {'const': 'v1'}}, 'C 6')
-    >>> r.insert({'k2': {'const': 'v1'}}, 'C 6')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 6', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: True
-    {'k1': 'v1', 'k2': 2}: True
-    {'k1': 'v2', 'k2': 'v1'}: True
-    {'k1': 'v2', 'k2': 2}: False
-
-    Clients can be deregistered again (the result is False if the registry
-    is empty after the deletion):
-    >>> r.insert({'k1': {'const': 'v1'}}, 'C 7')
-    >>> r.delete('C 7')
-    True
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 7', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 2}: False
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 2}: False
-
-    The get function returns all clients with registered templates matching
-    a given message:
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.get(m)}")
-    {'k1': 'v1', 'k2': 'v1'}: ['C 5', 'C 1', 'C 6']
-    {'k1': 'v1', 'k2': 2}: ['C 5', 'C 1', 'C 6', 'C 4']
-    {'k1': 'v2', 'k2': 'v1'}: ['C 5', 'C 2', 'C 6']
-    {'k1': 'v2', 'k2': 2}: ['C 5', 'C 3', 'C 4']
-
-    The get_templates function returns all templates for a given client:
-    >>> for c in ['C 1', 'C 2', 'C 3', 'C 4', 'C 5', 'C 6']:
-    ...     print(f"{c}: {r.get_templates(c)}")
-    C 1: [{'k1': {'const': 'v1'}}]
-    C 2: [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
-    C 3: [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
-    C 4: [{'k2': {'const': 2}}]
-    C 5: [{}]
-    C 6: [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
-    """
-
-    def __init__(self) -> None:
-        """Initialise an empty registry.
-
-        >>> r = MessageTemplateRegistry()
-        """
-        self._clients: List[str] = []
-        self._children: Dict[str, Dict[str, MessageTemplateRegistry]] = {}
-
-    def insert(self, template: MessageTemplate, client: str) -> None:
-        """Register a client for a template.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v1'}}, 'C 1')
-        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v2'}}, 'C 2')
-        >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v1'}}, 'C 3')
-        >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v2'}}, 'C 4')
-        >>> r.insert({}, 'C 5')
-
-        Implementation details:
-        -----------------------
-        The tree nodes on the way to a registered object are used/created
-        in the order given in the message template, which can be used to
-        design more efficient lookups (e.g., putting rarer key-value pairs
-        earlier in the template).
-        >>> r._clients
-        ['C 5']
-        >>> r._children.keys()
-        dict_keys(['k1'])
-        >>> r._children['k1'].keys()
-        dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-        >>> r._children['k1']['{"const": "v1"}']._clients
-        []
-        >>> r._children['k1']['{"const": "v1"}']._children.keys()
-        dict_keys(['k2'])
-        >>> r._children['k1']['{"const": "v1"}']._children['k2'].keys()
-        dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v1"}'])._clients
-        ['C 1']
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-        dict_keys([])
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v2"}'])._clients
-        ['C 2']
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-        dict_keys([])
-        >>> r._children['k1']['{"const": "v2"}']._clients
-        []
-        >>> r._children['k1']['{"const": "v2"}']._children.keys()
-        dict_keys(['k2'])
-        >>> r._children['k1']['{"const": "v2"}']._children['k2'].keys()
-        dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-        >>> (r._children['k1']['{"const": "v2"}']
-        ...   ._children['k2']['{"const": "v1"}'])._clients
-        ['C 3']
-        >>> (r._children['k1']['{"const": "v2"}']
-        ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-        dict_keys([])
-        >>> (r._children['k1']['{"const": "v2"}']
-        ...   ._children['k2']['{"const": "v2"}'])._clients
-        ['C 4']
-        >>> (r._children['k1']['{"const": "v2"}']
-        ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-        dict_keys([])
-        """
-        if not template:
-            self._clients.append(client)
-        else:
-            key, schema = next(iter(template.items()))
-            schema_string = json.dumps(schema)
-            reduced_template = MessageTemplate({k: template[k]
-                                                for k in template
-                                                if k != key})
-            if key not in self._children:
-                self._children[key] = {}
-            if schema_string not in self._children[key]:
-                self._children[key][schema_string] = MessageTemplateRegistry()
-            self._children[key][schema_string].insert(reduced_template, client)
-
-    def delete(self, client: str) -> bool:
-        """Unregister a client from all templates.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v1'}}, 'C 1')
-        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v2'}}, 'C 2')
-        >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v1'}}, 'C 3')
-        >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v2'}}, 'C 4')
-        >>> r.insert({}, 'C 5')
-        >>> r.delete('C 3')
-        True
-        >>> r.delete('C 4')
-        True
-
-        Implementation details:
-        -----------------------
-        If parts of the tree become superfluous by the deletion of the
-        client, they are also completely removed to reduce the lookup
-        effort and keep the tree clean.
-        >>> r._clients
-        ['C 5']
-        >>> r._children.keys()
-        dict_keys(['k1'])
-        >>> r._children['k1'].keys()
-        dict_keys(['{"const": "v1"}'])
-        >>> r._children['k1']['{"const": "v1"}']._clients
-        []
-        >>> r._children['k1']['{"const": "v1"}']._children.keys()
-        dict_keys(['k2'])
-        >>> r._children['k1']['{"const": "v1"}']._children['k2'].keys()
-        dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v1"}'])._clients
-        ['C 1']
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-        dict_keys([])
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v2"}'])._clients
-        ['C 2']
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-        dict_keys([])
-        """
-        self._clients = [c for c in self._clients if c != client]
-        new_children: Dict[str, Dict[str, MessageTemplateRegistry]] = {}
-        for key in self._children:
-            new_children[key] = {}
-            for schema in self._children[key]:
-                if self._children[key][schema].delete(client):
-                    new_children[key][schema] = self._children[key][schema]
-            if not new_children[key]:
-                del new_children[key]
-        self._children = new_children
-        if self._clients or self._children:
-            return True
-        return False
-
-    def check(self, client: str, message: Message) -> bool:
-        """Get if a client has a registered template matching a message.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-        ...     print(f"{m}: {r.check('Client 1', m)}")
-        {'k1': 'v1', 'k2': 'v1'}: True
-        {'k1': 'v1', 'k2': 'v2'}: True
-        {'k1': 'v2', 'k2': 'v1'}: False
-        {'k1': 'v2', 'k2': 'v2'}: False
-        >>> r.insert({'k2': {'const': 'v2'}}, 'Client 2')
-        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-        ...     print(f"{m}: {r.check('Client 2', m)}")
-        {'k1': 'v1', 'k2': 'v1'}: False
-        {'k1': 'v1', 'k2': 'v2'}: True
-        {'k1': 'v2', 'k2': 'v1'}: False
-        {'k1': 'v2', 'k2': 'v2'}: True
-        """
-        if client in self._clients:
-            return True
-        for key in self._children:
-            if key in message:
-                for schema_string in self._children[key]:
-                    schema = json.loads(schema_string)
-                    validator = jsonschema.Draft7Validator(schema)
-                    validated = True
-                    for error in validator.iter_errors(message[key]):
-                        validated = False
-                    if validated:
-                        child = self._children[key][schema_string]
-                        if child.check(client, message):
-                            return True
-        return False
-
-    def get(self, message: Message) -> List[str]:
-        """Get all clients registered for templates matching a message.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-        >>> r.insert({'k2': {'const': 'v2'}}, 'Client 2')
-        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-        ...     print(f"{m}: {r.get(m)}")
-        {'k1': 'v1', 'k2': 'v1'}: ['Client 1']
-        {'k1': 'v1', 'k2': 'v2'}: ['Client 1', 'Client 2']
-        {'k1': 'v2', 'k2': 'v1'}: []
-        {'k1': 'v2', 'k2': 'v2'}: ['Client 2']
-        """
-        result = []
-        for client in self._clients:
-            if client not in result:
-                result.append(client)
-        for key in self._children:
-            if key in message:
-                for schema_string in self._children[key]:
-                    schema = json.loads(schema_string)
-                    validator = jsonschema.Draft7Validator(schema)
-                    validated = True
-                    for error in validator.iter_errors(message[key]):
-                        validated = False
-                    if validated:
-                        child = self._children[key][schema_string]
-                        for client in child.get(message):
-                            if client not in result:
-                                result.append(client)
-        return result
-
-    def get_templates(self, client: str) -> List[MessageTemplate]:
-        """Get all templates for a client.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-        >>> r.get_templates('Client 1')
-        [{'k1': {'const': 'v1'}}]
-        >>> r.insert({'k1': {'const': 'v2'},
-        ...           'k2': {'type': 'string'}}, 'Client 2')
-        >>> r.get_templates('Client 2')
-        [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
-        >>> r.insert({'k1': {'const': 'v2'},
-        ...           'k2': {'type': 'integer'}}, 'Client 3')
-        >>> r.get_templates('Client 3')
-        [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
-        >>> r.insert({'k2': {'const': 2}}, 'Client 4')
-        >>> r.get_templates('Client 4')
-        [{'k2': {'const': 2}}]
-        >>> r.insert({}, 'Client 5')
-        >>> r.get_templates('Client 5')
-        [{}]
-        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 6')
-        >>> r.insert({'k2': {'const': 'v1'}}, 'Client 6')
-        >>> r.get_templates('Client 6')
-        [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
-        """
-        result = []
-        if client in self._clients:
-            result.append(MessageTemplate())
-        for key in self._children:
-            for schema_string in self._children[key]:
-                schema = json.loads(schema_string)
-                child = self._children[key][schema_string]
-                for template in child.get_templates(client):
-                    current = MessageTemplate({key: schema})
-                    current.update(template)
-                    result.append(current)
-        return result
-
-
-class BusException(Exception):
-    """Raise for errors in using message bus."""
-
-
-class MessageBus:
-    """Provide an asynchronous message bus.
-
-    The bus executes asynchronous callbacks for all messages to be received
-    by a client. We use a simple callback printing the message in all
-    examples:
-    >>> def callback_for_receiver(receiver):
-    ...     print(f"Creating callback for {receiver}.")
-    ...     async def callback(message):
-    ...         print(f"{receiver}: {message}")
-    ...     return callback
-
-    Clients can be registered at the bus with a name, lists of message
-    templates they want to use for sending and receiving and a callback
-    function for receiving. An empty list of templates means that the
-    client does not want to send or receive any messages, respectively.
-    A list with an empty template means that it wants to send arbitrary
-    or receive all messages, respectively:
-    >>> async def setup(bus):
-    ...     print("Setting up.")
-    ...     bus.register('Logger', 'Test Plugin',
-    ...                  [],
-    ...                  [{}],
-    ...                  callback_for_receiver('Logger'))
-    ...     bus.register('Client 1', 'Test Plugin',
-    ...                  [{'k1': {'type': 'string'}}],
-    ...                  [{'target': {'const': 'Client 1'}}],
-    ...                  callback_for_receiver('Client 1'))
-    ...     bus.register('Client 2', 'Test Plugin',
-    ...                  [{}],
-    ...                  [{'target': {'const': 'Client 2'}}],
-    ...                  callback_for_receiver('Client 2'))
-
-    The bus itself is addressed by the empty string. It sends messages for
-    each registration and deregestration of a client with a key 'event' and
-    a value of 'registered' or 'unregistered', a key 'client' with the
-    client's name as value and for registrations also keys 'sends' and
-    'receives' with all templates registered for the client for sending and
-    receiving.
-
-    Clients can send to the bus with the send function. Each message has to
-    declare a sender. The send templates of that sender are checked for a
-    template matching the message. We cannot prevent arbitrary code from
-    impersonating any sender, but this should only be done in debugging or
-    management situations.
-
-    Messages that are intended for a specific client by convention have a
-    key 'target' with the target client's name as value. Such messages are
-    often commands to the client to do something, which is by convention
-    indicated by a key 'command' with a value that indicates what should be
-    done.
-
-    The bus, for example, reacts to a message with 'target': '' and
-    'command': 'get clients' by sending one message for each currently
-    registered with complete information about its registered send and
-    receive templates.
-
-    >>> async def send(bus):
-    ...     print("Sending messages.")
-    ...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
-    ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
-    ...     await bus.send({'sender': '', 'target': '',
-    ...                     'command': 'get clients'})
-
-    The run function executes the message bus forever. If we want to stop
-    it, we have to explicitly cancel the task:
-    >>> async def main():
-    ...     bus = MessageBus()
-    ...     await setup(bus)
-    ...     bus_task = asyncio.create_task(bus.run())
-    ...     await send(bus)
-    ...     await asyncio.sleep(0)
-    ...     bus_task.cancel()
-    >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-    Setting up.
-    Creating callback for Logger.
-    Creating callback for Client 1.
-    Creating callback for Client 2.
-    Sending messages.
-    Logger: {'sender': '', 'event': 'registered',
-             'client': 'Logger', 'plugin': 'Test Plugin',
-             'sends': [], 'receives': [{}]}
-    Logger: {'sender': '', 'event': 'registered',
-             'client': 'Client 1', 'plugin': 'Test Plugin',
-             'sends': [{'k1': {'type': 'string'}}],
-             'receives': [{'target': {'const': 'Client 1'}}]}
-    Logger: {'sender': '', 'event': 'registered',
-             'client': 'Client 2', 'plugin': 'Test Plugin',
-             'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
-    Logger: {'sender': 'Client 1', 'k1': 'Test'}
-    Logger: {'sender': 'Client 2', 'target': 'Client 1'}
-    Client 1: {'sender': 'Client 2', 'target': 'Client 1'}
-    Logger: {'sender': '', 'target': '', 'command': 'get clients'}
-    Logger: {'sender': '', 'client': 'Logger', 'plugin': 'Test Plugin',
-             'sends': [], 'receives': [{}]}
-    Logger: {'sender': '', 'client': 'Client 1', 'plugin': 'Test Plugin',
-             'sends': [{'k1': {'type': 'string'}}],
-             'receives': [{'target': {'const': 'Client 1'}}]}
-    Logger: {'sender': '', 'client': 'Client 2', 'plugin': 'Test Plugin',
-             'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
-    """
-
-    def __init__(self) -> None:
-        """Initialise a new bus without clients.
-
-        >>> async def main():
-        ...     bus = MessageBus()
-        >>> asyncio.run(main())
-        """
-        self._queue: asyncio.Queue = asyncio.Queue()
-        self._plugins: Dict[str, str] = {}
-        self._send_reg: MessageTemplateRegistry = MessageTemplateRegistry()
-        self._recv_reg: MessageTemplateRegistry = MessageTemplateRegistry()
-        self._callbacks: Dict[str, MessageCallback] = {}
-
-    def register(self, client: str, plugin: str,
-                 sends: Iterable[MessageTemplate],
-                 receives: Iterable[MessageTemplate],
-                 callback: MessageCallback) -> None:
-        """Register a client at the message bus.
-
-        >>> async def callback(message):
-        ...     print(message)
-        >>> async def main():
-        ...     bus = MessageBus()
-        ...     bus.register('Logger', 'Test Plugin',
-        ...                  [],    # send nothing
-        ...                  [{}],  # receive everything
-        ...                  callback)
-        ...     bus.register('Client 1', 'Test Plugin',
-        ...                  [{'k1': {'type': 'string'}}],
-        ...                      # send with key 'k1' and string value
-        ...                  [{'target': {'const': 'Client 1'}}],
-        ...                      # receive for this client
-        ...                  callback)
-        ...     bus.register('Client 2', 'Test Plugin',
-        ...                  [{}],  # send arbitrary
-        ...                  [{'target': {'const': 'Client 2'}}],
-        ...                      # receive for this client
-        ...                  callback)
-        >>> asyncio.run(main())
-        """
-        if not client:
-            raise BusException("Client name is not allowed to be empty.")
-        if client in self._plugins:
-            raise BusException(f"Client '{client}' already registered"
-                               " at message bus.")
-        event = Message('')
-        event['event'] = 'registered'
-        event['client'] = client
-        self._plugins[client] = plugin
-        event['plugin'] = plugin
-        for template in sends:
-            self._send_reg.insert(template, client)
-        event['sends'] = self._send_reg.get_templates(client)
-        for template in receives:
-            self._recv_reg.insert(template, client)
-        event['receives'] = self._recv_reg.get_templates(client)
-        self._callbacks[client] = callback
-        self._queue.put_nowait(event)
-
-    def unregister(self, client: str) -> None:
-        """Unregister a client from the message bus.
-
-        >>> async def callback(message):
-        ...     print(message)
-        >>> async def main():
-        ...     bus = MessageBus()
-        ...     bus.register('Client 1', 'Test Plugin',
-        ...                  [{'k1': {'type': 'string'}}],
-        ...                  [{'target': {'const': 'Client 1'}}],
-        ...                  callback)
-        ...     bus.unregister('Client 1')
-        >>> asyncio.run(main())
-        """
-        if client not in self._plugins:
-            return
-        event = Message('')
-        event['event'] = 'unregistered'
-        event['client'] = client
-        del self._plugins[client]
-        self._send_reg.delete(client)
-        self._recv_reg.delete(client)
-        if client in self._callbacks:
-            del self._callbacks[client]
-        self._queue.put_nowait(event)
-
-    async def run(self) -> None:
-        """Run the message bus forever.
-
-        >>> async def main():
-        ...     bus = MessageBus()
-        ...     bus_task = asyncio.create_task(bus.run())
-        ...     bus_task.cancel()
-        >>> asyncio.run(main())
-        """
-        while True:
-            message = await self._queue.get()
-            if ('target' in message and
-                    message['target'] == '' and
-                    'command' in message and
-                    message['command'] == 'get clients'):
-                for client in self._plugins:
-                    answer = Message('')
-                    answer['client'] = client
-                    answer['plugin'] = self._plugins[client]
-                    answer['sends'] = self._send_reg.get_templates(client)
-                    answer['receives'] = self._recv_reg.get_templates(client)
-                    await self._queue.put(answer)
-            for client in self._recv_reg.get(message):
-                await self._callbacks[client](message)
-            self._queue.task_done()
-
-    async def send(self, message: Message) -> None:
-        """Send a message to the message bus.
-
-        >>> async def callback(message):
-        ...     print(f"Got: {message}")
-        >>> async def main():
-        ...     bus = MessageBus()
-        ...     bus.register('Client 1', 'Test Plugin',
-        ...                  [{'k1': {'type': 'string'}}],
-        ...                  [{'target': {'const': 'Client 1'}}],
-        ...                  callback)
-        ...     bus.register('Client 2', 'Test Plugin',
-        ...                  [{}],
-        ...                  [{'target': {'const': 'Client 2'}}],
-        ...                  callback)
-        ...     bus_task = asyncio.create_task(bus.run())
-        ...     await bus.send({'sender': 'Client 1', 'target': 'Client 2',
-        ...                     'k1': 'Test'})
-        ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
-        ...     try:
-        ...         await bus.send({'sender': 'Client 1', 'target': 'Client 2',
-        ...                         'k1': 42})
-        ...     except BusException as e:
-        ...         print(e)
-        ...     await asyncio.sleep(0)
-        ...     bus_task.cancel()
-        >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-        Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
-        not allowed for sender 'Client 1'.
-        Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
-        Got: {'sender': 'Client 2', 'target': 'Client 1'}
-        """
-        assert isinstance(message['sender'], str)
-        sender = message['sender']
-        if sender:
-            if not self._send_reg.check(sender, message):
-                raise BusException(f"Message '{message}' not allowed for"
-                                   f" sender '{sender}'.")
-        await self._queue.put(message)

Classes

-class Message -(sender:Â str, init:Â Dict[str,Â Union[NoneType,Â str,Â int,Â float,Â bool,Â Dict[str,Â Any],Â List[Any]]]Â =Â None) -

Define arbitrary message.

Messages are dictionaries with string keys and values that are strings, -integers, floats, Booleans, dictionaries that recursively have string -keys and values of any of these types, or lists with elements that have -any of these types. These constraints are checked when setting key-value -pairs of the message.

A message has to have a sender, which is set by the constructor:

>>> m = Message('Example sender')
->>> print(m)
-{'sender': 'Example sender'}
-

A dictionary can be given to the constructor:

>>> m = Message('Example sender', {'key 1': 'value 1', 'key 2': 'value 2'})
->>> print(m)
-{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-

Or the message can be modified after construction:

>>> m = Message('Example sender', {'key 1': 'value 1'})
->>> m['key 2'] = 'value 2'
->>> print(m)
-{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-

Initialise message.

Message is initialised with given sender and possibly given -key-value pairs:

>>> m = Message('Example sender')
->>> print(m)
-{'sender': 'Example sender'}
->>> m = Message('Example sender', {'key 1': 'value 1'})
->>> print(m)
-{'sender': 'Example sender', 'key 1': 'value 1'}
-

The sender can be overwritten by the key-value pairs:

>>> m = Message('Example sender', {'sender': 'Another sender'})
->>> print(m)
-{'sender': 'Another sender'}
-

-Expand source code -

class Message(Dict[str, MessageValue]):
-    """Define arbitrary message.
-
-    Messages are dictionaries with string keys and values that are strings,
-    integers, floats, Booleans, dictionaries that recursively have string
-    keys and values of any of these types, or lists with elements that have
-    any of these types. These constraints are checked when setting key-value
-    pairs of the message.
-
-    A message has to have a sender, which is set by the constructor:
-    >>> m = Message('Example sender')
-    >>> print(m)
-    {'sender': 'Example sender'}
-
-    A dictionary can be given to the constructor:
-    >>> m = Message('Example sender', {'key 1': 'value 1', 'key 2': 'value 2'})
-    >>> print(m)
-    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-
-    Or the message can be modified after construction:
-    >>> m = Message('Example sender', {'key 1': 'value 1'})
-    >>> m['key 2'] = 'value 2'
-    >>> print(m)
-    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-    """
-
-    def __init__(self, sender: str,
-                 init: Dict[str, MessageValue] = None) -> None:
-        """Initialise message.
-
-        Message is initialised with given sender and possibly given
-        key-value pairs:
-        >>> m = Message('Example sender')
-        >>> print(m)
-        {'sender': 'Example sender'}
-        >>> m = Message('Example sender', {'key 1': 'value 1'})
-        >>> print(m)
-        {'sender': 'Example sender', 'key 1': 'value 1'}
-
-        The sender can be overwritten by the key-value pairs:
-        >>> m = Message('Example sender', {'sender': 'Another sender'})
-        >>> print(m)
-        {'sender': 'Another sender'}
-        """
-        if not isinstance(sender, str):
-            raise TypeError(f"'{sender}' is not a valid sender name"
-                            " (not a string).")
-        self['sender'] = sender
-        if init is not None:
-            self.update(init)
-
-    @staticmethod
-    def check_value(value: MessageValue) -> bool:
-        """Check recursively if a given value is valid.
-
-        None, strings, integers, floats and Booleans are valid:
-        >>> Message.check_value(None)
-        True
-        >>> Message.check_value('Spam')
-        True
-        >>> Message.check_value(42)
-        True
-        >>> Message.check_value(42.42)
-        True
-        >>> Message.check_value(False)
-        True
-
-        Other basic types are not valid:
-        >>> Message.check_value(b'bytes')
-        False
-        >>> Message.check_value(1j)
-        False
-
-        Dictionaries with string keys and recursively valid values are valid:
-        >>> Message.check_value({'str value': 'Spam', 'int value': 42,
-        ...                      'float value': 42.42, 'bool value': False})
-        True
-
-        Empty dictionaries are valid:
-        >>> Message.check_value({})
-        True
-
-        Dictionaries with other keys are not valid:
-        >>> Message.check_value({42: 'int key'})
-        False
-
-        Dictionaries with invalid values are not valid:
-        >>> Message.check_value({'complex value': 1j})
-        False
-
-        Lists with valid elements are valid:
-        >>> Message.check_value(['Spam', 42, 42.42, False])
-        True
-
-        Empty lists are valid:
-        >>> Message.check_value([])
-        True
-
-        Lists with invalid elements are not valid:
-        >>> Message.check_value([1j])
-        False
-        """
-        if value is None:
-            return True
-        elif (isinstance(value, str) or isinstance(value, int) or
-                isinstance(value, float) or isinstance(value, bool)):
-            return True
-        elif isinstance(value, dict):
-            for key in value:
-                if not isinstance(key, str):
-                    return False
-                if not Message.check_value(value[key]):
-                    return False
-            return True
-        elif isinstance(value, list):
-            for element in value:
-                if not Message.check_value(element):
-                    return False
-            return True
-        return False
-
-    def __setitem__(self, key: str, value: MessageValue) -> None:
-        """Check key and value before putting pair into dict.
-
-        >>> m = Message('Example sender')
-        >>> m['key'] = 'value'
-        >>> m['dict'] = {'k1': 'v1', 'k2': 2}
-        >>> print(m)  # doctest: +NORMALIZE_WHITESPACE
-        {'sender': 'Example sender', 'key': 'value',
-         'dict': {'k1': 'v1', 'k2': 2}}
-        >>> m = Message('Example sender')
-        >>> m[42] = 'int key'
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in Message (not a string).
-        >>> m['complex value'] = 1j
-        Traceback (most recent call last):
-          ...
-        TypeError: '1j' is not a valid value in Message.
-        """
-        if not isinstance(key, str):
-            raise TypeError(f"'{key}' is not a valid key in Message"
-                            " (not a string).")
-        if not self.check_value(value):
-            raise TypeError(f"'{value}' is not a valid value in Message.")
-        super().__setitem__(key, value)
-
-    def update(self, *args, **kwargs) -> None:
-        """Override update to use validity checks.
-
-        >>> m = Message('Example sender')
-        >>> m.update({'key 1': 'value 1', 'key 2': 'value 2'})
-        >>> print(m)
-        {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-        >>> m.update({42: 'int key'})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in Message (not a string).
-        >>> m.update({'complex value': 1j})
-        Traceback (most recent call last):
-          ...
-        TypeError: '1j' is not a valid value in Message.
-
-        This is also used in __init__:
-        >>> m = Message('Example sender', {'key': 'value'})
-        >>> print(m)
-        {'sender': 'Example sender', 'key': 'value'}
-        >>> m = Message('Example sender', {42: 'int key'})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in Message (not a string).
-        >>> m = Message('Example sender', {'complex value': 1j})
-        Traceback (most recent call last):
-          ...
-        TypeError: '1j' is not a valid value in Message.
-        """
-        if args:
-            if len(args) > 1:
-                raise TypeError("update expected at most 1 argument,"
-                                f" got {len(args)}")
-            other = dict(args[0])
-            for key in other:
-                self[key] = other[key]
-        for key in kwargs:
-            self[key] = kwargs[key]
-
-    def setdefault(self, key: str, value: MessageValue = None) -> MessageValue:
-        """Override setdefault to use validity checks.
-
-        >>> m = Message('Example sender')
-        >>> m.setdefault('key', 'value 1')
-        'value 1'
-        >>> m.setdefault('key', 'value 2')
-        'value 1'
-        >>> m.setdefault(42, 'int key')
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in Message (not a string).
-        >>> m.setdefault('complex value', 1j)
-        Traceback (most recent call last):
-          ...
-        TypeError: '1j' is not a valid value in Message.
-
-        But __setitem__ is not called if the key is already present:
-        >>> m.setdefault('key', 1j)
-        'value 1'
-        """
-        if key not in self:
-            self[key] = value
-        return self[key]

Ancestors

builtins.dict
typing.Generic

Static methods

-def check_value(value:Â Union[NoneType,Â str,Â int,Â float,Â bool,Â Dict[str,Â Any],Â List[Any]]) â>Â bool -

Check recursively if a given value is valid.

None, strings, integers, floats and Booleans are valid:

>>> Message.check_value(None)
-True
->>> Message.check_value('Spam')
-True
->>> Message.check_value(42)
-True
->>> Message.check_value(42.42)
-True
->>> Message.check_value(False)
-True
-

Other basic types are not valid:

>>> Message.check_value(b'bytes')
-False
->>> Message.check_value(1j)
-False
-

Dictionaries with string keys and recursively valid values are valid:

>>> Message.check_value({'str value': 'Spam', 'int value': 42,
-...                      'float value': 42.42, 'bool value': False})
-True
-

Empty dictionaries are valid:

>>> Message.check_value({})
-True
-

Dictionaries with other keys are not valid:

>>> Message.check_value({42: 'int key'})
-False
-

Dictionaries with invalid values are not valid:

>>> Message.check_value({'complex value': 1j})
-False
-

Lists with valid elements are valid:

>>> Message.check_value(['Spam', 42, 42.42, False])
-True
-

Empty lists are valid:

>>> Message.check_value([])
-True
-

Lists with invalid elements are not valid:

>>> Message.check_value([1j])
-False
-

-Expand source code -

@staticmethod
-def check_value(value: MessageValue) -> bool:
-    """Check recursively if a given value is valid.
-
-    None, strings, integers, floats and Booleans are valid:
-    >>> Message.check_value(None)
-    True
-    >>> Message.check_value('Spam')
-    True
-    >>> Message.check_value(42)
-    True
-    >>> Message.check_value(42.42)
-    True
-    >>> Message.check_value(False)
-    True
-
-    Other basic types are not valid:
-    >>> Message.check_value(b'bytes')
-    False
-    >>> Message.check_value(1j)
-    False
-
-    Dictionaries with string keys and recursively valid values are valid:
-    >>> Message.check_value({'str value': 'Spam', 'int value': 42,
-    ...                      'float value': 42.42, 'bool value': False})
-    True
-
-    Empty dictionaries are valid:
-    >>> Message.check_value({})
-    True
-
-    Dictionaries with other keys are not valid:
-    >>> Message.check_value({42: 'int key'})
-    False
-
-    Dictionaries with invalid values are not valid:
-    >>> Message.check_value({'complex value': 1j})
-    False
-
-    Lists with valid elements are valid:
-    >>> Message.check_value(['Spam', 42, 42.42, False])
-    True
-
-    Empty lists are valid:
-    >>> Message.check_value([])
-    True
-
-    Lists with invalid elements are not valid:
-    >>> Message.check_value([1j])
-    False
-    """
-    if value is None:
-        return True
-    elif (isinstance(value, str) or isinstance(value, int) or
-            isinstance(value, float) or isinstance(value, bool)):
-        return True
-    elif isinstance(value, dict):
-        for key in value:
-            if not isinstance(key, str):
-                return False
-            if not Message.check_value(value[key]):
-                return False
-        return True
-    elif isinstance(value, list):
-        for element in value:
-            if not Message.check_value(element):
-                return False
-        return True
-    return False

Methods

-def update(self, *args, **kwargs) â>Â NoneType -

Override update to use validity checks.

>>> m = Message('Example sender')
->>> m.update({'key 1': 'value 1', 'key 2': 'value 2'})
->>> print(m)
-{'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
->>> m.update({42: 'int key'})
-Traceback (most recent call last):
-  ...
-TypeError: '42' is not a valid key in Message (not a string).
->>> m.update({'complex value': 1j})
-Traceback (most recent call last):
-  ...
-TypeError: '1j' is not a valid value in Message.
-

This is also used in init:

>>> m = Message('Example sender', {'key': 'value'})
->>> print(m)
-{'sender': 'Example sender', 'key': 'value'}
->>> m = Message('Example sender', {42: 'int key'})
-Traceback (most recent call last):
-  ...
-TypeError: '42' is not a valid key in Message (not a string).
->>> m = Message('Example sender', {'complex value': 1j})
-Traceback (most recent call last):
-  ...
-TypeError: '1j' is not a valid value in Message.
-

-Expand source code -

def update(self, *args, **kwargs) -> None:
-    """Override update to use validity checks.
-
-    >>> m = Message('Example sender')
-    >>> m.update({'key 1': 'value 1', 'key 2': 'value 2'})
-    >>> print(m)
-    {'sender': 'Example sender', 'key 1': 'value 1', 'key 2': 'value 2'}
-    >>> m.update({42: 'int key'})
-    Traceback (most recent call last):
-      ...
-    TypeError: '42' is not a valid key in Message (not a string).
-    >>> m.update({'complex value': 1j})
-    Traceback (most recent call last):
-      ...
-    TypeError: '1j' is not a valid value in Message.
-
-    This is also used in __init__:
-    >>> m = Message('Example sender', {'key': 'value'})
-    >>> print(m)
-    {'sender': 'Example sender', 'key': 'value'}
-    >>> m = Message('Example sender', {42: 'int key'})
-    Traceback (most recent call last):
-      ...
-    TypeError: '42' is not a valid key in Message (not a string).
-    >>> m = Message('Example sender', {'complex value': 1j})
-    Traceback (most recent call last):
-      ...
-    TypeError: '1j' is not a valid value in Message.
-    """
-    if args:
-        if len(args) > 1:
-            raise TypeError("update expected at most 1 argument,"
-                            f" got {len(args)}")
-        other = dict(args[0])
-        for key in other:
-            self[key] = other[key]
-    for key in kwargs:
-        self[key] = kwargs[key]

-def setdefault(self, key:Â str, value:Â Union[NoneType,Â str,Â int,Â float,Â bool,Â Dict[str,Â Any],Â List[Any]]Â =Â None) â>Â Union[NoneType,Â str,Â int,Â float,Â bool,Â Dict[str,Â Any],Â List[Any]] -

Override setdefault to use validity checks.

>>> m = Message('Example sender')
->>> m.setdefault('key', 'value 1')
-'value 1'
->>> m.setdefault('key', 'value 2')
-'value 1'
->>> m.setdefault(42, 'int key')
-Traceback (most recent call last):
-  ...
-TypeError: '42' is not a valid key in Message (not a string).
->>> m.setdefault('complex value', 1j)
-Traceback (most recent call last):
-  ...
-TypeError: '1j' is not a valid value in Message.
-

But setitem is not called if the key is already present:

>>> m.setdefault('key', 1j)
-'value 1'
-

-Expand source code -

def setdefault(self, key: str, value: MessageValue = None) -> MessageValue:
-    """Override setdefault to use validity checks.
-
-    >>> m = Message('Example sender')
-    >>> m.setdefault('key', 'value 1')
-    'value 1'
-    >>> m.setdefault('key', 'value 2')
-    'value 1'
-    >>> m.setdefault(42, 'int key')
-    Traceback (most recent call last):
-      ...
-    TypeError: '42' is not a valid key in Message (not a string).
-    >>> m.setdefault('complex value', 1j)
-    Traceback (most recent call last):
-      ...
-    TypeError: '1j' is not a valid value in Message.
-
-    But __setitem__ is not called if the key is already present:
-    >>> m.setdefault('key', 1j)
-    'value 1'
-    """
-    if key not in self:
-        self[key] = value
-    return self[key]

-class MessageTemplate -(init:Â Dict[str,Â Union[bool,Â Dict[str,Â Union[NoneType,Â str,Â int,Â float,Â bool,Â Dict[str,Â Any],Â List[Any]]]]]Â =Â None) -

Define a message template.

A message template is a mapping from string keys to JSON schemas as -values:

>>> t = MessageTemplate({'key 1': {'const': 'value'},
-...                      'key 2': {'type': 'string'}})
->>> t['key 3'] = {'type': 'object',
-...               'properties': {'key 1': {'type': 'number'},
-...                              'key 2': True}}
-

A message template matches a message if all keys of the template are -contained in the message and the values in the message validate against -the respective schemas:

>>> t.check(Message('Example Sender',
-...                 {'key 1': 'value', 'key 2': 'some string',
-...                  'key 3': {'key 1': 42, 'key 2': None}}))
-True
-

An empty mapping therefore matches all messages:

>>> t = MessageTemplate()
->>> t.check(Message('Example Sender', {'arbitrary': 'content'}))
-True
-

Initialise message.

Template is initialised empty or with given key-value pairs:

>>> t = MessageTemplate()
->>> print(t)
-{}
->>> t = MessageTemplate({'key': {'const': 'value'}})
->>> print(t)
-{'key': {'const': 'value'}}
-

-Expand source code -

class MessageTemplate(Dict[str, JSONSchema]):
-    """Define a message template.
-
-    A message template is a mapping from string keys to JSON schemas as
-    values:
-    >>> t = MessageTemplate({'key 1': {'const': 'value'},
-    ...                      'key 2': {'type': 'string'}})
-    >>> t['key 3'] = {'type': 'object',
-    ...               'properties': {'key 1': {'type': 'number'},
-    ...                              'key 2': True}}
-
-    A message template matches a message if all keys of the template are
-    contained in the message and the values in the message validate against
-    the respective schemas:
-    >>> t.check(Message('Example Sender',
-    ...                 {'key 1': 'value', 'key 2': 'some string',
-    ...                  'key 3': {'key 1': 42, 'key 2': None}}))
-    True
-
-    An empty mapping therefore matches all messages:
-    >>> t = MessageTemplate()
-    >>> t.check(Message('Example Sender', {'arbitrary': 'content'}))
-    True
-    """
-
-    def __init__(self, init: Dict[str, JSONSchema] = None) -> None:
-        """Initialise message.
-
-        Template is initialised empty or with given key-value pairs:
-        >>> t = MessageTemplate()
-        >>> print(t)
-        {}
-        >>> t = MessageTemplate({'key': {'const': 'value'}})
-        >>> print(t)
-        {'key': {'const': 'value'}}
-        """
-        if init is not None:
-            self.update(init)
-
-    @staticmethod
-    def from_message(message: Message) -> 'MessageTemplate':
-        """Create template from message.
-
-        Template witch constant schemas is created from message:
-        >>> m = Message('Example Sender', {'key': 'value'})
-        >>> t = MessageTemplate.from_message(m)
-        >>> print(t)
-        {'sender': {'const': 'Example Sender'}, 'key': {'const': 'value'}}
-        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
-        ...                                'list': [None, True, 'string']})
-        >>> t = MessageTemplate.from_message(m)
-        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-        {'sender': {'const': 'Example Sender'},
-         'dict': {'type': 'object',
-                  'properties': {'int': {'const': 42},
-                                 'float': {'const': 42.42}}},
-         'list': {'type': 'array',
-                  'items': [{'const': None},
-                            {'const': True},
-                            {'const': 'string'}]}}
-
-        This is especially useful for clients that send certain fully
-        predefined messages, where the message is given in the configuration
-        and the template for the registration can be constructed by this
-        method.
-        """
-        def schema_from_value(value: MessageValue) -> JSONSchema:
-            schema: JSONSchema = False
-            if value is None:
-                schema = {'const': None}
-            elif (isinstance(value, str) or isinstance(value, int) or
-                    isinstance(value, float) or isinstance(value, bool)):
-                schema = {'const': value}
-            elif isinstance(value, dict):
-                properties = {}
-                for inner_key in value:
-                    inner_value: Message = value[inner_key]
-                    properties[inner_key] = schema_from_value(inner_value)
-                schema = {'type': 'object',
-                          'properties': properties}
-            elif isinstance(value, list):
-                schema = {'type': 'array',
-                          'items': [schema_from_value(element)
-                                    for element in value]}
-            return schema
-        template = MessageTemplate()
-        for key in message:
-            template[key] = schema_from_value(message[key])
-        return template
-
-    def __setitem__(self, key: str, value: JSONSchema) -> None:
-        """Check key and value before putting pair into dict.
-
-        >>> t = MessageTemplate()
-        >>> t['key 1'] = {'const': 'value'}
-        >>> t['key 2'] = {'type': 'string'}
-        >>> t['key 3'] = {'type': 'object',
-        ...               'properties': {'key 1': {'type': 'number'},
-        ...                              'key 2': True}}
-        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
-         'key 3': {'type': 'object',
-                   'properties': {'key 1': {'type': 'number'},
-                                  'key 2': True}}}
-        >>> t[42] = {'const': 'int key'}
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in MessageTemplate (not a string).
-        >>> t['key'] = 'schema'  # doctest: +NORMALIZE_WHITESPACE
-        Traceback (most recent call last):
-          ...
-        TypeError: 'schema' is not a valid value in MessageTemplate
-        (not a valid JSON schema).
-        """
-        if not isinstance(key, str):
-            raise TypeError(f"'{key}' is not a valid key in MessageTemplate"
-                            " (not a string).")
-        try:
-            jsonschema.Draft7Validator.check_schema(value)
-            # Draft7Validator is hardcoded, because _LATEST_VERSION is
-            # non-public in jsonschema and we also perhaps do not want to
-            # upgrade automatically.
-        except jsonschema.exceptions.SchemaError:
-            raise TypeError(f"'{value}' is not a valid value in"
-                            " MessageTemplate (not a valid JSON schema).")
-        super().__setitem__(key, value)
-
-    def update(self, *args, **kwargs) -> None:
-        """Override update to use validity checks.
-
-        >>> t = MessageTemplate()
-        >>> t.update({'key 1': {'const': 'value'},
-        ...           'key 2': {'type': 'string'},
-        ...           'key 3': {'type': 'object',
-        ...                     'properties': {'key 1': {'type': 'number'},
-        ...                                    'key 2': True}}})
-        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
-         'key 3': {'type': 'object',
-                   'properties': {'key 1': {'type': 'number'},
-                                  'key 2': True}}}
-        >>> t.update({42: {'const': 'int key'}})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in MessageTemplate (not a string).
-        >>> t.update({'key': 'schema'})  # doctest: +NORMALIZE_WHITESPACE
-        Traceback (most recent call last):
-          ...
-        TypeError: 'schema' is not a valid value in MessageTemplate
-        (not a valid JSON schema).
-
-        This is also used in __init__:
-        >>> t = MessageTemplate({'key 1': {'const': 'value'},
-        ...                      'key 2': {'type': 'string'},
-        ...                      'key 3': {'type': 'object',
-        ...                                'properties': {
-        ...                                    'key 1': {'type': 'number'},
-        ...                                    'key 2': True}}})
-        >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-        {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
-         'key 3': {'type': 'object',
-                   'properties': {'key 1': {'type': 'number'},
-                                  'key 2': True}}}
-        >>> t = MessageTemplate({42: {'const': 'int key'}})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in MessageTemplate (not a string).
-        >>> t = MessageTemplate({'key': 'schema'})
-        ... # doctest: +NORMALIZE_WHITESPACE
-        Traceback (most recent call last):
-          ...
-        TypeError: 'schema' is not a valid value in MessageTemplate
-        (not a valid JSON schema).
-        """
-        if args:
-            if len(args) > 1:
-                raise TypeError("update expected at most 1 argument,"
-                                f" got {len(args)}")
-            other = dict(args[0])
-            for key in other:
-                self[key] = other[key]
-        for key in kwargs:
-            self[key] = kwargs[key]
-
-    def setdefault(self, key: str, value: JSONSchema = None) -> JSONSchema:
-        """Override setdefault to use validity checks.
-
-        >>> t = MessageTemplate()
-        >>> t.setdefault('key 1', {'const': 'value'})
-        {'const': 'value'}
-        >>> t.setdefault('key 2', {'type': 'string'})
-        {'type': 'string'}
-        >>> t.setdefault('key 3', {'type': 'object',
-        ...                        'properties': {'key 1': {'type': 'number'},
-        ...                                       'key 2': True}})
-        ... # doctest: +NORMALIZE_WHITESPACE
-        {'type': 'object',
-                   'properties': {'key 1': {'type': 'number'},
-                                  'key 2': True}}
-        >>> t.setdefault(42, {'const': 'int key'})
-        Traceback (most recent call last):
-          ...
-        TypeError: '42' is not a valid key in MessageTemplate (not a string).
-        >>> t.setdefault('key', 'schema')  # doctest: +NORMALIZE_WHITESPACE
-        Traceback (most recent call last):
-          ...
-        TypeError: 'schema' is not a valid value in MessageTemplate
-        (not a valid JSON schema).
-
-        But __setitem__ is not called if the key is already present:
-        >>> t.setdefault('key 1', 'schema')
-        {'const': 'value'}
-        """
-        if key not in self:
-            if value is not None:
-                self[key] = value
-            else:
-                self[key] = True
-        return self[key]
-
-    def check(self, message: Message) -> bool:
-        """Check message against this template.
-
-        Constant values have to match exactly:
-        >>> t = MessageTemplate({'key': {'const': 'value'}})
-        >>> t.check(Message('Example Sender', {'key': 'value'}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 'other value'}))
-        False
-
-        But for integers, floats with the same value are also valid:
-        >>> t = MessageTemplate({'key': {'const': 42}})
-        >>> t.check(Message('Example Sender', {'key': 42}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 42.0}))
-        True
-
-        Type integer is valid for floats with zero fractional part, but
-        not by floats with non-zero fractional part:
-        >>> t = MessageTemplate({'key': {'type': 'integer'}})
-        >>> t.check(Message('Example Sender', {'key': 42}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 42.0}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 42.42}))
-        False
-
-        Type number is valid for arbitrary ints or floats:
-        >>> t = MessageTemplate({'key': {'type': 'number'}})
-        >>> t.check(Message('Example Sender', {'key': 42}))
-        True
-        >>> t.check(Message('Example Sender', {'key': 42.42}))
-        True
-
-        All keys in template have to be present in message:
-        >>> t = MessageTemplate({'key 1': {'const': 'value'},
-        ...                      'key 2': {'type': 'string'},
-        ...                      'key 3': {'type': 'object',
-        ...                                'properties': {
-        ...                                    'key 1': {'type': 'number'},
-        ...                                    'key 2': True,
-        ...                                    'key 3': False}}})
-        >>> t.check(Message('Example Sender',
-        ...                 {'key 1': 'value', 'key 2': 'some string'}))
-        False
-
-        But for nested objects their properties do not necessarily have
-        to be present:
-        >>> t.check(Message('Example Sender',
-        ...                 {'key 1': 'value', 'key 2': 'some string',
-        ...                  'key 3': {'key 1': 42}}))
-        True
-
-        Schema True matches everything (even None):
-        >>> t.check(Message('Example Sender',
-        ...                 {'key 1': 'value', 'key 2': 'some string',
-        ...                  'key 3': {'key 2': None}}))
-        True
-
-        Schema False matches nothing:
-        >>> t.check(Message('Example Sender',
-        ...                 {'key 1': 'value', 'key 2': 'some string',
-        ...                  'key 3': {'key 3': True}}))
-        False
-
-        Message is valid for the constant template created from it:
-        >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
-        ...                                'list': [None, True, 'string']})
-        >>> t = MessageTemplate.from_message(m)
-        >>> t.check(m)
-        True
-        """
-        for key in self:
-            if key not in message:
-                return False
-            else:
-                validator = jsonschema.Draft7Validator(self[key])
-                for error in validator.iter_errors(message[key]):
-                    return False
-        return True

Ancestors

builtins.dict
typing.Generic

Static methods

-def from_message(message:Â Message) â>Â MessageTemplate -

Create template from message.

Template witch constant schemas is created from message:

>>> m = Message('Example Sender', {'key': 'value'})
->>> t = MessageTemplate.from_message(m)
->>> print(t)
-{'sender': {'const': 'Example Sender'}, 'key': {'const': 'value'}}
->>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
-...                                'list': [None, True, 'string']})
->>> t = MessageTemplate.from_message(m)
->>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-{'sender': {'const': 'Example Sender'},
- 'dict': {'type': 'object',
-          'properties': {'int': {'const': 42},
-                         'float': {'const': 42.42}}},
- 'list': {'type': 'array',
-          'items': [{'const': None},
-                    {'const': True},
-                    {'const': 'string'}]}}
-

This is especially useful for clients that send certain fully -predefined messages, where the message is given in the configuration -and the template for the registration can be constructed by this -method.

-Expand source code -

@staticmethod
-def from_message(message: Message) -> 'MessageTemplate':
-    """Create template from message.
-
-    Template witch constant schemas is created from message:
-    >>> m = Message('Example Sender', {'key': 'value'})
-    >>> t = MessageTemplate.from_message(m)
-    >>> print(t)
-    {'sender': {'const': 'Example Sender'}, 'key': {'const': 'value'}}
-    >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
-    ...                                'list': [None, True, 'string']})
-    >>> t = MessageTemplate.from_message(m)
-    >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-    {'sender': {'const': 'Example Sender'},
-     'dict': {'type': 'object',
-              'properties': {'int': {'const': 42},
-                             'float': {'const': 42.42}}},
-     'list': {'type': 'array',
-              'items': [{'const': None},
-                        {'const': True},
-                        {'const': 'string'}]}}
-
-    This is especially useful for clients that send certain fully
-    predefined messages, where the message is given in the configuration
-    and the template for the registration can be constructed by this
-    method.
-    """
-    def schema_from_value(value: MessageValue) -> JSONSchema:
-        schema: JSONSchema = False
-        if value is None:
-            schema = {'const': None}
-        elif (isinstance(value, str) or isinstance(value, int) or
-                isinstance(value, float) or isinstance(value, bool)):
-            schema = {'const': value}
-        elif isinstance(value, dict):
-            properties = {}
-            for inner_key in value:
-                inner_value: Message = value[inner_key]
-                properties[inner_key] = schema_from_value(inner_value)
-            schema = {'type': 'object',
-                      'properties': properties}
-        elif isinstance(value, list):
-            schema = {'type': 'array',
-                      'items': [schema_from_value(element)
-                                for element in value]}
-        return schema
-    template = MessageTemplate()
-    for key in message:
-        template[key] = schema_from_value(message[key])
-    return template

Methods

-def update(self, *args, **kwargs) â>Â NoneType -

Override update to use validity checks.

>>> t = MessageTemplate()
->>> t.update({'key 1': {'const': 'value'},
-...           'key 2': {'type': 'string'},
-...           'key 3': {'type': 'object',
-...                     'properties': {'key 1': {'type': 'number'},
-...                                    'key 2': True}}})
->>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-{'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
- 'key 3': {'type': 'object',
-           'properties': {'key 1': {'type': 'number'},
-                          'key 2': True}}}
->>> t.update({42: {'const': 'int key'}})
-Traceback (most recent call last):
-  ...
-TypeError: '42' is not a valid key in MessageTemplate (not a string).
->>> t.update({'key': 'schema'})  # doctest: +NORMALIZE_WHITESPACE
-Traceback (most recent call last):
-  ...
-TypeError: 'schema' is not a valid value in MessageTemplate
-(not a valid JSON schema).
-

This is also used in init:

>>> t = MessageTemplate({'key 1': {'const': 'value'},
-...                      'key 2': {'type': 'string'},
-...                      'key 3': {'type': 'object',
-...                                'properties': {
-...                                    'key 1': {'type': 'number'},
-...                                    'key 2': True}}})
->>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-{'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
- 'key 3': {'type': 'object',
-           'properties': {'key 1': {'type': 'number'},
-                          'key 2': True}}}
->>> t = MessageTemplate({42: {'const': 'int key'}})
-Traceback (most recent call last):
-  ...
-TypeError: '42' is not a valid key in MessageTemplate (not a string).
->>> t = MessageTemplate({'key': 'schema'})
-... # doctest: +NORMALIZE_WHITESPACE
-Traceback (most recent call last):
-  ...
-TypeError: 'schema' is not a valid value in MessageTemplate
-(not a valid JSON schema).
-

-Expand source code -

def update(self, *args, **kwargs) -> None:
-    """Override update to use validity checks.
-
-    >>> t = MessageTemplate()
-    >>> t.update({'key 1': {'const': 'value'},
-    ...           'key 2': {'type': 'string'},
-    ...           'key 3': {'type': 'object',
-    ...                     'properties': {'key 1': {'type': 'number'},
-    ...                                    'key 2': True}}})
-    >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-    {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
-     'key 3': {'type': 'object',
-               'properties': {'key 1': {'type': 'number'},
-                              'key 2': True}}}
-    >>> t.update({42: {'const': 'int key'}})
-    Traceback (most recent call last):
-      ...
-    TypeError: '42' is not a valid key in MessageTemplate (not a string).
-    >>> t.update({'key': 'schema'})  # doctest: +NORMALIZE_WHITESPACE
-    Traceback (most recent call last):
-      ...
-    TypeError: 'schema' is not a valid value in MessageTemplate
-    (not a valid JSON schema).
-
-    This is also used in __init__:
-    >>> t = MessageTemplate({'key 1': {'const': 'value'},
-    ...                      'key 2': {'type': 'string'},
-    ...                      'key 3': {'type': 'object',
-    ...                                'properties': {
-    ...                                    'key 1': {'type': 'number'},
-    ...                                    'key 2': True}}})
-    >>> print(t)  # doctest: +NORMALIZE_WHITESPACE
-    {'key 1': {'const': 'value'}, 'key 2': {'type': 'string'},
-     'key 3': {'type': 'object',
-               'properties': {'key 1': {'type': 'number'},
-                              'key 2': True}}}
-    >>> t = MessageTemplate({42: {'const': 'int key'}})
-    Traceback (most recent call last):
-      ...
-    TypeError: '42' is not a valid key in MessageTemplate (not a string).
-    >>> t = MessageTemplate({'key': 'schema'})
-    ... # doctest: +NORMALIZE_WHITESPACE
-    Traceback (most recent call last):
-      ...
-    TypeError: 'schema' is not a valid value in MessageTemplate
-    (not a valid JSON schema).
-    """
-    if args:
-        if len(args) > 1:
-            raise TypeError("update expected at most 1 argument,"
-                            f" got {len(args)}")
-        other = dict(args[0])
-        for key in other:
-            self[key] = other[key]
-    for key in kwargs:
-        self[key] = kwargs[key]

-def setdefault(self, key:Â str, value:Â Union[bool,Â Dict[str,Â Union[NoneType,Â str,Â int,Â float,Â bool,Â Dict[str,Â Any],Â List[Any]]]]Â =Â None) â>Â Union[bool,Â Dict[str,Â Union[NoneType,Â str,Â int,Â float,Â bool,Â Dict[str,Â Any],Â List[Any]]]] -

Override setdefault to use validity checks.

>>> t = MessageTemplate()
->>> t.setdefault('key 1', {'const': 'value'})
-{'const': 'value'}
->>> t.setdefault('key 2', {'type': 'string'})
-{'type': 'string'}
->>> t.setdefault('key 3', {'type': 'object',
-...                        'properties': {'key 1': {'type': 'number'},
-...                                       'key 2': True}})
-... # doctest: +NORMALIZE_WHITESPACE
-{'type': 'object',
-           'properties': {'key 1': {'type': 'number'},
-                          'key 2': True}}
->>> t.setdefault(42, {'const': 'int key'})
-Traceback (most recent call last):
-  ...
-TypeError: '42' is not a valid key in MessageTemplate (not a string).
->>> t.setdefault('key', 'schema')  # doctest: +NORMALIZE_WHITESPACE
-Traceback (most recent call last):
-  ...
-TypeError: 'schema' is not a valid value in MessageTemplate
-(not a valid JSON schema).
-

But setitem is not called if the key is already present:

>>> t.setdefault('key 1', 'schema')
-{'const': 'value'}
-

-Expand source code -

def setdefault(self, key: str, value: JSONSchema = None) -> JSONSchema:
-    """Override setdefault to use validity checks.
-
-    >>> t = MessageTemplate()
-    >>> t.setdefault('key 1', {'const': 'value'})
-    {'const': 'value'}
-    >>> t.setdefault('key 2', {'type': 'string'})
-    {'type': 'string'}
-    >>> t.setdefault('key 3', {'type': 'object',
-    ...                        'properties': {'key 1': {'type': 'number'},
-    ...                                       'key 2': True}})
-    ... # doctest: +NORMALIZE_WHITESPACE
-    {'type': 'object',
-               'properties': {'key 1': {'type': 'number'},
-                              'key 2': True}}
-    >>> t.setdefault(42, {'const': 'int key'})
-    Traceback (most recent call last):
-      ...
-    TypeError: '42' is not a valid key in MessageTemplate (not a string).
-    >>> t.setdefault('key', 'schema')  # doctest: +NORMALIZE_WHITESPACE
-    Traceback (most recent call last):
-      ...
-    TypeError: 'schema' is not a valid value in MessageTemplate
-    (not a valid JSON schema).
-
-    But __setitem__ is not called if the key is already present:
-    >>> t.setdefault('key 1', 'schema')
-    {'const': 'value'}
-    """
-    if key not in self:
-        if value is not None:
-            self[key] = value
-        else:
-            self[key] = True
-    return self[key]

-def check(self, message:Â Message) â>Â bool -

Check message against this template.

Constant values have to match exactly:

>>> t = MessageTemplate({'key': {'const': 'value'}})
->>> t.check(Message('Example Sender', {'key': 'value'}))
-True
->>> t.check(Message('Example Sender', {'key': 'other value'}))
-False
-

But for integers, floats with the same value are also valid:

>>> t = MessageTemplate({'key': {'const': 42}})
->>> t.check(Message('Example Sender', {'key': 42}))
-True
->>> t.check(Message('Example Sender', {'key': 42.0}))
-True
-

Type integer is valid for floats with zero fractional part, but -not by floats with non-zero fractional part:

>>> t = MessageTemplate({'key': {'type': 'integer'}})
->>> t.check(Message('Example Sender', {'key': 42}))
-True
->>> t.check(Message('Example Sender', {'key': 42.0}))
-True
->>> t.check(Message('Example Sender', {'key': 42.42}))
-False
-

Type number is valid for arbitrary ints or floats:

>>> t = MessageTemplate({'key': {'type': 'number'}})
->>> t.check(Message('Example Sender', {'key': 42}))
-True
->>> t.check(Message('Example Sender', {'key': 42.42}))
-True
-

All keys in template have to be present in message:

>>> t = MessageTemplate({'key 1': {'const': 'value'},
-...                      'key 2': {'type': 'string'},
-...                      'key 3': {'type': 'object',
-...                                'properties': {
-...                                    'key 1': {'type': 'number'},
-...                                    'key 2': True,
-...                                    'key 3': False}}})
->>> t.check(Message('Example Sender',
-...                 {'key 1': 'value', 'key 2': 'some string'}))
-False
-

But for nested objects their properties do not necessarily have -to be present:

>>> t.check(Message('Example Sender',
-...                 {'key 1': 'value', 'key 2': 'some string',
-...                  'key 3': {'key 1': 42}}))
-True
-

Schema True matches everything (even None):

>>> t.check(Message('Example Sender',
-...                 {'key 1': 'value', 'key 2': 'some string',
-...                  'key 3': {'key 2': None}}))
-True
-

Schema False matches nothing:

>>> t.check(Message('Example Sender',
-...                 {'key 1': 'value', 'key 2': 'some string',
-...                  'key 3': {'key 3': True}}))
-False
-

Message is valid for the constant template created from it:

>>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
-...                                'list': [None, True, 'string']})
->>> t = MessageTemplate.from_message(m)
->>> t.check(m)
-True
-

-Expand source code -

def check(self, message: Message) -> bool:
-    """Check message against this template.
-
-    Constant values have to match exactly:
-    >>> t = MessageTemplate({'key': {'const': 'value'}})
-    >>> t.check(Message('Example Sender', {'key': 'value'}))
-    True
-    >>> t.check(Message('Example Sender', {'key': 'other value'}))
-    False
-
-    But for integers, floats with the same value are also valid:
-    >>> t = MessageTemplate({'key': {'const': 42}})
-    >>> t.check(Message('Example Sender', {'key': 42}))
-    True
-    >>> t.check(Message('Example Sender', {'key': 42.0}))
-    True
-
-    Type integer is valid for floats with zero fractional part, but
-    not by floats with non-zero fractional part:
-    >>> t = MessageTemplate({'key': {'type': 'integer'}})
-    >>> t.check(Message('Example Sender', {'key': 42}))
-    True
-    >>> t.check(Message('Example Sender', {'key': 42.0}))
-    True
-    >>> t.check(Message('Example Sender', {'key': 42.42}))
-    False
-
-    Type number is valid for arbitrary ints or floats:
-    >>> t = MessageTemplate({'key': {'type': 'number'}})
-    >>> t.check(Message('Example Sender', {'key': 42}))
-    True
-    >>> t.check(Message('Example Sender', {'key': 42.42}))
-    True
-
-    All keys in template have to be present in message:
-    >>> t = MessageTemplate({'key 1': {'const': 'value'},
-    ...                      'key 2': {'type': 'string'},
-    ...                      'key 3': {'type': 'object',
-    ...                                'properties': {
-    ...                                    'key 1': {'type': 'number'},
-    ...                                    'key 2': True,
-    ...                                    'key 3': False}}})
-    >>> t.check(Message('Example Sender',
-    ...                 {'key 1': 'value', 'key 2': 'some string'}))
-    False
-
-    But for nested objects their properties do not necessarily have
-    to be present:
-    >>> t.check(Message('Example Sender',
-    ...                 {'key 1': 'value', 'key 2': 'some string',
-    ...                  'key 3': {'key 1': 42}}))
-    True
-
-    Schema True matches everything (even None):
-    >>> t.check(Message('Example Sender',
-    ...                 {'key 1': 'value', 'key 2': 'some string',
-    ...                  'key 3': {'key 2': None}}))
-    True
-
-    Schema False matches nothing:
-    >>> t.check(Message('Example Sender',
-    ...                 {'key 1': 'value', 'key 2': 'some string',
-    ...                  'key 3': {'key 3': True}}))
-    False
-
-    Message is valid for the constant template created from it:
-    >>> m = Message('Example Sender', {'dict': {'int': 42, 'float': 42.42},
-    ...                                'list': [None, True, 'string']})
-    >>> t = MessageTemplate.from_message(m)
-    >>> t.check(m)
-    True
-    """
-    for key in self:
-        if key not in message:
-            return False
-        else:
-            validator = jsonschema.Draft7Validator(self[key])
-            for error in validator.iter_errors(message[key]):
-                return False
-    return True

-class MessageTemplateRegistry -

Manage a collection of message templates with registered clients.

A new MessageTemplateRegistry is created by:

>>> r = MessageTemplateRegistry()
-

Client names (strings) can be registered for message templates, which -are mappings from keys to JSON schemas:

>>> r.insert({'k1': {'const': 'v1'}}, 'C 1')
-

The check function checks if the templates registered for a client -match a given message:

>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-...     print(f"{m}: {r.check('C 1', m)}")
-{'k1': 'v1', 'k2': 'v1'}: True
-{'k1': 'v1', 'k2': 2}: True
-{'k1': 'v2', 'k2': 'v1'}: False
-{'k1': 'v2', 'k2': 2}: False
-

Clients can be registered for values validating against arbitrary JSON -schemas, e.g. all values of a certain type:

>>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}, 'C 2')
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-...     print(f"{m}: {r.check('C 2', m)}")
-{'k1': 'v1', 'k2': 'v1'}: False
-{'k1': 'v1', 'k2': 2}: False
-{'k1': 'v2', 'k2': 'v1'}: True
-{'k1': 'v2', 'k2': 2}: False
->>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}, 'C 3')
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-...     print(f"{m}: {r.check('C 3', m)}")
-{'k1': 'v1', 'k2': 'v1'}: False
-{'k1': 'v1', 'k2': 2}: False
-{'k1': 'v2', 'k2': 'v1'}: False
-{'k1': 'v2', 'k2': 2}: True
-

The order of key-value pairs does not have to match the order in the -messages and keys can be left out:

>>> r.insert({'k2': {'const': 2}}, 'C 4')
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-...     print(f"{m}: {r.check('C 4', m)}")
-{'k1': 'v1', 'k2': 'v1'}: False
-{'k1': 'v1', 'k2': 2}: True
-{'k1': 'v2', 'k2': 'v1'}: False
-{'k1': 'v2', 'k2': 2}: True
-

A registration for an empty template matches all messages:

>>> r.insert({}, 'C 5')
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-...     print(f"{m}: {r.check('C 5', m)}")
-{'k1': 'v1', 'k2': 'v1'}: True
-{'k1': 'v1', 'k2': 2}: True
-{'k1': 'v2', 'k2': 'v1'}: True
-{'k1': 'v2', 'k2': 2}: True
-

A client can be registered for multiple templates:

>>> r.insert({'k1': {'const': 'v1'}}, 'C 6')
->>> r.insert({'k2': {'const': 'v1'}}, 'C 6')
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-...     print(f"{m}: {r.check('C 6', m)}")
-{'k1': 'v1', 'k2': 'v1'}: True
-{'k1': 'v1', 'k2': 2}: True
-{'k1': 'v2', 'k2': 'v1'}: True
-{'k1': 'v2', 'k2': 2}: False
-

Clients can be deregistered again (the result is False if the registry -is empty after the deletion):

>>> r.insert({'k1': {'const': 'v1'}}, 'C 7')
->>> r.delete('C 7')
-True
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-...     print(f"{m}: {r.check('C 7', m)}")
-{'k1': 'v1', 'k2': 'v1'}: False
-{'k1': 'v1', 'k2': 2}: False
-{'k1': 'v2', 'k2': 'v1'}: False
-{'k1': 'v2', 'k2': 2}: False
-

The get function returns all clients with registered templates matching -a given message:

>>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-...     print(f"{m}: {r.get(m)}")
-{'k1': 'v1', 'k2': 'v1'}: ['C 5', 'C 1', 'C 6']
-{'k1': 'v1', 'k2': 2}: ['C 5', 'C 1', 'C 6', 'C 4']
-{'k1': 'v2', 'k2': 'v1'}: ['C 5', 'C 2', 'C 6']
-{'k1': 'v2', 'k2': 2}: ['C 5', 'C 3', 'C 4']
-

The get_templates function returns all templates for a given client:

>>> for c in ['C 1', 'C 2', 'C 3', 'C 4', 'C 5', 'C 6']:
-...     print(f"{c}: {r.get_templates(c)}")
-C 1: [{'k1': {'const': 'v1'}}]
-C 2: [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
-C 3: [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
-C 4: [{'k2': {'const': 2}}]
-C 5: [{}]
-C 6: [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
-

Initialise an empty registry.

>>> r = MessageTemplateRegistry()
-

-Expand source code -

class MessageTemplateRegistry:
-    """Manage a collection of message templates with registered clients.
-
-    A new MessageTemplateRegistry is created by:
-    >>> r = MessageTemplateRegistry()
-
-    Client names (strings) can be registered for message templates, which
-    are mappings from keys to JSON schemas:
-    >>> r.insert({'k1': {'const': 'v1'}}, 'C 1')
-
-    The check function checks if the templates registered for a client
-    match a given message:
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 1', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: True
-    {'k1': 'v1', 'k2': 2}: True
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 2}: False
-
-    Clients can be registered for values validating against arbitrary JSON
-    schemas, e.g. all values of a certain type:
-    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}, 'C 2')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 2', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 2}: False
-    {'k1': 'v2', 'k2': 'v1'}: True
-    {'k1': 'v2', 'k2': 2}: False
-    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}, 'C 3')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 3', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 2}: False
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 2}: True
-
-    The order of key-value pairs does not have to match the order in the
-    messages and keys can be left out:
-    >>> r.insert({'k2': {'const': 2}}, 'C 4')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 4', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 2}: True
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 2}: True
-
-    A registration for an empty template matches all messages:
-    >>> r.insert({}, 'C 5')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 5', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: True
-    {'k1': 'v1', 'k2': 2}: True
-    {'k1': 'v2', 'k2': 'v1'}: True
-    {'k1': 'v2', 'k2': 2}: True
-
-    A client can be registered for multiple templates:
-    >>> r.insert({'k1': {'const': 'v1'}}, 'C 6')
-    >>> r.insert({'k2': {'const': 'v1'}}, 'C 6')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 6', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: True
-    {'k1': 'v1', 'k2': 2}: True
-    {'k1': 'v2', 'k2': 'v1'}: True
-    {'k1': 'v2', 'k2': 2}: False
-
-    Clients can be deregistered again (the result is False if the registry
-    is empty after the deletion):
-    >>> r.insert({'k1': {'const': 'v1'}}, 'C 7')
-    >>> r.delete('C 7')
-    True
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.check('C 7', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 2}: False
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 2}: False
-
-    The get function returns all clients with registered templates matching
-    a given message:
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 2},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 2}]:
-    ...     print(f"{m}: {r.get(m)}")
-    {'k1': 'v1', 'k2': 'v1'}: ['C 5', 'C 1', 'C 6']
-    {'k1': 'v1', 'k2': 2}: ['C 5', 'C 1', 'C 6', 'C 4']
-    {'k1': 'v2', 'k2': 'v1'}: ['C 5', 'C 2', 'C 6']
-    {'k1': 'v2', 'k2': 2}: ['C 5', 'C 3', 'C 4']
-
-    The get_templates function returns all templates for a given client:
-    >>> for c in ['C 1', 'C 2', 'C 3', 'C 4', 'C 5', 'C 6']:
-    ...     print(f"{c}: {r.get_templates(c)}")
-    C 1: [{'k1': {'const': 'v1'}}]
-    C 2: [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
-    C 3: [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
-    C 4: [{'k2': {'const': 2}}]
-    C 5: [{}]
-    C 6: [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
-    """
-
-    def __init__(self) -> None:
-        """Initialise an empty registry.
-
-        >>> r = MessageTemplateRegistry()
-        """
-        self._clients: List[str] = []
-        self._children: Dict[str, Dict[str, MessageTemplateRegistry]] = {}
-
-    def insert(self, template: MessageTemplate, client: str) -> None:
-        """Register a client for a template.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v1'}}, 'C 1')
-        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v2'}}, 'C 2')
-        >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v1'}}, 'C 3')
-        >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v2'}}, 'C 4')
-        >>> r.insert({}, 'C 5')
-
-        Implementation details:
-        -----------------------
-        The tree nodes on the way to a registered object are used/created
-        in the order given in the message template, which can be used to
-        design more efficient lookups (e.g., putting rarer key-value pairs
-        earlier in the template).
-        >>> r._clients
-        ['C 5']
-        >>> r._children.keys()
-        dict_keys(['k1'])
-        >>> r._children['k1'].keys()
-        dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-        >>> r._children['k1']['{"const": "v1"}']._clients
-        []
-        >>> r._children['k1']['{"const": "v1"}']._children.keys()
-        dict_keys(['k2'])
-        >>> r._children['k1']['{"const": "v1"}']._children['k2'].keys()
-        dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v1"}'])._clients
-        ['C 1']
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-        dict_keys([])
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v2"}'])._clients
-        ['C 2']
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-        dict_keys([])
-        >>> r._children['k1']['{"const": "v2"}']._clients
-        []
-        >>> r._children['k1']['{"const": "v2"}']._children.keys()
-        dict_keys(['k2'])
-        >>> r._children['k1']['{"const": "v2"}']._children['k2'].keys()
-        dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-        >>> (r._children['k1']['{"const": "v2"}']
-        ...   ._children['k2']['{"const": "v1"}'])._clients
-        ['C 3']
-        >>> (r._children['k1']['{"const": "v2"}']
-        ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-        dict_keys([])
-        >>> (r._children['k1']['{"const": "v2"}']
-        ...   ._children['k2']['{"const": "v2"}'])._clients
-        ['C 4']
-        >>> (r._children['k1']['{"const": "v2"}']
-        ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-        dict_keys([])
-        """
-        if not template:
-            self._clients.append(client)
-        else:
-            key, schema = next(iter(template.items()))
-            schema_string = json.dumps(schema)
-            reduced_template = MessageTemplate({k: template[k]
-                                                for k in template
-                                                if k != key})
-            if key not in self._children:
-                self._children[key] = {}
-            if schema_string not in self._children[key]:
-                self._children[key][schema_string] = MessageTemplateRegistry()
-            self._children[key][schema_string].insert(reduced_template, client)
-
-    def delete(self, client: str) -> bool:
-        """Unregister a client from all templates.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v1'}}, 'C 1')
-        >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v2'}}, 'C 2')
-        >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v1'}}, 'C 3')
-        >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v2'}}, 'C 4')
-        >>> r.insert({}, 'C 5')
-        >>> r.delete('C 3')
-        True
-        >>> r.delete('C 4')
-        True
-
-        Implementation details:
-        -----------------------
-        If parts of the tree become superfluous by the deletion of the
-        client, they are also completely removed to reduce the lookup
-        effort and keep the tree clean.
-        >>> r._clients
-        ['C 5']
-        >>> r._children.keys()
-        dict_keys(['k1'])
-        >>> r._children['k1'].keys()
-        dict_keys(['{"const": "v1"}'])
-        >>> r._children['k1']['{"const": "v1"}']._clients
-        []
-        >>> r._children['k1']['{"const": "v1"}']._children.keys()
-        dict_keys(['k2'])
-        >>> r._children['k1']['{"const": "v1"}']._children['k2'].keys()
-        dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v1"}'])._clients
-        ['C 1']
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-        dict_keys([])
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v2"}'])._clients
-        ['C 2']
-        >>> (r._children['k1']['{"const": "v1"}']
-        ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-        dict_keys([])
-        """
-        self._clients = [c for c in self._clients if c != client]
-        new_children: Dict[str, Dict[str, MessageTemplateRegistry]] = {}
-        for key in self._children:
-            new_children[key] = {}
-            for schema in self._children[key]:
-                if self._children[key][schema].delete(client):
-                    new_children[key][schema] = self._children[key][schema]
-            if not new_children[key]:
-                del new_children[key]
-        self._children = new_children
-        if self._clients or self._children:
-            return True
-        return False
-
-    def check(self, client: str, message: Message) -> bool:
-        """Get if a client has a registered template matching a message.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-        ...     print(f"{m}: {r.check('Client 1', m)}")
-        {'k1': 'v1', 'k2': 'v1'}: True
-        {'k1': 'v1', 'k2': 'v2'}: True
-        {'k1': 'v2', 'k2': 'v1'}: False
-        {'k1': 'v2', 'k2': 'v2'}: False
-        >>> r.insert({'k2': {'const': 'v2'}}, 'Client 2')
-        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-        ...     print(f"{m}: {r.check('Client 2', m)}")
-        {'k1': 'v1', 'k2': 'v1'}: False
-        {'k1': 'v1', 'k2': 'v2'}: True
-        {'k1': 'v2', 'k2': 'v1'}: False
-        {'k1': 'v2', 'k2': 'v2'}: True
-        """
-        if client in self._clients:
-            return True
-        for key in self._children:
-            if key in message:
-                for schema_string in self._children[key]:
-                    schema = json.loads(schema_string)
-                    validator = jsonschema.Draft7Validator(schema)
-                    validated = True
-                    for error in validator.iter_errors(message[key]):
-                        validated = False
-                    if validated:
-                        child = self._children[key][schema_string]
-                        if child.check(client, message):
-                            return True
-        return False
-
-    def get(self, message: Message) -> List[str]:
-        """Get all clients registered for templates matching a message.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-        >>> r.insert({'k2': {'const': 'v2'}}, 'Client 2')
-        >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-        ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-        ...     print(f"{m}: {r.get(m)}")
-        {'k1': 'v1', 'k2': 'v1'}: ['Client 1']
-        {'k1': 'v1', 'k2': 'v2'}: ['Client 1', 'Client 2']
-        {'k1': 'v2', 'k2': 'v1'}: []
-        {'k1': 'v2', 'k2': 'v2'}: ['Client 2']
-        """
-        result = []
-        for client in self._clients:
-            if client not in result:
-                result.append(client)
-        for key in self._children:
-            if key in message:
-                for schema_string in self._children[key]:
-                    schema = json.loads(schema_string)
-                    validator = jsonschema.Draft7Validator(schema)
-                    validated = True
-                    for error in validator.iter_errors(message[key]):
-                        validated = False
-                    if validated:
-                        child = self._children[key][schema_string]
-                        for client in child.get(message):
-                            if client not in result:
-                                result.append(client)
-        return result
-
-    def get_templates(self, client: str) -> List[MessageTemplate]:
-        """Get all templates for a client.
-
-        >>> r = MessageTemplateRegistry()
-        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-        >>> r.get_templates('Client 1')
-        [{'k1': {'const': 'v1'}}]
-        >>> r.insert({'k1': {'const': 'v2'},
-        ...           'k2': {'type': 'string'}}, 'Client 2')
-        >>> r.get_templates('Client 2')
-        [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
-        >>> r.insert({'k1': {'const': 'v2'},
-        ...           'k2': {'type': 'integer'}}, 'Client 3')
-        >>> r.get_templates('Client 3')
-        [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
-        >>> r.insert({'k2': {'const': 2}}, 'Client 4')
-        >>> r.get_templates('Client 4')
-        [{'k2': {'const': 2}}]
-        >>> r.insert({}, 'Client 5')
-        >>> r.get_templates('Client 5')
-        [{}]
-        >>> r.insert({'k1': {'const': 'v1'}}, 'Client 6')
-        >>> r.insert({'k2': {'const': 'v1'}}, 'Client 6')
-        >>> r.get_templates('Client 6')
-        [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
-        """
-        result = []
-        if client in self._clients:
-            result.append(MessageTemplate())
-        for key in self._children:
-            for schema_string in self._children[key]:
-                schema = json.loads(schema_string)
-                child = self._children[key][schema_string]
-                for template in child.get_templates(client):
-                    current = MessageTemplate({key: schema})
-                    current.update(template)
-                    result.append(current)
-        return result

Methods

-def insert(self, template:Â MessageTemplate, client:Â str) â>Â NoneType -

>>> r = MessageTemplateRegistry()
->>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v1'}}, 'C 1')
->>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v2'}}, 'C 2')
->>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v1'}}, 'C 3')
->>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v2'}}, 'C 4')
->>> r.insert({}, 'C 5')
-

Implementation details:

The tree nodes on the way to a registered object are used/created -in the order given in the message template, which can be used to -design more efficient lookups (e.g., putting rarer key-value pairs -earlier in the template).

>>> r._clients
-['C 5']
->>> r._children.keys()
-dict_keys(['k1'])
->>> r._children['k1'].keys()
-dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
->>> r._children['k1']['{"const": "v1"}']._clients
-[]
->>> r._children['k1']['{"const": "v1"}']._children.keys()
-dict_keys(['k2'])
->>> r._children['k1']['{"const": "v1"}']._children['k2'].keys()
-dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
->>> (r._children['k1']['{"const": "v1"}']
-...   ._children['k2']['{"const": "v1"}'])._clients
-['C 1']
->>> (r._children['k1']['{"const": "v1"}']
-...   ._children['k2']['{"const": "v1"}'])._children.keys()
-dict_keys([])
->>> (r._children['k1']['{"const": "v1"}']
-...   ._children['k2']['{"const": "v2"}'])._clients
-['C 2']
->>> (r._children['k1']['{"const": "v1"}']
-...   ._children['k2']['{"const": "v2"}'])._children.keys()
-dict_keys([])
->>> r._children['k1']['{"const": "v2"}']._clients
-[]
->>> r._children['k1']['{"const": "v2"}']._children.keys()
-dict_keys(['k2'])
->>> r._children['k1']['{"const": "v2"}']._children['k2'].keys()
-dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
->>> (r._children['k1']['{"const": "v2"}']
-...   ._children['k2']['{"const": "v1"}'])._clients
-['C 3']
->>> (r._children['k1']['{"const": "v2"}']
-...   ._children['k2']['{"const": "v1"}'])._children.keys()
-dict_keys([])
->>> (r._children['k1']['{"const": "v2"}']
-...   ._children['k2']['{"const": "v2"}'])._clients
-['C 4']
->>> (r._children['k1']['{"const": "v2"}']
-...   ._children['k2']['{"const": "v2"}'])._children.keys()
-dict_keys([])
-

-Expand source code -

def insert(self, template: MessageTemplate, client: str) -> None:
-    """Register a client for a template.
-
-    >>> r = MessageTemplateRegistry()
-    >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v1'}}, 'C 1')
-    >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v2'}}, 'C 2')
-    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v1'}}, 'C 3')
-    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v2'}}, 'C 4')
-    >>> r.insert({}, 'C 5')
-
-    Implementation details:
-    -----------------------
-    The tree nodes on the way to a registered object are used/created
-    in the order given in the message template, which can be used to
-    design more efficient lookups (e.g., putting rarer key-value pairs
-    earlier in the template).
-    >>> r._clients
-    ['C 5']
-    >>> r._children.keys()
-    dict_keys(['k1'])
-    >>> r._children['k1'].keys()
-    dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-    >>> r._children['k1']['{"const": "v1"}']._clients
-    []
-    >>> r._children['k1']['{"const": "v1"}']._children.keys()
-    dict_keys(['k2'])
-    >>> r._children['k1']['{"const": "v1"}']._children['k2'].keys()
-    dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-    >>> (r._children['k1']['{"const": "v1"}']
-    ...   ._children['k2']['{"const": "v1"}'])._clients
-    ['C 1']
-    >>> (r._children['k1']['{"const": "v1"}']
-    ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-    dict_keys([])
-    >>> (r._children['k1']['{"const": "v1"}']
-    ...   ._children['k2']['{"const": "v2"}'])._clients
-    ['C 2']
-    >>> (r._children['k1']['{"const": "v1"}']
-    ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-    dict_keys([])
-    >>> r._children['k1']['{"const": "v2"}']._clients
-    []
-    >>> r._children['k1']['{"const": "v2"}']._children.keys()
-    dict_keys(['k2'])
-    >>> r._children['k1']['{"const": "v2"}']._children['k2'].keys()
-    dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-    >>> (r._children['k1']['{"const": "v2"}']
-    ...   ._children['k2']['{"const": "v1"}'])._clients
-    ['C 3']
-    >>> (r._children['k1']['{"const": "v2"}']
-    ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-    dict_keys([])
-    >>> (r._children['k1']['{"const": "v2"}']
-    ...   ._children['k2']['{"const": "v2"}'])._clients
-    ['C 4']
-    >>> (r._children['k1']['{"const": "v2"}']
-    ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-    dict_keys([])
-    """
-    if not template:
-        self._clients.append(client)
-    else:
-        key, schema = next(iter(template.items()))
-        schema_string = json.dumps(schema)
-        reduced_template = MessageTemplate({k: template[k]
-                                            for k in template
-                                            if k != key})
-        if key not in self._children:
-            self._children[key] = {}
-        if schema_string not in self._children[key]:
-            self._children[key][schema_string] = MessageTemplateRegistry()
-        self._children[key][schema_string].insert(reduced_template, client)

-def delete(self, client:Â str) â>Â bool -

Unregister a client from all templates.

>>> r = MessageTemplateRegistry()
->>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v1'}}, 'C 1')
->>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v2'}}, 'C 2')
->>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v1'}}, 'C 3')
->>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v2'}}, 'C 4')
->>> r.insert({}, 'C 5')
->>> r.delete('C 3')
-True
->>> r.delete('C 4')
-True
-

Implementation details:

If parts of the tree become superfluous by the deletion of the -client, they are also completely removed to reduce the lookup -effort and keep the tree clean.

>>> r._clients
-['C 5']
->>> r._children.keys()
-dict_keys(['k1'])
->>> r._children['k1'].keys()
-dict_keys(['{"const": "v1"}'])
->>> r._children['k1']['{"const": "v1"}']._clients
-[]
->>> r._children['k1']['{"const": "v1"}']._children.keys()
-dict_keys(['k2'])
->>> r._children['k1']['{"const": "v1"}']._children['k2'].keys()
-dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
->>> (r._children['k1']['{"const": "v1"}']
-...   ._children['k2']['{"const": "v1"}'])._clients
-['C 1']
->>> (r._children['k1']['{"const": "v1"}']
-...   ._children['k2']['{"const": "v1"}'])._children.keys()
-dict_keys([])
->>> (r._children['k1']['{"const": "v1"}']
-...   ._children['k2']['{"const": "v2"}'])._clients
-['C 2']
->>> (r._children['k1']['{"const": "v1"}']
-...   ._children['k2']['{"const": "v2"}'])._children.keys()
-dict_keys([])
-

-Expand source code -

def delete(self, client: str) -> bool:
-    """Unregister a client from all templates.
-
-    >>> r = MessageTemplateRegistry()
-    >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v1'}}, 'C 1')
-    >>> r.insert({'k1': {'const': 'v1'}, 'k2': {'const': 'v2'}}, 'C 2')
-    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v1'}}, 'C 3')
-    >>> r.insert({'k1': {'const': 'v2'}, 'k2': {'const': 'v2'}}, 'C 4')
-    >>> r.insert({}, 'C 5')
-    >>> r.delete('C 3')
-    True
-    >>> r.delete('C 4')
-    True
-
-    Implementation details:
-    -----------------------
-    If parts of the tree become superfluous by the deletion of the
-    client, they are also completely removed to reduce the lookup
-    effort and keep the tree clean.
-    >>> r._clients
-    ['C 5']
-    >>> r._children.keys()
-    dict_keys(['k1'])
-    >>> r._children['k1'].keys()
-    dict_keys(['{"const": "v1"}'])
-    >>> r._children['k1']['{"const": "v1"}']._clients
-    []
-    >>> r._children['k1']['{"const": "v1"}']._children.keys()
-    dict_keys(['k2'])
-    >>> r._children['k1']['{"const": "v1"}']._children['k2'].keys()
-    dict_keys(['{"const": "v1"}', '{"const": "v2"}'])
-    >>> (r._children['k1']['{"const": "v1"}']
-    ...   ._children['k2']['{"const": "v1"}'])._clients
-    ['C 1']
-    >>> (r._children['k1']['{"const": "v1"}']
-    ...   ._children['k2']['{"const": "v1"}'])._children.keys()
-    dict_keys([])
-    >>> (r._children['k1']['{"const": "v1"}']
-    ...   ._children['k2']['{"const": "v2"}'])._clients
-    ['C 2']
-    >>> (r._children['k1']['{"const": "v1"}']
-    ...   ._children['k2']['{"const": "v2"}'])._children.keys()
-    dict_keys([])
-    """
-    self._clients = [c for c in self._clients if c != client]
-    new_children: Dict[str, Dict[str, MessageTemplateRegistry]] = {}
-    for key in self._children:
-        new_children[key] = {}
-        for schema in self._children[key]:
-            if self._children[key][schema].delete(client):
-                new_children[key][schema] = self._children[key][schema]
-        if not new_children[key]:
-            del new_children[key]
-    self._children = new_children
-    if self._clients or self._children:
-        return True
-    return False

-def check(self, client:Â str, message:Â Message) â>Â bool -

Get if a client has a registered template matching a message.

>>> r = MessageTemplateRegistry()
->>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-...     print(f"{m}: {r.check('Client 1', m)}")
-{'k1': 'v1', 'k2': 'v1'}: True
-{'k1': 'v1', 'k2': 'v2'}: True
-{'k1': 'v2', 'k2': 'v1'}: False
-{'k1': 'v2', 'k2': 'v2'}: False
->>> r.insert({'k2': {'const': 'v2'}}, 'Client 2')
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-...     print(f"{m}: {r.check('Client 2', m)}")
-{'k1': 'v1', 'k2': 'v1'}: False
-{'k1': 'v1', 'k2': 'v2'}: True
-{'k1': 'v2', 'k2': 'v1'}: False
-{'k1': 'v2', 'k2': 'v2'}: True
-

-Expand source code -

def check(self, client: str, message: Message) -> bool:
-    """Get if a client has a registered template matching a message.
-
-    >>> r = MessageTemplateRegistry()
-    >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-    ...     print(f"{m}: {r.check('Client 1', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: True
-    {'k1': 'v1', 'k2': 'v2'}: True
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 'v2'}: False
-    >>> r.insert({'k2': {'const': 'v2'}}, 'Client 2')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-    ...     print(f"{m}: {r.check('Client 2', m)}")
-    {'k1': 'v1', 'k2': 'v1'}: False
-    {'k1': 'v1', 'k2': 'v2'}: True
-    {'k1': 'v2', 'k2': 'v1'}: False
-    {'k1': 'v2', 'k2': 'v2'}: True
-    """
-    if client in self._clients:
-        return True
-    for key in self._children:
-        if key in message:
-            for schema_string in self._children[key]:
-                schema = json.loads(schema_string)
-                validator = jsonschema.Draft7Validator(schema)
-                validated = True
-                for error in validator.iter_errors(message[key]):
-                    validated = False
-                if validated:
-                    child = self._children[key][schema_string]
-                    if child.check(client, message):
-                        return True
-    return False

-def get(self, message:Â Message) â>Â List[str] -

Get all clients registered for templates matching a message.

>>> r = MessageTemplateRegistry()
->>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
->>> r.insert({'k2': {'const': 'v2'}}, 'Client 2')
->>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-...     print(f"{m}: {r.get(m)}")
-{'k1': 'v1', 'k2': 'v1'}: ['Client 1']
-{'k1': 'v1', 'k2': 'v2'}: ['Client 1', 'Client 2']
-{'k1': 'v2', 'k2': 'v1'}: []
-{'k1': 'v2', 'k2': 'v2'}: ['Client 2']
-

-Expand source code -

def get(self, message: Message) -> List[str]:
-    """Get all clients registered for templates matching a message.
-
-    >>> r = MessageTemplateRegistry()
-    >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-    >>> r.insert({'k2': {'const': 'v2'}}, 'Client 2')
-    >>> for m in [{'k1': 'v1', 'k2': 'v1'}, {'k1': 'v1', 'k2': 'v2'},
-    ...           {'k1': 'v2', 'k2': 'v1'}, {'k1': 'v2', 'k2': 'v2'}]:
-    ...     print(f"{m}: {r.get(m)}")
-    {'k1': 'v1', 'k2': 'v1'}: ['Client 1']
-    {'k1': 'v1', 'k2': 'v2'}: ['Client 1', 'Client 2']
-    {'k1': 'v2', 'k2': 'v1'}: []
-    {'k1': 'v2', 'k2': 'v2'}: ['Client 2']
-    """
-    result = []
-    for client in self._clients:
-        if client not in result:
-            result.append(client)
-    for key in self._children:
-        if key in message:
-            for schema_string in self._children[key]:
-                schema = json.loads(schema_string)
-                validator = jsonschema.Draft7Validator(schema)
-                validated = True
-                for error in validator.iter_errors(message[key]):
-                    validated = False
-                if validated:
-                    child = self._children[key][schema_string]
-                    for client in child.get(message):
-                        if client not in result:
-                            result.append(client)
-    return result

-def get_templates(self, client:Â str) â>Â List[MessageTemplate] -

Get all templates for a client.

>>> r = MessageTemplateRegistry()
->>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
->>> r.get_templates('Client 1')
-[{'k1': {'const': 'v1'}}]
->>> r.insert({'k1': {'const': 'v2'},
-...           'k2': {'type': 'string'}}, 'Client 2')
->>> r.get_templates('Client 2')
-[{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
->>> r.insert({'k1': {'const': 'v2'},
-...           'k2': {'type': 'integer'}}, 'Client 3')
->>> r.get_templates('Client 3')
-[{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
->>> r.insert({'k2': {'const': 2}}, 'Client 4')
->>> r.get_templates('Client 4')
-[{'k2': {'const': 2}}]
->>> r.insert({}, 'Client 5')
->>> r.get_templates('Client 5')
-[{}]
->>> r.insert({'k1': {'const': 'v1'}}, 'Client 6')
->>> r.insert({'k2': {'const': 'v1'}}, 'Client 6')
->>> r.get_templates('Client 6')
-[{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
-

-Expand source code -

def get_templates(self, client: str) -> List[MessageTemplate]:
-    """Get all templates for a client.
-
-    >>> r = MessageTemplateRegistry()
-    >>> r.insert({'k1': {'const': 'v1'}}, 'Client 1')
-    >>> r.get_templates('Client 1')
-    [{'k1': {'const': 'v1'}}]
-    >>> r.insert({'k1': {'const': 'v2'},
-    ...           'k2': {'type': 'string'}}, 'Client 2')
-    >>> r.get_templates('Client 2')
-    [{'k1': {'const': 'v2'}, 'k2': {'type': 'string'}}]
-    >>> r.insert({'k1': {'const': 'v2'},
-    ...           'k2': {'type': 'integer'}}, 'Client 3')
-    >>> r.get_templates('Client 3')
-    [{'k1': {'const': 'v2'}, 'k2': {'type': 'integer'}}]
-    >>> r.insert({'k2': {'const': 2}}, 'Client 4')
-    >>> r.get_templates('Client 4')
-    [{'k2': {'const': 2}}]
-    >>> r.insert({}, 'Client 5')
-    >>> r.get_templates('Client 5')
-    [{}]
-    >>> r.insert({'k1': {'const': 'v1'}}, 'Client 6')
-    >>> r.insert({'k2': {'const': 'v1'}}, 'Client 6')
-    >>> r.get_templates('Client 6')
-    [{'k1': {'const': 'v1'}}, {'k2': {'const': 'v1'}}]
-    """
-    result = []
-    if client in self._clients:
-        result.append(MessageTemplate())
-    for key in self._children:
-        for schema_string in self._children[key]:
-            schema = json.loads(schema_string)
-            child = self._children[key][schema_string]
-            for template in child.get_templates(client):
-                current = MessageTemplate({key: schema})
-                current.update(template)
-                result.append(current)
-    return result

-class BusException -(*args, **kwargs) -

Raise for errors in using message bus.

-Expand source code -

class BusException(Exception):
-    """Raise for errors in using message bus."""

Ancestors

builtins.Exception
builtins.BaseException

-class MessageBus -

Provide an asynchronous message bus.

The bus executes asynchronous callbacks for all messages to be received -by a client. We use a simple callback printing the message in all -examples:

>>> def callback_for_receiver(receiver):
-...     print(f"Creating callback for {receiver}.")
-...     async def callback(message):
-...         print(f"{receiver}: {message}")
-...     return callback
-

Clients can be registered at the bus with a name, lists of message -templates they want to use for sending and receiving and a callback -function for receiving. An empty list of templates means that the -client does not want to send or receive any messages, respectively. -A list with an empty template means that it wants to send arbitrary -or receive all messages, respectively:

>>> async def setup(bus):
-...     print("Setting up.")
-...     bus.register('Logger', 'Test Plugin',
-...                  [],
-...                  [{}],
-...                  callback_for_receiver('Logger'))
-...     bus.register('Client 1', 'Test Plugin',
-...                  [{'k1': {'type': 'string'}}],
-...                  [{'target': {'const': 'Client 1'}}],
-...                  callback_for_receiver('Client 1'))
-...     bus.register('Client 2', 'Test Plugin',
-...                  [{}],
-...                  [{'target': {'const': 'Client 2'}}],
-...                  callback_for_receiver('Client 2'))
-

The bus itself is addressed by the empty string. It sends messages for -each registration and deregestration of a client with a key 'event' and -a value of 'registered' or 'unregistered', a key 'client' with the -client's name as value and for registrations also keys 'sends' and -'receives' with all templates registered for the client for sending and -receiving.

Clients can send to the bus with the send function. Each message has to -declare a sender. The send templates of that sender are checked for a -template matching the message. We cannot prevent arbitrary code from -impersonating any sender, but this should only be done in debugging or -management situations.

Messages that are intended for a specific client by convention have a -key 'target' with the target client's name as value. Such messages are -often commands to the client to do something, which is by convention -indicated by a key 'command' with a value that indicates what should be -done.

The bus, for example, reacts to a message with 'target': '' and -'command': 'get clients' by sending one message for each currently -registered with complete information about its registered send and -receive templates.

>>> async def send(bus):
-...     print("Sending messages.")
-...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
-...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
-...     await bus.send({'sender': '', 'target': '',
-...                     'command': 'get clients'})
-

The run function executes the message bus forever. If we want to stop -it, we have to explicitly cancel the task:

>>> async def main():
-...     bus = MessageBus()
-...     await setup(bus)
-...     bus_task = asyncio.create_task(bus.run())
-...     await send(bus)
-...     await asyncio.sleep(0)
-...     bus_task.cancel()
->>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-Setting up.
-Creating callback for Logger.
-Creating callback for Client 1.
-Creating callback for Client 2.
-Sending messages.
-Logger: {'sender': '', 'event': 'registered',
-         'client': 'Logger', 'plugin': 'Test Plugin',
-         'sends': [], 'receives': [{}]}
-Logger: {'sender': '', 'event': 'registered',
-         'client': 'Client 1', 'plugin': 'Test Plugin',
-         'sends': [{'k1': {'type': 'string'}}],
-         'receives': [{'target': {'const': 'Client 1'}}]}
-Logger: {'sender': '', 'event': 'registered',
-         'client': 'Client 2', 'plugin': 'Test Plugin',
-         'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
-Logger: {'sender': 'Client 1', 'k1': 'Test'}
-Logger: {'sender': 'Client 2', 'target': 'Client 1'}
-Client 1: {'sender': 'Client 2', 'target': 'Client 1'}
-Logger: {'sender': '', 'target': '', 'command': 'get clients'}
-Logger: {'sender': '', 'client': 'Logger', 'plugin': 'Test Plugin',
-         'sends': [], 'receives': [{}]}
-Logger: {'sender': '', 'client': 'Client 1', 'plugin': 'Test Plugin',
-         'sends': [{'k1': {'type': 'string'}}],
-         'receives': [{'target': {'const': 'Client 1'}}]}
-Logger: {'sender': '', 'client': 'Client 2', 'plugin': 'Test Plugin',
-         'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
-

Initialise a new bus without clients.

>>> async def main():
-...     bus = MessageBus()
->>> asyncio.run(main())
-

-Expand source code -

class MessageBus:
-    """Provide an asynchronous message bus.
-
-    The bus executes asynchronous callbacks for all messages to be received
-    by a client. We use a simple callback printing the message in all
-    examples:
-    >>> def callback_for_receiver(receiver):
-    ...     print(f"Creating callback for {receiver}.")
-    ...     async def callback(message):
-    ...         print(f"{receiver}: {message}")
-    ...     return callback
-
-    Clients can be registered at the bus with a name, lists of message
-    templates they want to use for sending and receiving and a callback
-    function for receiving. An empty list of templates means that the
-    client does not want to send or receive any messages, respectively.
-    A list with an empty template means that it wants to send arbitrary
-    or receive all messages, respectively:
-    >>> async def setup(bus):
-    ...     print("Setting up.")
-    ...     bus.register('Logger', 'Test Plugin',
-    ...                  [],
-    ...                  [{}],
-    ...                  callback_for_receiver('Logger'))
-    ...     bus.register('Client 1', 'Test Plugin',
-    ...                  [{'k1': {'type': 'string'}}],
-    ...                  [{'target': {'const': 'Client 1'}}],
-    ...                  callback_for_receiver('Client 1'))
-    ...     bus.register('Client 2', 'Test Plugin',
-    ...                  [{}],
-    ...                  [{'target': {'const': 'Client 2'}}],
-    ...                  callback_for_receiver('Client 2'))
-
-    The bus itself is addressed by the empty string. It sends messages for
-    each registration and deregestration of a client with a key 'event' and
-    a value of 'registered' or 'unregistered', a key 'client' with the
-    client's name as value and for registrations also keys 'sends' and
-    'receives' with all templates registered for the client for sending and
-    receiving.
-
-    Clients can send to the bus with the send function. Each message has to
-    declare a sender. The send templates of that sender are checked for a
-    template matching the message. We cannot prevent arbitrary code from
-    impersonating any sender, but this should only be done in debugging or
-    management situations.
-
-    Messages that are intended for a specific client by convention have a
-    key 'target' with the target client's name as value. Such messages are
-    often commands to the client to do something, which is by convention
-    indicated by a key 'command' with a value that indicates what should be
-    done.
-
-    The bus, for example, reacts to a message with 'target': '' and
-    'command': 'get clients' by sending one message for each currently
-    registered with complete information about its registered send and
-    receive templates.
-
-    >>> async def send(bus):
-    ...     print("Sending messages.")
-    ...     await bus.send({'sender': 'Client 1', 'k1': 'Test'})
-    ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
-    ...     await bus.send({'sender': '', 'target': '',
-    ...                     'command': 'get clients'})
-
-    The run function executes the message bus forever. If we want to stop
-    it, we have to explicitly cancel the task:
-    >>> async def main():
-    ...     bus = MessageBus()
-    ...     await setup(bus)
-    ...     bus_task = asyncio.create_task(bus.run())
-    ...     await send(bus)
-    ...     await asyncio.sleep(0)
-    ...     bus_task.cancel()
-    >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-    Setting up.
-    Creating callback for Logger.
-    Creating callback for Client 1.
-    Creating callback for Client 2.
-    Sending messages.
-    Logger: {'sender': '', 'event': 'registered',
-             'client': 'Logger', 'plugin': 'Test Plugin',
-             'sends': [], 'receives': [{}]}
-    Logger: {'sender': '', 'event': 'registered',
-             'client': 'Client 1', 'plugin': 'Test Plugin',
-             'sends': [{'k1': {'type': 'string'}}],
-             'receives': [{'target': {'const': 'Client 1'}}]}
-    Logger: {'sender': '', 'event': 'registered',
-             'client': 'Client 2', 'plugin': 'Test Plugin',
-             'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
-    Logger: {'sender': 'Client 1', 'k1': 'Test'}
-    Logger: {'sender': 'Client 2', 'target': 'Client 1'}
-    Client 1: {'sender': 'Client 2', 'target': 'Client 1'}
-    Logger: {'sender': '', 'target': '', 'command': 'get clients'}
-    Logger: {'sender': '', 'client': 'Logger', 'plugin': 'Test Plugin',
-             'sends': [], 'receives': [{}]}
-    Logger: {'sender': '', 'client': 'Client 1', 'plugin': 'Test Plugin',
-             'sends': [{'k1': {'type': 'string'}}],
-             'receives': [{'target': {'const': 'Client 1'}}]}
-    Logger: {'sender': '', 'client': 'Client 2', 'plugin': 'Test Plugin',
-             'sends': [{}], 'receives': [{'target': {'const': 'Client 2'}}]}
-    """
-
-    def __init__(self) -> None:
-        """Initialise a new bus without clients.
-
-        >>> async def main():
-        ...     bus = MessageBus()
-        >>> asyncio.run(main())
-        """
-        self._queue: asyncio.Queue = asyncio.Queue()
-        self._plugins: Dict[str, str] = {}
-        self._send_reg: MessageTemplateRegistry = MessageTemplateRegistry()
-        self._recv_reg: MessageTemplateRegistry = MessageTemplateRegistry()
-        self._callbacks: Dict[str, MessageCallback] = {}
-
-    def register(self, client: str, plugin: str,
-                 sends: Iterable[MessageTemplate],
-                 receives: Iterable[MessageTemplate],
-                 callback: MessageCallback) -> None:
-        """Register a client at the message bus.
-
-        >>> async def callback(message):
-        ...     print(message)
-        >>> async def main():
-        ...     bus = MessageBus()
-        ...     bus.register('Logger', 'Test Plugin',
-        ...                  [],    # send nothing
-        ...                  [{}],  # receive everything
-        ...                  callback)
-        ...     bus.register('Client 1', 'Test Plugin',
-        ...                  [{'k1': {'type': 'string'}}],
-        ...                      # send with key 'k1' and string value
-        ...                  [{'target': {'const': 'Client 1'}}],
-        ...                      # receive for this client
-        ...                  callback)
-        ...     bus.register('Client 2', 'Test Plugin',
-        ...                  [{}],  # send arbitrary
-        ...                  [{'target': {'const': 'Client 2'}}],
-        ...                      # receive for this client
-        ...                  callback)
-        >>> asyncio.run(main())
-        """
-        if not client:
-            raise BusException("Client name is not allowed to be empty.")
-        if client in self._plugins:
-            raise BusException(f"Client '{client}' already registered"
-                               " at message bus.")
-        event = Message('')
-        event['event'] = 'registered'
-        event['client'] = client
-        self._plugins[client] = plugin
-        event['plugin'] = plugin
-        for template in sends:
-            self._send_reg.insert(template, client)
-        event['sends'] = self._send_reg.get_templates(client)
-        for template in receives:
-            self._recv_reg.insert(template, client)
-        event['receives'] = self._recv_reg.get_templates(client)
-        self._callbacks[client] = callback
-        self._queue.put_nowait(event)
-
-    def unregister(self, client: str) -> None:
-        """Unregister a client from the message bus.
-
-        >>> async def callback(message):
-        ...     print(message)
-        >>> async def main():
-        ...     bus = MessageBus()
-        ...     bus.register('Client 1', 'Test Plugin',
-        ...                  [{'k1': {'type': 'string'}}],
-        ...                  [{'target': {'const': 'Client 1'}}],
-        ...                  callback)
-        ...     bus.unregister('Client 1')
-        >>> asyncio.run(main())
-        """
-        if client not in self._plugins:
-            return
-        event = Message('')
-        event['event'] = 'unregistered'
-        event['client'] = client
-        del self._plugins[client]
-        self._send_reg.delete(client)
-        self._recv_reg.delete(client)
-        if client in self._callbacks:
-            del self._callbacks[client]
-        self._queue.put_nowait(event)
-
-    async def run(self) -> None:
-        """Run the message bus forever.
-
-        >>> async def main():
-        ...     bus = MessageBus()
-        ...     bus_task = asyncio.create_task(bus.run())
-        ...     bus_task.cancel()
-        >>> asyncio.run(main())
-        """
-        while True:
-            message = await self._queue.get()
-            if ('target' in message and
-                    message['target'] == '' and
-                    'command' in message and
-                    message['command'] == 'get clients'):
-                for client in self._plugins:
-                    answer = Message('')
-                    answer['client'] = client
-                    answer['plugin'] = self._plugins[client]
-                    answer['sends'] = self._send_reg.get_templates(client)
-                    answer['receives'] = self._recv_reg.get_templates(client)
-                    await self._queue.put(answer)
-            for client in self._recv_reg.get(message):
-                await self._callbacks[client](message)
-            self._queue.task_done()
-
-    async def send(self, message: Message) -> None:
-        """Send a message to the message bus.
-
-        >>> async def callback(message):
-        ...     print(f"Got: {message}")
-        >>> async def main():
-        ...     bus = MessageBus()
-        ...     bus.register('Client 1', 'Test Plugin',
-        ...                  [{'k1': {'type': 'string'}}],
-        ...                  [{'target': {'const': 'Client 1'}}],
-        ...                  callback)
-        ...     bus.register('Client 2', 'Test Plugin',
-        ...                  [{}],
-        ...                  [{'target': {'const': 'Client 2'}}],
-        ...                  callback)
-        ...     bus_task = asyncio.create_task(bus.run())
-        ...     await bus.send({'sender': 'Client 1', 'target': 'Client 2',
-        ...                     'k1': 'Test'})
-        ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
-        ...     try:
-        ...         await bus.send({'sender': 'Client 1', 'target': 'Client 2',
-        ...                         'k1': 42})
-        ...     except BusException as e:
-        ...         print(e)
-        ...     await asyncio.sleep(0)
-        ...     bus_task.cancel()
-        >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-        Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
-        not allowed for sender 'Client 1'.
-        Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
-        Got: {'sender': 'Client 2', 'target': 'Client 1'}
-        """
-        assert isinstance(message['sender'], str)
-        sender = message['sender']
-        if sender:
-            if not self._send_reg.check(sender, message):
-                raise BusException(f"Message '{message}' not allowed for"
-                                   f" sender '{sender}'.")
-        await self._queue.put(message)

Methods

-def register(self, client:Â str, plugin:Â str, sends:Â Iterable[MessageTemplate], receives:Â Iterable[MessageTemplate], callback:Â Callable[[ForwardRef('Message')],Â Coroutine[Any,Â Any,Â NoneType]]) â>Â NoneType -

>>> async def callback(message):
-...     print(message)
->>> async def main():
-...     bus = MessageBus()
-...     bus.register('Logger', 'Test Plugin',
-...                  [],    # send nothing
-...                  [{}],  # receive everything
-...                  callback)
-...     bus.register('Client 1', 'Test Plugin',
-...                  [{'k1': {'type': 'string'}}],
-...                      # send with key 'k1' and string value
-...                  [{'target': {'const': 'Client 1'}}],
-...                      # receive for this client
-...                  callback)
-...     bus.register('Client 2', 'Test Plugin',
-...                  [{}],  # send arbitrary
-...                  [{'target': {'const': 'Client 2'}}],
-...                      # receive for this client
-...                  callback)
->>> asyncio.run(main())
-

-Expand source code -

def register(self, client: str, plugin: str,
-             sends: Iterable[MessageTemplate],
-             receives: Iterable[MessageTemplate],
-             callback: MessageCallback) -> None:
-    """Register a client at the message bus.
-
-    >>> async def callback(message):
-    ...     print(message)
-    >>> async def main():
-    ...     bus = MessageBus()
-    ...     bus.register('Logger', 'Test Plugin',
-    ...                  [],    # send nothing
-    ...                  [{}],  # receive everything
-    ...                  callback)
-    ...     bus.register('Client 1', 'Test Plugin',
-    ...                  [{'k1': {'type': 'string'}}],
-    ...                      # send with key 'k1' and string value
-    ...                  [{'target': {'const': 'Client 1'}}],
-    ...                      # receive for this client
-    ...                  callback)
-    ...     bus.register('Client 2', 'Test Plugin',
-    ...                  [{}],  # send arbitrary
-    ...                  [{'target': {'const': 'Client 2'}}],
-    ...                      # receive for this client
-    ...                  callback)
-    >>> asyncio.run(main())
-    """
-    if not client:
-        raise BusException("Client name is not allowed to be empty.")
-    if client in self._plugins:
-        raise BusException(f"Client '{client}' already registered"
-                           " at message bus.")
-    event = Message('')
-    event['event'] = 'registered'
-    event['client'] = client
-    self._plugins[client] = plugin
-    event['plugin'] = plugin
-    for template in sends:
-        self._send_reg.insert(template, client)
-    event['sends'] = self._send_reg.get_templates(client)
-    for template in receives:
-        self._recv_reg.insert(template, client)
-    event['receives'] = self._recv_reg.get_templates(client)
-    self._callbacks[client] = callback
-    self._queue.put_nowait(event)

-def unregister(self, client:Â str) â>Â NoneType -

Unregister a client from the message bus.

>>> async def callback(message):
-...     print(message)
->>> async def main():
-...     bus = MessageBus()
-...     bus.register('Client 1', 'Test Plugin',
-...                  [{'k1': {'type': 'string'}}],
-...                  [{'target': {'const': 'Client 1'}}],
-...                  callback)
-...     bus.unregister('Client 1')
->>> asyncio.run(main())
-

-Expand source code -

def unregister(self, client: str) -> None:
-    """Unregister a client from the message bus.
-
-    >>> async def callback(message):
-    ...     print(message)
-    >>> async def main():
-    ...     bus = MessageBus()
-    ...     bus.register('Client 1', 'Test Plugin',
-    ...                  [{'k1': {'type': 'string'}}],
-    ...                  [{'target': {'const': 'Client 1'}}],
-    ...                  callback)
-    ...     bus.unregister('Client 1')
-    >>> asyncio.run(main())
-    """
-    if client not in self._plugins:
-        return
-    event = Message('')
-    event['event'] = 'unregistered'
-    event['client'] = client
-    del self._plugins[client]
-    self._send_reg.delete(client)
-    self._recv_reg.delete(client)
-    if client in self._callbacks:
-        del self._callbacks[client]
-    self._queue.put_nowait(event)

-async def run(self) â>Â NoneType -

Run the message bus forever.

>>> async def main():
-...     bus = MessageBus()
-...     bus_task = asyncio.create_task(bus.run())
-...     bus_task.cancel()
->>> asyncio.run(main())
-

-Expand source code -

async def run(self) -> None:
-    """Run the message bus forever.
-
-    >>> async def main():
-    ...     bus = MessageBus()
-    ...     bus_task = asyncio.create_task(bus.run())
-    ...     bus_task.cancel()
-    >>> asyncio.run(main())
-    """
-    while True:
-        message = await self._queue.get()
-        if ('target' in message and
-                message['target'] == '' and
-                'command' in message and
-                message['command'] == 'get clients'):
-            for client in self._plugins:
-                answer = Message('')
-                answer['client'] = client
-                answer['plugin'] = self._plugins[client]
-                answer['sends'] = self._send_reg.get_templates(client)
-                answer['receives'] = self._recv_reg.get_templates(client)
-                await self._queue.put(answer)
-        for client in self._recv_reg.get(message):
-            await self._callbacks[client](message)
-        self._queue.task_done()

-async def send(self, message:Â Message) â>Â NoneType -

Send a message to the message bus.

>>> async def callback(message):
-...     print(f"Got: {message}")
->>> async def main():
-...     bus = MessageBus()
-...     bus.register('Client 1', 'Test Plugin',
-...                  [{'k1': {'type': 'string'}}],
-...                  [{'target': {'const': 'Client 1'}}],
-...                  callback)
-...     bus.register('Client 2', 'Test Plugin',
-...                  [{}],
-...                  [{'target': {'const': 'Client 2'}}],
-...                  callback)
-...     bus_task = asyncio.create_task(bus.run())
-...     await bus.send({'sender': 'Client 1', 'target': 'Client 2',
-...                     'k1': 'Test'})
-...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
-...     try:
-...         await bus.send({'sender': 'Client 1', 'target': 'Client 2',
-...                         'k1': 42})
-...     except BusException as e:
-...         print(e)
-...     await asyncio.sleep(0)
-...     bus_task.cancel()
->>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
-not allowed for sender 'Client 1'.
-Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
-Got: {'sender': 'Client 2', 'target': 'Client 1'}
-

-Expand source code -

async def send(self, message: Message) -> None:
-    """Send a message to the message bus.
-
-    >>> async def callback(message):
-    ...     print(f"Got: {message}")
-    >>> async def main():
-    ...     bus = MessageBus()
-    ...     bus.register('Client 1', 'Test Plugin',
-    ...                  [{'k1': {'type': 'string'}}],
-    ...                  [{'target': {'const': 'Client 1'}}],
-    ...                  callback)
-    ...     bus.register('Client 2', 'Test Plugin',
-    ...                  [{}],
-    ...                  [{'target': {'const': 'Client 2'}}],
-    ...                  callback)
-    ...     bus_task = asyncio.create_task(bus.run())
-    ...     await bus.send({'sender': 'Client 1', 'target': 'Client 2',
-    ...                     'k1': 'Test'})
-    ...     await bus.send({'sender': 'Client 2', 'target': 'Client 1'})
-    ...     try:
-    ...         await bus.send({'sender': 'Client 1', 'target': 'Client 2',
-    ...                         'k1': 42})
-    ...     except BusException as e:
-    ...         print(e)
-    ...     await asyncio.sleep(0)
-    ...     bus_task.cancel()
-    >>> asyncio.run(main())  # doctest: +NORMALIZE_WHITESPACE
-    Message '{'sender': 'Client 1', 'target': 'Client 2', 'k1': 42}'
-    not allowed for sender 'Client 1'.
-    Got: {'sender': 'Client 1', 'target': 'Client 2', 'k1': 'Test'}
-    Got: {'sender': 'Client 2', 'target': 'Client 1'}
-    """
-    assert isinstance(message['sender'], str)
-    sender = message['sender']
-    if sender:
-        if not self._send_reg.check(sender, message):
-            raise BusException(f"Message '{message}' not allowed for"
-                               f" sender '{sender}'.")
-    await self._queue.put(message)

+controlpi

+controlpi.baseplugin

+controlpi.messagebus

+controlpi.pluginregistry

+controlpi_plugins

+controlpi_plugins.state

Inherited Members

Inherited Members

Inherited Members

Inherited Members

Inherited Members

Inherited Members

+controlpi_plugins.util

Inherited Members

Inherited Members

Inherited Members

Inherited Members

Inherited Members

Inherited Members

+controlpi_plugins.wait

Inherited Members

Inherited Members

Inherited Members

Inherited Members

Classes

Ancestors

Ancestors

Subclasses

Methods

Sub-modules

Functions

Classes

Ancestors

Static methods

Methods

Ancestors

Static methods

Methods

Methods

Implementation details:

Implementation details:

Ancestors

Methods

Classes

Ancestors

Sub-modules

Classes

Ancestors

Class variables

Methods

Ancestors

Class variables

Methods

Ancestors

Class variables

Methods

Ancestors

Class variables

Methods

Classes

Ancestors

Class variables

Methods

Ancestors

Class variables

Methods

Ancestors

Class variables

Methods

Ancestors

Class variables

Methods

Classes

Ancestors

Class variables

Methods

Ancestors

Class variables

Methods