Add `hlapi.v1arch` API (#186)

* Add `hlapi.v1arch` API

Introduce new sub-package `pysnmp.hlapi.v1arch` which
wraps otherwise very detailed packet-level SNMP
messaging into a handful of convenience functions.

As a side effect, the `pysnmp.hlapi.*` sub-packages
moved under `pysnmp.hlapi.v3arch` though `pysnmp.hlapi`
still exposes `pysnmp.hlappi.v3arch.*` symbols to
retain some degree of backward compatibility.

The signature of the hlapi `.sendNotification()` call
has changed to accept `*varBinds` instead of a sequence
of `varBinds`. The rationale is to unify this method
call with similar methods of CommandGenerator.

* Add v1arch docs and reshuffle hlapi docs

2 files changed, 38 insertions, 6 deletions

diff --git a/pysnmp/proto/api/v1.py b/pysnmp/proto/api/v1.py
index 709a0b68..e6a138df 100644
--- a/pysnmp/proto/api/v1.py
+++ b/pysnmp/proto/api/v1.py
@@ -139,12 +139,20 @@ class PDUAPI(object):
 
     def getVarBindTable(self, reqPDU, rspPDU):
         if apiPDU.getErrorStatus(rspPDU) == 2:
-            varBindRow = []
-            for varBind in apiPDU.getVarBinds(reqPDU):
-                varBindRow.append((varBind[0], null))
-            return [varBindRow]
+            varBindRow = [(vb[0], null) for vb in apiPDU.getVarBinds(reqPDU)]
         else:
-            return [apiPDU.getVarBinds(rspPDU)]
+            varBindRow = apiPDU.getVarBinds(rspPDU)
+        return [varBindRow]
+
+    def getNextVarBinds(self, varBinds, errorIndex=None):
+        errorIndication = None
+
+        if errorIndex:
+            return errorIndication, []
+
+        rspVarBinds = [(vb[0], null) for vb in varBinds]
+
+        return errorIndication, rspVarBinds
 
 
 apiPDU = PDUAPI()
diff --git a/pysnmp/proto/api/v2c.py b/pysnmp/proto/api/v2c.py
index eec78e79..cf381ced 100644
--- a/pysnmp/proto/api/v2c.py
+++ b/pysnmp/proto/api/v2c.py
@@ -60,6 +60,25 @@ class PDUAPI(v1.PDUAPI):
     def getVarBindTable(self, reqPDU, rspPDU):
         return [apiPDU.getVarBinds(rspPDU)]
 
+    def getNextVarBinds(self, varBinds, errorIndex=None):
+        errorIndication = None
+
+        rspVarBinds = []
+
+        if errorIndex:
+            return errorIndication, rspVarBinds
+
+        for idx, varBind in enumerate(varBinds):
+            if varBind[1].tagSet in (
+                    rfc1905.NoSuchObject.tagSet,
+                    rfc1905.NoSuchInstance.tagSet,
+                    rfc1905.EndOfMibView.tagSet):
+                continue
+
+            rspVarBinds.append((varBind[0], null))
+
+        return errorIndication, rspVarBinds
+
     def setEndOfMibError(self, pdu, errorIndex):
         varBindList = self.getVarBindList(pdu)
         varBindList[errorIndex - 1].setComponentByPosition(
@@ -115,10 +134,15 @@ class BulkPDUAPI(PDUAPI):
         reqVarBinds = self.getVarBinds(reqPDU)
 
         N = min(int(nonRepeaters), len(reqVarBinds))
-        R = max(len(reqVarBinds) - N, 0)
 
         rspVarBinds = self.getVarBinds(rspPDU)
 
+        # shortcut for the most trivial case
+        if N == 0 and len(reqVarBinds) == 1:
+            return [[vb] for vb in rspVarBinds]
+
+        R = max(len(reqVarBinds) - N, 0)
+
         varBindTable = []
 
         if R: