Errors and supporting types¶

The objects on this page are referenced throughout the library reference and the docstrings — as the exceptions an operation raises, the type a call hands back, or the MIB services the high-level API is built on. They are collected here so that every one of those references resolves.

Exceptions¶

exception pysnmp.error.PySnmpError¶

Base class for pysnmp exceptions.

Carries the exception it was raised from, if any, into its own string form, so a caller that only logs str(exc) still sees the underlying failure.

property cause: tuple¶

The chained exception as a sys.exc_info()-shaped triple.

Empty triple when this exception was not raised while another was being handled.

__str__() → str¶: The message, with the exception this was raised from appended.

exception pysnmp.smi.error.SmiError(*args: Any, **context: Any)¶

Raised when a MIB cannot be loaded or a managed object cannot be served.

Raised by the SMI layer. It derives from both PySnmpError and PyAsn1Error, so either is enough to catch it.

Warnings¶

exception pysnmp.error.PySnmpCryptoWarning¶

Base class for warnings about SNMPv3 cryptographic protocol selection.

Subclasses of this warning are raised at user configuration time rather than at packet processing time. They derive from UserWarning (not DeprecationWarning) so that they remain visible under Python’s default warning filters, since ignoring them has security consequences.

exception pysnmp.error.PySnmpWeakCryptoWarning¶: The selected protocol is no longer considered cryptographically safe.

exception pysnmp.error.PySnmpNonStandardCryptoWarning¶: The selected protocol is not standards-track and may not interoperate.

Return types¶

class pysnmp.hlapi.types.SnmpResponse(errorIndication: Any, errorStatus: Any, errorIndex: Any, varBinds: Any)¶

Result of an SNMP command (GET / SET / NEXT / BULK / notification).

This is a NamedTuple subclass of tuple, so existing code that unpacks the 4-tuple positionally continues to work unchanged:

errorIndication, errorStatus, errorIndex, varBinds = await getCmd(...)

errorIndication¶

None on success, or an error-indication object/string on SNMP engine error.

Type:: Any

errorStatus¶

0 / None on success, or a truthy value indicating a protocol-level PDU error.

Type:: Any

errorIndex¶

0 when no error, otherwise a 1-based index into varBinds referring to the variable that caused the error.

Type:: Any

varBinds¶

A sequence of resolved var-bind pairs (typically ObjectType instances).

Type:: Any

Create new instance of SnmpResponse(errorIndication, errorStatus, errorIndex, varBinds)

pysnmp.proto.rfc1905.endOfMibView¶

Returned by GETNEXT and GETBULK when there is nothing past this OID.

The value a response carries in place of a variable binding when a walk has run past the end of the MIB view.

class pysnmp.proto.rfc1902.ObjectName(value: ~typing.Any = <NoValue object>, **kwargs: ~typing.Any)¶

Transport¶

class pysnmp.hlapi.transport.TransportAddrT¶: The address shape a concrete transport target speaks. Each transport has its own – a (host, port) pair for UDP over IPv4 and IPv6, a path string for Unix domain sockets – so AbstractTransportTarget is generic in it rather than naming one its subclasses would have to contradict.

class pysnmp.hlapi.transport.AbstractTransportTarget(transportAddr: TransportAddrT, timeout: int = 1, retries: int = 5, tagList: Any = b'')¶

setLocalAddress(iface: tuple[str, ...] | None) → AbstractTransportTarget[TransportAddrT]¶

Set source address.

Parameters:: iface (tuple) – Indicates network address of a local interface from which SNMP packets will be originated. Format is the same as of transportAddress.
Returns:: self

MIB services¶

class pysnmp.smi.builder.MibBuilder¶

Loads MIB modules and holds the symbols they define.

A module is searched for across every registered source, and where more than one source has it, the copy stating the newest MODULE-IDENTITY revision wins; search order settles only what the revisions cannot. Loading a module loads what it IMPORTS first, so asking for one symbol can pull in a graph of them.

Assemble the search path, in the order modules are looked for.

The environment comes first (PYSNMP_MIB_PKGS, PYSNMP_MIB_DIRS, PYSNMP_MIB_DIR), then the core modules, which are inserted at the front so nothing overrides the ones the engine itself needs, then the generated ones. That ordering is what lets a user’s copy of a MIB shadow the bundled one without being able to displace the framework modules.

PYSNMP_MIB_DBS names corpora rather than sources and so is handled separately, at the end: a corpus is searched only where the sources come up empty, which is what keeps configuring one from changing any answer a deployment already had.

Raises:: SmiError – PYSNMP_MIB_DBS names something that is not a readable: corpus.

addMibSources(*mibSources: Any) → None¶: Add sources to search, opening each one.

