Introduce asyncio binding to hlapi.v1arch (#244)

The hlapi.v1arch asyncio API is intended to be very similar to
hlapi.v3arch.asyncio from its signature viewpoint, however it
should be faster at the expense of no SNMPv3 support.

6 files changed, 357 insertions, 0 deletions

diff --git a/examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py b/examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py
new file mode 100644
index 00000000..d63332f9
--- /dev/null
+++ b/examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py
@@ -0,0 +1,55 @@
+"""
+SNMPv1 TRAP with defaults
++++++++++++++++++++++++++
+
+Send SNMPv1 TRAP 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.v1arch.asyncio import *
+
+
+@asyncio.coroutine
+def run():
+
+    snmpDispatcher = SnmpDispatcher()
+
+    iterator = sendNotification(
+        snmpDispatcher,
+        CommunityData('public', mpModel=0),
+        UdpTransportTarget(('demo.snmplabs.com', 162)),
+        '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'))
+        )
+    )
+
+    errorIndication, errorStatus, errorIndex, varBinds = yield from iterator
+
+    if errorIndication:
+        print(errorIndication)
+
+    snmpDispatcher.transportDispatcher.closeDispatcher()
+
+
+asyncio.get_event_loop().run_until_complete(run())
diff --git a/examples/hlapi/v1arch/asyncio/agent/ntforg/multiple-notifications-at-once.py b/examples/hlapi/v1arch/asyncio/agent/ntforg/multiple-notifications-at-once.py
new file mode 100644
index 00000000..f81c909d
--- /dev/null
+++ b/examples/hlapi/v1arch/asyncio/agent/ntforg/multiple-notifications-at-once.py
@@ -0,0 +1,59 @@
+"""
+Multiple concurrent notifications
++++++++++++++++++++++++++++++++++
+
+Send multiple SNMP notifications at once using the following options:
+
+* SNMPv2c
+* with community name 'public'
+* over IPv4/UDP
+* send INFORM notification
+* to multiple Managers
+* with TRAP ID 'coldStart' specified as a MIB symbol
+
+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
+
+"""#
+import asyncio
+from pysnmp.hlapi.v1arch.asyncio import *
+
+
+@asyncio.coroutine
+def sendone(snmpDispatcher, hostname, notifyType):
+
+    iterator = sendNotification(
+        snmpDispatcher,
+        CommunityData('public'),
+        UdpTransportTarget((hostname, 162)),
+        notifyType,
+        NotificationType(
+            ObjectIdentity('1.3.6.1.6.3.1.1.5.2')
+        ).loadMibs('SNMPv2-MIB')
+    )
+
+    errorIndication, errorStatus, errorIndex, varBinds = yield from iterator
+
+    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]))
+
+
+snmpDispatcher = SnmpDispatcher()
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(
+    asyncio.wait(
+        [sendone(snmpDispatcher, 'demo.snmplabs.com', 'trap'),
+         sendone(snmpDispatcher, 'demo.snmplabs.com', 'inform')]
+    )
+)
diff --git a/examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py b/examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
new file mode 100644
index 00000000..c0532c09
--- /dev/null
+++ b/examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
@@ -0,0 +1,65 @@
+"""
+Bulk walk MIB
++++++++++++++
+
+Send a series of SNMP GETBULK requests using the following options:
+
+* with SNMPv2c, community 'public'
+* over IPv4/UDP
+* to an Agent at demo.snmplabs.com:161
+* for all OIDs past SNMPv2-MIB::system
+* run till end-of-mib condition is reported by Agent
+* based on asyncio I/O framework
+
+Functionally similar to:
+
+| $ snmpbulkwalk -v2c -c public -Cn0 -Cr50 \
+|                demo.snmplabs.com  SNMPv2-MIB::system
+
+"""#
+import asyncio
+from pysnmp.hlapi.v1arch.asyncio import *
+
+
+@asyncio.coroutine
+def run(varBinds):
+
+    snmpDispatcher = SnmpDispatcher()
+
+    while True:
+        iterator = bulkCmd(
+            snmpDispatcher,
+            CommunityData('public'),
+            UdpTransportTarget(('demo.snmplabs.com', 161)),
+            0, 50,
+            *varBinds
+        )
+
+        errorIndication, errorStatus, errorIndex, varBindTable = yield from iterator
+
+        if errorIndication:
+            print(errorIndication)
+            break
+
+        elif errorStatus:
+            print('%s at %s' % (
+                errorStatus.prettyPrint(),
+                errorIndex and varBinds[int(errorIndex) - 1][0] or '?'
+            )
+                  )
+        else:
+            for varBindRow in varBindTable:
+                for varBind in varBindRow:
+                    print(' = '.join([x.prettyPrint() for x in varBind]))
+
+        varBinds = varBindTable[-1]
+        if isEndOfMib(varBinds):
+            break
+
+    snmpDispatcher.transportDispatcher.closeDispatcher()
+
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(
+    run([ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'))])
+)
diff --git a/examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py b/examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py
new file mode 100644
index 00000000..f0e14ae5
--- /dev/null
+++ b/examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py
@@ -0,0 +1,59 @@
+"""
+Concurrent queries
+++++++++++++++++++
+
+Send multiple SNMP GET requests at once using the following options:
+
+* with SNMPv2c, community 'public'
+* over IPv4/UDP
+* to multiple Agents at demo.snmplabs.com
+* for instance of SNMPv2-MIB::sysDescr.0 MIB object
+* based on asyncio I/O framework
+
+Functionally similar to:
+
+| $ snmpget -v2c -c public demo.snmplabs.com:1161 SNMPv2-MIB::sysDescr.0
+| $ snmpget -v2c -c public demo.snmplabs.com:2161 SNMPv2-MIB::sysDescr.0
+| $ snmpget -v2c -c public demo.snmplabs.com:3161 SNMPv2-MIB::sysDescr.0
+
+"""#
+import asyncio
+from pysnmp.hlapi.v1arch.asyncio import *
+
+
+@asyncio.coroutine
+def getone(snmpDispatcher, hostname):
+
+    iterator = getCmd(
+        snmpDispatcher,
+        CommunityData('public'),
+        UdpTransportTarget(hostname),
+        ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0))
+    )
+
+    errorIndication, errorStatus, errorIndex, varBinds = yield from iterator
+
+    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]))
+
+
+snmpDispatcher = SnmpDispatcher()
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(
+    asyncio.wait(
+        [getone(snmpDispatcher, ('demo.snmplabs.com', 1161)),
+         getone(snmpDispatcher, ('demo.snmplabs.com', 2161)),
+         getone(snmpDispatcher, ('demo.snmplabs.com', 3161))]
+    )
+)
diff --git a/examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-sequential-queries.py b/examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-sequential-queries.py
new file mode 100644
index 00000000..3ce3c232
--- /dev/null
+++ b/examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-sequential-queries.py
@@ -0,0 +1,68 @@
+"""
+Sequential queries
+++++++++++++++++++
+
+Send multiple SNMP GET requests one by one using the following options:
+
+* with SNMPv2c, community 'public'
+* over IPv4/UDP
+* to multiple Agents at demo.snmplabs.com
+* for instance of SNMPv2-MIB::sysDescr.0 MIB object
+* based on asyncio I/O framework
+
+Functionally similar to:
+
+| $ snmpget -v2c -c public demo.snmplabs.com:1161 SNMPv2-MIB::sysDescr.0
+| $ snmpget -v2c -c public demo.snmplabs.com:2161 SNMPv2-MIB::sysDescr.0
+| $ snmpget -v2c -c public demo.snmplabs.com:3161 SNMPv2-MIB::sysDescr.0
+
+"""#
+import asyncio
+from pysnmp.hlapi.v1arch.asyncio import *
+
+
+@asyncio.coroutine
+def getone(snmpDispatcher, hostname):
+
+    iterator = getCmd(
+        snmpDispatcher,
+        CommunityData('public'),
+        UdpTransportTarget(hostname),
+        ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0))
+    )
+
+    errorIndication, errorStatus, errorIndex, varBinds = yield from iterator
+
+    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]))
+
+
+@asyncio.coroutine
+def getall(snmpDispatcher, hostnames):
+    for hostname in hostnames:
+        yield from getone(snmpDispatcher, hostname)
+
+
+snmpDispatcher = SnmpDispatcher()
+
+loop = asyncio.get_event_loop()
+
+loop.run_until_complete(
+    getall(
+        snmpDispatcher, [
+            ('demo.snmplabs.com', 1161),
+            ('demo.snmplabs.com', 2161),
+            ('demo.snmplabs.com', 3161)
+        ]
+    )
+)
diff --git a/examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py b/examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py
new file mode 100644
index 00000000..5659a3a5
--- /dev/null
+++ b/examples/hlapi/v1arch/asyncio/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 the 1.3.6.1.2.1.1.1.0 OID (e.g. SNMPv2-MIB::sysDescr.0 MIB object)
+  * Based on asyncio I/O framework
+
+Functionally similar to:
+
+| $ snmpget -v1 -c public demo.snmplabs.com SNMPv2-MIB::sysDescr.0
+
+"""#
+import asyncio
+from pysnmp.hlapi.v1arch.asyncio import *
+
+
+@asyncio.coroutine
+def run():
+    snmpDispatcher = SnmpDispatcher()
+
+    iterator = getCmd(
+        snmpDispatcher,
+        CommunityData('public', mpModel=0),
+        UdpTransportTarget(('demo.snmplabs.com', 161)),
+        ('1.3.6.1.2.1.1.1.0', None)
+    )
+
+    errorIndication, errorStatus, errorIndex, varBinds = yield from iterator
+
+    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]))
+
+    snmpDispatcher.transportDispatcher.closeDispatcher()
+
+
+asyncio.get_event_loop().run_until_complete(run())