updated

2 files changed, 206 insertions, 125 deletions

diff --git a/README b/README
index 254b41b..fa9bb98 100644
--- a/README
+++ b/README
@@ -15,10 +15,9 @@ FEATURES
   Managed Objects
 * Complete SNMP entity implementation
 * USM Extended Security Options support (3DES, 192/256-bit AES encryption)
-* Extensible network transports framework (UDP and UNIX domain implemented)
+* Extensible network transports framework (UDP/IPv4, UDP/IPv6 and UNIX domain sockets already implemented)
 * Asynchronous socket-based IO API support
 * Twisted (http://twistedmatrix.com) integration
-* IPv6 transport support
 * Python eggs and py2exe friendly
 * 100% Python, works with Python 2.4 though 3.3 (alpha 2)
 * MT-safe (only if run locally to a thread)
@@ -37,7 +36,7 @@ MISFEATURES
 -----------
 
 * Much slower than C implementations. Some optimization still possible.
-* No pure-Python MIB compiler. But there's a workaround, read on.
+* No pure-Python MIB compiler. The libsmi's smidump tool used for one-time MIB compilation.
 
 INSTALLATION
 ------------
@@ -53,7 +52,8 @@ OPERATION
 As of this writing, PySNMP implements two SNMP architectures -- the first
 is a legacy one specified by SNMPv1 & v2c standards [5]. It is quite 
 low-level and protocol-oriented by design. In particular, it requires
-application to manage transport failures, access issues and so on.
+application to manage authentication and access issues, deal with transport
+failures and similar housekeeping stuff.
 
 The second model supported by PySNMP is aligned to SNMPv3 architecture, 
 as specified in [4]. Here is an example on querying SNMP agent
@@ -64,13 +64,14 @@ privacy enabled:
 
 from pysnmp.entity.rfc3413.oneliner import cmdgen
 
-userData = cmdgen.UsmUserData('test-user', 'authkey1', 'privkey1')
-targetAddr = cmdgen.UdpTransportTarget(('localhost', 161))
+cmdGen = cmdgen.CommandGenerator()
 
-errorIndication, errorStatus, \
-    errorIndex, varBinds = cmdgen.CommandGenerator().getCmd(
-        userData, targetAddr, (('SNMPv2-MIB', 'sysDescr'), 0)
-    )
+errorIndication, errorStatus, errorIndex, varBinds = cmdGen.getCmd(
+    cmdgen.CommunityData('public'),
+    cmdgen.UdpTransportTarget(('localhost', 161)),
+    cmdgen.MibVariable('SNMPv2-MIB', 'sysDescr', 0),
+    lookupNames=True, lookupValues=True
+)
 
 if errorIndication: # SNMP engine errors
     print errorIndication
@@ -91,19 +92,20 @@ For more examples, please see the examples directory in the PySNMP distribution.
 MIB SUPPORT
 -----------
 
-The pysnmp.smi sub-package defines and implements data model for SNMP SMI
+The pysnmp.smi package component defines and implements data model for SNMP SMI
 objects. With that model, various objects defined in MIB file could be
 implemented in Python, loaded into SNMP entity and used for verification and
 visualisation purposes (SNMP manager side) and/or become management targets
 (SNMP agent side).
 
-While MIB parser/codegenerator has not been implemented in PySNMP, the
-smidump tool of libsmi library [6] could be used for automatic convertion
-of MIB text files into Python code. The produced code relies on PySNMP
-SMI library.
+While MIB parser/codegenerator has not yet been implemented in PySNMP, the
+smidump tool of libsmi library [6] could be used for automatic, one-time 
+convertion of MIB text files into specific Python programs designed to be
+dynamically loaded and used by PySNMP engine.
 
-In order to convert MIB text files into pysnmp.smi-compliant Python source,
-please, use build-pysnmp-mib utility as shipped with PySNMP distribution.
+To simplify smidump tool invocation followed by libsmi2pysnmp script, PySNMP
+distribution includes a build-pysnmp-mib shell script. You should use it for
+one-time MIB text modules convertion into PySNMP format.
 
 A large set of pre-compiled MIB files is shipped along the pysnmp-mibs
 package.[2]
diff --git a/docs/pysnmp-tutorial.html b/docs/pysnmp-tutorial.html
index 6701124..36fb2d3 100644
--- a/docs/pysnmp-tutorial.html
+++ b/docs/pysnmp-tutorial.html
@@ -367,9 +367,10 @@ the darkest corners of SNMP specifications all in Python programming language.
 </P>
 
 <P>
-This paper is dedicated to PySNMP revisions from 4.1.x and up. Previous
-PySNMP versions do not follow the architecture and interfaces described
-in this tutorial.
+This paper is dedicated to PySNMP revisions 4.2.3 and up. Since PySNMP API's
+evolve over time, older revisions may provide slightly different interfaces
+than those described in this tutorial. Please refer to release-specific
+documentation for a more precise information.
 </P>
 
 <P>
@@ -560,7 +561,7 @@ operations as well as for rapid prototyping.
 </P>
 
 <P>
-All Command Generator Applications are implemented within a single class:
+All Command Generator Applications are implemented by a single class:
 </P>
 
 <A NAME="CommandGenerator"></A>
@@ -570,6 +571,13 @@ All Command Generator Applications are implemented within a single class:
 <P>
 Create a SNMP Command Generator object.
 </P>
+
+<P>
+Although instantiation of this class is cheap, in the course of its further
+use, SNMP engine configuration is built and maintained though methods infocation.
+Therefore it is advised to keep and reuse CommandGenerator instance (or <STRONG>snmpEngine</STRONG>
+instance if passed as an initializer) for as long as possible within user applicatin.
+</P>
 </DD>
 </DL>
 
@@ -583,7 +591,9 @@ specific request types.
 <DT><STRONG>getCmd</STRONG>(
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
-<STRONG>*varNames</STRONG>
+<STRONG>*varNames</STRONG>,
+<STRONG>lookupNames=False</STRONG>,
+<STRONG>lookupValues=False</STRONG>
 )</DT>
 
 <DD>
@@ -605,7 +615,7 @@ The <STRONG>getCmd</STRONG> method returns a tuple of
 <STRONG>errorIndication</STRONG>, 
 <STRONG>errorStatus</STRONG>,
 <STRONG>errorIndex</STRONG>,
-<STRONG>varBinds</STRONG>. 
+<STRONG>varBinds</STRONG>.
 </P>
 
 <P>
@@ -625,21 +635,38 @@ explanatory text error message.
 </P>
 
 <P>
-The <STRONG>varBinds</STRONG> is a tuple of <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A>. Those found in response are bound by position to
-Managed Object names passed in request.
+The <STRONG>varBinds</STRONG> is a sequence of <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A>.
+Those found in response are bound by position to Managed Object names passed in request.
+</P>
+
+<P>
+If <STRONG>lookupNames</STRONG> parameter evaluates to True, PySNMP will attempt to gather more
+information on <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A> returned in
+<STRONG>varBinds</STRONG> by searching for relevant MIB module and looking up there. Instance of
+<A HREF="#MIB-VARIABLE">MibVariable</A> class will be returned as Managed Object names.
 </P>
+
+<P>
+If <STRONG>lookupValues</STRONG> parameter evaluates to True, Managed Objects Instances values
+returned in <STRONG>varBinds</STRONG> may be converted into a more precise type (employing
+<A HREF="#TEXTUAL-CONVENTION-AS-A-TYPE">TEXTUAL-CONVENTION</A> data
+from MIB) if PySNMP has relevant MIB loaded. Otherwise response values will belong to
+protocol-level <A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Object Instance value types</A>.
+</P>
+
 </DD>
 </DL>
 
 <P>
-The following code performs SNMP GET operation over SNMPv1:
+The following code performs SNMP GET operation over SNMPv2c:
 </P>
 
 <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
 <PRE>
->>> from pysnmp.entity.rfc3413.oneliner import cmdgen
->>> errorIndication, errorStatus, errorIndex, varBinds = cmdgen.CommandGenerator().getCmd(
-... cmdgen.CommunityData('my-agent', 'public', 0),
+>>> from pysnmp.entity.rfc3413.oneliner import cmdgen           
+>>> cmdGen = cmdgen.CommandGenerator()
+>>> errorIndication, errorStatus, errorIndex, varBinds = cmdGen.getCmd(
+... cmdgen.CommunityData('public'),
 ... cmdgen.UdpTransportTarget(('localhost', 161)),
 ... '1.3.6.1.2.1.1.1.0',
 ... '1.3.6.1.2.1.1.2.0'
@@ -660,7 +687,9 @@ None
 <DT><STRONG>setCmd</STRONG>(
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
-<STRONG>*varBinds</STRONG>
+<STRONG>*varBinds</STRONG>,
+<STRONG>lookupNames=False</STRONG>,
+<STRONG>lookupValues=False</STRONG>
 )</DT>
 
 <DD>
@@ -669,16 +698,15 @@ Perform SNMP SET request and return a response or error indication.
 </P>
 
 <P>
-The <STRONG>authData</STRONG> and <STRONG>transportTarget</STRONG> parameters
-have he same semantics as in <A HREF="#CommandGenerator.getCmd">getCmd</A>
+The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
+<STRONG>lookupNames</STRONG> and <STRONG>lookupValues</STRONG>  parameters
+have the same semantics as in <A HREF="#CommandGenerator.getCmd">getCmd</A>
 method.
 </P>
 
 <P>
 The <STRONG>*varBinds</STRONG> input parameter is a sequence of
-Managed Objects to be applied at Agent. The syntax of
-<STRONG>*varBinds</STRONG> is the same as in
-<A HREF="#CommandGenerator.getCmd">getCmd</A> method.
+<A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects</A> to be modified at the Agent.
 </P>
 
 <P>
@@ -687,19 +715,14 @@ The <STRONG>setCmd</STRONG> method returns a tuple of
 <STRONG>errorStatus</STRONG>,
 <STRONG>errorIndex</STRONG>,
 <STRONG>varBinds</STRONG>. 
-</P>
-
-<P>
-The <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG> and
-<STRONG>errorIndex</STRONG> parameters have the same meaning as in
-<A HREF="#CommandGenerator.getCmd">getCmd</A> method.
+having the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method.
 </P>
 
 </DD>
 </DL>
 
 <P>
-The following code performs SNMP SET operation over SNMPv2c:
+The following code performs SNMP SET operation over SNMPv1:
 </P>
 
 <TABLE BGCOLOR="lightgray" BORDER=0 WIDTH=100%><TR><TD>
@@ -707,9 +730,9 @@ The following code performs SNMP SET operation over SNMPv2c:
 >>> from pysnmp.entity.rfc3413.oneliner import cmdgen
 >>> from pysnmp.proto import rfc1902
 >>> errorIndication, errorStatus, errorIndex, varBinds = cmdgen.CommandGenerator().setCmd(
-... cmdgen.CommunityData('my-agent', 'public', 1),
+... cmdgen.CommunityData('public', mpModel=0),
 ... cmdgen.UdpTransportTarget(('localhost', 161)),
-... ((1,3,6,1,2,1,1,1,0), rfc1902.OctetString('my system description'))
+... ('1.3.6.1.2.1.1.1.0', rfc1902.OctetString('my system description'))
 ... )
 >>> print(errorIndication)
 None
@@ -725,19 +748,37 @@ notWritable(17)
 <DT><STRONG>nextCmd</STRONG>(
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
-<STRONG>*varNames</STRONG>
+<STRONG>*varNames</STRONG>,
+<STRONG>lookupNames=False</STRONG>,
+<STRONG>lookupValues=False</STRONG>,
+<STRONG>lexicographicMode=False</STRONG>,
+<STRONG>ignoreNonIncreasingOid=False</STRONG>,
+<STRONG>maxRows=0</STRONG>
 )</DT>
 
 <DD>
 <P>
 Perform SNMP GETNEXT request and return a response or error indication.
 The GETNEXT request type implies referring to Managed Objects whose Object
-Names are next to those used in request.
+Names are "next greater" to those used in request.
 </P>
 
 <P>
-Input parameters to the <STRONG>nextCmd</STRONG> method are the same as to 
-<A HREF="#CommandGenerator.getCmd">getCmd</A>.
+The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
+<STRONG>lookupNames</STRONG> and <STRONG>lookupValues</STRONG>  parameters
+have the same semantics as in <A HREF="#CommandGenerator.getCmd">getCmd</A>
+method.
+</P>
+
+<P>
+The <STRONG>*varNames</STRONG> parameter is a sequence of
+<A HREF="#MANAGED-OBJECT-NAME-VALUE">Managed Objects names</A> to query Agent
+for their "next" greater neignbours' Managed Objects Instances values. Unlike
+the same-named parameter of <A HREF="#CommandGenerator.getCmd">getCmd</A> method,
+a partial (prefix part of) Managed Objects names are allowed here. For instance,
+a <STRONG>'1.3.6.1'</STRONG> argument would ask the Agent to report Managed Object
+Instance value with the next greater name known to this Agent (which may turn out
+to be <STRONG>'1.3.6.1.2.1.1.1.0'</STRONG>).
 </P>
 
 <P>
@@ -755,7 +796,7 @@ The <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG> and
 </P>
 
 <P>
-The <STRONG>varBindTable</STRONG> parameter is a tuple of
+The <STRONG>varBindTable</STRONG> parameter is a sequence of
 <STRONG>varBinds</STRONG>. Each <STRONG>varBind</STRONG> of 
 <STRONG>varBinds</STRONG> in <STRONG>varBindTable</STRONG> represent a 
 set of Managed Objects whose Object Names reside inside 
@@ -769,13 +810,20 @@ in a single response, and regardless of the prefix property).
 </P>
 
 <P>
-It's also possible to modify the above behaviour so that the 
+It's possible to modify the above behaviour so that the 
 <STRONG>varBindTable</STRONG> returned would contain *all*
-Managed Objects from those passed in request up till the end of
+Managed Objects from those passed in request up to the end of
 the list of available Managed Objects at the Agent. This option
-is enabled by setting the <STRONG>lexicographicMode</STRONG>
-attribute of the <STRONG>CommandGenerator</STRONG> class instance
-to True.
+is enabled by passing the <STRONG>lexicographicMode=True</STRONG>
+parameter to <STRONG>nextCmd</STRONG> method.
+</P>
+
+<P>
+In some cases application is also interested in some contiguous set of Managed
+Objects Instances not necessarily strictly belonging to the same subtree.
+The <STRONG>maxRows=NNN</STRONG> parameter to <STRONG>nextCmd</STRONG> would stop
+Command Generator once the required number (NNN) of Managed Objects Instances are
+retrieved from the Agent.
 </P>
 
 <P>
@@ -796,7 +844,7 @@ over SNMPv3:
 >>> errorIndication, errorStatus, errorIndex, varBindTable = cmdgen.CommandGenerator().nextCmd(
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
 ... cmdgen.UdpTransportTarget(('localhost', 161)),
-... (1,3,6,1,2,1,1)
+... '1.3.6.1.2.1.1'
 ... )
 >>> print(errorIndication)
 None
@@ -821,20 +869,27 @@ None
 <STRONG>transportTarget</STRONG>,
 <STRONG>nonRepeaters</STRONG>,
 <STRONG>maxRepetitions</STRONG>,
-<STRONG>*varNames</STRONG>
+<STRONG>*varNames</STRONG>,
+<STRONG>lookupNames=False</STRONG>,
+<STRONG>lookupValues=False</STRONG>,
+<STRONG>lexicographicMode=False</STRONG>,
+<STRONG>ignoreNonIncreasingOid=False</STRONG>,
+<STRONG>maxRows=0</STRONG>
 )</DT>
 
 <DD>
 <P>
 Perform SNMP GETBULK request and return a response or error indication.
 The GETBULK request type has the same semantics as GETNEXT one except that
-the latter queries a bulk of Managed Objects at once.
+the latter is able to report multiple Managed Objects per each Managed Object
+name passed in request.
 </P>
 
 <P>
 The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
-<STRONG>*varNames</STRONG> input parameters to the <STRONG>bulkCmd</STRONG> 
-method are the same as to  <STRONG>nextCmd</STRONG>.
+<STRONG>*varNames</STRONG>, <STRONG>lookupNames</STRONG>, <STRONG>lookupValues</STRONG>,
+<STRONG>lexicographicMode</STRONG> and <STRONG>maxRows</STRONG> input parameters to the
+<STRONG>bulkCmd</STRONG> method are the same as of <STRONG>nextCmd</STRONG>.
 </P>
 
 <P>
@@ -846,7 +901,7 @@ instance with in a request.
 <P>
 The <STRONG>maxRepetitions</STRONG> parameter indicates for how many instances
 of Managed Objects in the rest of <STRONG>*varNames</STRONG>, besides first 
-<STRONG>nonRepeaters</STRONG> ones, should be queried with single request.
+<STRONG>nonRepeaters</STRONG> ones, should be queried within  a single request.
 </P>
 
 <P>
@@ -855,12 +910,9 @@ The <STRONG>bulkCmd</STRONG> method returns a tuple of
 <STRONG>errorStatus</STRONG>,
 <STRONG>errorIndex</STRONG>,
 <STRONG>varBindTable</STRONG>.
+having same meaning as in <A HREF="#CommandGenerator.nextCmd">nextCmd</A> method.
 </P>
 
-<P>
-The <STRONG>errorIndication</STRONG>, <STRONG>errorStatus</STRONG>,
-<STRONG>errorIndex</STRONG> and <STRONG>varBindTable</STRONG> parameters have
-the same meaning as in <A HREF="#CommandGenerator.getCmd">getCmd</A> method.
 </P>
 </DD>
 </DL>
@@ -877,7 +929,7 @@ over SNMPv3:
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
 ... cmdgen.UdpTransportTarget(('localhost', 161)),
 ... 0, 25, # nonRepeaters, maxRepetitions
-... (1,3,6,1,2,1,1)
+... '1.3.6.1.2.1.1'
 ... )
 >>> print(errorIndication)
 None
