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:
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