File: README.txt

package info (click to toggle)
python-bsddb3 3.3.0-2
  • links: PTS
  • area: main
  • in suites: woody
  • size: 3,656 kB
  • ctags: 1,539
  • sloc: python: 3,663; ansic: 3,197; makefile: 39; sh: 24
file content (181 lines) | stat: -rw-r--r-- 6,203 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
README.txt
bsddb3.db v3.3
http://pybsddb.sourceforge.net/
September 12, 2001
--------------------------------------


Here is yet another BerkeleyDB wrapper module for Python.  This one is
different from the ones that Gregory P. Smith <greg@electricrain.com>
and I have done in the past in that it doesn't use SWIG.  This one is
completely hand-crafted, and there are no "shadow classes" or other
SWIG related overhead.

This module provides a nearly complete wrapping of the Sleepycat C API
for the Database Environment, Database, Cursor, Transaction and Lock
objects, and each of these is exposed as a Python Type in the
bsddb3.db module.  The database objects can use different access
methods: btree, hash, recno, and queue.  For the first time all of
these are fully supported in the Python wrappers.  Please see the
documents in the docs directory for more details on the types and
methods provided.

There is also a collection of test cases in the test directory that
can be used to validate the modules, as well as giving an idea of how
to use bsddb3.db.

Thanks to The Written Word (http://thewrittenword.com/), bsddb3 is
known to pass its unit tests on these platforms:

     HP-UX	  10.20, 11.00
     Tru64 UNIX	  4.0D, 5.0
     IRIX	  6.2, 6.5
     Solaris	  2.5.1, 2.6, 7, 8

In addition I've run it on a few varieties of Linux and of course on
Win32.



Installation
------------

If you are on a Win32 system then you can just get the binary
installer and run it and then you'll be all set.  If you want to build
it yourself, you can follow the directions below, but see the comments
in setup.py first.

If you are on a Unix/Linux system then keep reading...

The Python Distutils are used to build and install bsddb3.db, so it is
fairly simple to get things ready to go.

0. Check the patches directory for any updates required for the
   version of the Berkeley DB library that you have.  If a patch(s)
   are indicated in the README then apply it to your Berkeley DB
   sources and rebuild it.

1. First, make sure that you have Berkeley DB 3.1.x,r 3.2.x or 3.3.x
   (I'm using 3.3.11 currently) and that it is built and installed.
   Setup.py will detect a db3 or BerkeleyDB directory under either
   /usr or /usr/local; this will catch installations from RPMs and
   most hand installations under Unix.  If setup.py can't find your
   libdb then you can give it a hint either in the environment (using
   the BERKELEYDB_DIR evironment variable) or on the command line by
   specifying the directory containing the include and lib directory.
   For example:

	    --berkeley-db=/stuff/BerkeleyDB.3.1


   If your Berkeley DB was built as a shared library, and if that
   shared library is not on the runtime load path, then you can
   specify the additional linker flags needed to find the shared
   library on the command line as well.  For example:

	   --lflags="-Xlinker -rpath -Xlinker /stuff/BerkeleyDB.3.1/lib"

   or perhaps just

           --lflags="-R /stuff/BerkeleyDB.3.1/lib"

   Check your compiler and linker documentation to be sure.

   It is also possible to specify linking against a different library
   with the --libs switch:

           --libs="-ldb3"
           --libs="-ldb3 -lnsl"



   NOTE: My recommendation is to not rely on pre-built versions of
   BerkeleyDB since on some systems there can be several versions
   already installed and it's sometimes difficult to tell which you
   are linking with when building bsddb3.  Instead get the sources
   from http://www.sleepycat.com/ and build/install it yourself as a
   static library and let setup.py find it in /usr/local.  It's not
   such a big library that you have to worry about wasting space by
   not dynamically linking and doing it this way will possibly save
   you some gray hairs.



2. From the main bsddb3 distribution directory run this command, (plus
   any extra flags needed as discussed above):

	python setup.py build_ext --inplace

   If your Python was built with the old bsddb module built-in
   (statically linked) then the setup script will complain and you'll
   have to type "yes" to build anything.  Please see the note below
   about remedying this.


3. To run the test suite change into the test directory and run this
   command, (assuming your shell is bash or compatible):

	export PYTHONPATH=..
	python test_all.py

   If you would like to see some verbose output from the tests simply
   add the word "verbose" to the command line.  You can also run only
   the tests in a particular test module by themselves.  For example:

	python test_lock.py


4. To install the extension module and the Python modules in the
   bsddb3 package, change back to the root distribution directory and
   run this command as the root user:

	python setup.py install


That's it!




Rebuilding Python w/o bsddb
---------------------------

If the old bsddb is linked statically with Python all kinds of strange
problems can happen when you try to use bsddb3.  Everything from
seg-faults, to getting strange errors on every test, to working
perfectly on some tests, but locking up the process on others.  How
strange can it get?  Try this:

    python -c "from bsddb3.db import *;print version(), DB_VERSION_STRING"

On one machine I got this output:

    (3, 1, 14) Sleepycat Software: Berkeley DB 3.1.17: (July 31, 2000)

Notice the different version numbers?  One set is coming from the DB
library, the other from a macro in db.h so it is actually coming from
my _db.c.  The strange part is that bsddb3 was staticly linked with
3.1.17, but it was still calling functions in the 3.1.14 version
linked with Python.

The best way (only way?) to fix this is to get the old bsddb extension
out of the Python executable.  If the old bsddb is a dynamic extension
module loaded from a shared library, then everything is peachy and
bsddb3 works perfectly.  To do this, edit Modules/Setup.config in the
Python 2.0 distribution and remove the # from in front of *shared*,
then recompile and reinstall Python.  If you just want to remove the
old bsddb entirely, just comment out the following line starting with
bsddb, and then rebuild and install Python.


-- Robin
robin@alldunn.com