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

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

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)

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)

Bases: json.encoder.JSONEncoder

A JSONEncoder that can handle ProtocolElements

default(o)

Return a data structure that JSON can handle

Parameters:o – The object to convert Returns:A serializable data structure

class dhcpkit.protocol_element.ProtocolElement

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)

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

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

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

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

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

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

Save the internal state of this object as a buffer.

Returns:The buffer with the data from this element

validate()

Subclasses may overwrite this method to validate their state. Subclasses are expected to raise a ValueError if validation fails.

validate_contains(elements: Iterable)

Utility method that subclasses can use in their validate method for verifying that all sub-elements are allowed to be contained in this element. Will raise ValueError if validation fails.

Parameters:elements – The list of sub-elements

class dhcpkit.protocol_element.UnknownProtocolElement(data: bytes = b'')

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

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

save() → Union

Save the internal state of this object as a buffer.

Returns:The buffer with the data from this element