Installing the Python bindings

Libmei ships with Python bindings, allowing you to use Python to manipulate MEI files.

We use the boost.python library, and recommend installing it using the homebrew package manager on the OS X operating system. To install boost.python, first install homebrew following the installation instructions on the homebrew website. Then, we recommend installing Python as a framework with the command brew install python --framework --universal. Then install the boost.python library with the command brew install boost-python (or brew install boost-python3). If running on Ubuntu, you may need additional libraries, which can be downloaded with the command sudo apt-get install build-essential python-dev python-setuptools libboost-python-dev libboost-thread-dev.

Change into the python directory in the Libmei source:

$libmei> cd python

Run the Setup script:

$libmei/python> python setup.py build

If all goes well you can then install it. Some users may require sudo:

$libmei/python> [sudo] python setup.py install

To run the unit tests:

$libmei/python> python setup.py test

The steps above work out for Python 2. For Python 3, when you install homebrew, use brew install python3 --framework --universal to install Python 3 as a framework. Then install the boost.python library with the command brew install boost-python --c++11 --with-python3 --without-python. Afterwards, using python3 instead of python:

$libmei/python> python3 setup.py build

$libmei/python> [sudo] python3 setup.py install

$libmei/python> python3 setup.py test

!!!IMPORTANT!!!

When compilation fails, always remember to clean out any .so files from the Python directory, and also delete the build and test directories before you try again.

Troubleshooting

Headers not found

If you are on OS X, you will need to move the mei.framework to a location where the Python bindings can find it. The easiest is at /Library/Frameworks. If you are in XCode 4+, you can find the products of your build by going to the Organizer (top-right corner), selecting your project, and clicking the arrow next to "Derived Data." Your compiled framework will be a folder in the Build directory, depending on what you built it for (Debug or Release).

'mei/meielement.h' file not found

In this case, you need to tell the system where the framework is by using export CFLAGS="-F /Library/Frameworks"

Library not found for -lboost_python-mt

You should use export CFLAGS="-F /Library/Frameworks -I /usr/local/include -L /usr/local/lib" to tell the system where lboost_python-mt is by using -L.

'boost/python.hpp' file not found

If this error happens, make sure you are using the Python interpreter installed by brew install python --framework --universal or brew install python3 --framework --universal. You can use which python or which python3 to know which interpreter you are actually using.

Version Mismatch

The most common cause of this bug is that Boost.Python is compiled against a different version of Python than libmei. This is especially common if you've installed them via the Homebrew package manager, thanks to an insidious little bug. The easiest way to fix this is to make sure you have Python compiled as a Framework (brew install python --enable-framework). Otherwise, see the linked bug report for more details on how to fix it.

"ImportError: No module named _libmei"

This error usually happens when you are importing pymei while still in the libmei/python directory. Try changing to a different directory and reimporting pymei.

"Missing boost_python-mt-py27"

This error sometimes occurs when using Ubuntu. Until a permanent fix is in place, in setup.py Line 27 remove "boost_python-mt-py{0}{1}".format(ver[0], ver[1]) from libraries = ["boost_python-mt-py{0}{1}".format(ver[0], ver[1]), "mei", "boost_python-py{0}{1}".format(ver[0], ver[1])] so you are left with libraries = ["mei", "boost_python-py{0}{1}".format(ver[0], ver[1])]