summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorelie <elie>2015-09-17 06:47:38 +0000
committerelie <elie>2015-09-17 06:47:38 +0000
commit6f91630f15177c440ee8d6e4b53d0a9abc69ab5c (patch)
treef9c15df05c28faaee64a6e4297c3be5c53cc3d87
parent5b7b13000f75e409138c758b29363c8d17b0fa58 (diff)
downloadpysnmp-6f91630f15177c440ee8d6e4b53d0a9abc69ab5c.tar.gz
* documenting async command generator
* minor fixes to markup
-rw-r--r--pysnmp/entity/engine.py4
-rw-r--r--pysnmp/entity/rfc3413/oneliner/cmdgen.py102
-rw-r--r--pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py16
-rw-r--r--pysnmp/entity/rfc3413/oneliner/sync/ntforg.py4
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.