updated

1 files changed, 187 insertions, 108 deletions

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>