Data Types¶

This section describes several classes that implement types defined in RFC 3416, Section 3.

`SimpleSyntax`¶

class snmp.smi.Integer¶: An alias for Integer32.

class snmp.smi.Integer32(value: int)¶

The default INTEGER type for SNMP.

The constructor raises a ValueError if the value is not in the range of a 32-bit two’s complement number.

property value: int¶: This object’s value as a native int.

__eq__(self, other: object) → bool¶: Compare two INTEGERs for equality both in value and in ASN.1 type. An Integer32 and an Unsigned32 with the same value are not equal because they differ in type.

class snmp.smi.OctetString(data: bytes)¶

A representation of an ASN.1 OCTET STRING.

The constructor raises a ValueError if the data is longer than 65535 bytes.

property data: bytes¶: The object’s raw data as a native bytes.

__eq__(self, other: object) → bool¶: Compare two OCTET STRINGS for equality both in value and in ASN.1 type. An OctetString and an Opaque containing the same data are not equal because they differ in type.

class snmp.smi.OID(*subidentifiers)¶

A representation of an ASN.1 OBJECT IDENTIFIER.

The subidentifiers argument list accepts between 0 and 128 integers. The first sub-identifier must be between 0 and 2, the second must be between 0 and 39, and the rest must be between 0 to (2^32)-1. The encoding rules do not support OIDs with less than 2 sub-identifiers, so when sent over the wire, the objects OID(), OID(0), OID(1), and OID(2) become OID(0, 0), OID(0, 0), OID(1, 0), and OID(2, 0), respectively.

The methods in this class are all non-mutating. The descriptions sometimes use words like “append” as shorthand for “return a new instance containing the sub-identifiers of this object followed by one or more additional subidentifier(s).”

classmethod parse(oid: str) → OID¶: Convert a string like "1.3.6.1.2.1.1.1.0" or ".1.3.6.1.2.1.1.1.0" into an OID. Raise a ValueError if oid does not represent a valid OID.

__str__() → str¶: Convert an OID into a string like "1.3.6.1.2.1.1.1.0".

__hash__() → int¶: This allows an OID to be used as a key in a dict.

__eq__(other: object) → bool¶: Compare two OIDs for equality.

__lt__(other: OID) → bool¶: Compare two OIDs lexicographically.

__len__() → int¶: Count the number of sub-identifiers.

__getitem__(n: int | slice) → int | tuple[int, ...]¶: Retrieve the sub-identifier(s) at index (or slice) n.

__iter__() → Iterator[int]¶: Iterate through the sub-identifiers.

extend(*subidentifiers: int) → OID¶: Append the given subidentifiers. Raise a ValueError if the result would be longer than 128 sub-identifiers.

startswith(prefix: OID) → bool¶: Similar to str.startswith().

withIndex(*index: Integer | OctetString | OID, implied: bool = False) → OID¶

Construct an SNMP variable name from an object type name and an index. This operation is the reverse of getIndex() and decodeIndex().

For example, the following code requests the description of interface 3:

ifDescr = OID.parse("1.3.6.1.2.1.2.2.1.2")
vb, = manager.get(ifDescr.withIndex(Integer(3)))
print(f"Description: {vb.value.data}")

In rare cases, the last variable in the INDEX clause is labelled as IMPLIED. For example, here’s a definition from the SNMP-NOTIFICATION-MIB:

snmpNotifyFilterEntry OBJECT-TYPE
    SYNTAX      SnmpNotifyFilterEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "An element of a filter profile.

         Entries in the snmpNotifyFilterTable are created and
         deleted using the snmpNotifyFilterRowStatus object."
    INDEX {         snmpNotifyFilterProfileName,
            IMPLIED snmpNotifyFilterSubtree }
    ::= { snmpNotifyFilterTable 1 }

When encoding such an index, you must set the implied argument to True.

This method raises a ValueError if the result would be longer than 128 sub-identifiers.

Additional Reading¶

RFC 1157, Section 3.2.6.3 explains the relationship between the “names” of object types, and the “names” of the instances of an object type. The word “names” means OIDs.

