CoAP defines a variety of options that affect request and response semantics. This module provides classes and functions to operate on native Python instances of the options, and to translate them between the Python instances and their encoded representation within messages
| copyright: | Copyright 2013, Peter A. Bigot |
|---|---|
| license: | Apache-2.0 |
Look up an option by number.
Returns the UrOption subclass registered for number, or None if no such option has been registered. number must be an int in the range 0 through 65535.
Return True iff number identifies a critical option.
A critical option is one that must be understood by the endpoint processing the message. This is indicated by bit 0 (0x01) of the number being set.
Return True iff the option number identifies an unsafe option.
An unsafe option is one that must be recognized by a proxy in order to safely forward (or cache) the message. This is indicated by bit 1 (0x02) of the number being set.
Return True iff the option number identifies a NoCacheKey option.
A NoCacheKey option is one for which the value of the option does not contribute to the key that identifies a matching value in a cache. This is encoded in bits 1 through 5 of the number. Options that are unsafe are always NoCacheKey options.
Encode a set of options into packed form.
This returns a bytes object that represents the encoding of options after they have been sorted. It may raise an exception if an option’s value cannot be encoded, but performs no semantic validation.
Extract a list of options from the packed data which is bytes.
Returns (options, remaining_data) where options is a list of instances of subclasses of UrOption. Options that are unknown to the infrastructure will be returned as instances of UnrecognizedOption. remaining_data will be the suffix of data that was not consumed when unpacking the options.
This will raise OptionDecodeError or other exceptions if the option data is malformed, but does no semantic validation
Verify that a set of options passes CoAP requirements.
Individual options have occurrence restrictions that are encoded within the options themselves and may be inspected by these methods:
CoAP Section 5.4.5 specifies that options violating these constraints are to be interpreted as unrecognized options. These are subsequently used to check for critical or unsafe options.
This method replaces individual recognized options in options with an equivalent unrecognized option instance based on is_request and each option’s restrictions. The resulting list of options is returned.
Sort a sequence of options into canonical order.
Return a list with the same elements as options sorted using the option number as the key. The sort is stable: options with the same number remain in their original order. This operation is used for duplicate detection and to calculate the delta required to encode options.
Abstract base for CoAP options.
If unpacked_value is not None, value will be initialized with that value; otherwise if packed_value is not None value will be initialized with the corresponding unpacked value; otherwise value will be None until a valid value is assigned.
Contains the value of the option. This is an instance of format.unpacked_type. Only values that pass the restrictions of format may be assigned to this property. Unacceptable values result in TypeError or OptionLengthError.
Return the sub-sequence of options in options that are instances of cls.
Note that the test is specifically for instances of the class; an instance of UnrecognizedOption will not be returned just because the number matches.
Return the first option in options that’s an instance of cls.
Returns None if no option in the options is an instance of *cls. Note that the test is specifically for instances of the class; an instance of UnrecognizedOption will not be returned just because the number matches.
An instance of format_empty, format_opaque, format_uint, or format_string. The instance is used to check that the value is acceptable for the option.
Passes self.number to is_critical_option().
Passes self.number to is_no_cache_key_option().
Passes self.number to is_unsafe_option().
A human-readable standard short name for the option, suitable for diagnostics. This is a read-only attribute with a Unicode string value.
The option number.
An unsigned integer in the range 0..65535. This is an IANA-registered value with the following policies (RFC 5226):
| Option Range | Policy |
|---|---|
| 0..255 | IETF Review or IESG Approval |
| 256..2047 | Specification Required |
| 2048..64999 | Designated Expert |
| 65000..65535 | Reserved for experiments |
The attribute is read-only. Each subclass of UrOption is registered during its definition. InvalidOptionType will be raised if a previously-registered option exists with the same option number.
Return True iff this option may appear at least once in a request message.
Return True iff this option may appear at least once in a response message.
Return True iff this option may appear multiple times in a request message.
Return True iff this option may appear multiple times in a response message.
Contains the value of the option. This is an instance of format.unpacked_type. Only values that pass the restrictions of format may be assigned to this property. Unacceptable values result in TypeError or OptionLengthError.
Bases: coapy.option.UrOption
Contains an option for which the registered UrOption subclass is not available or may not be used.
number must be provided, must be in the range 0 through 65535. unpacked_value and packed_value operate as in UrOption and accept only bytes objects.
UnrecognizedOption instances are structurally accepted in both request and response messages and instances with the same number may appear multiple times in each. Semantic restrictions may apply based on UrOption.is_critical().
Note
CoAP Section 5.4 specifies situations where an option must be treated as an unrecognized option even if its number matches a recognized option.
The option number associated with this option. This is a read-only attribute.
Unknown options carry their payload as uninterpreted bytes objects with a maximum length of 1034 octets.
Create an UnrecognizedOption from an existing (recognized) option.
This conversion is necessary per CoAP Section 5.4 in various instances where the recognized option is not accepted. Standard option processing then proceeds with the option left unrecognized.
The option number associated with this option. This is a read-only attribute.
The following table shows all options that are defined in base CoAP, along with the format and the maximum length of the packed value (and the minimum length if not zero).
Option Class Format Max (min) Length 1 IfMatch format_opaque 8 3 UriHost format_string 255 (1) 4 ETag format_opaque 8 (1) 5 IfNoneMatch format_empty 7 UriPort format_uint 2 8 LocationPath format_string 255 11 UriPath format_string 255 12 ContentFormat format_uint 2 14 MaxAge format_uint 4 15 UriQuery format_string 255 17 Accept format_uint 2 20 LocationQuery format_string 255 35 ProxyUri format_string 1034 (1) 39 ProxyScheme format_string 255 (1) 60 Size1 format_uint 4
Additional options are defined in protocol extensions.
Bases: coapy.option.UrOption
Option encoding the Internet host of a requested resource. See CoAP Section 5.10.1.
Bases: coapy.option.UrOption
Option encoding the transport-layer port of a requested resource. See CoAP Section 5.10.1.
Bases: coapy.option.UrOption
Option encoding (a segment of) the path of a requested resource. This option may occur multiple times. See CoAP Section 5.10.1.
Bases: coapy.option.UrOption
Option encoding (an element of) the query part of a requested resource. This option may occur multiple times. See CoAP Section 5.10.1.
Bases: coapy.option.UrOption
Option encoding the URI of a request directed through a forward-proxy. See CoAP Section 5.10.2.
If this option appears in a request, none of UriHost, UriPort, UriPath, or UriQuery may appear.
Bases: coapy.option.UrOption
Option encoding the schema for a URI of a request directed through a forward-proxy. In this case the remainder of the URI is constructed from UriHost, UriPort, UriPath, or UriQuery options. See CoAP Section 5.10.2.
Bases: coapy.option.UrOption
Option encoding the representation format of the message payload. See CoAP Section 5.10.3.
CoAP Section 12.3 deriving from Efficient XML Interchange (EXI) Format 1.0.
CoAP Section 12.3 deriving from RFC 4627.
See CoAP Section 12.3 deriving from RFC 6690.
CoAP Section 12.3 deriving from RFC 2045, RFC 2046.
CoAP Section 12.3 deriving from RFC 3023.
See CoAP Section 12.3 deriving from RFC 2046, RFC 3676, RFC 5147.
A map from integer content format values (e.g. TEXT_PLAIN) to the media type string for that format.
Bases: coapy.option.UrOption
Option encoding the representation format acceptable to a client. See CoAP Section 5.10.4.
Bases: coapy.option.UrOption
Option encoding the maximum time (in seconds) that a response may be cached before it is outdated. See CoAP Section 5.10.5.
Bases: coapy.option.UrOption
Option used for a resource-local short-hand for a given representation of a resource. See CoAP Section 5.10.6.
Bases: coapy.option.UrOption
Option encoding (a segment of) the path of a resource identified in a response. This option may occur multiple times. See CoAP Section 5.10.7.
Bases: coapy.option.UrOption
Option encoding (an element of) the query part of a resource identified in a response. This option may occur multiple times. See CoAP Section 5.10.7.
Bases: coapy.option.UrOption
Option used to make requests conditional on an ETag match. See CoAP Section 5.10.8.1.
Bases: coapy.option.UrOption
Option used to make requests conditional absence of a resource. See CoAP Section 5.10.8.2.
Bases: coapy.option.UrOption
Option providing size (in bytes) of a resource representation in a request. It may appear in an informational role in a diagnostic response. See CoAP Section 5.10.9.
When encoded option values are packed in space efficient ways depending on the format of the option value.
Abstract base for typed option value formatters.
CoAP options encode values as byte sequences in one of several formats including:
max_length is the maximum length of the packed representation in octets. min_length is the minimum length of the packed representation in octets.
‘Virtual’ method implemented by subclasses to do type-specific unpacking. The subclass implementation may assume value is of type bytes and that the length constraints on the packed representation have been checked. It must return an instance of unpacked_type.
The maximum acceptable length of the packed representation, in octets. This is a read-only property.
The minimum acceptable length of the packed representation, in octets. This is a read-only property.
‘Virtual’ method implemented by subclasses to do type-specific packing. The subclass implementation may assume value is of type unpacked_type and that the length constraints on the packed representation will be checked by to_packed().
‘Virtual’ method implemented by subclasses to represent the given value known to be in type unpacked_type. Return the text value as required by to_text().
Convert packed to its unpacked form.
If packed is not an instance of bytes then TypeError will be raised with packed as an argument.
If the length of packed is not between min_length and max_length (both inclusive) then OptionLengthError will be raised with packed as an argument.
Otherwise the value is unpacked and a corresponding instance of unpacked_type is returned.
The maximum acceptable length of the packed representation, in octets. This is a read-only property.
The minimum acceptable length of the packed representation, in octets. This is a read-only property.
Convert value to packed form.
If value is not an instance of unpacked_type then TypeError will be raised with value as an argument.
The return value is a bytes object with a length between min_length and max_length. If value results in a packed format that is not within these bounds, OptionLengthError will be raised with value as an argument.
Convert an unpacked_type value to a text (unicode) string holding a user-readable representation of the value.
This function does not validate length constraints on the value.
The Python type used for unpacked values. This is a read-only property.
Bases: coapy.option._format_base
Support options with no value.
The only acceptable value is a zero-length byte string. This is both the packed and unpacked value.
alias of str
Bases: coapy.option._format_base
Support options with opaque values.
Unpacked values are instances of bytes, and packing and unpacking is an identity operation.
alias of str
Bases: coapy.option._format_base
Supports options with variable-length unsigned integer values. max_length is the maximum number of octets in the packed format. The implicit min_length is always zero.
Unpacked values are instances of int. The packed value is big-endian in a bytes string with all zero-valued leading bytes removed. Thus the packed representation of zero is an empty string.
Per the CoAP specification packed values with leading NUL bytes will decode correctly; however, they are still subject to validation against max_length.
alias of int
Bases: coapy.option._format_base
Supports options with text values.
Unpacked values are Python Unicode (text) strings. Packed values are bytes in Net-Unicode form (RFC 5198), a canonicalized utf-8 encoding. Note that, as usual, the max_length and min_length attributes apply to the packed representation, which for non-ASCII text may be longer than the unpacked representation.
alias of unicode