dhcpkit.protocol_element module¶
The base class ProtocolElement
provides the basic structure for each element of the DHCP protocol. This base
class provides several functions:
- Parsing:
- Each subclass can parse a stream of bytes from a protocol packet and construct an instance that contains all the data from the byte stream as properties.
- Identification:
- Each category of ProtocolElement can determine which subclass is the most specific implementation for the data
being parsed. For example when letting the Message class
parse
a message it will look at the message type code in the byte steam and determine which specific subclass should parse the data (i.e. SolicitMessage, RequestMessage, ReplyMessage etc). Each category of ProtocolElement has its own registry that keeps track of which type code corresponds to which subclass.
- Saving:
- Each instance can save its contents to a stream of bytes as required by the protocol.
- Validation:
- Each element can validate if its contents are valid. As protocol elements often contain other protocol elements (a message has options, an option might have sub-options etc) there are standard tools for defining which protocol element may contain which other protocol elements and optionally define a minimum and maximum occurrence. Some elements may not occur more than once, some elements must occur at least once, etc.
- Representation:
- The default implementation provides __str__ and __repr__ methods so that protocol elements can be printed for debugging and represented as a parseable Python string.
-
class
dhcpkit.protocol_element.
AutoConstructorParams
[source]¶ Bases:
dhcpkit.protocol_element.AutoMayContainTree
Meta-class that stores the list of parameters for __init__ so that we don’t have to use inspect every time we want to know.
-
class
dhcpkit.protocol_element.
AutoMayContainTree
[source]¶ Bases:
type
Meta-class that automatically creates a _may_contain class property that is a ChainMap that links all parent _may_contain class properties.
-
class
dhcpkit.protocol_element.
ElementDataRepresentation
(element_representation: str)[source]¶ Bases:
object
Class that represents data in a nicer way when printing it with
ProtocolElement.__str__
.
-
class
dhcpkit.protocol_element.
JSONProtocolElementEncoder
(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]¶ Bases:
json.encoder.JSONEncoder
A JSONEncoder that can handle ProtocolElements
-
class
dhcpkit.protocol_element.
ProtocolElement
[source]¶ Bases:
object
A StructuredElement is a specific kind of class that represents a protocol message or option. Structured elements have the following extra requirements:
- The constructor parameters and the internal state properties must be identical So if an object has a property timeout which is an integer then the constructor must accept a named parameter called timeout which is stored in that property. The constructor must have appropriate default values if possible. Empty objects, lists, dictionaries etc are represented by a default value of None.
- The full internal state of the object must be loadable from a bytes object with the
load_from()
method - The full internal state of the object must be storable as a bytes object with the
save()
method
-
classmethod
add_may_contain
(klass: type, min_occurrence: int = 0, max_occurrence: int = 2147483647)[source]¶ Add the given class to the list of permitted sub-element classes, optionally with a minimum and maximum occurrence count.
Parameters: - klass – The class to add
- min_occurrence – Minimum occurrence for validation
- max_occurrence – Maximum occurrence for validation
-
classmethod
determine_class
(buffer: bytes, offset: int = 0) → type[source]¶ Return the appropriate class to parse this element with.
Parameters: - buffer – The buffer to read data from
- offset – The offset in the buffer where to start reading
Returns: The best known class for this data
-
classmethod
get_element_class
(element: object) → Union[source]¶ Get the class this element is classified as, for occurrence counting.
Parameters: element – Some element Returns: The class it classifies as
-
load_from
(buffer: bytes, offset: int = 0, length: int = None) → int[source]¶ Load the internal state of this object from the given buffer. The buffer may contain more data after the structured element is parsed. This data is ignored.
Parameters: - buffer – The buffer to read data from
- offset – The offset in the buffer where to start reading
- length – The amount of data we are allowed to read from the buffer
Returns: The number of bytes used from the buffer
-
classmethod
may_contain
(element: object) → bool[source]¶ Shortcut-method to verify that objects of this class may contain element
Parameters: element – Sub-element to verify Returns: Whether this class may contain element or not
-
classmethod
parse
(buffer: bytes, offset: int = 0, length: int = None) → Tuple[source]¶ Constructor for a new element of which the state is automatically loaded from the given buffer. Both the number of bytes used from the buffer and the instantiated element are returned. The class of the returned element may be a subclass of the current class if the parser can determine that the data in the buffer contains a subtype.
Parameters: - buffer – The buffer to read data from
- offset – The offset in the buffer where to start reading
- length – The amount of data we are allowed to read from the buffer
Returns: The number of bytes used from the buffer and the resulting element
-
save
() → Union[source]¶ Save the internal state of this object as a buffer.
Returns: The buffer with the data from this element
-
class
dhcpkit.protocol_element.
UnknownProtocolElement
(data: bytes = b'')[source]¶ Bases:
dhcpkit.protocol_element.ProtocolElement
Representation of a protocol element about which nothing is known.
-
load_from
(buffer: bytes, offset: int = 0, length: int = None) → int[source]¶ Load the internal state of this object from the given buffer. The buffer may contain more data after the structured element is parsed. This data is ignored.
Parameters: - buffer – The buffer to read data from
- offset – The offset in the buffer where to start reading
- length – The amount of data we are allowed to read from the buffer
Returns: The number of bytes used from the buffer
-