Annotation of /branches/WIP-pyshapelib-bramz/libraries/pyshapelib/README


Python bindings for Shapelib
============================

These are three python modules for shapelib:

   shapelib     read/write shapefiles

   dbflib       read/write dbf files

   shptree      quadtree for shapes

Shapelib is a free software library for reading and writing ESRI shape
files and can be found at http://shapelib.maptools.org/.

The bindings were partly created with SWIG, a tool that can generate
wrappers of C and C++ libraries for a variety of scripting languages.
It's homepage is http://www.swig.org.

The bindings themselves don't have a homepage at the moment, but the
source tarballs/zip files can be downloaded from
http://ftp.intevation.de/users/bh/pyshapelib/


Requirements
------------

To compile the bindings, you need shapelib 1.2.9 or newer and Python 2.0
or newer.

SWIG is not required. The files generated by SWIG are contained in the
archive. If you modify shapelib.i or dbflib.i and need to recreate the
generated files, you need SWIG 1.3 Alpha 5.  It's unlikely that other
versions will work.
In addition you need to add the following lines to  initdbflibc(void)
in dbflib_wrap.c.
    /* because we are in a python module now, we can give out
     * pointers to python's locale agonistic function 
     * XXX this clearly is a hack
     */
    DBFSetatof_function(&PyOS_ascii_atof);

You also need Python, of course.  If you installed prebuilt packages
such as RPMs of some Linux distributions, please make sure that the
development package is also installed.


License
-------

The shapelib python bindings are covered by the LGPL. See COPYING for
more information.


Compilation and Installation
----------------------------

Pyshapelib uses the python distutils which come with Python 2.0 or newer
and are also available separately from python.org for older versions.

To compile the bindings, unpack the archive under the shapelib archive
or move the directory there if you've already unpacked it.  The setup
script expects to find the shapelib files in the parent directory.  Then
run

    python setup.py build

to build the bindings. The result can be found under the (new) build
subirectory.

To install run

    python setup.py install

which will install the bindings into python's site-packages directory.
You can use the intall command's --prefix option to select a different
installatin directory. 

For more information about the setup.py script, invoke it with the
--help option:

    python setup.py --help


Documentation
-------------

There's no real documentation for the python bindings themselves, but
there's a simple demo/test script called pytest.py.

The change history is recorded in NEWS and in detail in ChangeLog.


Contact Information
-------------------

pyshapelib is currently being developed as part of the interactive
viewer for geographic data Thuban, so the best way to reach the
developers is to post on the Thuban mailing lists.

Thuban:
   http://thuban.intevation.org/

Thuban mailing lists:
   http://thuban.intevation.org/mailinglist.html
1	jan	1611
2			Python bindings for Shapelib
3			============================
4
5	bh	2215	These are three python modules for shapelib:
6	jan	1611
7	bh	2215	shapelib read/write shapefiles
8
9			dbflib read/write dbf files
10
11			shptree quadtree for shapes
12
13	jan	1611	Shapelib is a free software library for reading and writing ESRI shape
14	bernhard	2510	files and can be found at http://shapelib.maptools.org/.
15	jan	1611
16	bh	2215	The bindings were partly created with SWIG, a tool that can generate
17			wrappers of C and C++ libraries for a variety of scripting languages.
18			It's homepage is http://www.swig.org.
19	jan	1611
20	bh	2226	The bindings themselves don't have a homepage at the moment, but the
21			source tarballs/zip files can be downloaded from
22			http://ftp.intevation.de/users/bh/pyshapelib/
23	jan	1611
24
25			Requirements
26			------------
27
28	bh	2226	To compile the bindings, you need shapelib 1.2.9 or newer and Python 2.0
29			or newer.
30	jan	1611
31			SWIG is not required. The files generated by SWIG are contained in the
32	bh	2215	archive. If you modify shapelib.i or dbflib.i and need to recreate the
33			generated files, you need SWIG 1.3 Alpha 5. It's unlikely that other
34			versions will work.
35	bernhard	2704	In addition you need to add the following lines to initdbflibc(void)
36			in dbflib_wrap.c.
37			/* because we are in a python module now, we can give out
38			* pointers to python's locale agonistic function
39			* XXX this clearly is a hack
40			*/
41			DBFSetatof_function(&PyOS_ascii_atof);
42	jan	1611
43	bh	2215	You also need Python, of course. If you installed prebuilt packages
44			such as RPMs of some Linux distributions, please make sure that the
45	jan	1611	development package is also installed.
46
47
48			License
49			-------
50
51			The shapelib python bindings are covered by the LGPL. See COPYING for
52			more information.
53
54
55			Compilation and Installation
56			----------------------------
57
58			Pyshapelib uses the python distutils which come with Python 2.0 or newer
59			and are also available separately from python.org for older versions.
60
61			To compile the bindings, unpack the archive under the shapelib archive
62	bh	2215	or move the directory there if you've already unpacked it. The setup
63			script expects to find the shapelib files in the parent directory. Then
64			run
65	jan	1611
66			python setup.py build
67
68			to build the bindings. The result can be found under the (new) build
69			subirectory.
70
71			To install run
72
73			python setup.py install
74
75			which will install the bindings into python's site-packages directory.
76			You can use the intall command's --prefix option to select a different
77			installatin directory.
78
79			For more information about the setup.py script, invoke it with the
80			--help option:
81
82			python setup.py --help
83
84
85			Documentation
86			-------------
87
88			There's no real documentation for the python bindings themselves, but
89			there's a simple demo/test script called pytest.py.
90
91			The change history is recorded in NEWS and in detail in ChangeLog.
92	bh	2226
93
94			Contact Information
95			-------------------
96
97			pyshapelib is currently being developed as part of the interactive
98			viewer for geographic data Thuban, so the best way to reach the
99			developers is to post on the Thuban mailing lists.
100
101			Thuban:
102			http://thuban.intevation.org/
103
104			Thuban mailing lists:
105			http://thuban.intevation.org/mailinglist.html
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision