acme.etc.RequestUtils

module documentation

This module contains various utilty functions that are used to work with requests and responses.

Function	`contentAsString`	Convert a content to a string. If the content is a string, it is returned as is. If the content is a byte array, it is decoded to a string. If the content is neither a string nor a byte array, it is converted to a hex string.
Function	`createPositiveResponseResult`	Create a positive `Result` object with a request.
Function	`createRawRequest`	Create a dictionary with a couple of pre-initialized fields. No validation is done.
Function	`createRequestResultFromURI`	Create a `Result` object from a URI. The URI is unquoted, parsed and the request is created.
Function	`curlFromRequest`	Create a cURL command from a request.
Function	`deserializeContent`	Deserialize a data structure. Supported media serialization types are JSON and cbor.
Function	`deserializeData`	Deserialize data into a dictionary, depending on the serialization type.
Function	`determineSerialization`	Determine the type of serialization for a notification from either the url's ct query parameter, or the given list of csz (contentSerializations, attribute of a target AE/CSE), or the CSE's default serialization.
Function	`fillRequestWithArguments`	Fill a request with arguments from a `MultiDict`. The `MultiDict` contains the arguments from a request.
Function	`filterAttributes`	Filter a dictionary by a list of attributes to include.
Function	`fromHttpURL`	Make the path a valid oneM2M ID (unescape /~/ and /_/) and return it. This is valid of CoAP URL paths as well.
Function	`removeNoneValuesFromDict`	Remove Null/None-values from a dictionary, but ignore the ones specified in allowedNull.
Function	`serializeData`	Serialize a dictionary, depending on the serialization type.
Function	`toCoAPPath`	Make the path a valid CoAP URL path (escape / and //) and return it.
Function	`toHttpUrl`	Make the url a valid http URL (escape // and ///) and return it.

def contentAsString(content: bytes | str | Any, ct: ContentSerializationType) -> str: ¶

Convert a content to a string. If the content is a string, it is returned as is. If the content is a byte array, it is decoded to a string. If the content is neither a string nor a byte array, it is converted to a hex string.

Parameters
content:`bytes \| str \| Any`	The content to convert.
ct:`ContentSerializationType`	The content serialization type.

Returns
`str`	The content as a string.

def createPositiveResponseResult() -> Result: ¶

Create a positive Result object with a request.

Returns
`Result`	A `Result` object with a positive response.

def createRawRequest(**kwargs: Any) -> JSON: ¶

Create a dictionary with a couple of pre-initialized fields. No validation is done.

Parameters
**kwargs:`Any`	individual attributes to set in the request.

Returns
`JSON`	JSON dictionary with the request.

def createRequestResultFromURI(request: CSERequest, url: str) -> tuple[Result, str, ParseResult]: ¶

Create a Result object from a URI. The URI is unquoted, parsed and the request is created.

Parameters
request:`CSERequest`	The request to create.
url:`str`	The URL to parse.

Returns
`tuple[Result, str, ParseResult]`	A tuple with the `Result` object, the URL and the parsed URL.

def curlFromRequest(request: JSON) -> str: ¶

Create a cURL command from a request.

Parameters
request:`JSON`	The request to create the cURL command from.

Returns
`str`	A cURL command.

def deserializeContent(data: bytes, contentType: ContentSerializationType) -> JSON: ¶

Deserialize a data structure. Supported media serialization types are JSON and cbor.

Parameters
data:`bytes`	The data to deserialize.
contentType:`ContentSerializationType`	The content type of the data.

Returns
`JSON`	The deserialized data structure.

Raises
`UNSUPPORTED_MEDIA_TYPE if the content type is not supported.`
`BAD_REQUEST if the data is malformed.`

def deserializeData(data: bytes, ct: ContentSerializationType) -> JSON | None: ¶

Deserialize data into a dictionary, depending on the serialization type.

Parameters
data:`bytes`	The data to deserialize.
ct:`ContentSerializationType`	The data content serialization format.

Returns
`JSON \| None`	If the data is not None, but has a length of 0 then an empty dictionary is returned. If an unknown content serialization is specified then None is returned. Otherwise, a `JSON` object is returned.

def determineSerialization(url: str, csz: list[str], defaultSerialization: ContentSerializationType) -> ContentSerializationType | None: ¶

Determine the type of serialization for a notification from either the url's ct query parameter, or the given list of csz (contentSerializations, attribute of a target AE/CSE), or the CSE's default serialization.

As a side effect this function also validates the allowed URL scheme.

Parameters
url:`str`	The URL to parse.
csz:`list[str]`	The fallback content serialization.
defaultSerialization:`ContentSerializationType`	The CSE's defaults serialization.

Returns
`ContentSerializationType \| None`	The determined content serialization, or None if none could be determined.

def fillRequestWithArguments(arguments: MultiDict, dct: JSON, cseRequest: CSERequest, sep: str | None = None) -> CSERequest: ¶

Fill a request with arguments from a MultiDict. The MultiDict contains the arguments from a request.

Parameters
arguments:`MultiDict`	The `MultiDict` with the arguments.
dct:`JSON`	The dictionary to fill.
cseRequest:`CSERequest`	The `CSERequest` object to fill.
sep:`str \| None`	The separator for the attribute list.

Returns
`CSERequest`	The filled `CSERequest` object.

def filterAttributes(dct: JSON, attributesToInclude: list[str]) -> JSON: ¶

Filter a dictionary by a list of attributes to include.

Return:

Parameters
dct:`JSON`	Dictionary to filter.
attributesToInclude:`list[str]`	List of attributes to include.

Returns
`JSON`	Undocumented

def fromHttpURL(path: str) -> str: ¶

Make the path a valid oneM2M ID (unescape /~/ and /_/) and return it. This is valid of CoAP URL paths as well.

Parameters
path:`str`	The path to convert.

Returns
`str`	A valid ID with unescaped special characters.

def removeNoneValuesFromDict(jsn: JSON, allowedNull: list[str] | None = []) -> JSON: ¶

Remove Null/None-values from a dictionary, but ignore the ones specified in allowedNull.

Parameters
jsn:`JSON`	JSON dictionary.
allowedNull:`list[str] \| None`	Optional list of attribute names to ignore.

Returns
`JSON`	Return a new dictionary with None-value attributes removed.

def serializeData(data: JSON, ct: ContentSerializationType) -> str | bytes | JSON | None: ¶

Serialize a dictionary, depending on the serialization type.

Parameters
data:`JSON`	The data to serialize.
ct:`ContentSerializationType`	The data content serialization format.

Returns
`str \| bytes \| JSON \| None`	A data str or byte object with the serialized data, or None.

def toCoAPPath(path: str) -> str: ¶

Make the path a valid CoAP URL path (escape / and //) and return it.

Parameters
path:`str`	The path to convert.

Returns
`str`	A valid CoAP URL path with escaped special characters for oneM2M IDs

def toHttpUrl(url: str) -> str: ¶

Make the url a valid http URL (escape // and ///) and return it.

Parameters
url:`str`	The URL to convert.

Returns
`str`	A valid URL with escaped special characters.