* synchronous oneliner apps redesigned to offer Python generator-based

  API along with a more comprehensive set of accepted parameters.
* massively documented (in Sphinx, NumPy style)

9 files changed, 184 insertions, 7 deletions

diff --git a/examples/v1arch/asyncore/agent/cmdrsp/implementing-scalar-mib-objects.py b/examples/v1arch/asyncore/agent/cmdrsp/implementing-scalar-mib-objects.py
index 1007a475..5119a159 100644
--- a/examples/v1arch/asyncore/agent/cmdrsp/implementing-scalar-mib-objects.py
+++ b/examples/v1arch/asyncore/agent/cmdrsp/implementing-scalar-mib-objects.py
@@ -1,4 +1,24 @@
-# Command Responder Application (GET/GETNEXT)
+"""
+Implementing scalar MIB objects
++++++++++++++++++++++++++++++++
+
+Listen and respond to SNMP GET/GETNEXT queries with the following options:
+
+* SNMPv1 or SNMPv2c
+* with SNMP community "public"
+* over IPv4/UDP, listening at 127.0.0.1:161
+* over IPv6/UDP, listening at [::1]:161
+* serving two Managed Objects Instances (sysDescr.0 and sysUptime.0)
+
+Either of the following Net-SNMP commands will walk this Agent:
+
+| $ snmpwalk -v2c -c public 127.0.0.1 .1.3.6
+| $ snmpwalk -v2c -c public udp6:[::1] .1.3.6
+
+The Command Receiver below uses two distinct transports for communication 
+with Command Generators - UDP over IPv4 and UDP over IPv6.
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp, udp6, unix
 from pyasn1.codec.ber import encoder, decoder
diff --git a/examples/v1arch/asyncore/agent/ntforg/send-trap-over-ipv4-and-ipv6.py b/examples/v1arch/asyncore/agent/ntforg/send-trap-over-ipv4-and-ipv6.py
index 66c8a53f..e0be25a8 100644
--- a/examples/v1arch/asyncore/agent/ntforg/send-trap-over-ipv4-and-ipv6.py
+++ b/examples/v1arch/asyncore/agent/ntforg/send-trap-over-ipv4-and-ipv6.py
@@ -1,4 +1,27 @@
-# Notification Originator Application (TRAP)
+"""
+TRAP over multiple transports
++++++++++++++++++++++++++++++
+
+The following script sends two SNMP TRAP notification using the 
+following options:
+
+* with SNMPv1
+* with community name 'public'
+* over IPv4/UDP and IPv6/UDP
+* send TRAP notification
+* to a Manager at 127.0.0.1:162 and [::1]
+* with TRAP ID 'coldStart' specified as an OID
+* include managed objects information:
+* with default Uptime value
+* with default Agent Address with '127.0.0.1'
+* overriding Enterprise OID with 1.3.6.1.4.1.20408.4.1.1.2
+
+The following Net-SNMP commands will produce similar SNMP notification:
+
+| $ snmptrap -v1 -c public udp:127.0.0.1 1.3.6.1.4.1.20408.4.1.1.2 127.0.0.1 1 0 12345
+| $ snmptrap -v1 -c public udp6:[::1] 1.3.6.1.4.1.20408.4.1.1.2 127.0.0.1 1 0 12345
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp, udp6, unix
 from pyasn1.codec.ber import encoder
