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

Document.authenticate()

decrypt the document

Document.close()

close the document

Document.copyPage()

PDF only: copy a page to another location

Document.convertToPDF()

write a PDF version to memory

Document.deletePage()

PDF only: delete a page by its number

Document.deletePageRange()

PDF only: delete a range of pages

Document.embeddedFileAdd()

PDF only: add a new embedded file from buffer

Document.embeddedFileDel()

PDF only: delete an embedded file entry

Document.embeddedFileGet()

PDF only: extract an embedded file buffer

Document.embeddedFileInfo()

PDF only: metadata of an embedded file

Document.embeddedFileUpd()

PDF only: change an embedded file

Document.embeddedFileSetInfo()

PDF only: change metadata of an embedded file

Document.getPageFontList()

PDF only: make a list of fonts on a page

Document.getPageImageList()

PDF only: make a list of images on a page

Document.getPagePixmap()

create a pixmap of a page by page number

Document.getPageText()

extract the text of a page by page number

Document.getToC()

create a table of contents

Document.insertPage()

PDF only: insert a new page

Document.insertPDF()

PDF only: insert pages from another PDF

Document.layout()

re-paginate the document (if supported)

Document.loadPage()

read a page

Document.movePage()

PDF only: move a page to another location

Document.newPage()

PDF only: insert a new empty page

Document.save()

PDF only: save the document

Document.saveIncr()

PDF only: save the document incrementally

Document.searchPageFor()

search for a string on a page

Document.select()

PDF only: select a subset of pages

Document.setMetadata()

PDF only: set the metadata

Document.setToC()

PDF only: set the table of contents (TOC)

Document.write()

PDF only: writes the document to memory

Document.embeddedFileCount

number of embedded files

Document.FormFonts

PDF only: list of existing field fonts

Document.isClosed

has document been closed?

Document.isPDF

is this a PDF?

Document.isFormPDF

is this a Form PDF?

Document.isReflowable

is this a reflowable document?

Document.metadata

metadata

Document.name

filename of document

Document.needsPass

require password to access data?

Document.isEncrypted

document (still) encrypted?

Document.openErrCode

> 0 if repair occurred during open

Document.openErrMsg

last error message if openErrCode > 0

Document.outline

first Outline item

Document.pageCount

number of pages

Document.permissions

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 either filename or filetype must indicate its type.

  • If stream is None, then a document is created from a file given by filename. Its type is inferred from the extension, which can be overruled by specifying filetype.

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 or filetype.

    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 like application/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 to rect to specify layout information.

  • height (float) – may used together with width as an alternative to rect to specify layout information.

  • fontsize (float) – the default fontsize for reflowable document types. This parameter is ignored if none of the parameters rect or width and height are specified. Will be used to calculate the page layout.

Overview of possible forms (using the open synonym of Document):

>>> # 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 to False.

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, then doc.pageCount will be added until this is no longer the case. For example: to load the last page, you can specify doc.loadPage(-1). After this you have page.number == doc.pageCount - 1.

Return type

Page

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 integer n (not checked).

Return type

bytes

Returns

a Python bytes object containing a PDF file image. It is created by internally using write(garbage=4, deflate=True). See write(). You can output it directly to disk or open it as a PDF via fitz.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 if simple=False. Contains details of the link destination.

getPagePixmap(pno, *args, **kwargs)

Creates a pixmap from page pno (zero-based). Invokes Page.getPixmap().

Return type

Pixmap

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]. Where

  • xref (int) is the image object number,

  • smask (int optional) is the object number of its soft-mask image (if present),

  • width and height (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 (like DeviceRGB),

  • alt. colorspace (str optional) is any alternate colorspace depending on the value of colorspace,

  • name (str) is the symbolic name by which the page references the image in its content stream, and

  • filter (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 and name 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. Duplicate name entries on the other hand indicate the presence of “Form XObjects” on the page, e.g. generated by Page.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]. Where

  • xref (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 (like Type1 or TrueType 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), and

  • encoding (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 and name is unique. But by themselves, each of the two may occur multiple times. Duplicate name entries indicate the presence of “Form XObjects” on the page, e.g. generated by Page.showPDFpage().

getPageText(pno, output="text")

Extracts the text of a page given its page number pno (zero-based). Invokes Page.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 property isReflowable.

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 to rect.

  • height (float) – use it together with width as alternative to rect.

  • 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 a ValueError. 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 with select(), 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 to None. 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 of doc.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 property outline. Like with other output-oriented methods, changes become permanent only via save() (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], where

    • lvl is the hierarchy level (int > 0) of the item, starting with 1 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 on page in the current document. Use a dictionary (like the one given as output by getToC(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 and getToC() 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 if toc is an empty sequence.

Note

We currently always set the Outline attribute is_open to False. 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 table

    • 3 = 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 while permissions["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 number pno. Works exactly like the corresponding Page.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 in save(). 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 number start_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 PDF Document 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

  1. If from_page > to_page, pages will be copied in reverse order. If 0 <= from_page == to_page, then one page will be copied.

  2. 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 and len(doc) insert after the last page.

  • width (float) – page width.

  • height (float) – page height.

Return type

Page

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 and len(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 by len(doc) - 1. After that, condition 0 <= from_page <= to_page < len(doc) must be true. If the parameters are equal, one page will be deleted. This method invokes Page.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 if None.

  • ufilename (str) – optional unicode filename. Documentation only, will be set to filename if None.

  • desc (str) – optional description. Documentation only, will be set to name if None.

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 stored

  • filename – (str) filename

  • ufilename – (unicode) filename

  • desc – (str) description

  • size – (int) original file size

  • length – (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 an AttributeError.

Type

Outline

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 with Document.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, else False.

Type

bool

isFormPDF

True if this is a Form PDF document with field count greater zero, else False.

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 method layout().

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 if True.

Type

bool

isEncrypted

This indicator initially equals needsPass. After an authentication, it is set to False 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 (if isEncrypted=True and needPass=True). Keys are format, encryption, title, author, subject, keywords, creator, producer, creationDate, modDate. All item values are strings or None.

Except format and encryption, 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 contains None (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 if needsPass=False. In such cases not all permissions will probably have been granted. Check dictionary permissions 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 or filetype value with which Document 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 at Tools.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() and Page.getLinks() (which are available for all document types) and copy this information over to the output PDF. See demo pdf-converter.py.