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

  • 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 generated classes have extra support for iteration.
    • Some custom methods/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]


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

Edit | Attach | Watch | Print version | History: r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r4 - 2020-08-26 - JulianSmith
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 2014 Artifex Software Inc