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 aValueError
.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:
- 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:
- 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:
lhs (
NonStrictName
) – prefix to be tested.rhs (
NonStrictName
) – full name to test on.
- Return type:
bool
- Returns:
True
iflhs
is a prefix ofrhs
.
- 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:
- 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'