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

diff --git a/examples/hlapi/v3arch/asyncio/agent/ntforg/default-v1-trap.py b/examples/hlapi/v3arch/asyncio/agent/ntforg/default-v1-trap.py
new file mode 100644
index 00000000..6a0fefda
--- /dev/null
+++ b/examples/hlapi/v3arch/asyncio/agent/ntforg/default-v1-trap.py
@@ -0,0 +1,52 @@
+"""
+SNMPv1 TRAP with defaults
++++++++++++++++++++++++++
+
+Send SNMPv1 TRAP through unified SNMPv3 message processing framework
+using the following options:
+
+* SNMPv1
+* with community name 'public'
+* over IPv4/UDP
+* send TRAP notification
+* with Generic Trap #1 (warmStart) and Specific Trap 0
+* with default Uptime
+* with default Agent Address
+* with Enterprise OID 1.3.6.1.4.1.20408.4.1.1.2
+* include managed object information '1.3.6.1.2.1.1.1.0' = 'my system'
+
+Functionally similar to:
+
+| $ snmptrap -v1 -c public demo.snmplabs.com 1.3.6.1.4.1.20408.4.1.1.2 0.0.0.0 1 0 0 1.3.6.1.2.1.1.1.0 s "my system"
+
+"""#
+import asyncio
+from pysnmp.hlapi.v3arch.asyncio import *
+
+
+@asyncio.coroutine
+def run():
+    snmpEngine = SnmpEngine()
+    errorIndication, errorStatus, errorIndex, varBinds = yield from sendNotification(
+        snmpEngine,
+        CommunityData('public', mpModel=0),
+        UdpTransportTarget(('demo.snmplabs.com', 162)),
+        ContextData(),
+        'trap',
+        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'))
+        )
+    )
+
+    if errorIndication:
+        print(errorIndication)
+
+    snmpEngine.transportDispatcher.closeDispatcher()
+
+
+asyncio.get_event_loop().run_until_complete(run())