Index

API reference for diameter.message.avp.

AVP and AVP type definitions.

AvpEnumerated `module-attribute` ¶

AvpEnumerated = AvpInteger32

An AVP type that implements the "Enumerated". type.

As enumeration is a list of valid integer values, is an alias for AvpInteger32

Avp ¶

Avp(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

A generic AVP type.

Represents a single Diameter AVP with (practically) any content. Normally this class should not be instantiated manually at all. If an AVP is to be constructed by hand, it should be done using one of the subclasses, e.g. AvpInteger64, AvpTime etc, as those perform value type conversion, packing and unpacking automatically.

In most cases, an AVP should be constructed using the Avp.new factory, that produces a correct AVP type and pre-populates it if necessary, using the AVP_* and VENDOR_* constant values:

>>> session_id = Avp.new(constants.AVP_SESSION_ID)
>>> session_id.value = "dra.gy.mvno.net;221424325;287370797;65574b0c-2d02"
>>> pdp_address = Avp.new(constants.AVP_TGPP_PDP_ADDRESS, constants.VENDOR_TGPP)
>>> pdp_address.value = "10.40.93.32"
>>> # this has been set automatically
>>> pdp_address.is_mandatory
True

AVPs can also be created directly from received network bytes, or from an Unpacker instance that has its position set to the start of an AVP:

>>> avp_bytes = bytes.fromhex("000001cd40000016333232353140336770702e6f72670000")
>>> service_context_id = Avp.from_bytes(avp_bytes)
>>> str(service_context_id)
Service-Context-Id <Code: 0x1cd, Flags: 0x40 (-M-), Length: 22, Val: 32251@3gpp.org>

See Avp.from_bytes and Avp.from_unpacker for more details.

AVPs have a human-readable str output:

>>> input_packets = Avp.new(constants.AVP_ACCT_INPUT_PACKETS, value=17347878)
>>> str(input_packets)
Acct-Input-Packets <Code: 0x2f, Flags: 0x00 (---), Length: 12, Val: 17347878>

Parameters:

Name	Type	Description	Default
`code`	`int`	An AVP code, does not need to be a known code	`0`
`vendor_id`	`int`	A vendor ID, or zero if no vendor is set	`0`
`payload`	`bytes`	An optional AVP payload to initialise the AVP with. Must be a properly encoded value that matches the type of AVP.	`b''`
`flags`	`int`	An optional integer value for the AVP flags	`0`

code `instance-attribute` ¶

code: int = code

AVP code. Corresponds to AVP_* constant values.

flags `instance-attribute` ¶

flags: int = flags

AVP flags. These should not be set manually, refer to is_mandatory, is_private and vendor_id. The flags are updated automatically as these properties are changed.

is_mandatory `property` `writable` ¶

is_mandatory: bool

Indicates if the mandatory (M) flag is set, or sets it.

is_private `property` `writable` ¶

is_private: bool

Indicates if the private (P) flag is set, or sets it.

is_vendor `property` ¶

is_vendor: bool

Indicates if the AVP is vendor-specific (has non-zero vendor_id).

length `property` ¶

length

The entire length of the AVP, including header and vendor bit.

name `instance-attribute` ¶

name: str = 'Unknown'

The name of the AVP, e.g. "Session-Id". Not unique in any way.

payload `instance-attribute` ¶

payload: bytes = payload

The actual AVP payload as encoded bytes. This should not be set directly; the value property should be changed instead, which will automatically encode the payload correctly based on the type of the AVP.

value `property` `writable` ¶

value: Any

The actual AVP value. When altered, the AVP instance encodes and decodes the property accordingly, and alters its payload property.

vendor_id `property` `writable` ¶

vendor_id: int

The current vendor ID. When modified, the AVP flags are also automatically updated with the vendor set bit.

as_bytes ¶

as_bytes() -> bytes

Retrieve a byte-encoded AVP, including its header.

as_packed ¶

as_packed(packer: Packer) -> Packer

Append AVP byte-encoded contents, into a Packer instance.

Parameters:

Name	Type	Description	Default
`packer`	`Packer`	A packer instance, where the AVP contents are appended to, including its header	required

Returns:

Type	Description
`Packer`	The modified packer instance.

from_avp `classmethod` ¶

from_avp(another_avp: _AnyAvpType) -> _AnyAvpType

Create a copy based on another AVP.

Encodes the given AVP into bytes, then constructs a new AVP instance using Avp.from_bytes.

Parameters:

Name	Type	Description	Default
`another_avp`	`_AnyAvpType`	The AVP to copy.	required

Returns:

Type	Description
`_AnyAvpType`	A new AVP instance with data identical to the copy.

from_bytes `classmethod` ¶

from_bytes(avp_data: bytes) -> _AnyAvpType

Create new AVP from network received bytes.

Accepts byte strings and returns a python representation of the contents.

>>> avp_bytes = bytes.fromhex("000001cd40000016333232353140336770702e6f72670000")
>>> a = avp.Avp.from_bytes(avp_bytes)
>>>
>>> assert a.code == 461
>>> assert a.is_mandatory is True
>>> assert a.is_private is False
>>> assert a.is_vendor is False
>>> assert a.length == 22
>>> assert a.value == "32251@3gpp.org"

Parameters:

Name	Type	Description	Default
`avp_data`	`bytes`	Any network-received bytes that starts at an AVP boundary. May contain more than one AVP; the byte string is consumed until one full AVP has been decoded and the rest is discarded.	required

from_unpacker `classmethod` ¶

from_unpacker(unpacker: Unpacker) -> _AnyAvpType

Create a new AVP from an Unpacker instance.

Parameters:

Name	Type	Description	Default
`unpacker`	`Unpacker`	An instance of Unpacker that has its buffer set to a position where an AVP begins.	required

Returns:

Type	Description
`_AnyAvpType`	A new AVP. The position of the unpacker is set at the end of the AVP byte stream.

new `classmethod` ¶

new(
    avp_code: int,
    vendor_id: int = 0,
    value: str | int | float | bytes | list | datetime = None,
    is_mandatory: bool = None,
    is_private: bool = None,
) -> _AnyAvpType

Generates a new AVP.

The preferred way to build a new AVP. Returns an AVP that has a type that matches the AVP code, e.g. AVP_ACCT_INPUT_PACKETS would return an "Acct-Input_packets" AVP, as an instance of AvpInteger32.

Parameters:

Name	Type	Description	Default
`avp_code`	`int`	An AVP code or one of the `AVP_*` constants	required
`vendor_id`	`int`	A known vendor ID, must be set if a vendor-specific AVP is to be built	`0`
`value`	`str \| int \| float \| bytes \| list \| datetime`	An optional AVP value. If not given, will also not set any value, which may be an invalid operation for the AVP. A value can be set later by assigning a value to the `value` attribute. If given, the value must be valid for the type of AVP being created. E.g. an "Integer32" AVP must have a 32-bit integer as its value, a "Grouped" AVP must have a list of AVPs as its value, etc.	`None`
`is_mandatory`	`bool`	Optionally sets or unsets the mandatory flag manually. If not given, detaults to setting the flag based on whatever was defined in the dictionary originally	`None`
`is_private`	`bool`	Optionally sets or unsets the private flag. Default is to leave the flag untouched	`None`

AvpAddress ¶

AvpAddress(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements "Address".

According to rfc677, an Address format is derived from the OctetString format and represents usually an IPv4 or an IPv6 address, or an E.164 subscriber ID. The format contains both the value and the address family defined by IANAADFAM.

value `property` `writable` ¶

value: tuple[int, str]

The address family and its value. When reading, always returns a tuple containing the address family and a string representation of the actual address. Currently implemented address families are:

1: IP version 4
2: IP version 6
8: E.164

When setting a new value, only the actual string value should be set, the address family is determined automatically. E.g.:

>>> addr = AvpAddress()
>>> addr.value = "10.0.0.1"
>>> addr.value
(1, '10.0.0.1')
>>> addr.value = "41780009999"
>>> addr.value
(8, '41780009999')

If the value to be set cannot be parsed as a valid IPv4 or an IPv6 address, the address family is automatically set to E.164.

AvpFloat32 ¶

AvpFloat32(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements "Float32".

value `property` `writable` ¶

value: float

AVP value as a python float. When setting the value, it must be a 32-bit integer. Larger intergers will raise an AvpEncodeError.

AvpFloat64 ¶

AvpFloat64(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements "Float64".

value `property` `writable` ¶

value: float

AVP value as a python float. When setting the value, it must be a 64-bit integer. Larger numbers will raise an AvpEncodeError.

AvpGrouped ¶

AvpGrouped(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements "Grouped".

The "Grouped" AVP contains a sequence of AVPs. The actual AVP payload consists of a concatenated byte stream of individual AVPs, containing also their headers. The python value is represented as a list of Avp instances.

value `property` `writable` ¶

value: list[_AnyAvpType]

Set or read the list of grouped AVPs. The actual AVPs contained within are not decoded until the value is read for the first time. Once read, the value is cached internally and will not change, unless the entire AVP list is overwritten.

When setting a value, it must be set to an entire list of AVPs:

>>> grp = AvpGrouped()
>>> grp.value = [AvpOctetString(), AvpOctetString()]

Alternatively, the value can be operated as a regular list:

>>> grp = AvpGrouped()
>>> grp.value.append(AvpOctetString())

AvpInteger32 ¶

AvpInteger32(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements the "Integer32" type.

The "Integer32" type has a 32-bit signed value.

value `property` `writable` ¶

value: int

Sets or retrieves the AVP value as a python integer. When setting the value, it must be a 32-bit integer. Larger integers will raise an AvpEncodeError.

AvpInteger64 ¶

AvpInteger64(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements the "Integer64" type.

The "Integer64" type has a 64-bit signed value.

value `property` `writable` ¶

value: int

Sets or retrieves the AVP value as a python integer. When setting the value, it must be a 64-bit integer. Larger integers will raise an AvpEncodeError.

AvpOctetString ¶

AvpOctetString(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements the "OctetString" type.

The "OctetString" type contains arbitrary data of variable length.

value `property` `writable` ¶

value: bytes

Sets or retrieves the AVP value, as python bytes. When setting the value, it must be bytes. Any other type will raise an AvpEncodeError.

AvpTime ¶

AvpTime(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements the "Time" type.

According to rfc677, a Time format is derived from the OctetString basic AVP format. It contains four octets, in the same format as the first four bytes are in the NTP timestamp format, as defined in rfc5905.

The octets represent either the number of seconds since 0h on 1 January 1900 UTC, or since 6h 28m 16s on 7 February 2036 UTC. The NTP timestamp format would normally overflow in 2036, however rfc2030 extends its usage until 2104, by defining a specific date in 1968 as a cutoff point. Time values before the cutoff date in 1968 are considered to be dates after 2036, while time values after the cutoff are dates between 1968 and 2036.

As a result, the AvpTime type cannot represent dates before 20 January 1968 at all.

value `property` `writable` ¶

value: datetime

Sets or retrieves the AVP value, as an instance of python datetime. When setting the value, it must be an instance of datetime. Any other data type, or if the datetime instance contains an unsupported value, will raise an AvpEncodeError.

AvpUnsigned32 ¶

AvpUnsigned32(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements the "Unsigned32" type.

The "Unsigned32" type has a 32-bit unsigned value.

value `property` `writable` ¶

value: int

Sets or retrieves the AVP value as a python integer. When setting the value, it must be a 32-bit unsigned integer. Larger and signed integers will raise an AvpEncodeError.

AvpUnsigned64 ¶

AvpUnsigned64(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements the "Unsigned64" type.

The "Unsigned64" type has a 64-bit unsigned value.

value `property` `writable` ¶

value: int

Sets or retrieves the AVP value as a python integer. When setting the value, it must be a 64-bit unsigned integer. Larger and signed integers will raise an AvpEncodeError.

AvpUtf8String ¶

AvpUtf8String(
    code: int = 0,
    vendor_id: int = 0,
    payload: bytes = b"",
    flags: int = 0,
)

Bases: Avp

An AVP type that implements the "UTF8String" type.

According to rfc677, a UTF8String format is derived from the OctetString basic AVP format. It is defined as a human-readable string represented using the ISO/IEC IS 10646-1 character set, encoded as an OctetString using the UTF-8 transformation format. It translates to the basic python str type.

value `property` `writable` ¶

value: str

Sets or retrieves the AVP value, as a python str. When setting the value, it must be a string that can be encoded as utf-8. Any other data type, or strings that will not encode as utf-8, will raise an AvpEncodeError.

register ¶

register(
    avp: int,
    name: str,
    type_cls: type[_AnyAvpType],
    vendor: int = None,
    mandatory: bool = None,
)

Register a custom AVP definition.

Either overwrites an existing AVP definition or creates a new one.

Parameters:

Name	Type	Description	Default
`avp`	`int`	AVP code, required. If an existing code is used, it will overwrite the previous definition	required
`name`	`str`	AVP name, used in human-readable dumps and AVP representations. Usually in "Capitalised-Dash-Separated-Words" format	required
`type_cls`	`type[_AnyAvpType]`	AVP type class. Can be one of the existing types, such as `AvpOctetString`, `AvpInteger32`, etc., or a custom definition. When a custom definition is used, it should still subclass `Avp`.	required
`vendor`	`int`	Vendor code. Can be previously unused	`None`
`mandatory`	`bool`	Set the AVP mandatory flag. When overwriting existing AVPs, this should be set to the same value as the existing AVP.	`None`

# Add a new AVP definition for AVP 90000001 and vendor 9999999
from diameter.message.avp import avp, AvpUtf8String

VENDOR_SPECIAL = 9999999
AVP_SPECIAL_SESSION_ID = 90000001

avp.register(avp=AVP_SPECIAL_SESSION_ID,
             name="Special-Session-Id",
             cls=AvpUtf8String,
             vendor=VENDOR_SPECIAL)

Index

AvpEnumerated module-attribute ¶

Avp ¶

code instance-attribute ¶

flags instance-attribute ¶

is_mandatory property writable ¶

is_private property writable ¶

is_vendor property ¶

length property ¶

name instance-attribute ¶

payload instance-attribute ¶

value property writable ¶

vendor_id property writable ¶

as_bytes ¶

as_packed ¶

from_avp classmethod ¶

from_bytes classmethod ¶

from_unpacker classmethod ¶

new classmethod ¶

AvpAddress ¶

value property writable ¶

AvpFloat32 ¶

value property writable ¶

AvpFloat64 ¶

value property writable ¶

AvpGrouped ¶

value property writable ¶

AvpInteger32 ¶

value property writable ¶

AvpInteger64 ¶

value property writable ¶

AvpOctetString ¶

value property writable ¶

AvpTime ¶

value property writable ¶

AvpUnsigned32 ¶

value property writable ¶

AvpUnsigned64 ¶

value property writable ¶

AvpUtf8String ¶

value property writable ¶

register ¶

AvpEnumerated `module-attribute` ¶

code `instance-attribute` ¶

flags `instance-attribute` ¶

is_mandatory `property` `writable` ¶

is_private `property` `writable` ¶

is_vendor `property` ¶

length `property` ¶

name `instance-attribute` ¶

payload `instance-attribute` ¶

value `property` `writable` ¶

vendor_id `property` `writable` ¶

from_avp `classmethod` ¶

from_bytes `classmethod` ¶

from_unpacker `classmethod` ¶

new `classmethod` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶

value `property` `writable` ¶