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

1 files changed, 54 insertions, 0 deletions

diff --git a/examples/hlapi/v3arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py b/examples/hlapi/v3arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py
new file mode 100644
index 00000000..a1b5d9a0
--- /dev/null
+++ b/examples/hlapi/v3arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py
@@ -0,0 +1,54 @@
+"""
+Concurrent queries
+++++++++++++++++++
+
+Send multiple SNMP GET requests at once using the following options:
+
+* with SNMPv2c, community 'public'
+* over IPv4/UDP
+* to multiple Agents at demo.snmplabs.com
+* for instance of SNMPv2-MIB::sysDescr.0 MIB object
+* based on asyncio I/O framework
+
+Functionally similar to:
+
+| $ snmpget -v2c -c public demo.snmplabs.com:1161 SNMPv2-MIB::sysDescr.0
+| $ snmpget -v2c -c public demo.snmplabs.com:2161 SNMPv2-MIB::sysDescr.0
+| $ snmpget -v2c -c public demo.snmplabs.com:3161 SNMPv2-MIB::sysDescr.0
+
+"""#
+import asyncio
+from pysnmp.hlapi.v3arch.asyncio import *
+
+
+@asyncio.coroutine
+def getone(snmpEngine, hostname):
+    errorIndication, errorStatus, errorIndex, varBinds = yield from getCmd(
+        snmpEngine,
+        CommunityData('public'),
+        UdpTransportTarget(hostname),
+        ContextData(),
+        ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0))
+    )
+
+    if errorIndication:
+        print(errorIndication)
+    elif errorStatus:
+        print('%s at %s' % (
+            errorStatus.prettyPrint(),
+            errorIndex and varBinds[int(errorIndex) - 1][0] or '?'
+        )
+              )
+    else:
+        for varBind in varBinds:
+            print(' = '.join([x.prettyPrint() for x in varBind]))
+
+
+snmpEngine = SnmpEngine()
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(
+    asyncio.wait([getone(snmpEngine, ('demo.snmplabs.com', 1161)),
+                  getone(snmpEngine, ('demo.snmplabs.com', 2161)),
+                  getone(snmpEngine, ('demo.snmplabs.com', 3161))])
+)