@@ -943,12 +995,6 @@ unconfirmed notification or <STRONG>"inform"</STRONG> for a confirmed one.
 </P>
 
 <P>
-Be advised, that when using confirmed notification, Notification Receiver
-must know ContextEngineID of Notification Originator to be able to
-process and acknowledge confirmed notification.
-</P>
-
-<P>
 The <STRONG>notificationType</STRONG> parameter indicates the kind of
 event to notify Manager about in form of SMI NOTIFICATION-TYPE object
 name. For instance, (('SNMPv2-MIB', 'coldStart'),) or (1,3,6,1,6,3,1,1,5,1)
@@ -979,12 +1025,14 @@ The following code sends SNMP TRAP over SNMPv3:
 <PRE>
 >>> from pysnmp.entity.rfc3413.oneliner import cmdgen, ntforg
 >>> from pysnmp.proto.api import v2c
->>> errorIndication = ntforg.NotificationOriginator().sendNotification(
+>>>
+>>> ntfOrg = ntforg.NotificationOriginator()
+>>> errorIndication = ntfOrg.sendNotification(
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
 ... cmdgen.UdpTransportTarget(('localhost', 162)),
 ... 'trap',
-... (('SNMPv2-MIB', 'coldStart'),),
-... ((1,3,6,1,2,1,1,3,0), v2c.TimeTicks(44100))
+... cmdgen.MibVariable('SNMPv2-MIB', 'coldStart'),
+... ('1.3.6.1.2.1.1.3.0', v2c.TimeTicks(44100))
 )
 >>> print(errorIndication)
 None
@@ -1034,7 +1082,9 @@ asynchronous interface uses a callback function for delivering responses.
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
 <STRONG>varNames</STRONG>,
-(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>)
+(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>),
+<STRONG>lookupNames=False</STRONG>,
+<STRONG>lookupValues=False</STRONG>
 )</DT>
 
 <DD>
