Session Python Module¶

class ezsnmp.session.Session(hostname: str = 'localhost', port_number: str | int = '', version: str | int = '3', community: str = 'public', auth_protocol: str = '', auth_passphrase: str = '', security_engine_id: str = '', context_engine_id: str = '', security_level: str = '', context: str = '', security_username: str = '', privacy_protocol: str = '', privacy_passphrase: str = '', boots_time: str = '', retries: str | int = '3', timeout: str | int = '1', load_mibs: str = '', mib_directories: str = '', print_enums_numerically: bool = False, print_full_oids: bool = False, print_oids_numerically: bool = False, print_timeticks_numerically: bool = False, print_hex_strings: bool = False, set_max_repeaters_to_num: str | int = '10')¶

Bases: SessionBase

Python wrapper class for SessionBase, providing a Pythonic interface for managing Net-SNMP sessions.

Supports SNMP v1, v2c, and v3. Wraps the underlying C++ SessionBase class generated via SWIG. Use as a context manager (with statement) to ensure the session is closed and resources are released automatically.

Supported operations:

get() — SNMP GET
get_next() — SNMP GETNEXT
walk() — SNMP WALK
bulk_get() — SNMP GETBULK (v2c/v3 only)
bulk_walk() — SNMP bulk WALK (v2c/v3 only)
set() — SNMP SET

Example:

from ezsnmp import Session

with Session(hostname='localhost', community='public', version=2) as session:
    results = session.get(['sysDescr.0', 'sysLocation.0'])
    for item in results:
        print(item.oid, item.value)

__init__(hostname: str = 'localhost', port_number: str | int = '', version: str | int = '3', community: str = 'public', auth_protocol: str = '', auth_passphrase: str = '', security_engine_id: str = '', context_engine_id: str = '', security_level: str = '', context: str = '', security_username: str = '', privacy_protocol: str = '', privacy_passphrase: str = '', boots_time: str = '', retries: str | int = '3', timeout: str | int = '1', load_mibs: str = '', mib_directories: str = '', print_enums_numerically: bool = False, print_full_oids: bool = False, print_oids_numerically: bool = False, print_timeticks_numerically: bool = False, print_hex_strings: bool = False, set_max_repeaters_to_num: str | int = '10')¶

Initialize the Session object with NetSNMP session parameters.

Parameters:

hostname (str) – The hostname or IP address of the SNMP agent.
port_number (Union[str, int]) – The port number of the SNMP agent.
version (Union[str, int]) –
The SNMP version to use. All of the following forms are accepted and equivalent for SNMPv2c:
- Integer 2 — automatically converted to "2c" internally.
- String "2" — passed through as-is; net-snmp accepts -v 2.
- String "2c" — the canonical form; passed through as-is.
For other versions use 1 / "1" (SNMPv1) or 3 / "3" (SNMPv3).
community (str) – The community string for SNMPv1/v2c.
auth_protocol (str) – The authentication protocol (e.g., “MD5”, “SHA”).
auth_passphrase (str) – The authentication passphrase.
security_engine_id (str) – The security engine ID.
context_engine_id (str) – The context engine ID.
security_level (str) – The security level (e.g., “noAuthNoPriv”, “authNoPriv”, “authPriv”).
context (str) – The SNMPv3 context name used to identify a collection of management information (SNMPv3 only).
security_username (str) – The security username.
privacy_protocol (str) – The privacy protocol (e.g., “DES”, “AES”).
privacy_passphrase (str) – The privacy passphrase.
boots_time (str) – The SNMPv3 authoritative engine boots and time, formatted as “BOOTS,TIME” (e.g., “1,100”). Used to synchronize with the agent’s time window.
retries (Union[str, int]) – The number of retries.
timeout (Union[str, int]) – The timeout value in seconds.
load_mibs (str) – Comma-separated string of MIB modules to load.
mib_directories (str) – Comma-separated string of directories to search for MIB files.
print_enums_numerically (bool) – Whether to print enums numerically.
print_full_oids (bool) – Whether to print full OIDs.
print_oids_numerically (bool) – Whether to print OIDs numerically.
print_timeticks_numerically (bool) – Whether to print timeticks numerically.
print_hex_strings (bool) – Whether to print OCTET STRING values in hex format.
set_max_repeaters_to_num (Union[str, int]) – The maximum number of repeaters for GETBULK PDUs. Defaults to 10. Only applies to bulk_get() and bulk_walk().

