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

diff --git a/examples/hlapi/v3arch/asyncore/sync/manager/cmdgen/pull-whole-mib.py b/examples/hlapi/v3arch/asyncore/sync/manager/cmdgen/pull-whole-mib.py
new file mode 100644
index 00000000..b9103de3
--- /dev/null
+++ b/examples/hlapi/v3arch/asyncore/sync/manager/cmdgen/pull-whole-mib.py
@@ -0,0 +1,37 @@
+"""
+Walk whole MIB
+++++++++++++++
+
+Send a series of SNMP GETNEXT requests using the following options:
+
+* with SNMPv3, user 'usr-md5-none', MD5 authentication, no privacy
+* over IPv4/UDP
+* to an Agent at demo.snmplabs.com:161
+* for all OIDs in IF-MIB
+
+Functionally similar to:
+
+| $ snmpwalk -v3 -lauthPriv -u usr-md5-none -A authkey1 -X privkey1 demo.snmplabs.com  IF-MIB::
+
+"""#
+from pysnmp.hlapi import *
+
+for (errorIndication,
+     errorStatus,
+     errorIndex,
+     varBinds) in nextCmd(SnmpEngine(),
+                          UsmUserData('usr-md5-none', 'authkey1'),
+                          UdpTransportTarget(('demo.snmplabs.com', 161)),
+                          ContextData(),
+                          ObjectType(ObjectIdentity('IF-MIB'))):
+
+    if errorIndication:
+        print(errorIndication)
+        break
+    elif errorStatus:
+        print('%s at %s' % (errorStatus.prettyPrint(),
+                            errorIndex and varBinds[int(errorIndex) - 1][0] or '?'))
+        break
+    else:
+        for varBind in varBinds:
+            print(' = '.join([x.prettyPrint() for x in varBind]))