@@ -1087,10 +1137,12 @@ it must return a true value. Otherwise, it returns false.
 </DL>
 
 <P>
-The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG> and
-<STRONG>varNames</STRONG> parameters have the same meaning as in
-<A HREF="#CommandGenerator.getCmd">getCmd</A>
-method.
+The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
+<STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and
+<STRONG>lookupValues</STRONG> parameters have the same meaning as in
+<A HREF="#CommandGenerator.getCmd">getCmd</A> method except that
+<STRONG>varNames</STRONG> is passed as a sequence, not as individual
+Managed Objects Instances names.
 </P>
 
 <P>
@@ -1107,7 +1159,9 @@ matching subsequent response to this request.
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
 <STRONG>varBinds</STRONG>,
-(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>)
+(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>),
+<STRONG>lookupNames=False</STRONG>,
+<STRONG>lookupValues=False</STRONG>
 )</DT>
 
 <DD>
@@ -1117,9 +1171,12 @@ Prepare SNMP SET request to be dispatched. Return the
 </P>
 
 <P>
-The <STRONG>authData</STRONG> and <STRONG>transportTarget</STRONG>
-parameters have the same meaning as in 
-<A HREF="#CommandGenerator.getCmd">CommandGenerator.getCmd</A> method.
+The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
+<STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and
+<STRONG>lookupValues</STRONG> parameters have the same meaning as in
+<A HREF="#CommandGenerator.setCmd"setCmd</A> method except that
+<STRONG>varBinds</STRONG> is passed as a sequence, not as individual
+Managed Objects Instances.
 </P>
 
 <P>