property args¶

Get the tuple of arguments used for NetSNMP commands.

Type:: tuple

property auth_passphrase¶

Get the authentication passphrase.

Type:: str

property auth_protocol¶

Get the authentication protocol.

Type:: str

property boots_time¶

Get the boots time.

Type:: str

bulk_get(oids=None)¶

Performs an SNMP GETBULK operation to retrieve values for one or more OIDs.

Requires SNMPv2c or SNMPv3. GETBULK is not supported in SNMPv1.

Accepts either a single OID string or a list of OID strings.

Parameters:

oids (Union[str, list[str], None]) – A single OID string or a list of Object Identifiers (OIDs) to retrieve values from. Defaults to None, which is treated as an empty list.

Returns:

A tuple of Result objects containing SNMP variable bindings with attributes: oid (str), index (str), value (str), and type (str)

Return type:

tuple[Result]

Raises:

GenericError – If the exception type is GenericErrorBase.
ConnectionError – If the exception type is ConnectionErrorBase.
NoSuchInstanceError – If the exception type is NoSuchInstanceErrorBase.
NoSuchNameError – If the exception type is NoSuchNameErrorBase.
NoSuchObjectError – If the exception type is NoSuchObjectErrorBase.
PacketError – If the exception type is PacketErrorBase.
ParseError – If the exception type is ParseErrorBase.
TimeoutError – If the exception type is TimeoutErrorBase.
UndeterminedTypeError – If the exception type is UndeterminedTypeErrorBase.
UnknownObjectIDError – If the exception type is UnknownObjectIDErrorBase.
Exception – If the exception type does not match any of the above, the original exception e is raised.

Example:

>>> from ezsnmp import Session
>>> session = Session(hostname="localhost", community="public", version="2")
>>> results = session.bulk_get(["1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.2.0"])
>>> for item in results:
...     print("OID:", item.oid)
...     print("Index:", item.index)
...     print("Value:", item.value)
...     print("Type:", item.type)
...     print("---")

bulk_walk(oids=None)¶

Performs a bulk SNMP walk (GETBULK-based) operation to retrieve a collection of values. The bulk walk operation is designed to return multiple OIDs in a single request, making it more efficient than regular walk operations for retrieving large amounts of data.

Requires SNMPv2c or SNMPv3. GETBULK is not supported in SNMPv1.

Accepts either a single OID string or a list of OID strings.

Parameters:

oids (Union[str, list[str], None]) – A single OID string or a list of base OIDs to start the walks from. Defaults to None, which is treated as an empty list.

Returns:

A tuple of Result objects containing SNMP variable bindings. Each Result object has attributes: oid (str), index (str), value (str), and type (str)

Return type:

tuple[Result]

Raises:

ConnectionError – If the exception type is ConnectionErrorBase.
GenericError – If the exception type is GenericErrorBase.
NoSuchInstanceError – If the exception type is NoSuchInstanceErrorBase.
NoSuchNameError – If the exception type is NoSuchNameErrorBase.
NoSuchObjectError – If the exception type is NoSuchObjectErrorBase.
PacketError – If the exception type is PacketErrorBase.
ParseError – If the exception type is ParseErrorBase.
TimeoutError – If the exception type is TimeoutErrorBase.
UndeterminedTypeError – If the exception type is UndeterminedTypeErrorBase.
UnknownObjectIDError – If the exception type is UnknownObjectIDErrorBase.
Exception – If the exception type does not match any of the above, the original exception e is raised.

Example (single OID string):

>>> from ezsnmp import Session
>>> session = Session(hostname="localhost", community="public", version="2")
>>> results = session.bulk_walk("1.3.6.1.2.1")
>>> print("OID:", results[0].oid)

Example (list of OIDs):

>>> results = session.bulk_walk(["1.3.6.1.2.1.1", "1.3.6.1.2.1.2"])
>>> for item in results:
...     print("OID:", item.oid)
...     print("Index:", item.index)
...     print("Value:", item.value)
...     print("Type:", item.type)
...     print("---")

close()¶: Close the SNMP session and release resources.

property community¶

Get the community string for SNMPv1/v2c.

Type:: str

property context¶

Get the SNMPv3 context name.

Type:: str

property context_engine_id¶

