async command generator documented + fixes

5 files changed, 320 insertions, 35 deletions

diff --git a/TODO.txt b/TODO.txt
index ae8ded1..3d2117d 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -54,3 +54,12 @@ Sparse notes on major existing problems/plans
   may need a means to deal only with specific node types.
 
 * redesign proto.errind.ErrorIndication
+
+* move LCD and var-bind management routines from Async* classes
+
+* make oneliner helper routines more general, not bound to asyncore-based
+  implementation
+
+* improve oneliner modules layout to make it possible to create more
+  transport-specific oneliner interfaces
+ 
diff --git a/docs/source/docs/v3arch/asyncore/oneliner/contents.rst b/docs/source/docs/v3arch/asyncore/oneliner/contents.rst
index 5a52135..2c0e3a8 100644
--- a/docs/source/docs/v3arch/asyncore/oneliner/contents.rst
+++ b/docs/source/docs/v3arch/asyncore/oneliner/contents.rst
@@ -21,6 +21,11 @@ other tasks till pending message is sent out (by I/O dispacher) and
 response is arrived. At that point a previously supplied callback function
 will be invoked and response data will be passed along.
 
+SNMP security configuration is conveyed to SNMP engine via
+:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData`
+and :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData`
+classes:
+
 .. toctree::
    :maxdepth: 2
 
@@ -35,17 +40,6 @@ operations as well as for rapid prototyping.
 .. toctree::
    :maxdepth: 2
 
-   /docs/v3arch/asyncore/oneliner/manager/cmdgen/async.rst
-   /docs/v3arch/asyncore/oneliner/agent/ntforg/async.rst
-
-SNMP security configuration is conveyed to SNMP engine via
-:py:class:`~pysnmp.entity.rfc3413.oneliner.auth.CommunityData`
-and :py:class:`~pysnmp.entity.rfc3413.oneliner.auth.UsmUserData`
-classes:
-
-.. toctree::
-   :maxdepth: 2
-
    /docs/v3arch/asyncore/oneliner/security-configuration
 
 Type of network transport SNMP engine uses along with transport
diff --git a/pysnmp/entity/rfc3413/oneliner/cmdgen.py b/pysnmp/entity/rfc3413/oneliner/cmdgen.py
index d6f51e4..31a4e45 100644
--- a/pysnmp/entity/rfc3413/oneliner/cmdgen.py
+++ b/pysnmp/entity/rfc3413/oneliner/cmdgen.py
@@ -231,17 +231,17 @@ class AsyncCommandGenerator:
 
         return __varBinds
 
-    def unmakeVarBinds(self, snmpEngine, varBinds, lookupMib=False):
+    def unmakeVarBinds(self, snmpEngine, varBinds, lookupMib=True):
         if lookupMib:
             mibViewController = self.getMibViewController(snmpEngine)
             varBinds = [ ObjectType(ObjectIdentity(x[0]), x[1]).resolveWithMib(mibViewController) for x in varBinds ]
 
         return varBinds
 