diff --git a/examples/v1arch/asyncore/manager/cmdgen/broadcast-agent-discovery.py b/examples/v1arch/asyncore/manager/cmdgen/broadcast-agent-discovery.py
index 2ac0f181..cd8c3c99 100644
--- a/examples/v1arch/asyncore/manager/cmdgen/broadcast-agent-discovery.py
+++ b/examples/v1arch/asyncore/manager/cmdgen/broadcast-agent-discovery.py
@@ -1,3 +1,25 @@
+"""
+Broadcast SNMP message (IPv4)
++++++++++++++++++++++++++++++
+
+Send SNMP GET request to broadcast address and wait for respons(es):
+
+* with SNMPv2c, community 'public'
+* over IPv4/UDP
+* to all Agents via broadcast address 255.255.255.255:161
+* for OIDs in tuple form
+
+Here we send out a single SNMP request and wait for potentially many SNMP 
+responses from multiple SNMP Agents listening in local broadcast domain.
+Since we can't predict the exact number of Agents responding, this script 
+just waits for arbitrary time for collecting all responses. This technology
+is also known as SNMP-based discovery.
+
+This script performs similar to the following Net-SNMP command:
+
+| $ snmpget -v2c -c public -ObentU 255.255.255.255 1.3.6.1.2.1.1.1.0 1.3.6.1.2.1.1.3.0
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp
 from pyasn1.codec.ber import encoder, decoder
diff --git a/examples/v1arch/asyncore/manager/cmdgen/fetch-scalar-value.py b/examples/v1arch/asyncore/manager/cmdgen/fetch-scalar-value.py
index a44707ea..e7fa029b 100644
--- a/examples/v1arch/asyncore/manager/cmdgen/fetch-scalar-value.py
+++ b/examples/v1arch/asyncore/manager/cmdgen/fetch-scalar-value.py
@@ -1,4 +1,19 @@
-# GET Command Generator
+"""
+Fetch scalar MIB variables (SNMPv1)
++++++++++++++++++++++++++++++++++++
+
+Perform SNMP GET operation with the following options:
+
+* with SNMPv1, community 'public'
+* over IPv4/UDP
+* to an Agent at 195.218.195.228:161
+* for OIDs in tuple form
+
+This script performs similar to the following Net-SNMP command:
+
+| $ snmpget -v1 -c public -ObentU 195.218.195.228 1.3.6.1.2.1.1.1.0 1.3.6.1.2.1.1.3.0
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp, udp6, unix
 from pyasn1.codec.ber import encoder, decoder
diff --git a/examples/v1arch/asyncore/manager/cmdgen/getbulk-pull-whole-mib.py b/examples/v1arch/asyncore/manager/cmdgen/getbulk-pull-whole-mib.py
index d4c7ca75..8ba9af62 100644
--- a/examples/v1arch/asyncore/manager/cmdgen/getbulk-pull-whole-mib.py
+++ b/examples/v1arch/asyncore/manager/cmdgen/getbulk-pull-whole-mib.py
@@ -1,4 +1,20 @@
-# GETBULK Command Generator (SNMPv2c only)
+"""
+Bulk walk Agent MIB (SNMPv2c)
++++++++++++++++++++++++++++++
+
+Perform SNMP GETBULK operation with the following options:
+
+* with SNMPv2c, community 'public'
+* over IPv4/UDP
+* to an Agent at 195.218.195.228:161
+* for OID in tuple form
+* with non-repeaters=0 and max-repeaters=25
+
+This script performs similar to the following Net-SNMP command:
+
+| $ snmpbulkwalk -v2c -c public -ObentU -Cn0 -Cr25 195.218.195.228 1.3.6
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp
 from pyasn1.codec.ber import encoder, decoder
diff --git a/examples/v1arch/asyncore/manager/cmdgen/getnext-pull-whole-mib.py b/examples/v1arch/asyncore/manager/cmdgen/getnext-pull-whole-mib.py
index d0cefc37..b3e16f19 100644
--- a/examples/v1arch/asyncore/manager/cmdgen/getnext-pull-whole-mib.py
+++ b/examples/v1arch/asyncore/manager/cmdgen/getnext-pull-whole-mib.py
@@ -1,4 +1,19 @@
-# GETNEXT Command Generator
+"""
+Walk Agent MIB (SNMPv1)
++++++++++++++++++++++++
+
+Perform SNMP GETNEXT operation with the following options:
+
+* with SNMPv1, community 'public'
+* over IPv4/UDP
+* to an Agent at 195.218.195.228:161
+* for OID in tuple form
+
+This script performs similar to the following Net-SNMP command:
+
+| $ snmpwalk -v1 -c public -ObentU 195.218.195.228 1.3.6
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp
 from pyasn1.codec.ber import encoder, decoder
