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 multiple 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 multiple 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). 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("---")