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

6 files changed, 0 insertions, 337 deletions

diff --git a/examples/hlapi/asyncio/agent/ntforg/default-v1-trap.py b/examples/hlapi/asyncio/agent/ntforg/default-v1-trap.py
deleted file mode 100644
index 92d3e70e..00000000
--- a/examples/hlapi/asyncio/agent/ntforg/default-v1-trap.py
+++ /dev/null
@@ -1,50 +0,0 @@
-"""
-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.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')
-        ).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())
diff --git a/examples/hlapi/asyncio/agent/ntforg/multiple-notifications-at-once.py b/examples/hlapi/asyncio/agent/ntforg/multiple-notifications-at-once.py
deleted file mode 100644
index 74cedeea..00000000
--- a/examples/hlapi/asyncio/agent/ntforg/multiple-notifications-at-once.py
+++ /dev/null
@@ -1,64 +0,0 @@
-"""
-Multiple concurrent notifications
-+++++++++++++++++++++++++++++++++
-
-Send multiple SNMP notifications at once using the following options:
-
-* SNMPv2c and SNMPv3
-* with community name 'public'
-* over IPv4/UDP
-* send 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
-| $ snmptrap -v2c -c public demo.snmplabs.com 12345 1.3.6.1.6.3.1.1.5.2
-
-"""#
-import asyncio
-from pysnmp.hlapi.asyncio import *
-
-
-@asyncio.coroutine
-def sendone(snmpEngine, hostname, notifyType):
-    (errorIndication,
-     errorStatus,
-     errorIndex,
-     varBinds) = yield from 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')
-        ).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)
-    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]))
-
-
-snmpEngine = SnmpEngine()
-
-loop = asyncio.get_event_loop()
-loop.run_until_complete(
-    asyncio.wait([sendone(snmpEngine, 'demo.snmplabs.com', 'trap'),
-                  sendone(snmpEngine, 'demo.snmplabs.com', 'inform')])
-)
diff --git a/examples/hlapi/asyncio/manager/cmdgen/getbulk-to-eom.py b/examples/hlapi/asyncio/manager/cmdgen/getbulk-to-eom.py
deleted file mode 100644
index e453e6b5..00000000
--- a/examples/hlapi/asyncio/manager/cmdgen/getbulk-to-eom.py
+++ /dev/null
@@ -1,63 +0,0 @@
-"""
-Bulk walk MIB
-+++++++++++++
-
-Send a series of SNMP GETBULK requests using the following options:
-
-* with SNMPv3, user 'usr-none-none', no authentication, no privacy
-* 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 -v3 -lnoAuthNoPriv -u usr-none-none -Cn0 -Cr50 \
-|                demo.snmplabs.com  SNMPv2-MIB::system
-
-"""#
-import asyncio
-from pysnmp.hlapi.asyncio import *
-
-
-@asyncio.coroutine
-def run(varBinds):
-    snmpEngine = SnmpEngine()
-    while True:
-        (errorIndication,
-         errorStatus,
-         errorIndex,
-         varBindTable) = yield from bulkCmd(
-            snmpEngine,
-            UsmUserData('usr-none-none'),
-            UdpTransportTarget(('demo.snmplabs.com', 161)),
-            ContextData(),
-            0, 50,
-            *varBinds)
-
-        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
-
-    snmpEngine.transportDispatcher.closeDispatcher()
-
-
-loop = asyncio.get_event_loop()
-loop.run_until_complete(
-    run([ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr'))])
-)
diff --git a/examples/hlapi/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py b/examples/hlapi/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py
deleted file mode 100644
index ad9c441b..00000000
--- a/examples/hlapi/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py
+++ /dev/null
@@ -1,54 +0,0 @@
-"""
-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.asyncio import *
-
-
-@asyncio.coroutine
-def getone(snmpEngine, hostname):
-    errorIndication, errorStatus, errorIndex, varBinds = yield from getCmd(
-        snmpEngine,
-        CommunityData('public'),
-        UdpTransportTarget(hostname),
-        ContextData(),
-        ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0))
-    )
-
-    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]))
-
-
-snmpEngine = SnmpEngine()
-
-loop = asyncio.get_event_loop()
-loop.run_until_complete(
-    asyncio.wait([getone(snmpEngine, ('demo.snmplabs.com', 1161)),
-                  getone(snmpEngine, ('demo.snmplabs.com', 2161)),
-                  getone(snmpEngine, ('demo.snmplabs.com', 3161))])
-)
diff --git a/examples/hlapi/asyncio/manager/cmdgen/multiple-sequential-queries.py b/examples/hlapi/asyncio/manager/cmdgen/multiple-sequential-queries.py
deleted file mode 100644
index 4a43bc49..00000000
--- a/examples/hlapi/asyncio/manager/cmdgen/multiple-sequential-queries.py
+++ /dev/null
@@ -1,58 +0,0 @@
-"""
-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.asyncio import *
-
-
-@asyncio.coroutine
-def getone(snmpEngine, hostname):
-    errorIndication, errorStatus, errorIndex, varBinds = yield from getCmd(
-        snmpEngine,
-        CommunityData('public'),
-        UdpTransportTarget(hostname),
-        ContextData(),
-        ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0))
-    )
-
-    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(snmpEngine, hostnames):
-    for hostname in hostnames:
-        yield from getone(snmpEngine, hostname)
-
-
-snmpEngine = SnmpEngine()
-
-loop = asyncio.get_event_loop()
-loop.run_until_complete(getall(snmpEngine, [('demo.snmplabs.com', 1161),
-                                            ('demo.snmplabs.com', 2161),
-                                            ('demo.snmplabs.com', 3161)]))
diff --git a/examples/hlapi/asyncio/manager/cmdgen/v1-get.py b/examples/hlapi/asyncio/manager/cmdgen/v1-get.py
deleted file mode 100644
index 6147706d..00000000
--- a/examples/hlapi/asyncio/manager/cmdgen/v1-get.py
+++ /dev/null
@@ -1,48 +0,0 @@
-"""
-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 an instance of 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.asyncio import *
-
-
-@asyncio.coroutine
-def run():
-    snmpEngine = SnmpEngine()
-    errorIndication, errorStatus, errorIndex, varBinds = yield from getCmd(
-        snmpEngine,
-        CommunityData('public', mpModel=0),
-        UdpTransportTarget(('demo.snmplabs.com', 161)),
-        ContextData(),
-        ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr', 0))
-    )
-
-    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]))
-
-    snmpEngine.transportDispatcher.closeDispatcher()
-
-
-asyncio.get_event_loop().run_until_complete(run())