RFC 2578, Section 7.7 specifies how an object is encoded as an INDEX, including the meaning of the IMPLIED keyword.

getIndex(prefix: OID, cls=Integer, implied=False)¶

Decode the index portion of an SNMP variable name, so long as the index is a single value. For a multi-part index, use decodeIndex().

For example, this snippet requests the first interface description in ifTable, and uses the returned OID to determine its ifIndex.

ifDescr = OID.parse("1.3.6.1.2.1.2.2.1.2")
vb, = manager.getNext(ifDescr)
index = vb.name.getIndex(ifDescr).value
description = vb.value.data
print(f"Description for interface {index}: {description}")

You can also use the cls parameter to decode a non-Integer index. Here is a contrived example of this:

prefix = OID.parse("1.2.3.4")
oid = prefix.extend(5, 1, 2, 3, 4, 5)
index = oid.getIndex(prefix, OID)
print(index)   # prints "1.2.3.4.5"

In rare cases, the variable in the INDEX clause is labelled as IMPLIED. For example, here’s a definition from the SNMP-NOTIFICATION-MIB:

snmpNotifyEntry OBJECT-TYPE
    SYNTAX      SnmpNotifyEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "An entry in this table selects a set of management targets
         which should receive notifications, as well as the type of

         notification which should be sent to each selected
         management target.

         Entries in the snmpNotifyTable are created and
         deleted using the snmpNotifyRowStatus object."
    INDEX { IMPLIED snmpNotifyName }
    ::= { snmpNotifyTable 1 }

When decoding such an index, you must set the implied argument to True.

If the OID does not begin with prefix, this method will raise a BadPrefix exception. If there is a problem decoding the index, it will raise an IndexDecodeError.

decodeIndex(prefix: OID, *types: type, implied=False) → tuple[...]¶

Decode the index portion of an SNMP variable name.

Note

This method always returns the index as a tuple, even if the length is 1. It is therefore recommended to use getIndex() when the index consists of a single value.

Here’s a real object type definition from the IP-MIB:

ipAddressPrefixEntry OBJECT-TYPE
    SYNTAX     IpAddressPrefixEntry
    MAX-ACCESS not-accessible
    STATUS     current
    DESCRIPTION
           "An entry in the ipAddressPrefixTable."
    INDEX    { ipAddressPrefixIfIndex, ipAddressPrefixType,
               ipAddressPrefixPrefix, ipAddressPrefixLength }
    ::= { ipAddressPrefixTable 1 }

Notice that there are four variables in the INDEX. You can determine the data type of each variable by tracing their SYNTAX clauses until you get to a primitive type. You can then decode the index by passing the corresponding classes to decodeIndex() via the types argument list. Here is a code sample that does just that:

ipAddressPrefixOrigin = OID.parse("1.3.6.1.2.1.4.32.1.5")
vb, = manager.getNext(ipAddressPrefixOrigin)
index = vb.name.decodeIndex(
   ipAddressPrefixOrigin,
   Integer,
   Integer,
   OctetString,
   Integer,
)

print(f"ifIndex: {index[0].value}")
print(f"type: {index[1].value}")
print(f"prefix: {index[2].data}")
print(f"length: {index[3].value}")
print(f"origin: {vb.value.value}")

In rare cases, the last variable in the INDEX clause is labelled as IMPLIED. For example, here’s a definition from the SNMP-NOTIFICATION-MIB:

snmpNotifyFilterEntry OBJECT-TYPE
    SYNTAX      SnmpNotifyFilterEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
        "An element of a filter profile.

         Entries in the snmpNotifyFilterTable are created and
         deleted using the snmpNotifyFilterRowStatus object."
    INDEX {         snmpNotifyFilterProfileName,
            IMPLIED snmpNotifyFilterSubtree }
    ::= { snmpNotifyFilterTable 1 }

When decoding such an index, you must set the implied argument to True.

If the OID does not begin with prefix, this method will raise a BadPrefix exception. If there is a problem decoding the index, it will raise an IndexDecodeError.