Get the context engine ID.

Type:: str

get(oids=None)¶

Performs an SNMP GET operation to retrieve values for one or more OIDs.

Accepts either a single OID string or a list of OID strings.

Parameters:

oids (Union[str, list[str], None]) – A single OID string or a list of Object Identifiers (OIDs) to retrieve values from. Defaults to None, which is treated as an empty list.

Returns:

A tuple of Result objects containing SNMP variable bindings with attributes: oid (str), index (str), value (str), and type (str)

Return type:

tuple[Result]

Raises:

GenericError – If the exception type is GenericErrorBase.
ConnectionError – If the exception type is ConnectionErrorBase.
NoSuchInstanceError – If the exception type is NoSuchInstanceErrorBase.
NoSuchNameError – If the exception type is NoSuchNameErrorBase.
NoSuchObjectError – If the exception type is NoSuchObjectErrorBase.
PacketError – If the exception type is PacketErrorBase.
ParseError – If the exception type is ParseErrorBase.
TimeoutError – If the exception type is TimeoutErrorBase.
UndeterminedTypeError – If the exception type is UndeterminedTypeErrorBase.
UnknownObjectIDError – If the exception type is UnknownObjectIDErrorBase.
Exception – If the exception type does not match any of the above, the original exception e is raised.

Example (single OID string):

>>> from ezsnmp import Session
>>> session = Session(hostname="localhost", community="public", version="2")
>>> result = session.get("1.3.6.1.2.1.1.1.0")
>>> print("OID:", result[0].oid)

Example (list of OIDs):

>>> results = session.get(["1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.2.0"])
>>> for item in results:
...     print("OID:", item.oid)
...     print("Index:", item.index)
...     print("Value:", item.value)
...     print("Type:", item.type)
...     print("---")

get_next(oids=None)¶

Performs an SNMP GETNEXT operation to retrieve the next object instance for each of the specified OIDs.

Accepts either a single OID string or a list of OID strings.

Parameters:

oids (Union[str, list[str], None]) – A single OID string or a list of Object Identifiers (OIDs) to get next values from. Defaults to None, which is treated as an empty list.

Returns:

A tuple of Result objects containing SNMP variable bindings with attributes: oid (str), index (str), value (str), and type (str)

Return type:

tuple[Result]

Raises:

GenericError – If the exception type is GenericErrorBase.
ConnectionError – If the exception type is ConnectionErrorBase.
NoSuchInstanceError – If the exception type is NoSuchInstanceErrorBase.
NoSuchNameError – If the exception type is NoSuchNameErrorBase.
NoSuchObjectError – If the exception type is NoSuchObjectErrorBase.
PacketError – If the exception type is PacketErrorBase.
ParseError – If the exception type is ParseErrorBase.
TimeoutError – If the exception type is TimeoutErrorBase.
UndeterminedTypeError – If the exception type is UndeterminedTypeErrorBase.
UnknownObjectIDError – If the exception type is UnknownObjectIDErrorBase.
Exception – If the exception type does not match any of the above, the original exception e is raised.

Example:

>>> from ezsnmp import Session
>>> session = Session(hostname="localhost", community="public", version="2")
>>> results = session.get_next(["1.3.6.1.2.1.1.1.0"])
>>> for item in results:
...     print("OID:", item.oid)
...     print("Index:", item.index)
...     print("Value:", item.value)
...     print("Type:", item.type)
...     print("---")

property hostname¶

Get the hostname or IP address of the SNMP agent.

Type:: str

property load_mibs¶

Get the list of MIBs to load.

Type:: str

property mib_directories¶

Get the directories to search for MIBs.

Type:: str

property port_number¶

Get the port number of the SNMP agent.

Type:: str

property print_enums_numerically¶

Get whether to print enums numerically.

Type:: bool

property print_full_oids¶

Get whether to print full OIDs.

Type:: bool

property print_hex_strings¶

Get whether to print OCTET STRING values as hex strings.

Type:: bool

property print_oids_numerically¶

Get whether to print OIDs numerically.

Type:: bool

property print_timeticks_numerically¶

Get whether to print timeticks numerically.

Type:: bool

property privacy_passphrase¶

Get the privacy passphrase.

Type:: str

property privacy_protocol¶

Get the privacy protocol.

Type:: str

property retries¶

Get the number of retries.

Type:: str

property security_engine_id¶

