* Asyncore and asyncio-based APIs reworked to become functions.

* Asyncio and Twisted API moved entirely into high-level domain to
  be aligned with other high-level APIs. This WILL BREAK backward
  compatibility for those apps that use Twisted API.

14 files changed, 268 insertions, 2 deletions

diff --git a/docs/source/docs/hlapi/asyncio/agent/ntforg/notification.rst b/docs/source/docs/hlapi/asyncio/agent/ntforg/notification.rst
new file mode 100644
index 0000000..954c923
--- /dev/null
+++ b/docs/source/docs/hlapi/asyncio/agent/ntforg/notification.rst
@@ -0,0 +1,8 @@
+
+TRAP/INFORM notification
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.asyncio.sendNotification
diff --git a/docs/source/docs/hlapi/asyncio/contents.rst b/docs/source/docs/hlapi/asyncio/contents.rst
new file mode 100644
index 0000000..ab7d8e0
--- /dev/null
+++ b/docs/source/docs/hlapi/asyncio/contents.rst
@@ -0,0 +1,60 @@
+
+SNMP with asyncio
+=================
+
+There are a handful of most basic SNMP Applications defined by RFC3413 and
+called Standard Applications. Those implementing Manager side of the system
+(:RFC:`3411#section-3.1.3.1`) are Command Generator (initiating GET, SET,
+GETNEXT, GETBULK operations) and Notification Receiver (handling arrived 
+notifications). On Agent side (:RFC:`3411#section-3.1.3.2`) there are
+Command Responder (handling GET, SET, GETNEXT, GETBULK operations) and
+Notification Originator (issuing TRAP and INFORM notifications). In 
+PySNMP Standard Applications are implemented on top of SNMPv3 framework.
+
+There're two kinds of high-level programming interfaces to Standard SNMP
+Applications: synchronous and asynchronous. They are similar in terms of
+call signatures but differ in behaviour. Synchronous calls block the whole
+application till requested operation is finished. Asynchronous interface
+breaks its synchronous version apart - at first required data are prepared
+and put on the outgoing queue. The the application is free to deal with
+other tasks till pending message is sent out (by I/O dispacher) and
+response is arrived. At that point a previously supplied callback function
+will be invoked and response data will be passed along.
+
+Command Generator
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/asyncio/manager/cmdgen/getcmd
+   /docs/hlapi/asyncio/manager/cmdgen/setcmd
+   /docs/hlapi/asyncio/manager/cmdgen/nextcmd
+   /docs/hlapi/asyncio/manager/cmdgen/bulkcmd
+
+Notification Originator
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/asyncio/agent/ntforg/notification 
+
+The asynchronous version is best suited for massively parallel SNMP
+messaging possibly handling other I/O activities in the same time. The
+synchronous version is advised to employ for singular and blocking
+operations as well as for rapid prototyping.
+
+Transport configuration
+-----------------------
+
+Type of network transport SNMP engine uses along with transport
+options is summarized by 
+:py:class:`~pysnmp.hlapi.asyncio.UdpTransportTarget`
+and
+:py:class:`~pysnmp.hlapi.asyncio.Udp6TransportTarget`
+container classes:
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/asyncio/transport-configuration
+
diff --git a/docs/source/docs/hlapi/asyncio/manager/cmdgen/bulkcmd.rst b/docs/source/docs/hlapi/asyncio/manager/cmdgen/bulkcmd.rst
new file mode 100644
index 0000000..970cfb1
--- /dev/null
+++ b/docs/source/docs/hlapi/asyncio/manager/cmdgen/bulkcmd.rst
@@ -0,0 +1,8 @@
+
+GETBULK command
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.asyncio.bulkCmd
diff --git a/docs/source/docs/hlapi/asyncio/manager/cmdgen/getcmd.rst b/docs/source/docs/hlapi/asyncio/manager/cmdgen/getcmd.rst
new file mode 100644
index 0000000..4ac0a52
--- /dev/null
+++ b/docs/source/docs/hlapi/asyncio/manager/cmdgen/getcmd.rst
@@ -0,0 +1,8 @@
+
+GET command
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.asyncio.getCmd
diff --git a/docs/source/docs/hlapi/asyncio/manager/cmdgen/nextcmd.rst b/docs/source/docs/hlapi/asyncio/manager/cmdgen/nextcmd.rst
new file mode 100644
index 0000000..b88291c
--- /dev/null
+++ b/docs/source/docs/hlapi/asyncio/manager/cmdgen/nextcmd.rst
@@ -0,0 +1,8 @@
+
+GETNEXT command
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.asyncio.nextCmd
diff --git a/docs/source/docs/hlapi/asyncio/manager/cmdgen/setcmd.rst b/docs/source/docs/hlapi/asyncio/manager/cmdgen/setcmd.rst
new file mode 100644
index 0000000..c34fc44
--- /dev/null
+++ b/docs/source/docs/hlapi/asyncio/manager/cmdgen/setcmd.rst
@@ -0,0 +1,8 @@
+
+SET command
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.asyncio.setCmd
diff --git a/docs/source/docs/hlapi/asyncore/contents.rst b/docs/source/docs/hlapi/asyncore/contents.rst
new file mode 100644
index 0000000..847c21d
--- /dev/null
+++ b/docs/source/docs/hlapi/asyncore/contents.rst
@@ -0,0 +1,69 @@
+
+High-level SNMP
+===============
+
+There are a handful of most basic SNMP Applications defined by RFC3413 and
+called Standard Applications. Those implementing Manager side of the system
+(:RFC:`3411#section-3.1.3.1`) are Command Generator (initiating GET, SET,
+GETNEXT, GETBULK operations) and Notification Receiver (handling arrived 
+notifications). On Agent side (:RFC:`3411#section-3.1.3.2`) there are
+Command Responder (handling GET, SET, GETNEXT, GETBULK operations) and
+Notification Originator (issuing TRAP and INFORM notifications). In 
+PySNMP Standard Applications are implemented on top of SNMPv3 framework.
+
+There're two kinds of high-level programming interfaces to Standard SNMP
+Applications: synchronous and asynchronous. They are similar in terms of
+call signatures but differ in behaviour. Synchronous calls block the whole
+application till requested operation is finished. Asynchronous interface
+breaks its synchronous version apart - at first required data are prepared
+and put on the outgoing queue. The the application is free to deal with
+other tasks till pending message is sent out (by I/O dispacher) and
+response is arrived. At that point a previously supplied callback function
+will be invoked and response data will be passed along.
+
+Synchronous Command Generator
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/asyncore/manager/cmdgen/getcmd
+   /docs/hlapi/asyncore/manager/cmdgen/setcmd
+   /docs/hlapi/asyncore/manager/cmdgen/nextcmd
+   /docs/hlapi/asyncore/manager/cmdgen/bulkcmd
+
+Synchronous Notification Originator
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/asyncore/agent/ntforg/notification 
+
+The asynchronous version is best suited for massively parallel SNMP
+messaging possibly handling other I/O activities in the same time. The
+synchronous version is advised to employ for singular and blocking
+operations as well as for rapid prototyping.
+
+Asynchronous operations
+-----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/asyncore/manager/cmdgen/async-command-generator
+   /docs/hlapi/asyncore/agent/ntforg/async-notification-originator
+
+Transport configuration
+-----------------------
+
+Type of network transport SNMP engine uses along with transport
+options is summarized by 
+:py:class:`~pysnmp.hlapi.asyncore.UdpTransportTarget`
+and
+:py:class:`~pysnmp.hlapi.asyncore.Udp6TransportTarget`
+container classes:
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/asyncore/transport-configuration
+
diff --git a/docs/source/docs/hlapi/asyncore/manager/cmdgen/async-command-generator.rst b/docs/source/docs/hlapi/asyncore/manager/cmdgen/async-command-generator.rst
index f8584a7..cd45072 100644
--- a/docs/source/docs/hlapi/asyncore/manager/cmdgen/async-command-generator.rst
+++ b/docs/source/docs/hlapi/asyncore/manager/cmdgen/async-command-generator.rst
@@ -5,5 +5,4 @@ Asynchronous Command Generator
 .. toctree::
    :maxdepth: 2
 