@@ -1128,11 +1185,6 @@ have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">
 AsynCommandGenerator.asyncGetCmd</A> method.
 </P>
 
-<P>
-The <STRONG>varBinds</STRONG> parameter has the same meaning as in 
-<A HREF="#CommandGenerator.setCmd">CommandGenerator.setCmd</A> method
-except that here it is passed in as a tuple.
-</P>
 </DD>
 </DL>
 
@@ -1142,7 +1194,9 @@ except that here it is passed in as a tuple.
 <STRONG>authData</STRONG>,
 <STRONG>transportTarget</STRONG>,
 <STRONG>varNames</STRONG>,
-(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>)
+(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>),
+<STRONG>lookupNames=False</STRONG>,
+<STRONG>lookupValues=False</STRONG>
 )</DT>
 
 <DD>
@@ -1152,9 +1206,12 @@ Prepare SNMP GETNEXT request to be dispatched. Return the
 </P>
 
 <P>
-The <STRONG>authData</STRONG> and <STRONG>transportTarget</STRONG>
-parameters have the same meaning as in 
-<A HREF="#CommandGenerator.nextCmd">CommandGenerator.nextCmd</A> method.
+The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
+<STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and
+<STRONG>lookupValues</STRONG> parameters have the same meaning as in
+<A HREF="#CommandGenerator.nextCmd">nextCmd</A> method except that
+<STRONG>varNames</STRONG> is passed as a sequence, not as individual
+Managed Objects Instances names.
 </P>
 
 <P>
