version-3-branch merged against trunk

1 files changed, 41 insertions, 39 deletions

diff --git a/README b/README
index e60381a..3352488 100644
--- a/README
+++ b/README
@@ -1,8 +1,8 @@
 
-SNMP engine for Python, version 2.0.8
--------------------------------------
+SNMP engine for Python, version 3.x
+-----------------------------------
 
-This is a Python implementation of SNMP v.1/v.2c engine. It's general
+This is a Python implementation of SNMP v.1/v.2c engine. Its general
 functionality is to assemble/disassemble SNMP messages from/into
 given SNMP Object IDs along with associated values. PySNMP also provides
 a few transport methods specific to TCP/IP networking.
@@ -10,30 +10,37 @@ a few transport methods specific to TCP/IP networking.
 PySNMP is written entirely in Python and is self-sufficient in terms
 that it does not rely on any third party tool (it is not a wrapper!).
 
-This code is known to be used under Python interpreter versions 1.5.2,
-1.6 and 2.0.
-
-This package is distributed under terms and conditions of BSD-style
+The PySNMP package is distributed under terms and conditions of BSD-style
 license. See the LICENSE file for details.
 
-PRECAUTIONS
+FEATURES
+--------
+
+* Complete SNMPv1 and SNMPv2c support
+* Seamless SNMP manager and agent roles support
+* Both synchronous and asynchronous IO API support
+* Fully documented API with many examples
+* Generic, objective ASN.1 framework
+* Partial MIB I/II data types and macros implementation (check
+  CVS at SF for recent development)
+* 100% Python, works with Python 1.x and later
+* MT-safe
+
+MISFEATURES
 -----------
 
-If you are starting a new project, consider trying the 3.x branch
-of PySNMP which is written in a more standards-compliant way and is
-[hopefully] stable enough by the time of this writing.
+* No MIB compiler (though, it's possible to compile ASN.1 code into PySNMP
+  classes by hand, oh...)
+* No SNMP v.3 support (though, it's almost implemented, check CVS at SF)
 
-Unfortunately, version 2.x of PySNMP software is *INCOMPATIBLE* with
-its 1.x branch at the moment. For a fully compatible solution, use the
-3.x branch of PySNMP package.
+PRECAUTIONS
+-----------
 
-While the pure-Python MIB compiler project is underway, the ASN.1
-types of Object IDs associated values must be explicitly specified
-whenever user application passes values to SNMP engine.
+For notes on backward compatibility with previous PySNMP revisions, please,
+refer to the COMPATIBILITY file in the PySNMP distribution.
 
-Lack of MIB support leads to another limitation -- all the PySNMP
-methods accept and report Object IDs only in dotted numeric (that is
-not symbolic) representation.
+Since MIB support is not integrated into PySNMP package at the moment, this
+software accept and report Object IDs only in a non-symbolic (dotted) notation.
 
 INSTALLATION
 ------------
@@ -50,13 +57,13 @@ directory in the following way (assuming your Python distribution
 resides under /usr/local/lib/python):
 
 $ cd /usr/local/lib/python/site-packages
-$ tar xvf /tmp/pysnmp-2.0.8.tar
-$ echo pysnmp-2.0.8 > pysnmp.pth
+$ tar xvf /tmp/pysnmp-3.3.1.tar
+$ echo pysnmp-3.3.1 > pysnmp.pth
 
 Alternatively, the $PYTHONPATH environment variable can be updated to
 point to your PySNMP package location (assuming your UNIX shell is bash):
 
-export PYTHONPATH=/home/ilya/src/py/pysnmp-2.0.8:$PYTHONPATH
+export PYTHONPATH=/home/ilya/src/py/pysnmp-3.3.1:$PYTHONPATH
 
 The latter trick is also known to work on Windows.
 
@@ -74,23 +81,18 @@ Here is an example of using pysnmp package for querying SNMP agent
 
 Python 1.5.2 (#3, Aug 25 1999, 19:14:24)  [GCC 2.8.1] on sunos5
 Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
->>> from pysnmp import role, v2c, asn1
->>> req = v2c.GETREQUEST()
->>> req['encoded_oids'] = [ asn1.OBJECTID().encode('1.3.6.1.2.1.1.1.0') ]
+>>> from pysnmp.proto import v1
+>>> from pysnmp.proto.api import generic
+>>> from pysnmp.mapping.udp import role
+>>> req = v1.GetRequest()
+>>> req.apiGetPdu().apiSetVarBind([('1.3.6.1.2.1.1.1.0', None)])
 >>> tr = role.manager(('router-1.glas.net', 161))
->>> (rawrsp, src) = tr.send_and_receive(req.encode())
->>> rsp = v2c.RESPONSE()
->>> rsp.decode(rawrsp)
->>> oids = map(lambda x:x[0], map(asn1.OBJECTID().decode, rsp['encoded_oids']))
->>> print oids
-['.1.3.6.1.2.1.1.1.0']
->>> vals = map(lambda x: x[0](), map(asn1.decode, rsp['encoded_vals']))
->>> print vals
-['Cisco Internetwork Operating System Software \015\012IOS (tm) 5300 Software
-(C5300-J-M), Experimental Version 12.1(20001115:152556) [haag-V121_4 102]
-\015\012Copyright (c) 1986-2000 by cisco Systems, Inc.\015\012Compiled
-Mon 20-Nov-00 19:22 by haag']
->>>
+>>> (answer, src) = tr.send_and_receive(req.encode())
+>>> rsp = v1.GetResponse()
+>>> rsp.decode(answer)
+>>> vars = rsp.apiGetPdu().apiGetVarBind()
+>>> print vars
+[('.1.3.6.1.2.1.1.1.0', OctetString('Cisco Internetwork Operating System Software \015\012IOS (tm) 5400 Software(C5400-JS-M), Version 12.2(11.8b), MAINTENANCE INTERIM SOFTWARE\015\012 Copyright (c) 1986-2002 by cisco Systems, Inc.\015\012Compiled Tue 30-Jul-02 19:02 by pwade'))]
 
 8X---------------- cut here --------------------