getMibSources() → tuple[Any, ...]¶: The sources currently searched.

loadModules(*modNames: str, **userCtx: Any) → Any¶: Load (optionally, compiling) pysnmp MIB modules.

importSymbols(modName: str, *symNames: str, **userCtx: Any) → tuple[Any, ...]¶: Fetch symbols from a module, loading the module first if it is not loaded.

class pysnmp.smi.view.MibViewController(mibBuilder)¶

Indexes what a builder loaded, and answers questions about names and OIDs.

Resolves a label to an OID and back, and walks to the next object in OID order across every loaded module – which is not the order the modules were loaded in, nor lexical order on their names.

Indexing is deferred until the first lookup, as in the instrumentation.

indexMib()¶

Rebuild the name and OID indices, unless nothing has been loaded since.

Every lookup calls this first, so the builder’s build counter is what keeps it from re-indexing on each one.

getOrderedModuleName(index)¶: The loaded module at that position, counting from either end.

getFirstModuleName()¶: The first loaded module.

getLastModuleName()¶: The last loaded module.

getNextModuleName(modName)¶: The module after this one.

getNodeNameByOid(nodeName, modName='')¶

Resolve an OID or a label to (oid, label, suffix).

An OID need not name an object exactly: the longest known prefix is what resolves, and the rest comes back as the suffix, which is how an instance under a column is named. An OID that resolves to nothing but itself is not in this MIB view at all – unless a corpus can say which module would have carried it, in which case that module is loaded and the lookup is tried once more.

getNodeNameByDesc(nodeName, modName='')¶: Resolve a MIB symbol’s name to (oid, label, suffix).

getNodeName(nodeName, modName='')¶

Resolve either an OID, a label, or a (symbol, index…) tuple.

The forms are tried in that order, since a caller may have any of the three and they cannot be told apart reliably by shape.

getOrderedNodeName(index, modName='', nodeType=None)¶: The object at that position in the module, optionally of one node type.

getFirstNodeName(modName='', nodeType=None)¶: The first object in the module, or the first of one node type.

getLastNodeName(modName='', nodeType=None)¶: The last object in the module, or the last of one node type.

getNextNodeName(nodeName, modName='')¶

The object after this one, in OID order.

OID order is neither the order the modules were loaded in nor lexical order on their names, which is why this cannot be answered from a plain mapping.

getParentNodeName(nodeName, modName='')¶: The object one level up, its last sub-identifier moved onto the suffix.

getNodeLocation(nodeName, modName='')¶

Which module defines an object, and under what label.

The answer comes from the index across all modules rather than from any one of them, since the caller is asking precisely because they do not know which module it is in.

getTypeName(typeName, modName='')¶: Which module defines a textual convention or type.

getOrderedTypeName(index, modName='')¶: The type at that position in the module, counting from either end.

getFirstTypeName(modName='')¶: The first type the module defines.

getLastTypeName(modName='')¶: The last type the module defines.

getNextType(typeName, modName='')¶: The type after this one.

getTableColumns(modName, rowSymName)¶

Return column metadata for a MIB table row.

Parameters:

modName – MIB module name (e.g. 'SNMPv2-MIB').
rowSymName – MIB symbol name of the table row/entry (e.g. 'sysOREntry').

Returns:

list of (colId, colName, colNode) tuples — one per column in the row. colId is the column number (last sub-OID), colName is the full OID tuple, and colNode is the MibTableColumn instance.

Raises:

SmiError – if the module or symbol is not found.

Examples

>>> from pysnmp.smi import builder
>>> mibBuilder = builder.MibBuilder()
>>> mibView = MibViewController(mibBuilder)
>>> cols = mibView.getTableColumns('SNMPv2-MIB', 'sysOREntry')
>>> [(colId, colNode.getMaxAccess()) for colId, colName, colNode in cols]
[(1, 'notaccessible'), (2, 'readonly'), (3, 'readonly'), (4, 'readonly')]

