Name and Component

ndn.encoding.name.Component module

Component module is a collection of functions processing NDN NameComponents. In python-ndn, a NameComponent is always encoded in TLV form, of type bytes, bytearray or memoryview.

The types of NameComonent follows Name Component Assignment policy. Type constants are following

Type

Description

TYPE_INVALID

Invalid name component type

TYPE_GENERIC

Implicit SHA-256 digest component

TYPE_IMPLICIT_SHA256

SHA-256 digest of Interest Parameters

TYPE_PARAMETERS_SHA256

Generic name component

TYPE_KEYWORD

Well-known keyword

TYPE_SEGMENT

Segment number

TYPE_BYTE_OFFSET

Byte offset

TYPE_VERSION

Version number

TYPE_TIMESTAMP

Unix timestamp in microseconds

TYPE_SEQUENCE_NUM

Sequence number

ndn.encoding.name.Component.CHARSET = {'%', '-', '.', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '=', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '_', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '~'}

The character set for NameComponent, which is unreserved characters + {‘=’, ‘%’}

ndn.encoding.name.Component.escape_str(val)

Escape a string to a legal URI string. Any characters not in the CHARSET will be converted into percent-hexadecimal encoding. '%' itself will not be escaped. For hex digits, lowercase is used.

Parameters:

val (str) – the string to escape.

Return type:

str

Returns:

the URI string.

Examples:
>>> from ndn.encoding.name import Component
>>> Component.escape_str('Kraus Bölter')
'Kraus%20B%C3%B6lter'
>>> Component.escape_str('all:%0a\tgcc -o a.out')
'all%3A%0a%09gcc%20-o%20a.out'
ndn.encoding.name.Component.from_byte_offset(offset)

Construct a Component from a byte offset.

Parameters:

offset (int) – the byte offset.

Return type:

bytearray

Returns:

the component.

ndn.encoding.name.Component.from_bytes(val, typ=8)

Construct a Component from bytes by adding a type and length.

Parameters:
  • val (Union[bytes, bytearray, memoryview]) – the value of the component.

  • typ (int) – the type of the component. TYPE_GENERIC by default.

Return type:

bytearray

Returns:

the component.

ndn.encoding.name.Component.from_hex(val, typ=8)

Construct a Component from hex string.

Parameters:
  • val (str) – a hexadecimal string.

  • typ (int) – the type of the component. TYPE_GENERIC by default.

Return type:

bytearray

Returns:

the component.

ndn.encoding.name.Component.from_number(val, typ)

Construct a Component from an integer.

Parameters:
  • val (int) – the integer.

  • typ (int) – the type of the component.

Return type:

bytearray

Returns:

the component.

ndn.encoding.name.Component.from_segment(segment)

Construct a Component from an segment number.

Parameters:

segment (int) – the segment number.

Return type:

bytearray

Returns:

the component.

ndn.encoding.name.Component.from_sequence_num(seq_num)

Construct a Component from a sequence number.

Parameters:

seq_num (int) – the sequence number.

Return type:

bytearray

Returns:

the component.

ndn.encoding.name.Component.from_str(val)

Construct a Component from URI string.

Parameters:

val (str) –

URI string. All characters should be from CHARSET, otherwise it would raise a ValueError.

Note

Additional periods are not allowed here. To create a zero-size Component, just pass an empty string '' in.

Return type:

bytearray

Returns:

the component.

Raises:

ValueError – the string is not a legal URI.

ndn.encoding.name.Component.from_timestamp(timestamp)

Construct a Component from a timestamp number.

Parameters:

timestamp (int) – the timestamp

Return type:

bytearray

Returns:

the component.

Examples:
>>> from ndn.encoding.name import Component
>>> from ndn.utils import timestamp
>>> Component.to_str(Component.from_timestamp(timestamp()))
'36=%00%00%01nH.%A7%90'
ndn.encoding.name.Component.from_version(version)

Construct a Component from a version number.

Parameters:

version (int) – the version number.

Return type:

bytearray

Returns:

the component.

ndn.encoding.name.Component.get_type(component)

Get the type from a Component.

Parameters:

component (Union[bytes, bytearray, memoryview]) – the component.

Return type:

int

Returns:

the type.

ndn.encoding.name.Component.get_value(component)

Get the value from a Component, in the form of memoryview.

Parameters:

component (Union[bytes, bytearray, memoryview]) – the component.

Return type:

memoryview

Returns:

