Glossary

buffered serializer

See serializer.

communication protocol

A set of formal rules describing how to transmit or exchange data, especially across a network.

In EasyNetwork, it is up to the developer to define his communication protocol using a protocol object.

composite converter

A converter that processes different objects in input and output.

See also

StapledPacketConverter class.

converter

An interface responsible for bridging the gap between the Python objects manipulated by the application/software and the data transfer objects handled by the serializer.

It must also ensure that deserialized objects are valid and usable by the application/software without post-processing.

data transfer object

An object that carry data between processes in order to reduce the number of methods calls. It is a flat data structure that contain no business logic.

In EasyNetwork, the DTOs are manipulated by the serializer and transformed into business objects by a converter.

DTO

See data transfer object.

incremental serializer

See serializer.

one-shot serializer

See serializer.

packet

A unit of data routed between an origin and a destination on a network.

protocol object

An object representing a communication protocol. It consists of a serializer and, optionally, a converter.

serializer

The lowest layer for passing from a Python object ( a DTO ) to raw data (bytes) and vice versa.

It must have no knowledge of the object’s validity with regard to the application/software logic, nor the meaning of data with regard to the communication protocol. This ensures a generic format that can be reused in any project.

For example, the JSONSerializer only knows how to translate dictionaries, lists, strings, numbers and special constants, and how to reinterpret them.

A serializer imposes its own limits on the objects it can translate and on the validity of the object itself (for example, as a JSON object, a dictionary must only have character strings as keys).

Ideally, a serializer should only handle primitive types and constants.

There are 3 types of serializers:

• one-shot serializers

  One-shot serializers provide the full representation of a Python object in bytes in a single function call, and need this same full representation to recreate the object at once.

• incremental serializers

  Incremental serializers, on the other hand, provide the full representation of the Python object in bytes part by part, sometimes including additional metadata used during deserialization.

  During deserialization, they have the ability to know when the packet is complete (and wait if incomplete) and which bytes are not part of the initial packet.

• buffered serializers

  An incremental serializer specialization that allows the use of a custom in-memory byte buffer, if supported by the underlying transport layer.

serializer wrapper

A serializer that transforms data coming from another serializer.

Example:

>>> from easynetwork.serializers import JSONSerializer
>>> from easynetwork.serializers.wrapper import Base64EncoderSerializer
>>> s = Base64EncoderSerializer(JSONSerializer())
>>> data = s.serialize({"data": 42})
>>> data
b'eyJkYXRhIjo0Mn0='
>>> s.deserialize(data)
{'data': 42}

Most of the time, a serializer wrapper is an incremental serializer in order to allow a one-shot serializer to be used in a stream context.