@@ -1179,7 +1236,9 @@ except that here it is passed in as a tuple.
 <STRONG>nonRepeaters</STRONG>,
 <STRONG>maxRepetitions</STRONG>,
 <STRONG>varNames</STRONG>,
-(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>)
+(<STRONG>cbFun</STRONG>, <STRONG>cbCtx</STRONG>),
+<STRONG>lookupNames=False</STRONG>,
+<STRONG>lookupValues=False</STRONG>
 )</DT>
 
 <DD>
@@ -1190,9 +1249,12 @@ Prepare SNMP GETBULK request to be dispatched. Return the
 
 <P>
 The <STRONG>authData</STRONG>, <STRONG>transportTarget</STRONG>,
-<STRONG>nonRepeaters</STRONG> and <STRONG>maxRepetitions</STRONG>
-parameters have the same meaning as in 
-<A HREF="#CommandGenerator.nextCmd">CommandGenerator.nextCmd</A> method.
+<STRONG>nonRepeaters</STRONG>, <STRONG>maxRepetitions</STRONG>
+<STRONG>varNames</STRONG>, <STRONG>lookupNames</STRONG> and
+<STRONG>lookupValues</STRONG> parameters have the same meaning as in
+<A HREF="#CommandGenerator.bulkCmd">bulkCmd</A> method except that
+<STRONG>varNames</STRONG> is passed as a sequence, not as individual
+Managed Objects Instances names.
 </P>
 
 <P>
