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

diff --git a/examples/hlapi/v3arch/asyncore/sync/agent/ntforg/v3-inform.py b/examples/hlapi/v3arch/asyncore/sync/agent/ntforg/v3-inform.py
new file mode 100644
index 00000000..6f02024f
--- /dev/null
+++ b/examples/hlapi/v3arch/asyncore/sync/agent/ntforg/v3-inform.py
@@ -0,0 +1,45 @@
+"""
+INFORM, auth: MD5 privacy: DES
+++++++++++++++++++++++++++++++
+
+Send SNMP INFORM notification using the following options:
+
+* SNMPv3
+* with user 'usr-md5-des', auth: MD5, priv DES
+* over IPv4/UDP
+* send INFORM notification
+* with TRAP ID 'warmStart' specified as a string OID
+* include managed object information 1.3.6.1.2.1.1.5.0 = 'system name'
+
+Functionally similar to:
+
+| $ snmpinform -v3 -l authPriv -u usr-md5-des -A authkey1 -X privkey1 demo.snmplabs.com 12345 1.3.6.1.4.1.20408.4.1.1.2 1.3.6.1.2.1.1.1.0 s "my system"
+
+"""#
+from pysnmp.hlapi import *
+
+errorIndication, errorStatus, errorIndex, varBinds = next(
+    sendNotification(
+        SnmpEngine(),
+        UsmUserData('usr-md5-des', 'authkey1', 'privkey1'),
+        UdpTransportTarget(('demo.snmplabs.com', 162)),
+        ContextData(),
+        'inform',
+        NotificationType(
+            ObjectIdentity('1.3.6.1.6.3.1.1.5.2')
+        ).addVarBinds(
+             ObjectType(ObjectIdentity('1.3.6.1.2.1.1.5.0'), 'system name')
+        ).loadMibs(
+            'SNMPv2-MIB'
+        )
+    )
+)
+
+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]))