diff --git a/examples/v1arch/asyncore/manager/cmdgen/spoof-source-address.py b/examples/v1arch/asyncore/manager/cmdgen/spoof-source-address.py
index acaefacb..16009ab8 100644
--- a/examples/v1arch/asyncore/manager/cmdgen/spoof-source-address.py
+++ b/examples/v1arch/asyncore/manager/cmdgen/spoof-source-address.py
@@ -1,3 +1,33 @@
+"""
+Spoof IPv4 source address
++++++++++++++++++++++++++
+
+Send SNMP GET request from a non-local IP address:
+
+* with SNMPv2c, community 'public'
+* over IPv4/UDP
+* to an Agent at 195.218.195.228:161
+* from a non-local, spoofed IP 1.2.3.4 (root and Python 3.3+ required)
+* for OIDs in string form
+
+This script performs similar to the following Net-SNMP command:
+
+| $ snmpget -v2c -c public -ObentU 195.218.195.228 1.3.6.1.2.1.1.1.0 1.3.6.1.2.1.1.3.0
+
+But unlike the above command, this script issues SNMP request from a 
+non-default, non-local IP address.
+
+It is indeed possible to originate SNMP traffic from any valid local IP 
+addresses. It could be a secondary IP interface, for instance. Superuser 
+privileges are only required to send spoofed packets. Alternatively, 
+sending from local interface could also be achieved by binding to 
+it (via openClientMode() parameter).
+
+Agent would respond to the IP address you used as a source. So this script 
+could only get a response if that source address is somehow routed to the 
+host this script is running on. Otherwise it just times out.
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp
 from pysnmp.proto import api
diff --git a/examples/v1arch/asyncore/manager/cmdgen/v2c-set.py b/examples/v1arch/asyncore/manager/cmdgen/v2c-set.py
index f7c22bbd..a30bebb6 100644
--- a/examples/v1arch/asyncore/manager/cmdgen/v2c-set.py
+++ b/examples/v1arch/asyncore/manager/cmdgen/v2c-set.py
@@ -1,4 +1,19 @@
-# SET Command Generator
+"""
+SET string and integer scalars (SNMPv2c)
+++++++++++++++++++++++++++++++++++++++++
+
+Perform SNMP SET operation with the following options:
+
+* with SNMPv2c, community 'public'
+* over IPv4/UDP
+* to an Agent at 195.218.195.228:161
+* for OIDs in string form and values in form of pyasn1 objects
+
+This script performs similar to the following Net-SNMP command:
+
+| $ snmpset -v2c -c public -ObentU 195.218.195.228 1.3.6.1.2.1.1.9.1.3.1 s 'New description' 1.3.6.1.2.1.1.9.1.4.1 t 12
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp
 from pyasn1.codec.ber import encoder, decoder
diff --git a/examples/v1arch/asyncore/manager/ntfrcv/listen-on-ipv4-and-ipv6-interfaces.py b/examples/v1arch/asyncore/manager/ntfrcv/listen-on-ipv4-and-ipv6-interfaces.py
index 3a1b0266..b9073cf2 100644
--- a/examples/v1arch/asyncore/manager/ntfrcv/listen-on-ipv4-and-ipv6-interfaces.py
+++ b/examples/v1arch/asyncore/manager/ntfrcv/listen-on-ipv4-and-ipv6-interfaces.py
@@ -1,4 +1,25 @@
-# Notification Receiver (TRAP PDU)
+"""
+Listen for notifications at IPv4 & IPv6 interfaces
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Receive SNMP TRAP messages with the following options:
+
+* SNMPv1/SNMPv2c
+* with SNMP community "public"
+* over IPv4/UDP, listening at 127.0.0.1:162
+* over IPv6/UDP, listening at [::1]:162
+* print received data on stdout
+
+Either of the following Net-SNMP commands will send notifications to this 
+receiver:
+
+| $ snmptrap -v1 -c public 127.0.0.1 1.3.6.1.4.1.20408.4.1.1.2 127.0.0.1 1 1 123 1.3.6.1.2.1.1.1.0 s test
+| $ snmptrap -v2c -c public udp6:[::1] 123 1.3.6.1.6.3.1.1.5.1 1.3.6.1.2.1.1.5.0 s test
+
+Notification Receiver below uses two different transports for communication 
+with Notification Originators - UDP over IPv4 and UDP over IPv6.
+
+"""#
 from pysnmp.carrier.asyncore.dispatch import AsyncoreDispatcher
 from pysnmp.carrier.asyncore.dgram import udp, udp6, unix
 from pyasn1.codec.ber import decoder