@@ -1201,11 +1263,6 @@ have the same meaning as in <A HREF="#AsynCommandGenerator.asyncGetCmd">
 AsynCommandGenerator.asyncGetCmd</A> method.
 </P>
 
-<P>
-The <STRONG>varNames</STRONG> parameter has the same meaning as in 
-<A HREF="#CommandGenerator.bulkCmd">CommandGenerator.bulkCmd</A> method
-except that here it is passed in as a tuple.
-</P>
 </DD>
 </DL>
 
@@ -1255,7 +1312,7 @@ SNMPv3:
 >>> sendRequestHandle = asynCommandGenerator.asyncGetCmd(
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'), 
 ... cmdgen.UdpTransportTarget(('localhost', 161)), 
-... ((1,3,6,1,2,1,1,1,0),), 
+... ('1.3.6.1.2.1.1.1.0',), 
 ... (cbFun, None))
 >>> print(sendRequestHandle)
 1
@@ -1402,8 +1459,8 @@ SNMPv3:
 ... cmdgen.UsmUserData('my-user', 'my-authkey', 'my-privkey'),
 ... cmdgen.UdpTransportTarget(('localhost', 162)),
 ... 'inform',
-... ('SNMPv2-MIB', 'coldStart'),
-... ((1,3,6,1,2,1,1,1,0), v2c.TimeTicks(44100)),
+... cmdgen.MibVariable('SNMPv2-MIB', 'coldStart'),
+... ('1.3.6.1.2.1.1.1.0', v2c.TimeTicks(44100)),
 ... (cbFun, None))
 >>> print(sendRequestHandle)
 1
