C++ and Python APIs for MuPDF

Overview

API Stability

The C++ MuPDF API

• 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 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()).
• Provides a small number of extensions beyond the basic C API:

• • Some custom methods/constructors.

The Python MuPDF API

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

Building the C++ and Python MuPDF APIs

• 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.

    git clone --recursive git://git.ghostscript.com/mupdf.git

For more information:

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

Building auto-generated documentation

    ./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

How the build works

• Runs make internally.

• Uses clang-python to parse MuPDF's C API.

• Generates C++ classes for each fz_ struct, and uses various heuristics to define constructors, methods and static methods that call fz_() functions.

• Based on the C++ MuPDF API.

• If SWIG is version 4+, C++ comments are converted into Python doc-comments.

Generated files

C++ and Python APIs for MuPDF.

Overview:

The C++ MuPDF API:

• All C++ API code converts fz_ exceptions into C++ exceptions.
• All C++ API code uses auto-generated internal per-thread fz_context and do not take fz_context args.
• We generate C++ wrapper functions for most fz_ and pdf_ functions.
• We generate C++ class wrappers for most fz_ and pdf_ structs.
• Class methods provide access to most of the underlying C API functions (except for functions don't take struct args, e.g. fz_strlcpy()).
• We auto-detect fz_ and pdf_ fns suitable for wrapping as constructors, methods or static methods.
• We add a small number of extensions beyond the basic C API:
  • Some generated classes have extra support for iteration.
  • We add some custom methods/constructors.

The Python MuPDF API:

• Python MuPDF API is generated from the C++ MuPDF API's header files.
• Python MuPDF API is enough to allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.

Building the C++ and Python MuPDF APIs:

We require:

• Linux or OpenBSD.
• python-clang (version 6 or 7)
• python3-dev (version 3.6 or later)
• swig (version 3 or 4)

All building is done with the scripts/mupdfwrap.py script.

Build C++ and Python MuPDF APIs and run basic tests with:

    cd mupdf
    ./scripts/mupdfwrap.py -b all -t

Debug build:

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

For more details, run ./scripts/mupdfwrap.py -h to see help, or look at the doc-string at beginning of the script directly.

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.)

Example Python code:

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

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:

• Built by mupdfwrap.py -b m (also included in -b all).
• This runs make internally.

mupdfwrap.py 's 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 methods that call fz_() functions.
• C header file comments are copied into the generated C++ header files.

mupdfwrap.py 's 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+, we tell it to propagate C++ comments into the generated Python.

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]
                        classes.h
                        exceptions.h
                        functions.h
                        internal.h

Other internal generated files:

    mupdf/
        build/
        platform/
            c++/
                implementation/
                    *.cpp [MuPDF C++ implementation.]
            python/
                [SWIG files.]

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