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

diff --git a/examples/hlapi/v3arch/twisted/agent/ntforg/multiple-notifications-at-once.py b/examples/hlapi/v3arch/twisted/agent/ntforg/multiple-notifications-at-once.py
new file mode 100644
index 00000000..c234a827
--- /dev/null
+++ b/examples/hlapi/v3arch/twisted/agent/ntforg/multiple-notifications-at-once.py
@@ -0,0 +1,77 @@
+"""
+Multiple concurrent notifications
++++++++++++++++++++++++++++++++++
+
+Send multiple SNMP notifications at once using the following options:
+
+* SNMPv2c
+* with community name 'public'
+* over IPv4/UDP
+* send TRAP and INFORM notification
+* to multiple Managers
+* with TRAP ID 'coldStart' specified as a MIB symbol
+* include managed object information specified as var-bind objects pair
+
+Here we tag each SNMP-COMMUNITY-MIB::snmpCommunityTable row
+with the same tag as SNMP-TARGET-MIB::snmpTargetAddrTable row
+what leads to excessive tables information.
+
+Functionally similar to:
+
+| $ snmptrap -v2c -c public demo.snmplabs.com 12345 1.3.6.1.6.3.1.1.5.2
+| $ snmpinform -v2c -c public demo.snmplabs.com 12345 1.3.6.1.6.3.1.1.5.2
+
+"""#
+from twisted.internet.defer import DeferredList
+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 sendone(reactor, snmpEngine, hostname, notifyType):
+    d = sendNotification(
+        snmpEngine,
+        CommunityData('public', tag=hostname),
+        UdpTransportTarget((hostname, 162), tagList=hostname),
+        ContextData(),
+        notifyType,
+        NotificationType(
+            ObjectIdentity('1.3.6.1.6.3.1.1.5.2')
+        ).loadMibs(
+            'SNMPv2-MIB'
+        ).addVarBinds(
+            ('1.3.6.1.6.3.1.1.4.3.0', '1.3.6.1.4.1.20408.4.1.1.2'),
+            ('1.3.6.1.2.1.1.1.0', OctetString('my system'))
+        )
+    )
+    d.addCallback(success, hostname).addErrback(failure, hostname)
+    return d
+
+
+def sendall(reactor, destinations):
+    snmpEngine = SnmpEngine()
+
+    return DeferredList(
+        [sendone(reactor, snmpEngine, hostname, notifyType)
+         for hostname, notifyType in destinations]
+    )
+
+
+react(sendall, [[('demo.snmplabs.com', 'trap'),
+                 ('demo.snmplabs.com', 'inform')]])