@@ -1456,15 +1513,16 @@ passed in as a string.
 <P>
 Optional <STRONG>authKey</STRONG> parameter is a secret key (string typed)
 used within USM for SNMP PDU authorization. Setting it to a non-empty
-value implies MD5-based PDU authentication to take effect. Default hashing 
-method may be changed by means of further <STRONG>authProtocol</STRONG> 
-parameter.
+value implies MD5-based PDU authentication (<STRONG>usmHMACMD5AuthProtocol</STRONG>)
+to take effect. Default hashing method may be changed by means of further
+<STRONG>authProtocol</STRONG> parameter.
 </P>
 
 <P>
 Optional <STRONG>privKey</STRONG> parameter is a secret key (string typed)
 used within USM for SNMP PDU encryption. Setting it to a non-empty
-value implies MD5-based PDU authentication and DES-based encryption to 
+value implies MD5-based PDU authentication (<STRONG>usmHMACMD5AuthProtocol</STRONG>)
+and DES-based encryption (<STRONG>usmDESPrivProtocol</STRONG>) to 
 take effect. Default hashing and/or encryption methods may be changed by 
 means of further <STRONG>authProtocol</STRONG> and/or 
 <STRONG>privProtocol</STRONG> parameters.
@@ -1505,7 +1563,6 @@ All these symbols are defined in
 <A NAME="CommunityData"></A>
 <DL>
 <DT>class <STRONG>CommunityData</STRONG>(
-<STRONG>securityName</STRONG>,
 <STRONG>communityName</STRONG>,
 <STRONG>mpModel=1</STRONG>
 )</DT>
@@ -1514,11 +1571,6 @@ All these symbols are defined in
 Create an object holding Community-Based Security Model specific configuration
 parameters.
 </P>
-<P>
-Mandatory <STRONG>securityName</STRONG> parameter is Community-Based Security 
-Model username passed in as a string. For most purposes this can be an
-arbitrary string.
-</P>
 
 <P>
 Mandatory <STRONG>communityName</STRONG> parameter is SNMPv1/SNMPv2c Community name 
@@ -1538,8 +1590,9 @@ Optional <STRONG>mpModel</STRONG> parameter indicates whether SNMPv2c
 </H4>
 <P>
 Transport configuration object is Transport domain specific.
