README.rst
1==================
2python-poppler-qt5
3==================
4
5A Python binding for libpoppler-qt5 that aims for completeness and for being
6actively maintained.
7
8Created and currently maintained by Wilbert Berendsen <wbsoft@xs4all.nl>.
9
10Homepage: https://pypi.python.org/pypi/python-poppler-qt5/
11
12
13Usage::
14
15 import popplerqt5
16 d = popplerqt5.Poppler.Document.load('file.pdf')
17
18
19Documentation
20-------------
21
22The Python API closely follows the Poppler Qt5 C++ interface library API,
23documented at http://people.freedesktop.org/~aacid/docs/qt5/ .
24
25Note: Releases of PyQt5 < 5.4 currently do not support the QtXml module,
26all methods that use the QDomDocument, QDomElement and QDomNode types are
27disabled. This concerns the ``Document::toc()`` method and some constructors
28and the ``store()`` methods in the ``Annotation`` subclasses. So, using
29PyQt5 >= 5.4 is recommended.
30
31Wherever the C++ API requires ``QList``, ``QSet`` or ``QLinkedList``, any
32Python sequence can be used.
33API calls that return ``QList``, ``QSet`` or ``QLinkedList`` all return Python
34lists.
35
36There are a few other differences:
37
38``Poppler::Document::getPdfVersion(int *major, int *minor)`` can simply be
39called as ``d.getPdfVersion()``, (where ``d`` is a ``Poppler::Document``
40instance); it will return a tuple of two integers (major, minor).
41
42``Poppler::Document`` has ``__len__`` and ``__getitem__`` methods, corresponding
43to ``numPages()`` and ``page(int num)``.
44
45``Poppler::FontIterator`` (returned by ``Poppler::Document::newFontIterator``)
46is also a Python iterable (e.g. has ``__iter__()`` and ``__next__()`` methods).
47So although you can use::
48
49 it = document.newFontIterator()
50 while it.hasNext():
51 fonts = it.next() # list of FontInfo objects
52 ...
53
54you can also use the more Pythonic::
55
56 for fonts in document.newFontIterator():
57 ...
58
59In addition to the Poppler namespace, there are two toplevel module
60functions:
61
62 ``popplerqt5.version()``
63 returns the version of the ``python-poppler-qt5`` package as a
64 tuple of ints, e.g. ``(0, 18, 2)``.
65
66 ``popplerqt5.poppler_version()``
67 returns the version of the linked Poppler-Qt5 library as a
68 tuple of ints, e.g. ``(0, 24, 5)``.
69
70 This is determined at build time. If at build time the Poppler-Qt5
71 version could not be determined and was not specified, an empty
72 tuple might be returned.
73
74