Document¶
This class represents a document. It can be constructed from a file or from memory.
Since version 1.9.0 there exists the alias open
for this class.
For addional details on embedded files refer to Appendix 3.
Method / Attribute |
Short Description |
---|---|
decrypt the document |
|
close the document |
|
PDF only: copy a page to another location |
|
write a PDF version to memory |
|
PDF only: delete a page by its number |
|
PDF only: delete a range of pages |
|
PDF only: add a new embedded file from buffer |
|
PDF only: delete an embedded file entry |
|
PDF only: extract an embedded file buffer |
|
PDF only: metadata of an embedded file |
|
PDF only: change an embedded file |
|
PDF only: change metadata of an embedded file |
|
PDF only: make a list of fonts on a page |
|
PDF only: make a list of images on a page |
|
create a pixmap of a page by page number |
|
extract the text of a page by page number |
|
create a table of contents |
|
PDF only: insert a new page |
|
PDF only: insert pages from another PDF |
|
re-paginate the document (if supported) |
|
read a page |
|
PDF only: move a page to another location |
|
PDF only: insert a new empty page |
|
PDF only: save the document |
|
PDF only: save the document incrementally |
|
search for a string on a page |
|
PDF only: select a subset of pages |
|
PDF only: set the metadata |
|
PDF only: set the table of contents (TOC) |
|
PDF only: writes the document to memory |
|
number of embedded files |
|
PDF only: list of existing field fonts |
|
has document been closed? |
|
is this a PDF? |
|
is this a Form PDF? |
|
is this a reflowable document? |
|
metadata |
|
filename of document |
|
require password to access data? |
|
document (still) encrypted? |
|
> 0 if repair occurred during open |
|
last error message if openErrCode > 0 |
|
first Outline item |
|
number of pages |
|
permissions to access the document |
Class API
-
class
Document
¶ -
__init__
(self, filename=None, stream=None, filetype=None, rect=None, width=0, height=0, fontsize=11)¶ Creates a
Document
object.With default parameters, a new empty PDF document will be created.
If
stream
is given, then the document is created from memory and eitherfilename
orfiletype
must indicate its type.If
stream
isNone
, then a document is created from a file given byfilename
. Its type is inferred from the extension, which can be overruled by specifyingfiletype
.
- Parameters
filename (str|pathlib) – A UTF-8 string or
pathlib
object containing a file path (or a file type, see below).stream (bytes|bytearray|BytesIO) –
A memory area containing a supported document. Its type must be specified by either
filename
orfiletype
.Changed in version 1.14.13:
io.BytesIO
is now also supported.filetype (str) – A string specifying the type of document. This may be something looking like a filename (e.g.
"x.pdf"
), in which case MuPDF uses the extension to determine the type, or a mime type likeapplication/pdf
. Just using strings like"pdf"
will also work.rect (rect-like) – a rectangle specifying the desired page size. This parameter is only meaningful for documents with a variable page layout (“reflowable” documents), like e-books or HTML, and ignored otherwise. If specified, it must be a non-empty, finite rectangle with top-left coordinates (0, 0). Together with parameter
fontsize
, each page will be accordingly laid out and hence also determine the number of pages.width (float) – may used together with
height
as an alternative torect
to specify layout information.height (float) – may used together with
width
as an alternative torect
to specify layout information.fontsize (float) – the default fontsize for reflowable document types. This parameter is ignored if none of the parameters
rect
orwidth
andheight
are specified. Will be used to calculate the page layout.
Overview of possible forms (using the
open
synonym ofDocument
):>>> # from a file >>> doc = fitz.open("some.pdf") >>> doc = fitz.open("some.file", None, "pdf") # copes with wrong extension >>> doc = fitz.open("some.file", filetype="pdf") # copes with wrong extension
>>> # from memory >>> doc = fitz.open("pdf", mem_area) >>> doc = fitz.open(None, mem_area, "pdf") >>> doc = fitz.open(stream=mem_area, filetype="pdf")
>>> # new empty PDF >>> doc = fitz.open()
-
authenticate
(password)¶ Decrypts the document with the string
password
. If successful, all of the document’s data can be accessed (e.g. for rendering).- Parameters
password (str) – The password to be used.
- Return type
int
- Returns
positive value if decryption was successful, zero otherwise. If successful, indicator
isEncrypted
is set toFalse
.
-
loadPage
(pno=0)¶ Load a Page for further processing like rendering, text searching, etc.
- Parameters
pno (int) – page number, zero-based (0 is default and the first page of the document). Any value in
range(-inf, doc.pageCount)
is acceptable. If pno is negative, thendoc.pageCount
will be added until this is no longer the case. For example: to load the last page, you can specifydoc.loadPage(-1)
. After this you havepage.number == doc.pageCount - 1
.- Return type
Note
Documents also follow the Python sequence protocol with page numbers as indices:
doc.loadPage(n) == doc[n]
. Consequently, expressions like"for page in doc: ..."
and"for page in reversed(doc): ..."
will successively yield the document’s pages.-
convertToPDF
(from_page=-1, to_page=-1, rotate=0)¶ Create a PDF version of the current document and write it to memory. All document types (except PDF) are supported. The parameters have the same meaning as in
insertPDF()
. In essence, you can restrict the conversion to a page subset, specify page rotation, and revert page sequence.- Parameters
from_page (int) – first page to copy (0-based). Default is first page.
to_page (int) – last page to copy (0-based). Default is last page.
rotate (int) – rotation angle. Default is 0 (no rotation). Should be
n * 90
with an integern
(not checked).
- Return type
bytes
- Returns
a Python
bytes
object containing a PDF file image. It is created by internally usingwrite(garbage=4, deflate=True)
. Seewrite()
. You can output it directly to disk or open it as a PDF viafitz.open("pdf", pdfbytes)
. Here are some examples:
>>> # convert an XPS file to PDF >>> xps = fitz.open("some.xps") >>> pdfbytes = xps.convertToPDF() >>> >>> # either do this ---> >>> pdf = fitz.open("pdf", pdfbytes) >>> pdf.save("some.pdf") >>> >>> # or this ---> >>> pdfout = open("some.pdf", "wb") >>> pdfout.write(pdfbytes) >>> pdfout.close()
>>> # copy image files to PDF pages >>> # each page will have image dimensions >>> doc = fitz.open() # new PDF >>> imglist = [ ... image file names ...] # e.g. a directory listing >>> for img in imglist: imgdoc=fitz.open(img) # open image as a document pdfbytes=imgdoc.convertToPDF() # make a 1-page PDF of it imgpdf=fitz.open("pdf", pdfbytes) doc.insertPDF(imgpdf) # insert the image PDF >>> doc.save("allmyimages.pdf")
Note
The method uses the same logic as the
mutool convert
CLI. This works very well in most cases – however, beware of the following limitations.Image files: perfect, no issues detected. Apparently however, image transparency is ignored. If you need that (like for a watermark), use
Page.insertImage()
instead. Otherwise, this method is recommended for its much better prformance.XPS: appearance very good. Links work fine, outlines (bookmarks) are lost, but can easily be recovered 2.
EPUB, CBZ, FB2: similar to XPS.
SVG: medium. Roughly comparable to svglib.
-
getToC
(simple=True)¶ Creates a table of contents out of the document’s outline chain.
- Parameters
simple (bool) – Indicates whether a simple or a detailed ToC is required. If
simple == False
, each entry of the list also contains a dictionary with linkDest details for each outline entry.- Return type
list
- Returns
a list of lists. Each entry has the form
[lvl, title, page, dest]
. Its entries have the following meanings:lvl
– hierarchy level (positive int). The first entry is always 1. Entries in a row are either equal, increase by 1, or decrease by any number.title
– title (str)page
– 1-based page number (int). Page numbers< 1
either indicate a target outside this document or no target at all (see next entry).dest
– (dict) included only ifsimple=False
. Contains details of the link destination.
-
getPagePixmap
(pno, *args, **kwargs)¶ Creates a pixmap from page
pno
(zero-based). InvokesPage.getPixmap()
.- Return type
-
getPageImageList
(pno)¶ PDF only: Return a list of all image descriptions referenced by a page.
- Parameters
pno (int) – page number, 0-based, any value
< len(doc)
.- Return type
list
- Returns
a list of images shown on this page. Each entry looks like
[xref, smask, width, height, bpc, colorspace, alt. colorspace, name, filter]
. Wherexref
(int) is the image object number,smask
(int optional) is the object number of its soft-mask image (if present),width
andheight
(ints) are the image dimensions,bpc
(int) denotes the number of bits per component (a typical value is 8),colorspace
(str)a string naming the colorspace (likeDeviceRGB
),alt. colorspace
(str optional) is any alternate colorspace depending on the value ofcolorspace
,name
(str) is the symbolic name by which the page references the image in its content stream, andfilter
(str optional) is the decode filter of the image (Adobe PDF Reference 1.7, pp. 65).
See below how this information can be used to extract PDF images as separate files. Another demonstration:
>>> doc = fitz.open("pymupdf.pdf") >>> doc.getPageImageList(0) [[316, 0, 261, 115, 8, 'DeviceRGB', '', 'Im1', 'DCTDecode']] >>> pix = fitz.Pixmap(doc, 316) # 316 is the xref of the image >>> pix fitz.Pixmap(DeviceRGB, fitz.IRect(0, 0, 261, 115), 0)
Note
This list has no duplicate entries: the combination of
xref
andname
is unique. But by themselves, each of the two may occur multiple times. The same image may well be referenced under different names within a page. Duplicatename
entries on the other hand indicate the presence of “Form XObjects” on the page, e.g. generated byPage.showPDFpage()
.
-
getPageFontList
(pno)¶ PDF only: Return a list of all fonts referenced by the page.
- Parameters
pno (int) – page number, 0-based, any value
< len(doc)
.- Return type
list
- Returns
a list of fonts referenced by this page. Each entry looks like
[xref, ext, type, basefont, name, encoding]
. Wherexref
(int) is the font object number (may be zero if the PDF uses one of the builtin fonts directly),ext
(str) font file extension (e.g.ttf
, see Font File Extensions),type
(str) is the font type (likeType1
orTrueType
etc.),basefont
(str) is the base font name,name
(str) is the reference name (or label), by which the page references the font in its contents stream(s), andencoding
(str optional) the font’s character encoding if different from its built-in encoding (Adobe PDF Reference 1.7, p. 414):
>>> doc = fitz.open("some.pdf") >>> for f in doc.getPageFontList(0): print(f) [24, 'ttf', 'TrueType', 'DOKBTG+Calibri', 'R10', ''] [17, 'ttf', 'TrueType', 'NZNDCL+CourierNewPSMT', 'R14', ''] [32, 'ttf', 'TrueType', 'FNUUTH+Calibri-Bold', 'R8', ''] [28, 'ttf', 'TrueType', 'NOHSJV+Calibri-Light', 'R12', ''] [8, 'ttf', 'Type0', 'ECPLRU+Calibri', 'R23', 'Identity-H']
Note
This list has no duplicate entries: the combination of
xref
andname
is unique. But by themselves, each of the two may occur multiple times. Duplicatename
entries indicate the presence of “Form XObjects” on the page, e.g. generated byPage.showPDFpage()
.
-
getPageText
(pno, output="text")¶ Extracts the text of a page given its page number
pno
(zero-based). InvokesPage.getText()
.- Parameters
pno (int) – page number, 0-based, any value
< len(doc)
.output (str) – A string specifying the requested output format: text, html, json or xml. Default is
text
.
- Return type
str
-
layout
(rect=None, width=0, height=0, fontsize=11)¶ Re-paginate (“reflow”) the document based on the given page dimension and fontsize. This only affects some document types like e-books and HTML. Ignored if not supported. Supported documents have
True
in propertyisReflowable
.- Parameters
rect (rect-like) – desired page size. Must be finite, not empty and start at point (0, 0).
width (float) – use it together with
height
as alternative torect
.height (float) – use it together with
width
as alternative torect
.fontsize (float) – the desired default fontsize.
-
select
(s)¶ PDF only: Keeps only those pages of the document whose numbers occur in the list. Empty sequences or elements outside
range(len(doc))
will cause aValueError
. For more details see remarks at the bottom or this chapter.- Parameters
s (sequence) – A sequence (see Using Python Sequences as Arguments in PyMuPDF) of page numbers (zero-based) to be included. Pages not in the sequence will be deleted (from memory) and become unavailable until the document is reopened. Page numbers can occur multiple times and in any order: the resulting document will reflect the sequence exactly as specified.
-
setMetadata
(m)¶ PDF only: Sets or updates the metadata of the document as specified in
m
, a Python dictionary. As withselect()
, these changes become permanent only when you save the document. Incremental save is supported.- Parameters
m (dict) – A dictionary with the same keys as
metadata
(see below). All keys are optional. A PDF’s format and encryption method cannot be set or changed and will be ignored. If any value should not contain data, do not specify its key or set the value toNone
. If you use{}
all metadata information will be cleared to the string"none"
. If you want to selectively change only some values, modify a copy ofdoc.metadata
and use it as the argument. Arbitrary unicode values are possible if specified as UTF-8-encoded.
-
setToC
(toc)¶ PDF only: Replaces the complete current outline tree (table of contents) with the new one provided as the argument. After successful execution, the new outline tree can be accessed as usual via method
getToC()
or via propertyoutline
. Like with other output-oriented methods, changes become permanent only viasave()
(incremental save supported). Internally, this method consists of the following two steps. For a demonstration see example below.Step 1 deletes all existing bookmarks.
Step 2 creates a new TOC from the entries contained in
toc
.
- Parameters
toc (sequence) –
A Python nested sequence with all bookmark entries that should form the new table of contents. Each entry is a list with the following format. Output variants of method
getToC()
are also acceptable as input.[lvl, title, page, dest]
, wherelvl
is the hierarchy level (int > 0) of the item, starting with1
and being at most 1 higher than that of the predecessor,title
(str) is the title to be displayed. It is assumed to be UTF-8-encoded (relevant for multibyte code points only).page
(int) is the target page number (attention: 1-based to support getToC()-output), must be in valid page range if positive. Set this to-1
if there is no target, or the target is external.dest
(optional) is a dictionary or a number. If a number, it will be interpreted as the desired height (in points) this entry should point to onpage
in the current document. Use a dictionary (like the one given as output bygetToC(simple=False)
) if you want to store destinations that are either “named”, or reside outside this documennt (other files, internet resources, etc.).
- Return type
int
- Returns
outline
andgetToC()
will be updated upon successful execution. The return code will either equal the number of inserted items (len(toc)
) or the number of deleted items iftoc
is an empty sequence.
Note
We currently always set the Outline attribute
is_open
toFalse
. This shows all entries below level 1 as collapsed.
-
save
(outfile, garbage=0, clean=False, deflate=False, incremental=False, ascii=False, expand=0, linear=False, pretty=False, decrypt=True)¶ PDF only: Saves the document in its current state under the name
outfile
.- Parameters
outfile (str) – The file name to save to. Must be different from the original value if “incremental” is false or zero. When saving incrementally, “garbage” and “linear” must be false or zero and this parameter must equal the original filename (for convenience use
doc.name
).garbage (int) –
Do garbage collection. Positive values exclude
incremental
.0 = none
1 = remove unused objects
2 = in addition to 1, compact the
xref
table3 = in addition to 2, merge duplicate objects
4 = in addition to 3, check object streams for duplication (may be slow)
clean (bool) – Clean content streams 1.
deflate (bool) – Deflate (compress) uncompressed streams.
incremental (bool) – Only save changed objects. Excludes “garbage” and “linear”. Cannot be used for decrypted files and for repaired files (
openErrCode > 0
). In these cases saving to a new file is required.ascii (bool) – Where possible convert binary data to ASCII.
expand (int) –
Decompress objects. Generates versions that can be better read by some other programs.
0 = none
1 = images
2 = fonts
255 = all
linear (bool) – Save a linearised version of the document. This option creates a file format for improved performance when read via internet connections. Excludes “incremental”.
pretty (bool) – Prettify the document source for better readability.
decrypt (bool) – Save a decrypted copy (the default). If false, the resulting PDF will be encrypted with the same password as the original. Will be ignored for non-encrypted files.
-
saveIncr
()¶ PDF only: saves the document incrementally. This is a convenience abbreviation for
doc.save(doc.name, incremental=True)
.
Caution
A PDF may not be encrypted, but still be password protected against changes – see the
permissions
property. Performing incremental saves whilepermissions["edit"] == False
can lead to unpredictable results. Save to a new file in such a case. We also consider raising an exception under this condition.-
searchPageFor
(pno, text, hit_max=16, quads=False)¶ Search for
text
on page numberpno
. Works exactly like the correspondingPage.searchFor()
. Any integer-inf < pno < len(doc)
is acceptable.
-
write
(garbage=0, clean=False, deflate=False, ascii=False, expand=0, linear=False, pretty=False, decrypt=True)¶ PDF only: Writes the current content of the document to a bytes object instead of to a file like
save()
. Obviously, you should be wary about memory requirements. The meanings of the parameters exactly equal those insave()
. Cpater Collection of Recipes contains an example for using this method as a pre-processor to pdfrw.- Return type
bytes
- Returns
a bytes object containing the complete document data.
-
insertPDF
(docsrc, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True)¶ PDF only: Copy the page range [from_page, to_page] (including both) of PDF document
docsrc
into the current one. Inserts will start with page numberstart_at
. Negative values can be used to indicate default values. All pages thus copied will be rotated as specified. Links can be excluded in the target, see below. All page numbers are zero-based.- Parameters
docsrc (
Document
) – An opened PDFDocument
which must not be the current document object. However, it may refer to the same underlying file.from_page (int) – First page number in
docsrc
. Default is zero.to_page (int) – Last page number in
docsrc
to copy. Default is the last page.start_at (int) – First copied page will become page number
start_at
in the destination. If omitted, the page range will be appended to current document. If zero, the page range will be inserted before current first page.rotate (int) – All copied pages will be rotated by the provided value (degrees, integer multiple of 90).
links (bool) – Choose whether (internal and external) links should be included with the copy. Default is
True
. An internal link is always excluded if its destination is outside the copied page range.
Note
If
from_page > to_page
, pages will be copied in reverse order. If0 <= from_page == to_page
, then one page will be copied.docsrc
bookmarks will not be copied. It is easy however, to recover a table of contents for the resulting document. Look at the examples below and at program PDFjoiner.py in the examples directory: it can join PDF documents and at the same time piece together respective parts of the tables of contents.
-
newPage
(pno=-1, width=595, height=842)¶ PDF only: Insert an empty page.
- Parameters
pno (int) – page number in front of which the new page should be inserted. Must be in
range(-1, len(doc) + 1)
. Special values -1 andlen(doc)
insert after the last page.width (float) – page width.
height (float) – page height.
- Return type
- Returns
the created page object.
-
insertPage
(pno, text=None, fontsize=11, width=595, height=842, fontname="helv", fontfile=None, color=None)¶ PDF only: Insert a new page and insert some text. Convenience function which combines
Document.newPage()
and (parts of)Page.insertText()
.- Parameters
pno (int) –
page number (0-based) in front of which to insert. Must be in
range(-1, len(doc) + 1)
. Special values -1 andlen(doc)
insert after the last page.Changed in version 1.14.12: This is now a positional parameter
For the other parameters, please consult the aforementioned methods.
- Return type
int
- Returns
the result of
Page.insertText()
(number of successfully inserted lines).
-
deletePage
(pno=-1)¶ PDF only: Delete a page given by its 0-based number in
range(-inf, len(doc)-1)
.- Parameters
pno (int) – the page to be deleted. Negative number count backwards from the end of the document (like with indices).
-
deletePageRange
(from_page=-1, to_page=-1)¶ PDF only: Delete a range of pages specified as 0-based numbers. Any
-1
parameter will first be replaced bylen(doc) - 1
. After that, condition0 <= from_page <= to_page < len(doc)
must be true. If the parameters are equal, one page will be deleted. This method invokesPage.deletePage()
for each number in the given range.- Parameters
from_page (int) – the first page to be deleted.
to_page (int) – the last page to be deleted.
-
copyPage
(pno, to=-1)¶ PDF only: Copy a page within the document.
- Parameters
pno (int) – the page to be copied. Must be in range
0 <= pno < len(doc)
.to (int) – the page number in front of which to copy. To insert after the last page (default), specify
-1
.
-
movePage
(pno, to=-1)¶ PDF only: Move (copy and then delete original) a page within the document.
- Parameters
pno (int) – the page to be moved. Must be in range
0 <= pno < len(doc)
.to (int) – the page number in front of which to insert the moved page. To insert after the last page (default), specify
-1
.
-
embeddedFileAdd
(buffer, name, filename=None, ufilename=None, desc=None)¶ PDF only: Embed a new file. All string parameters except the name may be unicode (in previous versions, only ASCII worked correctly). File contents will be compressed (where beneficial).
- Parameters
buffer (bytes|bytearray|BytesIO) –
file contents.
Changed in version 1.14.13:
io.BytesIO
is now also supported.name (str) – entry identifier, must not already exist.
filename (str) – optional filename. Documentation only, will be set to
name
ifNone
.ufilename (str) – optional unicode filename. Documentation only, will be set to
filename
ifNone
.desc (str) – optional description. Documentation only, will be set to
name
ifNone
.
Note
The position of the new entry in the embedded files list can in general not be predicted. Do not assume a specific place (like the end or the beginning), even if the chosen name seems to suggest it. If you add several files with this method, their sequence in that list will probably not be maintained either. In addition, the various PDF viewers each seem to use their own ordering logic when showing the list of embedded files for the same PDF.
-
embeddedFileGet
(n)¶ PDF only: Retrieve the content of embedded file by its entry number or name. If the document is not a PDF, or entry cannot be found, an exception is raised.
- Parameters
n (int|str) – index or name of entry. An integer must be in
range(0, embeddedFileCount)
.- Return type
bytes
-
embeddedFileDel
(name)¶ PDF only: Remove an entry from /EmbeddedFiles. As always, physical deletion of the embedded file content (and file space regain) will occur when the document is saved to a new file with garbage option.
- Parameters
name (str) – name of entry. We do not support entry numbers for this function yet. If you need to e.g. delete all embedded files, scan through embedded files by number, and use the returned dictionary’s
name
entry to delete each one.- Return type
int
- Returns
the number of deleted file entries.
Caution
This function will delete every entry with this name. Be aware that PDFs not created with PyMuPDF may contain duplicate names, in which case more than one entry may be deleted.
-
embeddedFileInfo
(n)¶ PDF only: Retrieve information of an embedded file given by its number or by its name.
- Parameters
n (int/str) – index or name of entry. An integer must be in
range(0, embeddedFileCount)
.- Return type
dict
- Returns
a dictionary with the following keys:
name
– (str) name under which this entry is storedfilename
– (str) filenameufilename
– (unicode) filenamedesc
– (str) descriptionsize
– (int) original file sizelength
– (int) compressed file length
-
embeddedFileUpd
(n, buffer=None, filename=None, ufilename=None, desc=None)¶ PDF only: Change an embedded file given its entry number or name. All parameters are optional. Letting them default leads to a no-operation.
- Parameters
n (int/str) – index or name of entry. An integer must be in
range(0, embeddedFileCount)
.buffer (bytes|bytearray|BytesIO) –
the new file content.
Changed in version 1.14.13:
io.BytesIO
is now also supported.filename (str) – the new filename.
ufilename (str) – the new unicode filename.
desc (str) – the new description.
-
embeddedFileSetInfo
(n, filename=None, ufilename=None, desc=None)¶ PDF only: Change embedded file meta information. All parameters are optional. Letting them default will lead to a no-operation.
- Parameters
n (int|str) – index or name of entry. An integer must be in
range(0, embeddedFileCount)
.filename (str) – sets the filename.
ufilename (str) – sets the unicode filename.
desc (str) – sets the description.
Note
Deprecated subset of
embeddedFileUpd()
. Will be deleted in a future version.
-
close
()¶ Release objects and space allocations associated with the document. If created from a file, also closes it (releasing control to the OS).
-
outline
¶ Contains the first Outline entry of the document (or
None
). Can be used as a starting point to walk through all outline items. Accessing this property for encrypted, not authenticated documents will raise anAttributeError
.- Type
-
isClosed
¶ False
if document is still open. If closed, most other attributes and methods will have been deleted / disabled. In addition, Page objects referring to this document (i.e. created withDocument.loadPage()
) and their dependent objects will no longer be usable. For reference purposes,Document.name
still exists and will contain the filename of the original document (if applicable).- Type
bool
-
isPDF
¶ True
if this is a PDF document, elseFalse
.- Type
bool
-
isFormPDF
¶ True
if this is a Form PDF document with field count greater zero, elseFalse
.- Type
bool
-
isReflowable
¶ True
if document has a variable page layout (like e-books or HTML). In this case you can set the desired page dimensions during document creation (open) or via methodlayout()
.- Type
bool
-
needsPass
¶ Contains an indicator showing whether the document is password-protected against any access (
True
) or not (False
). This indicator remains unchanged – even after the document has been authenticated. Precludes incremental saves ifTrue
.- Type
bool
-
isEncrypted
¶ This indicator initially equals
needsPass
. After an authentication, it is set toFalse
to reflect the situation.- Type
bool
-
permissions
¶ Shows the permissions to access the document. Contains a dictionary likes this:
>>> doc.permissions {'print': True, 'edit': True, 'note': True, 'copy': True}
The keys have the obvious meanings of permissions to print, change, annotate and copy the document, respectively.
- Type
dict
-
metadata
¶ Contains the document’s meta data as a Python dictionary or
None
(ifisEncrypted=True
andneedPass=True
). Keys areformat
,encryption
,title
,author
,subject
,keywords
,creator
,producer
,creationDate
,modDate
. All item values are strings orNone
.Except
format
andencryption
, the key names correspond in an obvious way to the PDF keys/Creator
,/Producer
,/CreationDate
,/ModDate
,/Title
,/Author
,/Subject
, and/Keywords
respectively.format
contains the PDF version (e.g. ‘PDF-1.6’).encryption
either containsNone
(no encryption), or a string naming an encryption method (e.g.'Standard V4 R4 128-bit RC4'
). Note that an encryption method may be specified even ifneedsPass=False
. In such cases not all permissions will probably have been granted. Check dictionarypermissions
for details.If the date fields contain valid data (which need not be the case at all!), they are strings in the PDF-specific timestamp format “D:<TS><TZ>”, where
<TS> is the 12 character ISO timestamp
YYYYMMDDhhmmss
(YYYY
- year,MM
- month,DD
- day,hh
- hour,mm
- minute,ss
- second), and<TZ> is a time zone value (time intervall relative to GMT) containing a sign (‘+’ or ‘-‘), the hour (
hh
), and the minute ('mm'
, note the apostrophies!).
A Paraguayan value might hence look like
D:20150415131602-04'00'
, which corresponds to the timestamp April 15, 2015, at 1:16:02 pm local time Asuncion.
- Type
dict
-
name
¶ Contains the
filename
orfiletype
value with whichDocument
was created.- Type
str
-
pageCount
¶ Contains the number of pages of the document. May return 0 for documents with no pages. Function
len(doc)
will also deliver this result.- Type
int
-
openErrCode
¶ If
openErrCode > 0
, errors have occurred while opening / parsing the document, which usually means damages like document structure issues. In this case incremental save cannot be used. The document is available for processing however, potentially with restrictions (depending on damage details).- Type
int
-
openErrMsg
¶ Contains either an empty string or the last open error message if
openErrCode > 0
. To see all messages, look atTools.fitz_stderr
, e.g.print(fitz.TOOLS.fitz_stderr)
.- Type
str
-
embeddedFileCount
¶ Contains the number of files in the /EmbeddedFiles list, -1 if the document is not a PDF.
- Type
int
-
FormFonts
¶ A list of font resource names. Contains
None
if not a PDF and[]
if not a Form PDF.- Type
int
-
Note
For methods that change the structure of a PDF (insertPDF()
, select()
, copyPage()
, deletePage()
and others), be aware that objects or properties in your program may have been invalidated or orphaned. Examples are Page objects and their children (links and annotations), variables holding old page counts, tables of content and the like. Remember to keep such variables up to date or delete orphaned objects.
Remarks on select()
¶
Page numbers in the sequence need not be unique nor be in any particular order. This makes the method a versatile utility to e.g. select only the even or the odd pages, re-arrange a document from back to front, duplicate it, and so forth. In combination with text search or extraction you can also omit / include pages with no text or containing a certain text, etc.
If you have de-selected many pages, consider specifying the garbage
option to eventually reduce the resulting document’s size (when saving to a new file).
Also note, that this method preserves all links, annotations and bookmarks that are still valid. In other words: deleting pages only deletes references which point to de-selected pages. Page numbers of bookmarks (outline items) are automatically updated when a TOC is retrieved again after execution of this method. If a bookmark’s destination page happened to be deleted, then its page number will be set to -1
.
The results of this method can of course also be achieved using combinations of methods copyPage()
, deletePage()
etc. While there are many cases, when these methods are more practical, select()
is easier and safer to use when many pages are involved.
select()
Examples¶
In general, any sequence of integers that are in the document’s page range can be used. Here are some illustrations.
Delete pages with no text:
import fitz
doc = fitz.open("any.pdf")
r = list(range(len(doc))) # list of page numbers
for page in doc:
if not page.getText(): # page contains no text
r.remove(page.number) # remove page number from list
if len(r) < len(doc): # did we actually delete anything?
doc.select(r) # apply the list
doc.save("out.pdf", garbage=4) # save result to new PDF, OR
# update the original document ... *** VERY FAST! ***
doc.saveIncr()
Create a sub document with only the odd pages:
>>> import fitz
>>> doc = fitz.open("any.pdf")
>>> r = list(range(0, len(doc), 2))
>>> doc.select(r) # apply the list
>>> doc.save("oddpages.pdf", garbage=4) # save sub-PDF of the odd pages
Concatenate a document with itself:
>>> import fitz
>>> doc = fitz.open("any.pdf")
>>> r = list(range(len(doc)))
>>> r += r # turn PDF into a copy of itself
>>> doc.select(r)
>>> doc.save("any+any.pdf") # contains doubled <any.pdf>
Create document copy in reverse page order (well, don’t try with a million pages):
>>> import fitz
>>> doc = fitz.open("any.pdf")
>>> r = list(range(len(doc)))
>>> r.reverse()
>>> doc.select(r)
>>> doc.save("back-to-front.pdf")
setMetadata()
Example¶
Clear metadata information. If you do this out of privacy / data protection concerns, make sure you save the document as a new file with garbage > 0
. Only then the old /Info
object will also be physically removed from the file. In this case, you may also want to clear any XML metadata inserted by several PDF editors:
>>> import fitz
>>> doc=fitz.open("pymupdf.pdf")
>>> doc.metadata # look at what we currently have
{'producer': 'rst2pdf, reportlab', 'format': 'PDF 1.4', 'encryption': None, 'author':
'Jorj X. McKie', 'modDate': "D:20160611145816-04'00'", 'keywords': 'PDF, XPS, EPUB, CBZ',
'title': 'The PyMuPDF Documentation', 'creationDate': "D:20160611145816-04'00'",
'creator': 'sphinx', 'subject': 'PyMuPDF 1.9.1'}
>>> doc.setMetadata({}) # clear all fields
>>> doc.metadata # look again to show what happened
{'producer': 'none', 'format': 'PDF 1.4', 'encryption': None, 'author': 'none',
'modDate': 'none', 'keywords': 'none', 'title': 'none', 'creationDate': 'none',
'creator': 'none', 'subject': 'none'}
>>> doc._delXmlMetadata() # clear any XML metadata
>>> doc.save("anonymous.pdf", garbage = 4) # save anonymized doc
setToC()
Demonstration¶
This shows how to modify or add a table of contents. Also have a look at csv2toc.py and toc2csv.py in the examples directory.
>>> import fitz
>>> doc = fitz.open("test.pdf")
>>> toc = doc.getToC()
>>> for t in toc: print(t) # show what we have
[1, 'The PyMuPDF Documentation', 1]
[2, 'Introduction', 1]
[3, 'Note on the Name fitz', 1]
[3, 'License', 1]
>>> toc[1][1] += " modified by setToC" # modify something
>>> doc.setToC(toc) # replace outline tree
3 # number of bookmarks inserted
>>> for t in doc.getToC(): print(t) # demonstrate it worked
[1, 'The PyMuPDF Documentation', 1]
[2, 'Introduction modified by setToC', 1] # <<< this has changed
[3, 'Note on the Name fitz', 1]
[3, 'License', 1]
insertPDF()
Examples¶
(1) Concatenate two documents including their TOCs:
>>> doc1 = fitz.open("file1.pdf") # must be a PDF
>>> doc2 = fitz.open("file2.pdf") # must be a PDF
>>> pages1 = len(doc1) # save doc1's page count
>>> toc1 = doc1.getToC(False) # save TOC 1
>>> toc2 = doc2.getToC(False) # save TOC 2
>>> doc1.insertPDF(doc2) # doc2 at end of doc1
>>> for t in toc2: # increase toc2 page numbers
t[2] += pages1 # by old len(doc1)
>>> doc1.setToC(toc1 + toc2) # now result has total TOC
Obviously, similar ways can be found in more general situations. Just make sure that hierarchy levels in a row do not increase by more than one. Inserting dummy bookmarks before and after toc2
segments would heal such cases. A ready-to-use GUI (wxPython) solution can be found in script PDFjoiner.py of the examples directory.
(2) More examples:
>>> # insert 5 pages of doc2, where its page 21 becomes page 15 in doc1
>>> doc1.insertPDF(doc2, from_page=21, to_page=25, start_at=15)
>>> # same example, but pages are rotated and copied in reverse order
>>> doc1.insertPDF(doc2, from_page=25, to_page=21, start_at=15, rotate=90)
>>> # put copied pages in front of doc1
>>> doc1.insertPDF(doc2, from_page=21, to_page=25, start_at=0)
Other Examples¶
Extract all page-referenced images of a PDF into separate PNG files:
for i in range(len(doc)):
imglist = doc.getPageImageList(i)
for img in imglist:
xref = img[0] # xref number
pix = fitz.Pixmap(doc, xref) # make pixmap from image
if pix.n - pix.alpha < 4: # can be saved as PNG
pix.writePNG("p%s-%s.png" % (i, xref))
else: # CMYK: must convert first
pix0 = fitz.Pixmap(fitz.csRGB, pix)
pix0.writePNG("p%s-%s.png" % (i, xref))
pix0 = None # free Pixmap resources
pix = None # free Pixmap resources
Rotate all pages of a PDF:
>>> for page in doc: page.setRotation(90)
Footnotes
- 1
Content streams describe what (e.g. text or images) appears where and how on a page. PDF uses a specialized mini language similar to PostScript to do this (pp. 985 in Adobe PDF Reference 1.7), which gets interpreted when a page is loaded.
- 2
However, you can use
Document.getToC()
andPage.getLinks()
(which are available for all document types) and copy this information over to the output PDF. See demo pdf-converter.py.