acme.etc.IDUtils

module documentation

This module contains various utilty functions to handle, test and manipulate IDs.

There are no ACME CSE internal dependencies. This heelps to keep the module small and standalone.

Function	`csiFromRelativeAbsoluteUnstructured`	Get the csi from an unstructured CSE-relative, SP-relative, or absolute ID.
Function	`csiFromSPRelative`	Return the csi from a SP-relative resource ID. It is assumed that the passed ri is in SP-relative format.
Function	`getIdFromOriginator`	Get AE-ID-Stem or CSE-ID from the originator (in case SP-relative or Absolute was used).
Function	`getSPFromID`	Get the SP-ID from an Absolute resource ID. If the ID is not in absolute format, None is returned.
Function	`hasOnlyUnreserved`	Test that an ID only contains characters from the unreserved character set of RFC 3986.
Function	`isAbsolute`	Test whether a URI is in absolute format.
Function	`isCSERelative`	Test whether a URI is in CSE-relative format.
Function	`isCSI`	Test whether a URI is a CSE-ID.
Function	`isSPRelative`	Test whether a URI is SP-Relative.
Function	`isStructured`	Test whether a URI is in structured format.
Function	`isValidAEI`	Test for valid AE-ID format.
Function	`isValidCSI`	Test for valid CSE-ID format.
Function	`isValidID`	Test for a valid ID.
Function	`isValidPath`	Test for a valid path. A path is a string that does not start with a slash and does not contain spaces and invalid characters. It may contain slashes, but not at the beginning.
Function	`isValidSPID`	Test for valid SP-ID format.
Function	`localResourceID`	Test whether an ID is a resource ID of the local CSE.
Function	`noNamespace`	Remove the namespace part of an identifier and return the remainder.
Function	`originatorToID`	Convert an originator to a resource ID. The originator is expected to be in CSE-relative, SP-relative or absolute format.
Function	`toAbsolute`	Convert an ID to absolute format.
Function	`toCSERelative`	Convert an id to CSE-Relative format.
Function	`toSPRelative`	Add the CSI to an originator (if not already present).
Function	`uniqueAEI`	Create a new AE ID. An AE ID must always start with either "S" or "C".
Function	`uniqueID`	Generate a unique ID. This is for the moment just a large random number. NO check for uniqueness is done.
Function	`uniqueRI`	Generate a unique resource ID. Beside a random number it can have a prefix.
Function	`uniqueRN`	Generate a unique resource name. A resource name has a prefix and a random alpha-numeric string.
Function	`_randomID`	Generate an ID. Prevent certain patterns in the ID.
Variable	`_aeRx`	Regular expression to test for valid AE-ID format.
Variable	`_csiRx`	Regular expression to test for valid CSE-ID format (unreserved characters in IDs according to RFC 3986).
Variable	`_randomIDCharSet`	Character set for random IDs.
Variable	`_spidRx`	Regular expression to test for valid SP-ID format (unreserved characters in IDs according to RFC 3986).
Variable	`_unreserved`	Regular expression to test for unreserved characters.

def csiFromRelativeAbsoluteUnstructured(id: str) -> tuple[str, list[str]]: ¶

Get the csi from an unstructured CSE-relative, SP-relative, or absolute ID.

Parameters
id:`str`	unstructured ID.

Returns
`tuple[str, list[str]]`	Tuple (CSE ID (no leading slashes) without any SP-ID or CSE-ID, list of path elements). If the ID is None or empty, the return value is ('', []).

def csiFromSPRelative(ri: str) -> str | None: ¶

Return the csi from a SP-relative resource ID. It is assumed that the passed ri is in SP-relative format.

Parameters
ri:`str`	A SP-relative resource ID

Returns
`str \| None`	The csi of the resource ID, or None

def getIdFromOriginator(originator: str, idOnly: bool | None = False) -> str: ¶

Get AE-ID-Stem or CSE-ID from the originator (in case SP-relative or Absolute was used).

Parameters
originator:`str`	An originator.
idOnly:`bool \| None`	Indicator that only the CSE-local resource ID is provided.

Returns
`str`	Resource ID.

def getSPFromID(id: str) -> str: ¶

Get the SP-ID from an Absolute resource ID. If the ID is not in absolute format, None is returned.

Parameters
id:`str`	An Absolute resource ID.

Returns
`str`	The SP-ID of the resource ID without leading slashes, or None if the ID is not in absolute format.

def hasOnlyUnreserved(id: str) -> bool: ¶

Test that an ID only contains characters from the unreserved character set of RFC 3986.

Parameters
id:`str`	the ID to check.

Returns
`bool`	Boolean

def isAbsolute(uri: str) -> bool: ¶

Test whether a URI is in absolute format.

Parameters
uri:`str`	The URI to check

Returns
`bool`	Boolean if the URI is in absolute format

def isCSERelative(uri: str) -> bool: ¶

Test whether a URI is in CSE-relative format.

