Options

Supported Header Options

Name	Default
Content-type	text/plain
Max-age	60 seconds
Uri-Scheme	coap
Etag
Uri-Authority
Location
Uri-Path
Block EXPERIMENTAL

Classes and functions related to CoAP header options.

class coapy.options.Block(block_number=0, more=False, size_exponent=7)

Bases: coapy.options._Base

Support block-wise transfers of large resources.

Warning:

This is an experimental option. See draft-bormann-core-misc

Parameters:

• block_number – The number of the block
• more – A bool used in response messages to indicate the resource has additional blocks with higher block numbers.
• size_exponent – The base-2 exponent for the block size. The minimum exponent supported is 4 (a 16-octet block); the maximum is 11 (a 2048-octet block).

MAX_SIZE_EXPONENT

The maximum supported size for resource blocks is 2^11 or 2048 octets.

MIN_SIZE_EXPONENT

The minimum supported size for resource blocks is 2^4 or 16 octets.

block_number

The block number, starting at zero for the first block.

more

True iff there are subsequent blocks in the resource.

size_exponent

The base-2 exponent defining the size of each (non-final) block.

See MIN_SIZE_EXPONENT and MAX_SIZE_EXPONENT.

class coapy.options.ContentType(value=None)

Bases: coapy.options._Base

The Internet media type describing the message body.

Default

The default content type is text/plain.

packed

value_as_string

Access the value using its IANA-assigned media type encoding scheme, e.g. application/xml.

Note:Only media types that have been assigned CoAP integral values are allowed.

class coapy.options.Etag(value=None)

Bases: coapy.options._StringValue_mixin, coapy.options._Base

An opaque sequence of bytes specifying the version of resource representation.

MAX_VALUE_LENGTH

An ETag value cannot exceed four octets in length.

MIN_VALUE_LENGTH

An ETag value must have at least one octet.

class coapy.options.Location(value=None)

Bases: coapy.options._UriPath_mixin, coapy.options._Base

The location of a resource.

Normally used in in a response to indicate the location of a newly created resource.

class coapy.options.MaxAge(value=None)

Bases: coapy.options._IntegerValue_mixin, coapy.options._Base

The maximum age of a resource for use in cache control, in seconds.

coapy.options.Registry

A map from integral option types to the Python class that implements the option.

class coapy.options.UriAuthority(value=None)

Bases: coapy.options._StringValue_mixin, coapy.options._Base

The authority (host+port) part of the URI.

Default

By default, the URI authority is empty.

class coapy.options.UriPath(value=None)

Bases: coapy.options._UriPath_mixin, coapy.options._Base

The absolute path part of the URI.

Since all CoAP URI paths are absolute, the leading slash is elided from the option value.

Default

By default, the URI path is /, represented as an empty string.

class coapy.options.UriScheme(value=None)

Bases: coapy.options._StringValue_mixin, coapy.options._Base

The schema part of the URI.

Default

The default URI scheme is coap.

coapy.options.decode(num_options, payload)

Decode a set of CoAP options and extract a message body.

The specified number of options are pulled from the initial octets of the payload, and converted into instances of the corresponding option class. The return value is a pair (options, body) where options is a list of all recognized options in their order of appearance and body is the remainder of the payload after options have been stripped.

Parameters:

• num_options – The number of options to be extracted.
• payload – The packed options followed by an optional message body.

Returns:

(options, body)

Return type:

(list, str)

Raises:

Exception if an unrecognized critical option is encountered

coapy.options.encode(options, ignore_if_default=True)

Encode a set of CoAP options for transmission.

The options are sorted as required by CoAP. The return value is a pair (num_options, packed) where num_options is the number of options that were encoded, and packed is the octet sequence encoding those options.

Parameters:

• options – An iterable of option instances
• ignore_if_default – If True, any option instance that has the default value for the option is excluded from the packed representation.

Returns:

(num_options, packed_options)

Return type:

(int, str)

Raises:

Exception if a packed option exceeds the representable option length

coapy.options.length_of_vlint(value)

Parameter:value – Any non-negative integral value Returns:Determine the number of octets required to express value as by pack_vlint(). Return type:int

coapy.options.option_type_is_elective(type_val)

Parameter:type_val – the integral type value for an option Returns:True iff an option of Type type_val is elective (can be skipped if unrecognized).

coapy.options.pack_vlint(value)

Pack an integer into a string.

CoAP variable-length integers are packed into a sequence of octets in network byte order. Leading octets that would have a zero value are elided.

Parameter:value – Any non-negative integral value Return type:str

coapy.options.unpack_vlint(packed)

Extract an integer from a string as created by pack_vlint().

Parameter:packed – A string of octets containing a packed integer. Return type:int

Option Internals

Base Class for Options

class coapy.options._Base(value=None)

Base class for all CoAPy option classes.

Default

The default value of the option. None if the option has no default.

Note:This value is overridden in each class that implements a CoAP option with a default value.

Name

The standardized name of the option.

Note:This value is overridden in each class that implements a CoAP option.

Type

The type code for the option.

Options with an even type code are elective, while those with an odd type code are critical.

Note:This value is overridden in each class that implements a CoAP option.

classmethod is_critical()

Return True if this option must be understood.

is_default()

Return True iff the current value of the option is equal to the default value of the option.

This is used by encode to avoid unnececessarily packing options.

length

The length, in octets, of the packed option.

Note:This is a read-only property.

packed

The sequence of octets representing the option value in packed form (i.e., as it appears within an option header).

The sequence does not include the option delta or length, only the value.

Note:This is a read-only property. See:unpack

classmethod unpack(packed)

Create an instance of this option from a packed representation.

Parameter:packed – A sequence of octets representing the option value, exclusive of the option type and length. Return type:An instance of the leaf class. See:packed

value

The option value.

Python objects and type instances assigned as option values are validated within the limitations of the CoAP option’s packed representation. For example, assigning to an instance of UriPath a value that exceeds the length limitation of 270 will result in a ValueError.

In cases where the option value is expected to have an IANA-assigned significance but the specific assigned value is unrecognized, the value assignment is permitted if doing so does not violate the requirements of the packed option representation. For example, assigning a value of 15 to an instance of ContentType would be allowed, though the value 15 is not (currently) associated with a specific media type.

Mix-in Classes

The following classes are mixed-in to CoAP option classes to provide common support for representing and validating the option values.

class coapy.options._StringValue_mixin

Mix-in to support options with octet-sequence values.

MAX_VALUE_LENGTH

The maximum length, in octets, for the option value.

MIN_VALUE_LENGTH

The minimum length, in octets, for the option value.

value

Overrides the base value property. The assigned value must be a string within the limits of MIN_VALUE_LENGTH and MAX_VALUE_LENGTH for the option class.

class coapy.options._UriPath_mixin

Mix-in to support options with string values that represent URIs.

value

Overrides the string value property. In addition to length limitations, the assigned value must not start with a forward-slash.

class coapy.options._IntegerValue_mixin

Mix-in to support options with integral values.

MAX_VALUE

The maximum allowable value for the option.

MIN_VALUE

The minimum allowable value for the option.

value

Overrides the base value property. The assigned value must be an integral value within the limits of MIN_VALUE and MAX_VALUE for the option class.