-    # Async SNMP apps
+    # Standard SNMP apps follow
 
     def getCmd(self, snmpEngine, authData, transportTarget, contextData, 
-               varBinds, cbInfo, lookupMib=False):
+               varBinds, cbInfo, lookupMib=True):
         """Performs SNMP GET query.
 
         Based on passed parameters, prepares SNMP GET packet 
@@ -257,14 +257,16 @@ class AsyncCommandGenerator:
             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.
+            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.
+            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.
+        varBinds : tuple
+            A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` class
+            instances representing MIB variables to place into SNMP request.
    
         cbInfo : tuple
 
@@ -277,7 +279,7 @@ class AsyncCommandGenerator:
         ----------------
         lookupMib : bool
             `lookupMib` - load MIB and resolve response MIB variables at
-            the cost of slightly reduced performance. Default is `False`.
+            the cost of slightly reduced performance. Default is `True`.
 
         Notes
         -----
@@ -289,11 +291,12 @@ class AsyncCommandGenerator:
         * 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]
+        * errorStatus (str): True 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.
+          representing MIB variables returned in SNMP response in exactly
+          the same order as `varBinds` in request.
         * `cbCtx` : Original user-supplied object.
 
         Returns
@@ -359,7 +362,95 @@ class AsyncCommandGenerator:
         )
     
     def setCmd(self, snmpEngine, authData, transportTarget, contextData,
-               varBinds, cbInfo, lookupMib=False):
+               varBinds, cbInfo, lookupMib=True):
+        """Performs SNMP SET query.
+
+        Based on passed parameters, prepares SNMP SET packet 
+        (:RFC:`1905#section-4.2.5`) 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 : tuple
+            A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` 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 `True`.
+
+        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): True 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 in exactly
+          the same order as `varBinds` in request.
+        * `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.setCmd(snmpEngine,
+        ...          CommunityData('public'),
+        ...          UdpTransportTarget(('demo.snmplabs.com', 161)),
+        ...          ContextData(),
+        ...          ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysContact', 0), 'info@snmplabs.com'),
+        ...          (cbFun, None))
+        >>> snmpEngine.transportDispatcher.runDispatcher()
+        (None, 0, 0, [ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.4.0')), DisplayString('info@snmplabs.com'))])
+        >>>
+
+        """
         def __cbFun(snmpEngine, sendRequestHandle,
                     errorIndication, errorStatus, errorIndex,
                     varBinds, cbCtx):
@@ -392,7 +483,97 @@ class AsyncCommandGenerator:
         )
     
     def nextCmd(self, snmpEngine, authData, transportTarget, contextData,
-                varBinds, cbInfo, lookupMib=False):
+                varBinds, cbInfo, lookupMib=True):
+        """Performs SNMP GETNEXT query.
+
+        Based on passed parameters, prepares SNMP GETNEXT packet 
+        (:RFC:`1905#section-4.2.2`) 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 : tuple
+            A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` 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 `True`.
+
+        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): True value indicates SNMP PDU error.
+        * errorIndex (int): Non-zero value refers to `varBinds[errorIndex-1]`
+        * varBinds (tuple): A sequence of sequences (e.g. 2-D array) of
+          :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances
+          representing a table of MIB variables returned in SNMP response.
+          Inner sequences represent table rows and ordered exactly the same
+          as `varBinds` in request. Response to GETNEXT always contain a
+          single row.
+        * `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.nextCmd(snmpEngine,
+        ...           CommunityData('public'),
+        ...           UdpTransportTarget(('demo.snmplabs.com', 161)),
+        ...           ContextData(),
+        ...           ObjectType(ObjectIdentity('SNMPv2-MIB', 'system')),
+        ...           (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,
                     varBindTable, cbCtx):
@@ -422,7 +603,108 @@ class AsyncCommandGenerator:
 
     def bulkCmd(self, snmpEngine, authData, transportTarget, contextData,
                 nonRepeaters, maxRepetitions, varBinds, cbInfo,
-                lookupMib=False):
+                lookupMib=True):
+        """Performs SNMP GETBULK query.
+
+        Based on passed parameters, prepares SNMP GETBULK packet 
+        (:RFC:`1905#section-4.2.3`) 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.
+
+        nonRepeaters : int
+            One MIB variable is requested in response for the first 
+            `nonRepeaters` MIB variables in request.
+
+        maxRepetitions : int
+            `maxRepetitions` MIB variables are requested in response for each
+            of the remaining MIB variables in the request (e.g. excluding
+            `nonRepeaters`). Remote SNMP engine may choose lesser value than
+            requested.
+
+        varBinds : tuple
+            A sequence of :py:class:`~pysnmp.smi.rfc1902.ObjectType` 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 `True`.
+
+        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): True value indicates SNMP PDU error.
+        * errorIndex (int): Non-zero value refers to `varBinds[errorIndex-1]`
+        * varBinds (tuple): A sequence of sequences (e.g. 2-D array) of
+          :py:class:`~pysnmp.smi.rfc1902.ObjectType` class instances
+          representing a table of MIB variables returned in SNMP response.
+          Inner sequences represent table rows and ordered exactly the same
+          as `varBinds` in request. Number of rows might be less or equal
+          to `maxRepetitions` value in request.
+        * `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.bulkCmd(snmpEngine,
+        ...           CommunityData('public'),
+        ...           UdpTransportTarget(('demo.snmplabs.com', 161)),
+        ...           ContextData(),
+        ...           0, 2,
+        ...           ObjectType(ObjectIdentity('SNMPv2-MIB', 'system')),
+        ...           (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')), ObjectType(ObjectIdentity(ObjectName('1.3.6.1.2.1.1.2.0')), ObjectIdentifier('1.3.6.1.4.1.424242.1.1')] ])
+        >>>
+
+        """
         def __cbFun(snmpEngine, sendRequestHandle,
                     errorIndication, errorStatus, errorIndex,
                     varBindTable, cbCtx):
diff --git a/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py b/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py
index 5c82718..c0f8af1 100644
--- a/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py
+++ b/pysnmp/entity/rfc3413/oneliner/sync/cmdgen.py
@@ -42,9 +42,9 @@ def getCmd(snmpEngine, authData, transportTarget, contextData,
     errorIndication : str
         True value indicates SNMP engine error.
     errorStatus : str
-        Non-zero value indicates SNMP PDU error.
+        True 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.
@@ -152,9 +152,9 @@ def setCmd(snmpEngine, authData, transportTarget, contextData,
     errorIndication : str
         True value indicates SNMP engine error.
     errorStatus : str
-        Non-zero value indicates SNMP PDU error.
+        True 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.
@@ -273,9 +273,9 @@ def nextCmd(snmpEngine, authData, transportTarget, contextData,
     errorIndication : str
         True value indicates SNMP engine error.
     errorStatus : str
-        Non-zero value indicates SNMP PDU error.
+        True 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.
@@ -456,7 +456,7 @@ def bulkCmd(snmpEngine, authData, transportTarget, contextData,
     errorIndication : str
         True value indicates SNMP engine error.
     errorStatus : str
-        Non-zero value indicates SNMP PDU error.
+        True value indicates SNMP PDU error.
     errorIndex : int
         Non-zero value refers to *varBinds[errorIndex-1]
     varBinds : tuple
diff --git a/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py b/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py
index e16fd7c..93e047e 100644
--- a/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py
+++ b/pysnmp/entity/rfc3413/oneliner/sync/ntforg.py
@@ -51,9 +51,9 @@ def sendNotification(snmpEngine, authData, transportTarget, contextData,
     errorIndication : str
         True value indicates SNMP engine error.
     errorStatus : str
-        Non-zero value indicates SNMP PDU error.
+        True 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.