Python3k.md

+<!-- Name: Python3k -->
+<!-- Version: 2 -->
+<!-- Last-Modified: 2010/09/28 12:12:20 -->
+<!-- Author: springmeyer -->
+
+Mapnik supports Python 3k as of r2239.  Mapnik uses Boost Python for its Python bindings, and boost gained Python 3 support at the 1.41 release, thanks to the excellent work of Haoyu Bai. Haoyu also provided the patch for initial py3k support for Mapnik.
+
+The ticket tracking support is [#334](https://github.com/mapnik/mapnik/issues/334).
+
+## Building Boost with Python 3
+
+Before the issue (https://svn.boost.org/trac/boost/ticket/4609 ) is resolved, you'll need to apply this very small patch to boost: https://svn.boost.org/trac/boost/attachment/ticket/4609/bytes_to_string.patch
+
+Then add the following line to your `project-config.jam` or `user-config.jam`:
+
+
+    using python : 3.1 : /usr ;
+
+Change the `/usr` appropriately according to the prefix of your Python 3 installation.
+
+One mac os x using the Python.3.1 installer you would do:
+
+
+    using python : 3.1 : /Library/Frameworks/Python.framework/Versions/3.1 ;
+
+After [building boost](/wiki:Mapnik2#BuildingBoost/), you should have `libboost_python3.so` generated.
+
+## Building Mapnik
+
+You'll need to set `BOOST_INCLUDES` and `BOOST_LIBS` to your custom Boost build, set `BOOST_PYTHON_LIB = 'boost_python3'`, 
+and `PYTHON = '/usr/local/bin/python3'`. You might also want to set `PYTHON_PREFIX` to install the Python binding to a customized location.
+
+```sh
+    $ python scons/scons.py PYTHON=/usr/local/bin/python3 BOOST_PYTHON_LIB=boost_python3
+```
+
+*Note:* The SCons scripts, written in python, don't actually support Python3, but using the above command you can still compile Mapnik's python bindings against python3 (while the python uses to run SCons < 3).
+
+
+## Installing Mapnik
+
+You can run `scons install` to install mapnik and the Python binding as normal.
+
+During the install the SCons build scripts will automatically run the python3 provided `2to3` script needed to upgrade the syntax to valid Python 3 syntax.
+
+If this fails you will simply see this:
+
+
+```python
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File "/usr/local/lib/python3.1/site-packages/mapnik2/__init__.py", line 54, in <module>
+        from _mapnik2 import *
+    ImportError: No module named _mapnik2
+```
+
+In this case you need to manually run 2to3 over the installed bindings:
+
+```sh
+    $ cd $PYTHON_PREFIX/lib/python3.1/site-packages/mapnik2
+    $ 2to3 -w .
+```
+
+You will see the patch generated by 2to3, and the `-w` option indicates 2to3 to write the patch back to the files.
+
+
+# Testing Mapnik with Python 3
+
+First, you need a Python 3 version of `nose`, there's a SVN branch for that: http://python-nose.googlecode.com/svn/branches/py3k/
+
+Then convert the test suite to Python 3:
+
+    $ cp -r tests tests3
+    $ cd tests3
+    $ 2to3 -w .    
+
+Finally run the test suite inside `tests3` as normal.