exception BadPrefix¶

exception IndexDecodeError¶

`ApplicationSyntax`¶

class snmp.smi.IpAddress(addr: str)¶

An IPv4 address. The constructor raises a ValueError if the addr is not a valid IPv4 address string.

This is an OCTET STRING type, so it implements the same interface as OctetString.

property addr: str¶: The address in human-readable "X.X.X.X" format.

property data: bytes¶: A byte string encoding the address in network format.

__eq__(self, other: object) → bool¶: Two IpAddresses are equal if they represent the same address.

class snmp.smi.Counter32(value: int)¶

This class is exactly like Integer32, but allows only 32-bit unsigned values.

property value: int¶: This object’s value as a native int.

__eq__(self, other: object) → bool¶: Compare two INTEGERs for equality both in value and in ASN.1 type.

class snmp.smi.Unsigned¶: An alias for Unsigned32.

class snmp.smi.Unsigned32(value: int)¶

This class is exactly like Integer32, but allows only 32-bit unsigned values.

property value: int¶: This object’s value as a native int.

__eq__(self, other: object) → bool¶: Compare two INTEGERs for equality both in value and in ASN.1 type.

class snmp.smi.Gauge32(value: int)¶: Indistinguishable from Unsigned32 in all but name.

class snmp.smi.TimeTicks(value: int)¶

This class is exactly like Integer32, but allows only 32-bit unsigned values.

property value: int¶: This object’s value as a native int.

__eq__(self, other: object) → bool¶: Compare two INTEGERs for equality both in value and in ASN.1 type.

class snmp.smi.Opaque(data: bytes)¶

This class is exactly like OctetString.

property data: bytes¶: The object’s raw data as a native bytes.

__eq__(self, other: object) → bool¶: Compare two OCTET STRINGS for equality both in value and in ASN.1 type.

class snmp.smi.Counter64(value: int)¶

This class is exactly like Integer32, but allows only 64-bit unsigned values.

property value: int¶: This object’s value as a native int.

__eq__(self, other: object) → bool¶: Compare two INTEGERs for equality both in value and in ASN.1 type.

Variable Bindings¶

class snmp.smi.Null¶: A placeholder value for requests.

class snmp.smi.NoSuchObject¶

A special value in a response that means that the requested OID does not refer to a known object type.

__eq__(self, other: object) → bool¶: Check if other is an instance of NoSuchObject.

class snmp.smi.NoSuchInstance¶

A special value in a response meaning that the OID refers to a known object type, but there is no instance with the requested OID index.

__eq__(self, other: object) → bool¶: Check if other is an instance of NoSuchInstance.

class snmp.smi.EndOfMibView¶

A special value in a response to a GetNext or GetBulk request meaning that there are no variables following the requested OID.

__eq__(self, other: object) → bool¶: Check if other is an instance of EndOfMibView.

class snmp.smi.VarBind(oid: OID | str, value: Optional[Integer | OctetString | OID] = None)¶

property name: OID¶: The variable name, as an OID.

property value: Integer | OctetString | Null | OID¶: The variable value, which will be one of the types described on this page.

class snmp.smi.VarBindList(*varbinds: VarBind)¶

A SEQUENCE of VarBinds.

__len__() → int¶: Count the number of variable bindings in this list.

__getitem__(n: int | slice) → VarBind | tuple[VarBind, ...]¶: Retrieve the VarBind(s) at index (or slice) n.

__iter__() → Iterator[VarBind]¶: Iterate through the VarBinds.

Constants¶

snmp.smi.zeroDotZero¶: The OID representing "0.0". This is the OID equivalent of NULL.

Data Types¶

`SimpleSyntax`¶

Additional Reading¶

`ApplicationSyntax`¶

Variable Bindings¶

Constants¶

Table of Contents

Previous topic

Next topic

This Page

Data Types¶

SimpleSyntax¶

Additional Reading¶

ApplicationSyntax¶

Variable Bindings¶

Constants¶

`SimpleSyntax`¶

`ApplicationSyntax`¶