Parameters
uri:`str`	The URI to check

Returns
`bool`	Boolean if the URI is in CSE-relative format

def isCSI(uri: str) -> bool: ¶

Test whether a URI is a CSE-ID.

Parameters
uri:`str`	The URI to check

Returns
`bool`	Boolean if the URI is a CSE-ID

def isSPRelative(uri: str) -> bool: ¶

Test whether a URI is SP-Relative.

Parameters
uri:`str`	The URI to check

Returns
`bool`	Boolean

def isStructured(uri: str) -> bool: ¶

Test whether a URI is in structured format.

Parameters
uri:`str`	The URI to check

Returns
`bool`	Boolean if the URI is in structured format

def isValidAEI(aei: str) -> bool: ¶

Test for valid AE-ID format.

It takes SP-Relative AEI's into account.

Parameters
aei:`str`	The AE-ID to check

Returns
`bool`	Boolean

def isValidCSI(csi: str) -> bool: ¶

Test for valid CSE-ID format.

Parameters
csi:`str`	The CSE-ID to check

Returns
`bool`	Boolean

def isValidID(id: str, allowEmpty: bool | None = False) -> bool: ¶

Test for a valid ID.

Parameters
id:`str`	The ID to check
allowEmpty:`bool \| None`	Indicate whether an ID can be empty.

Returns
`bool`	Boolean

def isValidPath(id: str) -> bool: ¶

Test for a valid path. A path is a string that does not start with a slash and does not contain spaces and invalid characters. It may contain slashes, but not at the beginning.

Parameters
id:`str`	The ID to check

Returns
`bool`	Boolean

def isValidSPID(spid: str) -> bool: ¶

Test for valid SP-ID format.

Parameters
spid:`str`	The SP-ID to check

Returns
`bool`	Boolean

def localResourceID(ri: str) -> str | None: ¶

Test whether an ID is a resource ID of the local CSE.

Parameters
ri:`str`	A resource ID in CSE-relative, SP-relative, or absolute notation.

Returns
`str \| None`	If the ID targets a local resource then the CSE-relative form of the resource ID is returned, or None otherwise.

def noNamespace(id: str) -> str: ¶

Remove the namespace part of an identifier and return the remainder.

Example

'm2m:cnt' -> 'cnt'

Parameters
id:`str`	String with the identifier. May be prefixed with a domain.

Returns
`str`	String that only contains the ID

def originatorToID(originator: str) -> str: ¶

Convert an originator to a resource ID. The originator is expected to be in CSE-relative, SP-relative or absolute format.

Parameters
originator:`str`	An originator in CSE-relative, SP-relative or absolute format.

Returns
`str`	A resource ID in CSE-relative format.

def toAbsolute(id: str, spId: str | None = None) -> str: ¶

Convert an ID to absolute format.

Parameters
id:`str`	An ID in CSE-Relative or SP-Relative format.
spId:`str \| None`	Optional SP-ID. If not provided, the CSE-ID is used.

Returns
`str`	An ID in absolute format.

def toCSERelative(id: str) -> str: ¶

Convert an id to CSE-Relative format.

Parameters
id:`str`	An ID in SP-relative or absolute format.

Returns
`str`	An ID in CSE-Relative format.

def toSPRelative(id: str) -> str: ¶

Add the CSI to an originator (if not already present).

Parameters
id:`str`	A string with the originator or resource ID to convert.

Returns
`str`	A string in the format /<csi>/<id>.

def uniqueAEI(prefix: str | None = 'S') -> str: ¶

Create a new AE ID. An AE ID must always start with either "S" or "C".

Parameters
prefix:`str \| None`	"S" or "C"

Returns
`str`	String with the AE ID

def uniqueID() -> str: ¶

Generate a unique ID. This is for the moment just a large random number. NO check for uniqueness is done.

Returns
`str`	String with the identifier

def uniqueRI(prefix: str | None = '') -> str: ¶

Generate a unique resource ID. Beside a random number it can have a prefix.

Parameters
prefix:`str \| None`	Prefix for the ID

Returns
`str`	String with the new ID

def uniqueRN(prefix: str) -> str: ¶

Generate a unique resource name. A resource name has a prefix and a random alpha-numeric string.

Parameters
prefix:`str`	String prefix. If it contains a domain then that is removed

Returns
`str`	String with the resource name

def _randomID() -> str: ¶

Generate an ID. Prevent certain patterns in the ID.

Returns
`str`	String with a random ID

_aeRx = ¶

Regular expression to test for valid AE-ID format.

_csiRx = ¶

Regular expression to test for valid CSE-ID format (unreserved characters in IDs according to RFC 3986).

_randomIDCharSet = ¶

Character set for random IDs.

_spidRx = ¶

Regular expression to test for valid SP-ID format (unreserved characters in IDs according to RFC 3986).

_unreserved = ¶

Regular expression to test for unreserved characters.