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, 44 insertions, 0 deletions

diff --git a/examples/hlapi/v1arch/asyncore/manager/cmdgen/v2c-get.py b/examples/hlapi/v1arch/asyncore/manager/cmdgen/v2c-get.py
new file mode 100644
index 00000000..9ce8d7dd
--- /dev/null
+++ b/examples/hlapi/v1arch/asyncore/manager/cmdgen/v2c-get.py
@@ -0,0 +1,44 @@
+"""
+SNMP GET over SNMPv2c
++++++++++++++++++++++
+
+Send SNMP GET request using the following options:
+
+  * with SNMPv2c, community 'public'
+  * over IPv4/UDP
+  * to an Agent at demo.snmplabs.com:161
+  * for the 1.3.6.1.2.1.1.1.0 OID (e.g. SNMPv2-MIB::sysDescr.0 MIB object)
+
+Functionally similar to:
+
+| $ snmpget -v2c -c public demo.snmplabs.com 1.3.6.1.2.1.1.1.0
+
+"""#
+
+from pysnmp.hlapi.v1arch.asyncore import *
+
+
+def cbFun(errorIndication, errorStatus, errorIndex, varBinds, **context):
+    if errorIndication:
+        print(errorIndication)
+        return
+    elif errorStatus:
+        print('%s at %s' % (errorStatus.prettyPrint(),
+                            errorIndex and varBindTable[-1][int(errorIndex) - 1][0] or '?'))
+        return
+    else:
+        for varBind in varBinds:
+            print(' = '.join([x.prettyPrint() for x in varBind]))
+
+
+snmpDispatcher = SnmpDispatcher()
+
+stateHandle = getCmd(
+    snmpDispatcher,
+    CommunityData('public'),
+    UdpTransportTarget(('demo.snmplabs.com', 161)),
+    ('1.3.6.1.2.1.1.1.0', None),
+    cbFun=cbFun
+)
+
+snmpDispatcher.transportDispatcher.runDispatcher()