From 6f91630f15177c440ee8d6e4b53d0a9abc69ab5c Mon Sep 17 00:00:00 2001 From: elie Date: Thu, 17 Sep 2015 06:47:38 +0000 Subject: * documenting async command generator * minor fixes to markup --- pysnmp/entity/engine.py | 4 +- pysnmp/entity/rfc3413/oneliner/cmdgen.py | 102 ++++++++++++++++++++++++++ pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py | 16 ++-- pysnmp/entity/rfc3413/oneliner/sync/ntforg.py | 4 +- 4 files changed, 115 insertions(+), 11 deletions(-) diff --git a/pysnmp/entity/engine.py b/pysnmp/entity/engine.py index a15194d..97844bf 100644 --- a/pysnmp/entity/engine.py +++ b/pysnmp/entity/engine.py @@ -22,7 +22,9 @@ class SnmpEngine: See :RFC:`3412#section-2.1` (where it is termed *The Dispatcher*). With PySNMP design, `SnmpEngine` is the only stateful object, all SNMP - v3 operations require an instance of SNMP engine. + v3 operations require an instance of SNMP engine. Users do not normally + request services directly from `SnmpEngine`, but pass it around to + other PySNMP interfaces. It is possible to run multiple instances of `SnmpEngine` in the application. In a multithreaded environment, each thread that diff --git a/pysnmp/entity/rfc3413/oneliner/cmdgen.py b/pysnmp/entity/rfc3413/oneliner/cmdgen.py index 4f38d51..d6f51e4 100644 --- a/pysnmp/entity/rfc3413/oneliner/cmdgen.py +++ b/pysnmp/entity/rfc3413/oneliner/cmdgen.py @@ -20,6 +20,23 @@ SnmpEngine = engine.SnmpEngine nextID = nextid.Integer(0xffffffff) class AsyncCommandGenerator: + """Creates asyncore-based SNMP Command Generator object. + + This is a high-level wrapper around pure Command Generator + impementation that aims at simplyfing + :py:class:`pysnmp.entity.engine.SnmpEngine`'s Local Configuration + Datastore (:RFC:`2271#section-3.4.2`) management. Typically, + users instantiate `AsyncCommandGenerator` and call its + commmand-specific methods passing them canned Security, + Transport and SNMP Context parameters along with MIB variables + to deal with. `AsyncCommandGenerator` will manage LCD by + applying user-supplied configuratoin parameters and running + requested operation. + + See :RFC:`3413#section-3.1` for more information on SNMP + Command Generator purpose, design and supported operations. + + """ _null = univ.Null('') def _getCache(self, snmpEngine): @@ -225,6 +242,91 @@ class AsyncCommandGenerator: def getCmd(self, snmpEngine, authData, transportTarget, contextData, varBinds, cbInfo, lookupMib=False): + """Performs SNMP GET query. + + Based on passed parameters, prepares SNMP GET packet + (:RFC:`1905#section-4.2.1`) and schedules its transmission by + I/O framework at a later point of time. + + Parameters + ---------- + snmpEngine : :py:class:`~pysnmp.entity.engine.SnmpEngine` + Class instance representing SNMP engine. + + authData : :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData` or :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData` + Class instance representing SNMP credentials. + + transportTarget : :py:class:`~pysnmp.entity.rfc3413.oneliner.target.UdpTransportTarget` or :py:class:`~pysnmp.entity.rfc3413.oneliner.target.Udp6TransportTarget` + Class instance representing transport type along with SNMP peer address. + + contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` + Class instance representing SNMP ContextEngineId and ContextName values. + + varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` + One or more class instances representing MIB variables to place + into SNMP request. + + cbInfo : tuple + + * `cbFun` - user-supplied callable that is invoked to pass + SNMP response data or error to user at a later point of time. + * `cbCtx` - user-supplied object passing additional parameters + to/from `cbFun`. Default is `None`. + + Other Parameters + ---------------- + lookupMib : bool + `lookupMib` - load MIB and resolve response MIB variables at + the cost of slightly reduced performance. Default is `False`. + + Notes + ----- + User-supplied `cbFun` callable must have the following call + signature: + + * snmpEngine (:py:class:`~pysnmp.entity.engine.SnmpEngine`): + Class instance representing SNMP engine. + * sendRequestHandle (int): Unique request identifier. Can be used + for matching multiple ongoing requests with received responses. + * errorIndication (str): True value indicates SNMP engine error. + * errorStatus (str): Non-zero value indicates SNMP PDU error. + * errorIndex (int): Non-zero value refers to *varBinds[errorIndex-1] + * varBinds (tuple): A sequence of + :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances + representing MIB variables returned in SNMP response. + * `cbCtx` : Original user-supplied object. + + Returns + ------- + sendRequestHandle : int + Unique request identifier. Can be used for matching received + responses with ongoing requests. + + Raises + ------ + PySnmpError + Or its derivative indicating that an error occurred while + performing SNMP operation. + + Examples + -------- + >>> from pysnmp.entity.rfc3413.oneliner.cmdgen import * + >>> def cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx): + ... print(errorIndication, errorStatus, errorIndex, varBinds) + >>> + >>> snmpEngine = SnmpEngine() + >>> g = AsyncCommandGenerator() + >>> g.getCmd(snmpEngine, + ... CommunityData('public'), + ... UdpTransportTarget(('demo.snmplabs.com', 161)), + ... ContextData(), + ... ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0)), + ... (cbFun, None)) + >>> snmpEngine.transportDispatcher.runDispatcher() + (None, 0, 0, [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.1.0')), DisplayString('SunOS zeus.snmplabs.com 4.1.3_U1 1 sun4m'))]) + >>> + + """ def __cbFun(snmpEngine, sendRequestHandle, errorIndication, errorStatus, errorIndex, varBinds, cbCtx): diff --git a/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py b/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py index b3a42d7..5c82718 100644 --- a/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py +++ b/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py @@ -25,13 +25,13 @@ def getCmd(snmpEngine, authData, transportTarget, contextData, contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` Class instance representing SNMP ContextEngineId and ContextName values. - *varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` + \*varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` One or more class instances representing MIB variables to place into SNMP request. Other Parameters ---------------- - **options : + \*\*options : Request options: * `lookupMib` - load MIB and resolve response MIB variables at @@ -134,13 +134,13 @@ def setCmd(snmpEngine, authData, transportTarget, contextData, contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` Class instance representing SNMP ContextEngineId and ContextName values. - *varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` + \*varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` One or more class instances representing MIB variables to place into SNMP request. Other Parameters ---------------- - **options : + \*\*options : Request options: * `lookupMib` - load MIB and resolve response MIB variables at @@ -245,13 +245,13 @@ def nextCmd(snmpEngine, authData, transportTarget, contextData, contextData : :py:class:`~pysnmp.entity.rfc3413.oneliner.ctx.ContextData` Class instance representing SNMP ContextEngineId and ContextName values. - *varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` + \*varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` One or more class instances representing MIB variables to place into SNMP request. Other Parameters ---------------- - **options : + \*\*options : Request options: * `lookupMib` - load MIB and resolve response MIB variables at @@ -428,13 +428,13 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData, `nonRepeaters`). Remote SNMP engine may choose lesser value than requested. - *varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` + \*varBinds : :py:class:`~pysnmp.smi.rfc1902.ObjectType` One or more class instances representing MIB variables to place into SNMP request. Other Parameters ---------------- - **options : + \*\*options : Request options: * `lookupMib` - load MIB and resolve response MIB variables at diff --git a/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py b/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py index 16f3930..e16fd7c 100644 --- a/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py +++ b/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py @@ -40,7 +40,7 @@ def sendNotification(snmpEngine, authData, transportTarget, contextData, Other Parameters ---------------- - **options : + \*\*options : Request options: * `lookupMib` - load MIB and resolve response MIB variables at @@ -53,7 +53,7 @@ def sendNotification(snmpEngine, authData, transportTarget, contextData, errorStatus : str Non-zero value indicates SNMP PDU error. errorIndex : int - Non-zero value refers to *varBinds[errorIndex-1] + Non-zero value refers to \*varBinds[errorIndex-1] varBinds : tuple A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances representing MIB variables returned in SNMP response. -- cgit v1.2.1