C++ and Python APIs for MuPDF

Overview

API Stability

The C++ and Python MuPDF APIs are currently an alpha release and liable to change.

The C++ MuPDF API

• Provides C++ functions that wrap most fz_ and pdf_ functions.
• Provides C++ classes that wrap most fz_ and pdf_ structs.
• Class methods provide access to most of the underlying C API functions (except for functions that don't take struct args such as fz_strlcpy()).
• fz_ exceptions are converted into C++ exceptions.
• Functions and methods do not take fz_context arguments. (Automatically-generated per-thread contexts are used internally.)
• Provides a small number of extensions beyond the basic C API:
  • Some generated classes have extra support for iteration.
  • Some custom class methods and constructors.

The Python MuPDF API

• Generated from the C++ MuPDF API's header files.
• Allows implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.

Building the C++ and Python MuPDF APIs

Requirements:

• Linux or OpenBSD.
• clang-python version 6 or 7. [For example Debian python-clang, OpenBSD py3-llvm.]
• python3-dev version 3.6 or later.
• SWIG version 3 or 4.

Build MuPDF shared library, C++ and Python MuPDF APIs, and run basic tests:

    git clone --recursive git://git.ghostscript.com/mupdf.git
    cd mupdf
    ./scripts/mupdfwrap.py -b all -t

As above but do a debug build:

    ./scripts/mupdfwrap.py -d build/shared-debug -b all -t

For more information:

• Run ./scripts/mupdfwrap.py -h.
• Read the doc-string at beginning of scripts/mupdfwrap.py.

Building auto-generated documentation

Build HTML documentation for the C, C++ and Python APIs (using Doxygen and pydoc):

    ./scripts/mupdfwrap.py --doc all

This will generate these documentation roots:

• include/html/index.html [C API]
• platform/c++/include/html/index.html [C++ API]
• build/shared-release/mupdf.html [Python API]

Note that the content is ultimately all generated from the MuPDF C header file comments.

Using the Python API

Run python code with:

PYTHONPATH=build/shared-release LD_LIBRARY_PATH=build/shared-release

(This enables Python to find the mupdf module, and enables the system dynamic linker to find the shared libraries that implement the underlying C, C++ and Python MuPDF APIs.)

Minimal Python code that uses the mupdf module:

    import mupdf
    document = mupdf.Document('foo.pdf')

A simple example Python test script (run by scripts/mupdfwrap.py -t) is:

• scripts/mupdfwrap_test.py

More detailed usage of the Python API can be found in:

• scripts/mutool.py
• scripts/mutool_draw.py

How the build works

Building of MuPDF shared library:

• Runs make internally.

Generation of the C++ MuPDF API:

• Uses clang-python to parse MuPDF's C API.
• Generates C++ code that wraps the basic C interface.
• Generates C++ classes for each fz_ struct, and uses various heuristics to define constructors, methods and static methods that call fz_() functions.
• C header file comments are copied into the generated C++ header files.

Generation of the Python MuPDF API:

• Based on the C++ MuPDF API.
• Uses SWIG to parse the C++ headers and generate C++ and Python code.
• Defines some custom-written Python functions and methods.
• If SWIG is version 4+, C++ comments are converted into Python doc-comments.

Generated files

    mupdf/
        build/
            shared-release/    [Files needed at runtime]
                libmupdf.so    [implements C MuPDF API]
                libmupdfcpp.so [implements C++ MuPDF API]
                mupdf.py       [implements Python MuPDF API]
                _mupdf.so      [implements Python MuPDF API internals]
            shared-debug/
                [as shared-release but debug build]
        platform/
            c++/
                include/
                    mupdf/ [C++ MuPDF API header files]
                        classes.h
                        exceptions.h
                        functions.h
                        internal.h
                implementation/
                    *.cpp [MuPDF C++ implementation files]
            python/
                [SWIG build files]

Artifex Licensing

Artifex offers a dual licensing model for MuPDF. Meaning we offer both commercial licenses or the GNU Affero General Public License (AGPL).

While Open Source software may be free to use, that does not mean it is free of obligation. To determine whether your intended use of MuPDF is suitable for the AGPL, please read the full text of the AGPL license agreement on the FSF web site.

With a commercial license from Artifex, you maintain full ownership and control over your products, while allowing you to distribute your products to customers as you wish. You are not obligated to share your proprietary source code and this saves you from having to conform to the requirements and restrictions of the AGPL. For more information, please see our licensing page, or contact our sales team.

---

Please send any questions, comments or suggestions about this page to: julian.smith@artifex.com