-.. autoclass:: pysnmp.hlapi.asyncore.AsyncCommandGenerator
-   :members:
+.. autofunction:: pysnmp.hlapi.asyncore.getCmd
diff --git a/docs/source/docs/hlapi/twisted/agent/ntforg/notification.rst b/docs/source/docs/hlapi/twisted/agent/ntforg/notification.rst
new file mode 100644
index 0000000..7928912
--- /dev/null
+++ b/docs/source/docs/hlapi/twisted/agent/ntforg/notification.rst
@@ -0,0 +1,8 @@
+
+TRAP/INFORM notification
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.twisted.sendNotification
diff --git a/docs/source/docs/hlapi/twisted/contents.rst b/docs/source/docs/hlapi/twisted/contents.rst
new file mode 100644
index 0000000..d0decf2
--- /dev/null
+++ b/docs/source/docs/hlapi/twisted/contents.rst
@@ -0,0 +1,58 @@
+
+SNMP with Twisted
+=================
+
+There are a handful of most basic SNMP Applications defined by RFC3413 and
+called Standard Applications. Those implementing Manager side of the system
+(:RFC:`3411#section-3.1.3.1`) are Command Generator (initiating GET, SET,
+GETNEXT, GETBULK operations) and Notification Receiver (handling arrived 
+notifications). On Agent side (:RFC:`3411#section-3.1.3.2`) there are
+Command Responder (handling GET, SET, GETNEXT, GETBULK operations) and
+Notification Originator (issuing TRAP and INFORM notifications). In 
+PySNMP Standard Applications are implemented on top of SNMPv3 framework.
+
+There're two kinds of high-level programming interfaces to Standard SNMP
+Applications: synchronous and asynchronous. They are similar in terms of
+call signatures but differ in behaviour. Synchronous calls block the whole
+application till requested operation is finished. Asynchronous interface
+breaks its synchronous version apart - at first required data are prepared
+and put on the outgoing queue. The the application is free to deal with
+other tasks till pending message is sent out (by I/O dispacher) and
+response is arrived. At that point a previously supplied callback function
+will be invoked and response data will be passed along.
+
+Command Generator
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/twisted/manager/cmdgen/getcmd
+   /docs/hlapi/twisted/manager/cmdgen/setcmd
+   /docs/hlapi/twisted/manager/cmdgen/nextcmd
+   /docs/hlapi/twisted/manager/cmdgen/bulkcmd
+
+Notification Originator
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/twisted/agent/ntforg/notification 
+
+The asynchronous version is best suited for massively parallel SNMP
+messaging possibly handling other I/O activities in the same time. The
+synchronous version is advised to employ for singular and blocking
+operations as well as for rapid prototyping.
+
+Transport configuration
+-----------------------
+
+Type of network transport SNMP engine uses along with transport
+options is summarized by 
+:py:class:`~pysnmp.hlapi.twisted.UdpTransportTarget`
+container class:
+
+.. toctree::
+   :maxdepth: 2
+
+   /docs/hlapi/twisted/transport-configuration
+
diff --git a/docs/source/docs/hlapi/twisted/manager/cmdgen/bulkcmd.rst b/docs/source/docs/hlapi/twisted/manager/cmdgen/bulkcmd.rst
new file mode 100644
index 0000000..24fff6e
--- /dev/null
+++ b/docs/source/docs/hlapi/twisted/manager/cmdgen/bulkcmd.rst
@@ -0,0 +1,8 @@
+
+GETBULK command
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.twisted.bulkCmd
diff --git a/docs/source/docs/hlapi/twisted/manager/cmdgen/getcmd.rst b/docs/source/docs/hlapi/twisted/manager/cmdgen/getcmd.rst
new file mode 100644
index 0000000..53d3a14
--- /dev/null
+++ b/docs/source/docs/hlapi/twisted/manager/cmdgen/getcmd.rst
@@ -0,0 +1,8 @@
+
+GET command
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.twisted.getCmd
diff --git a/docs/source/docs/hlapi/twisted/manager/cmdgen/nextcmd.rst b/docs/source/docs/hlapi/twisted/manager/cmdgen/nextcmd.rst
new file mode 100644
index 0000000..54aa540
--- /dev/null
+++ b/docs/source/docs/hlapi/twisted/manager/cmdgen/nextcmd.rst
@@ -0,0 +1,8 @@
+
+GETNEXT command
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.twisted.nextCmd
diff --git a/docs/source/docs/hlapi/twisted/manager/cmdgen/setcmd.rst b/docs/source/docs/hlapi/twisted/manager/cmdgen/setcmd.rst
new file mode 100644
index 0000000..8a7890a
--- /dev/null
+++ b/docs/source/docs/hlapi/twisted/manager/cmdgen/setcmd.rst
@@ -0,0 +1,8 @@
+
+SET command
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.twisted.setCmd