Revised docs.

Development.md

@@ -24,12 +24,22 @@ poetry lock
 poetry version patch
 ```
 
+Edit `docs/poly.py` if the new version tag needs to be added to the list.
+
 ## Build Documentation
 
+To build current version documentation:
+
 ```bash
 poetry run make html -C docs
 ```
 
+To build multiple versions documentation:
+
+```bash
+poetry run sphinx-polyversion docs/poly.py
+```
+
 ## Check Port number
 
 ```bash

README.md

@@ -86,7 +86,7 @@ PySNMP is designed in a layered fashion. Top-level and easiest to use API is kno
 *hlapi*. Here's a quick example on how to SNMP GET:
 
 ```python
-from pysnmp.hlapi.v3arch.asyncio import *
+from pysnmp.hlapi.v1arch.asyncio import *
 from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType
 
 with Slim(1) as slim:

docs/source/conf.py

@@ -18,8 +18,10 @@
 
 # -- Load versioning data ----------------------------------------------------
 
-data = load(globals())  # adds variables `current` and `revisions`
-current: GitRef = data["current"]
+if "POLYVERSION_DATA" in os.environ:
+    # This is the case when polyversion documentation is built
+    data = load(globals())  # adds variables `current` and `revisions`
+    current: GitRef = data["current"]
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -164,7 +166,7 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = "PySNMP 7 Documentation"
+html_title = f"PySNMP {version} Documentation"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 # html_short_title = None

docs/source/docs/hlapi/v1arch/asyncio/agent/ntforg/notification.rst

@@ -0,0 +1,8 @@
+
+TRAP/INFORM notification
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.v1arch.asyncio.sendNotification

docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/bulkcmd.rst

@@ -0,0 +1,8 @@
+
+GETBULK command
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.v1arch.asyncio.bulkCmd

docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/bulkwalkcmd.rst

@@ -0,0 +1,8 @@
+
+BULK WALK Operation
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.v1arch.asyncio.bulkWalkCmd

docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/getcmd.rst

@@ -0,0 +1,8 @@
+
+GET command
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.v1arch.asyncio.getCmd

docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/nextcmd.rst

@@ -0,0 +1,8 @@
+
+GETNEXT command
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.v1arch.asyncio.nextCmd

docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/setcmd.rst

@@ -0,0 +1,8 @@
+
+SET command
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.v1arch.asyncio.setCmd

docs/source/docs/hlapi/v1arch/asyncio/manager/cmdgen/walkcmd.rst

@@ -0,0 +1,7 @@
+WALK Operation
+==============
+
+.. toctree::
+   :maxdepth: 2
+
+.. autofunction:: pysnmp.hlapi.v1arch.asyncio.walkCmd

docs/source/docs/pysnmp-hlapi-tutorial.rst

@@ -397,10 +397,10 @@ function.
    ...             ObjectType(ObjectIdentity('SNMPv2-MIB', 'sysDescr')))
    >>> g
    (None, 0, 0, [ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'), DisplayString('SunOS zeus.pysnmp.com'))])
-   >>> g
-   (None, 0, 0, [ObjectType(ObjectIdentity('1.3.6.1.2.1.1.2.0'), ObjectIdentity(ObjectIdentifier('1.3.6.1.4.1.8072.3.2.10')))])
 
-Iteration over the generator object "walk" over SNMP agent's MIB objects.
+Iteration over the generator object "walk" over SNMP agent's MIB objects
+requires :py:func:`~pysnmp.hlapi.v3arch.asyncio.walkCmd` function to be
+called.
 
 SNMPv2c introduced significant optimization to the *GETNEXT* command -
 the revised version is called *GETBULK* and is capable to gather and
@@ -409,8 +409,8 @@ non-repeaters and max-repetitions parameters can be used to influence
 MIB objects batching.
 
 PySNMP hides this *GETBULK* optimization at the protocol level, the
-:py:func:`~pysnmp.hlapi.v3arch.asyncio.bulkCmd` function exposes the same generator
-API as *getNext()* for convenience.
+:py:func:`~pysnmp.hlapi.v3arch.asyncio.bulkWalkCmd` function exposes the
+same generator API as *getNext()* for convenience.
 
 .. code-block:: python
 
@@ -425,9 +425,7 @@ API as *getNext()* for convenience.
    ...             ObjectType(ObjectIdentity('1.3.6')))
    >>>
    >>> g
-   (None, 0, 0, [ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'), DisplayString('SunOS zeus.pysnmp.com'))])
-   >>> g
-   (None, 0, 0, [ObjectType(ObjectIdentity('1.3.6.1.2.1.1.2.0'), ObjectIdentifier('1.3.6.1.4.1.20408'))])
+   (None, 0, 0, [ObjectType(ObjectIdentity('1.3.6.1.2.1.1.1.0'), DisplayString('SunOS zeus.pysnmp.com')), ObjectType(ObjectIdentity('1.3.6.1.2.1.1.2.0'), ObjectIdentifier('1.3.6.1.4.1.20408'))])
 
 Python generators can not only produce data, but it is also possible
 to send data into running generator object. That feature is used by

docs/source/examples/hlapi/v1arch/asyncio/index.rst

@@ -23,7 +23,7 @@ Here's a quick example on a simple SNMP GET by high-level API:
    :end-before: Functionally
 
 .. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py
-   :start-after: """#
+   :start-after: """  #
    :language: python
 
 The following code performs a series of SNMP GETNEXT operations effectively
@@ -34,7 +34,7 @@ fetching a table of SNMP variables from SNMP Agent:
    :end-before: Functionally
 
 .. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
-   :start-after: """#
+   :start-after: """  #
    :language: python
 
 More examples on Command Generator API usage follow.
@@ -53,7 +53,7 @@ The following code sends SNMP TRAP:
    :end-before: Functionally
 
 .. literalinclude:: /../../examples/hlapi/v1arch/asyncio/agent/ntforg/default-v1-trap.py
-   :start-after: """#
+   :start-after: """  #
    :language: python
 
 More examples on Notification Originator API usage follow.

docs/source/examples/hlapi/v1arch/asyncio/manager/cmdgen/snmp-versions.rst

@@ -6,21 +6,21 @@ Various SNMP versions
 
 .. include:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py
    :start-after: """
-   :end-before: """#
+   :end-before: """  #
 
 .. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get.py
-   :start-after: """#
+   :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: """#
+   :end-before: """  #
 
 .. literalinclude:: /../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py
-   :start-after: """#
+   :start-after: """  #
    :language: python
 
 :download:`Download</../../examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py>` script.

docs/source/faq/oids-not-increasing.rst

@@ -2,7 +2,7 @@
 Dealing with the "OID not increasing" error
 -------------------------------------------
 
-Q. I'm walking a particular Agent with the `nextCmd()` or `bulkCmd()`
+Q. I'm walking a particular Agent with the `walkCmd()` or `bulkWalkCmd()`
    functions. It works for some OIDs, but invariably fails at certain
    OID with the *OID not increasing* error. What does it mean and
    how do I fix that?

examples/hlapi/v1arch/asyncio/manager/cmdgen/getbulk-to-eom.py

@@ -48,11 +48,10 @@ async def run(varBinds):
                 )
             )
         else:
-            for varBindRow in varBindTable:
-                for varBind in varBindRow:
-                    print(" = ".join([x.prettyPrint() for x in varBind]))
+            for varBind in varBindTable:
+                print(" = ".join([x.prettyPrint() for x in varBind]))
 
-        varBinds = varBindTable[-1]
+        varBinds = varBindTable
         if isEndOfMib(varBinds):
             break
 

examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-get-slim.py

@@ -0,0 +1,46 @@
+"""
+SNMPv1
+++++++
+
+Send SNMP GET request using the following options:
+
+  * with SNMPv1, community 'public'
+  * over IPv4/UDP
+  * to an Agent at demo.pysnmp.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.pysnmp.com SNMPv2-MIB::sysDescr.0
+
+"""  #
+import asyncio
+from pysnmp.hlapi.v1arch.asyncio.slim import Slim
+from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType
+
+
+async def run():
+    with Slim(1) as slim:
+        errorIndication, errorStatus, errorIndex, varBinds = await slim.get(
+            "public",
+            "demo.pysnmp.com",
+            161,
+            ObjectType(ObjectIdentity("SNMPv2-MIB", "sysDescr", 0)),
+        )
+
+        if errorIndication:
+            print(errorIndication)
+        elif errorStatus:
+            print(
+                "{} at {}".format(
+                    errorStatus.prettyPrint(),
+                    errorIndex and varBinds[int(errorIndex) - 1][0] or "?",
+                )
+            )
+        else:
+            for varBind in varBinds:
+                print(" = ".join([x.prettyPrint() for x in varBind]))
+
+
+asyncio.run(run())

examples/hlapi/v3arch/asyncio/manager/cmdgen/v1-next.py → examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-next-slim.py

@@ -16,7 +16,7 @@
 
 """  #
 import asyncio
-from pysnmp.hlapi.asyncio.slim import Slim
+from pysnmp.hlapi.v1arch.asyncio.slim import Slim
 from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType
 
 

examples/hlapi/v3arch/asyncio/manager/cmdgen/v1-set.py → examples/hlapi/v1arch/asyncio/manager/cmdgen/v1-set-slim.py

@@ -16,7 +16,7 @@
 
 """  #
 import asyncio
-from pysnmp.hlapi.asyncio.slim import Slim
+from pysnmp.hlapi.v1arch.asyncio.slim import Slim
 from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType
 
 

examples/hlapi/v3arch/asyncio/manager/cmdgen/v2c-bulk.py → examples/hlapi/v1arch/asyncio/manager/cmdgen/v2c-bulk-slim.py

@@ -16,7 +16,7 @@
 
 """  #
 import asyncio
-from pysnmp.hlapi.asyncio.slim import Slim
+from pysnmp.hlapi.v1arch.asyncio.slim import Slim
 from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType
 
 

examples/hlapi/v1arch/asyncio/manager/cmdgen/v2c-get-slim.py

@@ -0,0 +1,46 @@
+"""
+SNMPv2c
++++++++
+
+Send SNMP GET request using the following options:
+
+  * with SNMPv2c, community 'public'
+  * over IPv4/UDP
+  * to an Agent at demo.pysnmp.com:161
+  * for an instance of SNMPv2-MIB::sysDescr.0 MIB object
+  * Based on asyncio I/O framework
+
+Functionally similar to:
+
+| $ snmpget -v2c -c public demo.pysnmp.com SNMPv2-MIB::sysDescr.0
+
+"""  #
+import asyncio
+from pysnmp.hlapi.v1arch.asyncio.slim import Slim
+from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType
+
+
+async def run():
+    with Slim() as slim:
+        errorIndication, errorStatus, errorIndex, varBinds = await slim.get(
+            "public",
+            "demo.pysnmp.com",
+            161,
+            ObjectType(ObjectIdentity("SNMPv2-MIB", "sysDescr", 0)),
+        )
+
+        if errorIndication:
+            print(errorIndication)
+        elif errorStatus:
+            print(
+                "{} at {}".format(
+                    errorStatus.prettyPrint(),
+                    errorIndex and varBinds[int(errorIndex) - 1][0] or "?",
+                )
+            )
+        else:
+            for varBind in varBinds:
+                print(" = ".join([x.prettyPrint() for x in varBind]))
+
+
+asyncio.run(run())

examples/hlapi/v3arch/asyncio/manager/cmdgen/v2c-next.py → examples/hlapi/v1arch/asyncio/manager/cmdgen/v2c-next-slim.py

@@ -16,7 +16,7 @@
 
 """  #
 import asyncio
-from pysnmp.hlapi.asyncio.slim import Slim
+from pysnmp.hlapi.v1arch.asyncio.slim import Slim
 from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType
 
 

examples/hlapi/v3arch/asyncio/manager/cmdgen/v2c-set.py → examples/hlapi/v1arch/asyncio/manager/cmdgen/v2c-set-slim.py

@@ -16,7 +16,7 @@
 
 """  #
 import asyncio
-from pysnmp.hlapi.asyncio.slim import Slim
+from pysnmp.hlapi.v1arch.asyncio.slim import Slim
 from pysnmp.smi.rfc1902 import ObjectIdentity, ObjectType
 
 

examples/hlapi/v3arch/asyncio/manager/cmdgen/getbulk-to-eom.py

@@ -42,11 +42,10 @@ async def run(varBinds):
                 f"{errorStatus.prettyPrint()} at {varBinds[int(errorIndex) - 1][0] if errorIndex else '?'}"
             )
         else:
-            for varBindRow in varBindTable:
-                for varBind in varBindRow:
-                    print(" = ".join([x.prettyPrint() for x in varBind]))
+            for varBind in varBindTable:
+                print(" = ".join([x.prettyPrint() for x in varBind]))
 
-        varBinds = varBindTable[-1]
+        varBinds = varBindTable
         if isEndOfMib(varBinds):
             break
     return