the value.

ndn.encoding.name.Component.to_canonical_uri(component)

Convert a Component into a canonical URI string without naming conventions. Returns an empty string '' for a 0-size Component.

Parameters:

component (Union[bytes, bytearray, memoryview]) – the component.

Return type:

str

Returns:

a canonical URI string.

ndn.encoding.name.Component.to_number(component)

Take the number encoded in the component out.

Parameters:

component (Union[bytes, bytearray, memoryview]) – the component.

Return type:

int

Returns:

an integer, which is the value of the component.

ndn.encoding.name.Component.to_str(component)

Convert a Component into a URI string. Returns an empty string '' for a 0-size Component.

Parameters:

component (Union[bytes, bytearray, memoryview]) – the component.

Return type:

str

Returns:

a URI string.

ndn.encoding.name.Name module

Name module is a collection of functions processing NDN Names.

ndn.encoding.name.Name.TYPE_NAME = 7

The TLV type of NDN Name.

ndn.encoding.name.Name.from_bytes(buf)

Decode the Name from its TLV encoded form.

Parameters:

buf (Union[bytes, bytearray, memoryview]) – encoded Name.

Returns:

Decoded Name.

Return type:

FormalName

Raises:

ValueError – if the Type is not TYPE_NAME .

ndn.encoding.name.Name.from_str(val)

Construct a Name from a URI string.

Parameters:

val (str) –

URI string. Character out of ndn.encoding.name.Component.CHARSET will be escaped automatically. Leading and tailing '/' will be removed.

Note

Additional periods are not allowed here. To create a zero-size Component, use two slashes to surround it. Also, there should be no scheme identifier and authority component in the URI.

Return type:

List[bytearray]

Returns:

FormalName.

Examples:
>>> from ndn.encoding.name import Name
>>> Name.from_str("example/name")
[bytearray(b'\x08\x07example'), bytearray(b'\x08\x04name')]
>>> Name.from_str("/a//32=b/")
[bytearray(b'\x08\x01a'), bytearray(b'\x08\x00'), bytearray(b'\x20\x01b')]
>>> Name.from_str('/a/../b')
[bytearray(b'\x08\x01a'), bytearray(b'\x08\x02..'), bytearray(b'\x08\x01b')]
ndn.encoding.name.Name.is_prefix(lhs, rhs)

Test if a Name is a prefix of another Name.

Parameters:
Return type:

bool

Returns:

True if lhs is a prefix of rhs.

ndn.encoding.name.Name.normalize(name)

Convert a NonStrictName to a FormalName. If name is a binary string, decode it. If name is a str, encode it into FormalName. If name is a list, encode all str elements into Components.

Parameters:

name (NonStrictName) – the NonStrictName.

Returns:

the FormalName. It may be a swallow copy of name.

Return type:

FormalName

Raises:

TypeError – if the name or one of its element has a unrecognized type.

Examples:
>>> from ndn.encoding.name import Name
>>> Name.normalize(f'{i}' for i in range(3))
[bytearray(b'\x08\x010'), bytearray(b'\x08\x011'), bytearray(b'\x08\x012')]
>>> Name.normalize(['Алек', b'%\x01\x00'])
[bytearray(b'\x08\x08\xd0\x90\xd0\xbb\xd0\xb5\xd0\xba'), b'%\x01\x00']
ndn.encoding.name.Name.to_bytes(name)

Encode a Name via TLV encoding.

Parameters:

name (NonStrictName) – Name to encode.

Return type:

bytes

Returns:

Encoded Name.

ndn.encoding.name.Name.to_canonical_uri(name)

Convert an NDN Name to a canonical URI string without naming conventions.

Parameters:

name (NonStrictName) – the input NDN Name.

Return type:

str

Returns:

the canonical URI.

Examples:
>>> from ndn.encoding.name import Name
>>> Name.to_canonical_uri('Σπυρίδων')
'/%CE%A3%CF%80%CF%85%CF%81%CE%AF%CE%B4%CF%89%CE%BD'
ndn.encoding.name.Name.to_str(name)

Convert an NDN Name to a URI string.

Parameters:

name (NonStrictName) – the input NDN Name.

Return type:

str

Returns:

the URI.

Examples:
>>> from ndn.encoding.name import Name
>>> Name.to_str('Σπυρίδων')
'/%CE%A3%CF%80%CF%85%CF%81%CE%AF%CE%B4%CF%89%CE%BD'