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

diff --git a/examples/hlapi/v3arch/twisted/manager/cmdgen/v1-get.py b/examples/hlapi/v3arch/twisted/manager/cmdgen/v1-get.py
new file mode 100644
index 00000000..e483354d
--- /dev/null
+++ b/examples/hlapi/v3arch/twisted/manager/cmdgen/v1-get.py
@@ -0,0 +1,51 @@
+"""
+SNMPv1
+++++++
+
+Send SNMP GET request using the following options:
+
+* with SNMPv1, community 'public'
+* over IPv4/UDP
+* to an Agent at demo.snmplabs.com:161
+* for two instances of SNMPv2-MIB::sysDescr.0 MIB object,
+* based on Twisted I/O framework
+
+Functionally similar to:
+
+| $ snmpget -v1 -c public demo.snmplabs.com SNMPv2-MIB::sysDescr.0
+
+"""#
+from twisted.internet.task import react
+from pysnmp.hlapi.v3arch.twisted import *
+
+
+def success(args, hostname):
+    (errorStatus, errorIndex, varBinds) = args
+
+    if errorStatus:
+        print('%s: %s at %s' % (hostname,
+                                errorStatus.prettyPrint(),
+                                errorIndex and varBinds[int(errorIndex) - 1][0] or '?'))
+    else:
+        for varBind in varBinds:
+            print(' = '.join([x.prettyPrint() for x in varBind]))
+
+
+def failure(errorIndication, hostname):
+    print('%s failure: %s' % (hostname, errorIndication))
+
+
+# noinspection PyUnusedLocal
+def getSysDescr(reactor, hostname):
+    d = getCmd(SnmpEngine(),
+               CommunityData('public', mpModel=0),
+               UdpTransportTarget((hostname, 161)),
+               ContextData(),
+               ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0)))
+
+    d.addCallback(success, hostname).addErrback(failure, hostname)
+
+    return d
+
+
+react(getSysDescr, ['demo.snmplabs.com'])