Get the security engine ID.

Type:: str

property security_level¶

Get the security level.

Type:: str

property security_username¶

Get the security username.

Type:: str

set(oids=None)¶

Performs an SNMP SET operation to set values for one or more OIDs.

Parameters:

oids (list) – A flat list of OID/type/value triples. Elements are ordered as [oid, type, value, oid, type, value, ...] where type is a single-character string indicating the SNMP data type (e.g. 'i' for INTEGER, 's' for STRING, 'o' for OBJECT IDENTIFIER, 'u' for UNSIGNED, 't' for TIMETICKS, 'a' for IPADDRESS, 'x' for HEX STRING). For the full list see snmpset(1). Defaults to None, treated as an empty list.

Returns:

A tuple of Result objects containing SNMP variable bindings with attributes: oid (str), index (str), value (str), and type (str)

Return type:

tuple[Result]

Raises:

GenericError – If the exception type is GenericErrorBase.
ConnectionError – If the exception type is ConnectionErrorBase.
NoSuchInstanceError – If the exception type is NoSuchInstanceErrorBase.
NoSuchNameError – If the exception type is NoSuchNameErrorBase.
NoSuchObjectError – If the exception type is NoSuchObjectErrorBase.
PacketError – If the exception type is PacketErrorBase.
ParseError – If the exception type is ParseErrorBase.
TimeoutError – If the exception type is TimeoutErrorBase.
UndeterminedTypeError – If the exception type is UndeterminedTypeErrorBase.
UnknownObjectIDError – If the exception type is UnknownObjectIDErrorBase.
Exception – If the exception type does not match any of the above, the original exception e is raised.

Example:

>>> from ezsnmp import Session
>>> session = Session(hostname="localhost", community="public", version="2")
>>> results = session.set([
...     ".1.3.6.1.6.3.12.1.2.1.2.116.101.115.116", "o", ".1.3.6.1.6.1.1",
...     ".1.3.6.1.6.3.12.1.2.1.3.116.101.115.116", "s", "1234",
...     ".1.3.6.1.6.3.12.1.2.1.9.116.101.115.116", "i", "4"
... ])
>>> for item in results:
...     print("OID:", item.oid)
...     print("Index:", item.index)
...     print("Value:", item.value)
...     print("Type:", item.type)
...     print("---")

property set_max_repeaters_to_num¶

Get the maximum number of repeaters for GETBULK PDUs.

Type:: str

property timeout¶

Get the timeout value.

Type:: str

to_dict()¶

Convert session to dictionary for logging/JSON serialization.

Sensitive fields (community, passwords) are masked.

Returns:: A dictionary of session parameters, with sensitive values masked.
Return type:: dict

property version¶

Get the SNMP version being used.

Type:: str

walk(oid='.')¶

Walks through the SNMP tree starting from the given OID. This method performs an SNMP walk operation, which retrieves a subtree of management values from the SNMP agent, starting from the specified OID.

Parameters:

oid (str) – The starting OID for the SNMP walk. Defaults to "." which starts the walk from the top of the OID tree.

Returns:

A tuple of Result objects containing SNMP variable bindings. Each Result object has attributes: oid (str), index (str), value (str), and type (str)

Return type:

tuple[Result]

Raises:

ConnectionError – If the exception type is ConnectionErrorBase.
GenericError – If the exception type is GenericErrorBase.
NoSuchInstanceError – If the exception type is NoSuchInstanceErrorBase.
NoSuchNameError – If the exception type is NoSuchNameErrorBase.
NoSuchObjectError – If the exception type is NoSuchObjectErrorBase.
PacketError – If the exception type is PacketErrorBase.
ParseError – If the exception type is ParseErrorBase.
TimeoutError – If the exception type is TimeoutErrorBase.
UndeterminedTypeError – If the exception type is UndeterminedTypeErrorBase.
UnknownObjectIDError – If the exception type is UnknownObjectIDErrorBase.
Exception – If the exception type does not match any of the above, the original exception e is raised.

Example:

>>> from ezsnmp import Session
>>> session = Session(hostname="localhost", community="public", version="2")
>>> results = session.walk("1.3.6.1.2.1")
>>> for item in results:
...     print("OID:", item.oid)
...     print("Index:", item.index)
...     print("Value:", item.value)
...     print("Type:", item.type)
...     print("---")