Column 1 is sysORIndex, the table’s INDEX. RFC 3418 declares it not-accessible; this example said readonly while the base layer was a 2017 freeze that got it wrong (pysnmp/pysnmp#198).

resolveCellOid(modName, rowSymName, column, *indices)¶

Resolve a table cell address into a full OID.

Parameters:

modName – MIB module name.
rowSymName – MIB symbol name of the table row/entry.
column – Column symbol name or number (last sub-OID).
indices – Typed index values (e.g. 'my-router' or 1).

Returns:

tuple of ints — the full OID identifying the cell.

Examples

>>> from pysnmp.smi import builder
>>> mibBuilder = builder.MibBuilder()
>>> mibView = MibViewController(mibBuilder)
>>> oid = mibView.resolveCellOid('SNMP-COMMUNITY-MIB',
...                              'snmpCommunityEntry', 2, 'my-router')
>>> oid
(1, 3, 6, 1, 6, 3, 18, 1, 1, 1, 2, 109, 121, 45, 114, 111, 117, 116, 101, 114)

getTableCellInfo(cellOid)¶

Split a table cell OID into its MIB names and typed indices.

Parameters:: cellOid – Complete table cell OID.
Returns:: (moduleName, rowName, columnName, indices).
Raises:: SmiError – if cellOid does not identify a table cell.

get_table_columns(modName, rowSymName)¶

Return column metadata for a MIB table row.

Parameters:

modName – MIB module name (e.g. 'SNMPv2-MIB').
rowSymName – MIB symbol name of the table row/entry (e.g. 'sysOREntry').

Returns:

list of (colId, colName, colNode) tuples — one per column in the row. colId is the column number (last sub-OID), colName is the full OID tuple, and colNode is the MibTableColumn instance.

Raises:

SmiError – if the module or symbol is not found.

Examples

>>> from pysnmp.smi import builder
>>> mibBuilder = builder.MibBuilder()
>>> mibView = MibViewController(mibBuilder)
>>> cols = mibView.getTableColumns('SNMPv2-MIB', 'sysOREntry')
>>> [(colId, colNode.getMaxAccess()) for colId, colName, colNode in cols]
[(1, 'notaccessible'), (2, 'readonly'), (3, 'readonly'), (4, 'readonly')]

Column 1 is sysORIndex, the table’s INDEX. RFC 3418 declares it not-accessible; this example said readonly while the base layer was a 2017 freeze that got it wrong (pysnmp/pysnmp#198).

resolve_cell_oid(modName, rowSymName, column, *indices)¶

Resolve a table cell address into a full OID.

Parameters:

modName – MIB module name.
rowSymName – MIB symbol name of the table row/entry.
column – Column symbol name or number (last sub-OID).
indices – Typed index values (e.g. 'my-router' or 1).

Returns:

tuple of ints — the full OID identifying the cell.

Examples

>>> from pysnmp.smi import builder
>>> mibBuilder = builder.MibBuilder()
>>> mibView = MibViewController(mibBuilder)
>>> oid = mibView.resolveCellOid('SNMP-COMMUNITY-MIB',
...                              'snmpCommunityEntry', 2, 'my-router')
>>> oid
(1, 3, 6, 1, 6, 3, 18, 1, 1, 1, 2, 109, 121, 45, 114, 111, 117, 116, 101, 114)

get_table_cell_info(cellOid)¶

Split a table cell OID into its MIB names and typed indices.

Parameters:: cellOid – Complete table cell OID.
Returns:: (moduleName, rowName, columnName, indices).
Raises:: SmiError – if cellOid does not identify a table cell.

Synchronous command generators¶

These are the blocking counterparts of the coroutines in GET command and its siblings. They take the same arguments and return the same tuple, having driven the event loop themselves.

pysnmp.hlapi.getCmd(snmpEngine: Any, authData: Any, transportTarget: Any, contextData: Any, *varBinds: Any, **options: Any) → Iterator[tuple[Any, Any, Any, Any]]¶: Blocking GET. Yields one result, then whatever bindings are sent back in.

pysnmp.hlapi.setCmd(snmpEngine: Any, authData: Any, transportTarget: Any, contextData: Any, *varBinds: Any, **options: Any) → Iterator[tuple[Any, Any, Any, Any]]¶: Blocking SET. Yields one result, then whatever bindings are sent back in.

pysnmp.hlapi.nextCmd(snmpEngine: Any, authData: Any, transportTarget: Any, contextData: Any, *varBinds: Any, **options: Any) → Iterator[tuple[Any, Any, Any, Any]]¶

Blocking GETNEXT, walking until the end of the subtree.

lexicographicMode decides whether the walk stops at the end of the subtree it started in or carries on to the end of the MIB; maxRows and maxCalls bound it either way.

pysnmp.hlapi.bulkCmd(snmpEngine: Any, authData: Any, transportTarget: Any, contextData: Any, nonRepeaters: Any, maxRepetitions: Any, *varBinds: Any, **options: Any) → Iterator[tuple[Any, Any, Any, Any]]¶

Blocking GETBULK, walking until the end of the subtree.

nonRepeaters is how many of the bindings are fetched once rather than walked, and maxRepetitions how many rows the agent should return per pass – a value larger than the response can hold is answered with fewer, not an error.

Navigation

Related Topics

Errors and supporting types¶

Exceptions¶

Warnings¶

Return types¶

Transport¶

MIB services¶

Synchronous command generators¶