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.

7 files changed, 181 insertions, 0 deletions

diff --git a/docs/source/examples/contents.rst b/docs/source/examples/contents.rst
index 7007fee8..d7e38fab 100644
--- a/docs/source/examples/contents.rst
+++ b/docs/source/examples/contents.rst
@@ -83,6 +83,11 @@ The v1 architecture
 
    /examples/hlapi/v1arch/asyncore/contents
 
+.. toctree::
+   :maxdepth: 2
+
+   /examples/hlapi/v1arch/asyncio/contents
+
 Low-level v3 architecture
 -------------------------
 
diff --git a/docs/source/examples/hlapi/v1arch/asyncio/agent/ntforg/advanced-topics.rst b/docs/source/examples/hlapi/v1arch/asyncio/agent/ntforg/advanced-topics.rst
new file mode 100644
index 00000000..3e3d9605
--- /dev/null
+++ b/docs/source/examples/hlapi/v1arch/asyncio/agent/ntforg/advanced-topics.rst
@@ -0,0 +1,17 @@
+.. toctree::
+   :maxdepth: 2
+
+Advanced Notification Originator
+--------------------------------
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/agent/ntforg/multiple-notifications-at-once.py
+   :start-after: """
+   :end-before: """#
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/agent/ntforg/multiple-notifications-at-once.py
+   :start-after: """#
+   :language: python
+
+:download:`Download</../../examples/hlapi/v1arch/asyncio/agent/ntforg/multiple-notifications-at-once.py>` script.
+
+See also: :doc:`library reference </docs/api-reference>`.
diff --git a/docs/source/examples/hlapi/v1arch/asyncio/agent/ntforg/common-notifications.rst b/docs/source/examples/hlapi/v1arch/asyncio/agent/ntforg/common-notifications.rst
new file mode 100644
index 00000000..d69f8efe
--- /dev/null
+++ b/docs/source/examples/hlapi/v1arch/asyncio/agent/ntforg/common-notifications.rst
@@ -0,0 +1,17 @@
+.. toctree::
+   :maxdepth: 2
+
+Common notifications
+--------------------
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py
+   :start-after: """
+   :end-before: """#
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py
+   :start-after: """#
+   :language: python
+
+:download:`Download</../../examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py>` script.
+
+See also: :doc:`library reference </docs/api-reference>`.
diff --git a/docs/source/examples/hlapi/v1arch/asyncio/contents.rst b/docs/source/examples/hlapi/v1arch/asyncio/contents.rst
new file mode 100644
index 00000000..ea1a90b1
--- /dev/null
+++ b/docs/source/examples/hlapi/v1arch/asyncio/contents.rst
@@ -0,0 +1,67 @@
+
+Asynchronous SNMP (asynio, v1arch)
+==================================
+
+The :mod:`asyncio` module first appeared in standard library since
+Python 3.3 (in provisional basis). Its main design feature is that it
+makes asynchronous code looking like synchronous one thus eliminating
+"callback hell".
+
+With `asyncio` built-in facilities, you could run many SNMP queries
+in parallel and/or sequentially, interleave SNMP queries with other I/O
+operations. See `asyncio resources <http://asyncio.org>`_
+repository for other `asyncio`-compatible modules.
+
+In most examples approximate analogues of well known Net-SNMP snmp* tools
+command line options are shown. That may help those readers who, by chance
+are familiar with Net-SNMP tools, better understanding what example code doe
+
+Here's a quick example on a simple SNMP GET by high-level API:
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py
+   :start-after: options:
+   :end-before: Functionally
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py
+   :start-after: """#
+   :language: python
+
+The following code performs a series of SNMP GETNEXT operations effectively
+fetching a table of SNMP variables from SNMP Agent:
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
+   :start-after: options:
+   :end-before: Functionally
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
+   :start-after: """#
+   :language: python
+
+More examples on Command Generator API usage follow.
+
+.. toctree::
+
+   /examples/hlapi/v1arch/asyncio/manager/cmdgen/snmp-versions
+   /examples/hlapi/v1arch/asyncio/manager/cmdgen/walking-operations
+   /examples/hlapi/v1arch/asyncio/manager/cmdgen/advanced-topics
+
+Sending SNMP TRAP's and INFORM's is as easy with PySNMP library.
+The following code sends SNMP TRAP:
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py
+   :start-after: options:
+   :end-before: Functionally
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py
+   :start-after: """#
+   :language: python
+
+More examples on Notification Originator API usage follow.
+
+.. toctree::
+
+   /examples/hlapi/v1arch/asyncio/agent/ntforg/common-notifications
+   /examples/hlapi/v1arch/asyncio/agent/ntforg/advanced-topics
+
+More sophisticated or less popular SNMP operations can still be performed 
+with PySNMP through its Native API to Standard SNMP Applications.
diff --git a/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/advanced-topics.rst b/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/advanced-topics.rst
new file mode 100644
index 00000000..be005a49
--- /dev/null
+++ b/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/advanced-topics.rst
@@ -0,0 +1,29 @@
+.. toctree::
+   :maxdepth: 2
+
+Advanced Command Generator
+--------------------------
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py
+   :start-after: """
+   :end-before: """#
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py
+   :start-after: """#
+   :language: python
+
+:download:`Download</../../examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-concurrent-queries-over-ipv4-and-ipv6.py>` script.
+
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-sequential-queries.py
+   :start-after: """
+   :end-before: """#
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-sequential-queries.py
+   :start-after: """#
+   :language: python
+
+:download:`Download</../../examples/hlapi/v1arch/asyncio/manager/cmdgen/multiple-sequential-queries.py>` script.
+
+
+See also: :doc:`library reference </docs/api-reference>`.
diff --git a/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/snmp-versions.rst b/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/snmp-versions.rst
new file mode 100644
index 00000000..1a4f02f4
--- /dev/null
+++ b/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/snmp-versions.rst
@@ -0,0 +1,29 @@
+.. toctree::
+   :maxdepth: 2
+
+Various SNMP versions
+----------------------
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py
+   :start-after: """
+   :end-before: """#
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py
+   :start-after: """#
+   :language: python
+
+:download:`Download</../../examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py>` script.
+
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
+   :start-after: """
+   :end-before: """#
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
+   :start-after: """#
+   :language: python
+
+:download:`Download</../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py>` script.
+
+
+See also: :doc:`library reference </docs/api-reference>`.
diff --git a/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/walking-operations.rst b/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/walking-operations.rst
new file mode 100644
index 00000000..97dba779
--- /dev/null
+++ b/docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/walking-operations.rst
@@ -0,0 +1,17 @@
+.. toctree::
+   :maxdepth: 2
+
+Walking operations
+------------------
+
+.. include:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
+   :start-after: """
+   :end-before: """#
+
+.. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
+   :start-after: """#
+   :language: python
+
+:download:`Download</../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py>` script.
+
+See also: :doc:`library reference </docs/api-reference>`.