-<STRONG>UdpTransportTarget</STRONG> class represents an Agent
-accessible through UDP domain transport.
+<STRONG>UdpTransportTarget</STRONG> class represents a pair of
+network endpoints (remote and optionally local addresses) of a
+UDP-over-IPv4 transport.
 </P>
 
 <A NAME="UdpTransportTarget"></A>
@@ -1551,18 +1604,22 @@ accessible through UDP domain transport.
 )</DT>
 <DD>
 <P>
-Create an object representing a single Agent accessible through UDP socket.
+Create an object representing a network path connecting two
+SNMP entities through a UDP/IPv4 socket.
 </P>
 <P>
-Mandatory <STRONG>transportAddr</STRONG> parameter indicates destination
-Agent address in form of tuple of <STRONG>FQDN</STRONG>, <STRONG>port</STRONG>
+Mandatory <STRONG>transportAddr</STRONG> parameter indicates remote address
+in form of tuple of <STRONG>FQDN</STRONG>, <STRONG>port</STRONG>
 where <STRONG>FQDN</STRONG> is a string and <STRONG>port</STRONG> is an 
 integer.
 </P>
 <P>
 Optional <STRONG>timeout</STRONG> and <STRONG>retries</STRONG> parameters
 may be used to modify default response timeout (1 second) and number 
-of succesive request retries (5 times).
+of succesive request retries (5 times). Optional <STRONG>localAddr</STRONG>
+parameter may be used for sending queries from specific local interface.
+The syntax of <STRONG>localAddr</STRONG> is the same as the syntax of
+<STRONG>transportAddr</STRONG>.
 </P>
 </DD>
 </DL>
@@ -1592,7 +1649,17 @@ which is derived from PyASN1
 <A HREF="http://pyasn1.sourceforge.net/#1.1.8">ObjectIdentifier</A>.
 In most cases, PySNMP APIs will automatically create an instance of
 ObjectIdentifier class from its initialization value. Therefore it's
-allowed to use a plain tuple of integers as a Managed Object Name.
+allowed to use a plain string of dot-separated numbers or a tuple of
+integers as a Managed Object Name.
+</P>
+
+<A NAME="MIB-VARIABLE">
+<P>
+In order to make use of additional information related to Managed Objects,
+such as their human-friendly representation, associated value type, description
+and other details contained in MIBs, the <A HREF="#MIB-VARIABLE-IMPL">MibVariable</A>
+class instances may be used interchangeably instead of <STRONG>ObjectName</STRONG>
+objects.
 </P>
 
 <A NAME="VAL-IMPL">
@@ -1777,11 +1844,23 @@ PyASN1 <A HREF="http://pyasn1.sourceforge.net/#1.1.7">OctetString</A>.
 </DD>
 </DL>
 
+<A NAME="TEXTUAL-CONVENTION-AS-A-TYPE"></A>
+<P>
+All the above types are directly used by SNMP protocol and can be exchanged
+between user application and PySNMP in the course of SNMP engine operations
+through PySNMP APIs. However, by SNMP design, some additional information
+on specific Managed Objects Instances value ranges and human-friendly representation
+can be carried by MIBs in form of <STRONG>TEXTUAL-CONVENTION</STRONG> SMI constructs.
+PySNMP implements this feature in form of <STRONG>TextualConvention</STRONG> class
+which is actually a derivative of one of the above Managed Objects Instance Value
+classes so objects of these classes can be used interchangeably in all PySNMP APIs.
+</P>
+
 <P>
-It's PySNMP design decision to always use <A HREF="#SMI">SMIv2</A>
-definitions for Managed Objects at the high-level API regardless of SNMP
-protocol version being used. For instance, an SNMPv3 Manager will always report
-SMIv2 types even when talking to SNMPv1 Agent (which is SMIv1-compliant).
+With PySNMP's SNMPv3 architecture, <A HREF="#SMI">SMIv2</A> definitions for Managed
+Objects are always used regardless of the underlying SNMP protocol version being talked
+with a peer. For instance, an SNMPv3 Manager will always report SMIv2 types even when 
+working to SNMPv1 Agent (which is SMIv1-compliant).
 </P>
 
 <P>