From 179886f7ade43d077d73c0ad6ac865bac3fec055 Mon Sep 17 00:00:00 2001 From: Jamie Lemon Date: Wed, 27 Mar 2024 21:31:35 +0000 Subject: [PATCH] Documentation updates - Removes dependency on Prism for code highlighting - Corrects indentation on document.rst - Adds new areas throughout the documentation to generally better explain things - --- docs/annot.rst | 3 +- docs/document-writer-class.rst | 7 +- docs/document.rst | 2335 +++++++++++++------------ docs/footer.rst | 11 - docs/header.rst | 101 +- docs/how-to-open-a-file.rst | 3 +- docs/page.rst | 6 +- docs/recipes-annotations.rst | 4 +- docs/recipes-drawing-and-graphics.rst | 36 +- docs/recipes-text.rst | 25 + docs/shape.rst | 2 + docs/textwriter.rst | 2 + docs/the-basics.rst | 809 ++++----- docs/widget.rst | 2 + 14 files changed, 1660 insertions(+), 1686 deletions(-) diff --git a/docs/annot.rst b/docs/annot.rst index 027b03de2..badb96728 100644 --- a/docs/annot.rst +++ b/docs/annot.rst @@ -5,7 +5,8 @@ ================ Annot ================ -**This class is supported for PDF documents only.** + +|pdf_only_class| Quote from the :ref:`AdobeManual`: "An annotation associates an object such as a note, sound, or movie with a location on a page of a PDF document, or provides a way to interact with the user by means of the mouse and keyboard." diff --git a/docs/document-writer-class.rst b/docs/document-writer-class.rst index 515d50ce6..a0900e19f 100644 --- a/docs/document-writer-class.rst +++ b/docs/document-writer-class.rst @@ -6,11 +6,14 @@ DocumentWriter ================ +|pdf_only_class| + + * New in v1.21.0 -This class represents a utility which can output various :ref:`document types supported by MuPDF`. +This class represents a utility which can output various :ref:`document types supported by PyMuPDF`. -In PyMuPDF only used for outputting PDF documents whose pages are populated by :ref:`Story` DOMs. +In :title:`PyMuPDF` only used for outputting PDF documents whose pages are populated by :ref:`Story` DOMs. Using DocumentWriter_ also for other document types might happen in the future. diff --git a/docs/document.rst b/docs/document.rst index 73c97e3c6..3141fd104 100644 --- a/docs/document.rst +++ b/docs/document.rst @@ -151,1897 +151,1906 @@ For details on **embedded files** refer to Appendix 3. .. class:: Document - .. index:: - pair: filename; open - pair: stream; open - pair: filetype; open - pair: rect; open - pair: width; open - pair: height; open - pair: fontsize; open - pair: open; Document - pair: filename; Document - pair: stream; Document - pair: filetype; Document - pair: rect; Document - pair: fontsize; Document + .. index:: + pair: filename; open + pair: stream; open + pair: filetype; open + pair: rect; open + pair: width; open + pair: height; open + pair: fontsize; open + pair: open; Document + pair: filename; Document + pair: stream; Document + pair: filetype; Document + pair: rect; Document + pair: fontsize; Document - .. method:: __init__(self, filename=None, stream=None, *, filetype=None, rect=None, width=0, height=0, fontsize=11) + .. method:: __init__(self, filename=None, stream=None, *, filetype=None, rect=None, width=0, height=0, fontsize=11) - * Changed in v1.14.13: support `io.BytesIO` for memory documents. - * Changed in v1.19.6: Clearer, shorter and more consistent exception messages. File type "pdf" is always assumed if not specified. Empty files and memory areas will always lead to exceptions. + * Changed in v1.14.13: support `io.BytesIO` for memory documents. + * Changed in v1.19.6: Clearer, shorter and more consistent exception messages. File type "pdf" is always assumed if not specified. Empty files and memory areas will always lead to exceptions. - Creates a *Document* object. + 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, if not a PDF, either *filename* or *filetype* must indicate its type. - * If *stream* is `None`, then a document is created from the file given by *filename*. Its type is inferred from the extension. This can be overruled by *filetype.* + * With default parameters, a **new empty PDF** document will be created. + * If *stream* is given, then the document is created from memory and, if not a PDF, either *filename* or *filetype* must indicate its type. + * If *stream* is `None`, then a document is created from the file given by *filename*. Its type is inferred from the extension. This can be overruled by *filetype.* - :arg str,pathlib filename: A UTF-8 string or *pathlib* object containing a file path. The document type is inferred from the filename extension. If not present or not matching :ref:`a supported type`, a PDF document is assumed. For memory documents, this argument may be used instead of `filetype`, see below. + :arg str,pathlib filename: A UTF-8 string or *pathlib* object containing a file path. The document type is inferred from the filename extension. If not present or not matching :ref:`a supported type`, a PDF document is assumed. For memory documents, this argument may be used instead of `filetype`, see below. - :arg bytes,bytearray,BytesIO stream: A memory area containing a supported document. If not a PDF, its type **must** be specified by either `filename` or `filetype`. + :arg bytes,bytearray,BytesIO stream: A memory area containing a supported document. If not a PDF, its type **must** be specified by either `filename` or `filetype`. - :arg str filetype: A string specifying the type of document. This may be anything 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" or ".pdf" will also work. May be omitted for PDF documents, otherwise must match :ref:`a supported document type`. + :arg str filetype: A string specifying the type of document. This may be anything 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" or ".pdf" will also work. May be omitted for PDF documents, otherwise must match :ref:`a supported document type`. - :arg rect_like rect: 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. + :arg rect_like rect: 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. - :arg float width: may used together with *height* as an alternative to *rect* to specify layout information. + :arg float width: may used together with *height* as an alternative to *rect* to specify layout information. - :arg float height: may used together with *width* as an alternative to *rect* to specify layout information. + :arg float height: may used together with *width* as an alternative to *rect* to specify layout information. - :arg float fontsize: the default :data:`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. + :arg float fontsize: the default :data:`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. - :raises TypeError: if the *type* of any parameter does not conform. - :raises FileNotFoundError: if the file / path cannot be found. Re-implemented as subclass of `RuntimeError`. - :raises EmptyFileError: if the file / path is empty or the `bytes` object in memory has zero length. A subclass of `FileDataError` and `RuntimeError`. - :raises ValueError: if an unknown file type is explicitly specified. - :raises FileDataError: if the document has an invalid structure for the given type -- or is no file at all (but e.g. a folder). A subclass of `RuntimeError`. + :raises TypeError: if the *type* of any parameter does not conform. + :raises FileNotFoundError: if the file / path cannot be found. Re-implemented as subclass of `RuntimeError`. + :raises EmptyFileError: if the file / path is empty or the `bytes` object in memory has zero length. A subclass of `FileDataError` and `RuntimeError`. + :raises ValueError: if an unknown file type is explicitly specified. + :raises FileDataError: if the document has an invalid structure for the given type -- or is no file at all (but e.g. a folder). A subclass of `RuntimeError`. - :return: A document object. If the document cannot be created, an exception is raised in the above sequence. Note that PyMuPDF-specific exceptions, `FileNotFoundError`, `EmptyFileError` and `FileDataError` are intercepted if you check for `RuntimeError`. + :return: A document object. If the document cannot be created, an exception is raised in the above sequence. Note that PyMuPDF-specific exceptions, `FileNotFoundError`, `EmptyFileError` and `FileDataError` are intercepted if you check for `RuntimeError`. - In case of problems you can see more detail in the internal messages store: `print(fitz.TOOLS.mupdf_warnings())` (which will be emptied by this call, but you can also prevent this -- consult :meth:`Tools.mupdf_warnings`). + In case of problems you can see more detail in the internal messages store: `print(fitz.TOOLS.mupdf_warnings())` (which will be emptied by this call, but you can also prevent this -- consult :meth:`Tools.mupdf_warnings`). - .. note:: Not all document types are checked for valid formats already at open time. Raster images for example will raise exceptions only later, when trying to access the content. Other types (notably with non-binary content) may also be opened (and sometimes **accessed**) successfully -- sometimes even when having invalid content for the format: + .. note:: Not all document types are checked for valid formats already at open time. Raster images for example will raise exceptions only later, when trying to access the content. Other types (notably with non-binary content) may also be opened (and sometimes **accessed**) successfully -- sometimes even when having invalid content for the format: - * HTM, HTML, XHTML: **always** opened, `metadata["format"]` is "HTML5", resp. "XHTML". - * XML, FB2: **always** opened, `metadata["format"]` is "FictionBook2". + * HTM, HTML, XHTML: **always** opened, `metadata["format"]` is "HTML5", resp. "XHTML". + * XML, FB2: **always** opened, `metadata["format"]` is "FictionBook2". - Overview of possible forms, note: `open` is a synonym of `Document`:: + Overview of possible forms, note: `open` is a synonym of `Document`:: - >>> # from a file - >>> doc = fitz.open("some.xps") - >>> # handle wrong extension - >>> doc = fitz.open("some.file", filetype="xps") - >>> - >>> # from memory, filetype is required if not a PDF - >>> doc = fitz.open("xps", mem_area) - >>> doc = fitz.open(None, mem_area, "xps") - >>> doc = fitz.open(stream=mem_area, filetype="xps") - >>> - >>> # new empty PDF - >>> doc = fitz.open() - >>> doc = fitz.open(None) - >>> doc = fitz.open("") + >>> # from a file + >>> doc = fitz.open("some.xps") + >>> # handle wrong extension + >>> doc = fitz.open("some.file", filetype="xps") + >>> + >>> # from memory, filetype is required if not a PDF + >>> doc = fitz.open("xps", mem_area) + >>> doc = fitz.open(None, mem_area, "xps") + >>> doc = fitz.open(stream=mem_area, filetype="xps") + >>> + >>> # new empty PDF + >>> doc = fitz.open() + >>> doc = fitz.open(None) + >>> doc = fitz.open("") - .. note:: Raster images with a wrong (but supported) file extension **are no problem**. MuPDF will determine the correct image type when file **content** is actually accessed and will process it without complaint. So `fitz.open("file.jpg")` will work even for a PNG image. - - The Document class can be also be used as a **context manager**. On exit, the document will automatically be closed. + .. note:: Raster images with a wrong (but supported) file extension **are no problem**. MuPDF will determine the correct image type when file **content** is actually accessed and will process it without complaint. So `fitz.open("file.jpg")` will work even for a PNG image. - >>> import fitz - >>> with fitz.open(...) as doc: - for page in doc: print("page %i" % page.number) - page 0 - page 1 - page 2 - page 3 - >>> doc.is_closed - True - >>> + The Document class can be also be used as a **context manager**. On exit, the document will automatically be closed. + >>> import fitz + >>> with fitz.open(...) as doc: + for page in doc: print("page %i" % page.number) + page 0 + page 1 + page 2 + page 3 + >>> doc.is_closed + True + >>> - .. method:: get_oc(xref) - * New in v1.18.4 + .. method:: get_oc(xref) - Return the cross reference number of an :data:`OCG` or :data:`OCMD` attached to an image or form xobject. + * New in v1.18.4 - :arg int xref: the :data:`xref` of an image or form xobject. Valid such cross reference numbers are returned by :meth:`Document.get_page_images`, resp. :meth:`Document.get_page_xobjects`. For invalid numbers, an exception is raised. - :rtype: int - :returns: the cross reference number of an optional contents object or zero if there is none. + Return the cross reference number of an :data:`OCG` or :data:`OCMD` attached to an image or form xobject. - .. method:: set_oc(xref, ocxref) + :arg int xref: the :data:`xref` of an image or form xobject. Valid such cross reference numbers are returned by :meth:`Document.get_page_images`, resp. :meth:`Document.get_page_xobjects`. For invalid numbers, an exception is raised. + :rtype: int + :returns: the cross reference number of an optional contents object or zero if there is none. - * New in v1.18.4 + .. method:: set_oc(xref, ocxref) - If *xref* represents an image or form xobject, set or remove the cross reference number *ocxref* of an optional contents object. + * New in v1.18.4 - :arg int xref: the :data:`xref` of an image or form xobject [#f5]_. Valid such cross reference numbers are returned by :meth:`Document.get_page_images`, resp. :meth:`Document.get_page_xobjects`. For invalid numbers, an exception is raised. - :arg int ocxref: the :data:`xref` number of an :data:`OCG` / :data:`OCMD`. If not zero, an invalid reference raises an exception. If zero, any OC reference is removed. + If *xref* represents an image or form xobject, set or remove the cross reference number *ocxref* of an optional contents object. + :arg int xref: the :data:`xref` of an image or form xobject [#f5]_. Valid such cross reference numbers are returned by :meth:`Document.get_page_images`, resp. :meth:`Document.get_page_xobjects`. For invalid numbers, an exception is raised. + :arg int ocxref: the :data:`xref` number of an :data:`OCG` / :data:`OCMD`. If not zero, an invalid reference raises an exception. If zero, any OC reference is removed. - .. method:: get_layers() - * New in v1.18.3 + .. method:: get_layers() - Show optional layer configurations. There always is a standard one, which is not included in the response. + * New in v1.18.3 - >>> for item in doc.get_layers(): print(item) - {'number': 0, 'name': 'my-config', 'creator': ''} - >>> # use 'number' as config identifier in add_ocg + Show optional layer configurations. There always is a standard one, which is not included in the response. - .. method:: add_layer(name, creator=None, on=None) + >>> for item in doc.get_layers(): print(item) + {'number': 0, 'name': 'my-config', 'creator': ''} + >>> # use 'number' as config identifier in add_ocg - * New in v1.18.3 + .. method:: add_layer(name, creator=None, on=None) - Add an optional content configuration. Layers serve as a collection of ON / OFF states for optional content groups and allow fast visibility switches between different views on the same document. + * New in v1.18.3 - :arg str name: arbitrary name. - :arg str creator: (optional) creating software. - :arg sequ on: a sequence of OCG :data:`xref` numbers which should be set to ON when this layer gets activated. All OCGs not listed here will be set to OFF. + Add an optional content configuration. Layers serve as a collection of ON / OFF states for optional content groups and allow fast visibility switches between different views on the same document. + :arg str name: arbitrary name. + :arg str creator: (optional) creating software. + :arg sequ on: a sequence of OCG :data:`xref` numbers which should be set to ON when this layer gets activated. All OCGs not listed here will be set to OFF. - .. method:: switch_layer(number, as_default=False) - * New in v1.18.3 + .. method:: switch_layer(number, as_default=False) - Switch to a document view as defined by the optional layer's configuration number. This is temporary, except if established as default. + * New in v1.18.3 - :arg int number: config number as returned by :meth:`Document.layer_configs`. - :arg bool as_default: make this the default configuration. + Switch to a document view as defined by the optional layer's configuration number. This is temporary, except if established as default. - Activates the ON / OFF states of OCGs as defined in the identified layer. If *as_default=True*, then additionally all layers, including the standard one, are merged and the result is written back to the standard layer, and **all optional layers are deleted**. + :arg int number: config number as returned by :meth:`Document.layer_configs`. + :arg bool as_default: make this the default configuration. + Activates the ON / OFF states of OCGs as defined in the identified layer. If *as_default=True*, then additionally all layers, including the standard one, are merged and the result is written back to the standard layer, and **all optional layers are deleted**. - .. method:: add_ocg(name, config=-1, on=True, intent="View", usage="Artwork") - * New in v1.18.3 + .. method:: add_ocg(name, config=-1, on=True, intent="View", usage="Artwork") - Add an optional content group. An OCG is the most important unit of information to determine object visibility. For a PDF, in order to be regarded as having optional content, at least one OCG must exist. + * New in v1.18.3 - :arg str name: arbitrary name. Will show up in supporting PDF viewers. - :arg int config: layer configuration number. Default -1 is the standard configuration. - :arg bool on: standard visibility status for objects pointing to this OCG. - :arg str,list intent: a string or list of strings declaring the visibility intents. There are two PDF standard values to choose from: "View" and "Design". Default is "View". Correct **spelling is important**. - :arg str usage: another influencer for OCG visibility. This will become part of the OCG's `/Usage` key. There are two PDF standard values to choose from: "Artwork" and "Technical". Default is "Artwork". Please only change when required. + Add an optional content group. An OCG is the most important unit of information to determine object visibility. For a PDF, in order to be regarded as having optional content, at least one OCG must exist. - :returns: :data:`xref` of the created OCG. Use as entry for `oc` parameter in supporting objects. + :arg str name: arbitrary name. Will show up in supporting PDF viewers. + :arg int config: layer configuration number. Default -1 is the standard configuration. + :arg bool on: standard visibility status for objects pointing to this OCG. + :arg str,list intent: a string or list of strings declaring the visibility intents. There are two PDF standard values to choose from: "View" and "Design". Default is "View". Correct **spelling is important**. + :arg str usage: another influencer for OCG visibility. This will become part of the OCG's `/Usage` key. There are two PDF standard values to choose from: "Artwork" and "Technical". Default is "Artwork". Please only change when required. - .. note:: Multiple OCGs with identical parameters may be created. This will not cause problems. Garbage option 3 of :meth:`Document.save` will get rid of any duplicates. + :returns: :data:`xref` of the created OCG. Use as entry for `oc` parameter in supporting objects. + .. note:: Multiple OCGs with identical parameters may be created. This will not cause problems. Garbage option 3 of :meth:`Document.save` will get rid of any duplicates. - .. method:: set_ocmd(xref=0, ocgs=None, policy="AnyOn", ve=None) - * New in v1.18.4 + .. method:: set_ocmd(xref=0, ocgs=None, policy="AnyOn", ve=None) - Create or update an :data:`OCMD`, **Optional Content Membership Dictionary.** + * New in v1.18.4 - :arg int xref: :data:`xref` of the OCMD to be updated, or 0 for a new OCMD. - :arg list ocgs: a sequence of :data:`xref` numbers of existing :data:`OCG` PDF objects. - :arg str policy: one of "AnyOn" (default), "AnyOff", "AllOn", "AllOff" (mixed or lower case). - :arg list ve: a "visibility expression". This is a list of arbitrarily nested other lists -- see explanation below. Use as an alternative to the combination *ocgs* / *policy* if you need to formulate more complex conditions. - :rtype: int - :returns: :data:`xref` of the OCMD. Use as `oc=xref` parameter in supporting objects, and respectively in :meth:`Document.set_oc` or :meth:`Annot.set_oc`. + Create or update an :data:`OCMD`, **Optional Content Membership Dictionary.** - .. note:: + :arg int xref: :data:`xref` of the OCMD to be updated, or 0 for a new OCMD. + :arg list ocgs: a sequence of :data:`xref` numbers of existing :data:`OCG` PDF objects. + :arg str policy: one of "AnyOn" (default), "AnyOff", "AllOn", "AllOff" (mixed or lower case). + :arg list ve: a "visibility expression". This is a list of arbitrarily nested other lists -- see explanation below. Use as an alternative to the combination *ocgs* / *policy* if you need to formulate more complex conditions. + :rtype: int + :returns: :data:`xref` of the OCMD. Use as `oc=xref` parameter in supporting objects, and respectively in :meth:`Document.set_oc` or :meth:`Annot.set_oc`. + + .. note:: + + Like an OCG, an OCMD has a visibility state ON or OFF, and it can be used like an OCG. In contrast to an OCG, the OCMD state is determined by evaluating the state of one or more OCGs via special forms of **boolean expressions.** If the expression evaluates to true, the OCMD state is ON and OFF for false. + + There are two ways to formulate OCMD visibility: + + 1. Use the combination of *ocgs* and *policy*: The *policy* value is interpreted as follows: + + - AnyOn -- (default) true if at least one OCG is ON. + - AnyOff -- true if at least one OCG is OFF. + - AllOn -- true if all OCGs are ON. + - AllOff -- true if all OCGs are OFF. + + Suppose you want two PDF objects be displayed exactly one at a time (if one is ON, then the other one must be OFF): + + Solution: use an **OCG** for object 1 and an **OCMD** for object 2. Create the OCMD via `set_ocmd(ocgs=[xref], policy="AllOff")`, with the :data:`xref` of the OCG. - Like an OCG, an OCMD has a visibility state ON or OFF, and it can be used like an OCG. In contrast to an OCG, the OCMD state is determined by evaluating the state of one or more OCGs via special forms of **boolean expressions.** If the expression evaluates to true, the OCMD state is ON and OFF for false. + 2. Use the **visibility expression** *ve*: This is a list of two or more items. The **first item** is a logical keyword: one of the strings **"and"**, **"or"**, or **"not"**. The **second** and all subsequent items must either be an integer or another list. An integer must be the :data:`xref` number of an OCG. A list must again have at least two items starting with one of the boolean keywords. This syntax is a bit awkward, but quite powerful: - There are two ways to formulate OCMD visibility: + - Each list must start with a logical keyword. + - If the keyword is a **"not"**, then the list must have exactly two items. If it is **"and"** or **"or"**, any number of other items may follow. + - Items following the logical keyword may be either integers or again a list. An *integer* must be the xref of an OCG. A *list* must conform to the previous rules. - 1. Use the combination of *ocgs* and *policy*: The *policy* value is interpreted as follows: + **Examples:** - - AnyOn -- (default) true if at least one OCG is ON. - - AnyOff -- true if at least one OCG is OFF. - - AllOn -- true if all OCGs are ON. - - AllOff -- true if all OCGs are OFF. + - `set_ocmd(ve=["or", 4, ["not", 5], ["and", 6, 7]])`. This delivers ON if the following is true: **"4 is ON, or 5 is OFF, or 6 and 7 are both ON"**. + - `set_ocmd(ve=["not", xref])`. This has the same effect as the OCMD example created under 1. - Suppose you want two PDF objects be displayed exactly one at a time (if one is ON, then the other one must be OFF): + For more details and examples see page 224 of :ref:`AdobeManual`. Also do have a look at example scripts `here `_. - Solution: use an **OCG** for object 1 and an **OCMD** for object 2. Create the OCMD via `set_ocmd(ocgs=[xref], policy="AllOff")`, with the :data:`xref` of the OCG. + Visibility expressions, `/VE`, are part of PDF specification version 1.6. So not all PDF viewers / readers may already support this feature and hence will react in some standard way for those cases. - 2. Use the **visibility expression** *ve*: This is a list of two or more items. The **first item** is a logical keyword: one of the strings **"and"**, **"or"**, or **"not"**. The **second** and all subsequent items must either be an integer or another list. An integer must be the :data:`xref` number of an OCG. A list must again have at least two items starting with one of the boolean keywords. This syntax is a bit awkward, but quite powerful: - - Each list must start with a logical keyword. - - If the keyword is a **"not"**, then the list must have exactly two items. If it is **"and"** or **"or"**, any number of other items may follow. - - Items following the logical keyword may be either integers or again a list. An *integer* must be the xref of an OCG. A *list* must conform to the previous rules. + .. method:: get_ocmd(xref) - **Examples:** + * New in v1.18.4 - - `set_ocmd(ve=["or", 4, ["not", 5], ["and", 6, 7]])`. This delivers ON if the following is true: **"4 is ON, or 5 is OFF, or 6 and 7 are both ON"**. - - `set_ocmd(ve=["not", xref])`. This has the same effect as the OCMD example created under 1. + Retrieve the definition of an :data:`OCMD`. - For more details and examples see page 224 of :ref:`AdobeManual`. Also do have a look at example scripts `here `_. + :arg int xref: the :data:`xref` of the OCMD. + :rtype: dict + :returns: a dictionary with the keys *xref*, *ocgs*, *policy* and *ve*. - Visibility expressions, `/VE`, are part of PDF specification version 1.6. So not all PDF viewers / readers may already support this feature and hence will react in some standard way for those cases. + .. method:: get_layer(config=-1) - .. method:: get_ocmd(xref) + * New in v1.18.3 - * New in v1.18.4 + List of optional content groups by status in the specified configuration. This is a dictionary with lists of cross reference numbers for OCGs that occur in the arrays `/ON`, `/OFF` or in some radio button group (`/RBGroups`). - Retrieve the definition of an :data:`OCMD`. + :arg int config: the configuration layer (default is the standard config layer). - :arg int xref: the :data:`xref` of the OCMD. - :rtype: dict - :returns: a dictionary with the keys *xref*, *ocgs*, *policy* and *ve*. + >>> pprint(doc.get_layer()) + {'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]} + >>> + .. method:: set_layer(config, *, on=None, off=None, basestate=None, rbgroups=None, locked=None) - .. method:: get_layer(config=-1) + * New in v1.18.3 - * New in v1.18.3 + * Changed in v1.22.5: Support list of *locked* OCGs. - List of optional content groups by status in the specified configuration. This is a dictionary with lists of cross reference numbers for OCGs that occur in the arrays `/ON`, `/OFF` or in some radio button group (`/RBGroups`). + Mass status changes of optional content groups. **Permanently** sets the status of OCGs. - :arg int config: the configuration layer (default is the standard config layer). + :arg int config: desired configuration layer, choose -1 for the default one. + :arg list on: list of :data:`xref` of OCGs to set ON. Replaces previous values. An empty list will cause no OCG being set to ON anymore. Should be specified if `basestate="ON"` is used. + :arg list off: list of :data:`xref` of OCGs to set OFF. Replaces previous values. An empty list will cause no OCG being set to OFF anymore. Should be specified if `basestate="OFF"` is used. + :arg str basestate: state of OCGs that are not mentioned in *on* or *off*. Possible values are "ON", "OFF" or "Unchanged". Upper / lower case possible. + :arg list rbgroups: a list of lists. Replaces previous values. Each sublist should contain two or more OCG xrefs. OCGs in the same sublist are handled like buttons in a radio button group: setting one to ON automatically sets all other group members to OFF. + :arg list locked: a list of OCG xref number that cannot be changed by the user interface. + Values `None` will not change the corresponding PDF array. + + >>> doc.set_layer(-1, basestate="OFF") # only changes the base state >>> pprint(doc.get_layer()) - {'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]} - >>> + {'basestate': 'OFF', 'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]} - .. method:: set_layer(config, *, on=None, off=None, basestate=None, rbgroups=None, locked=None) - * New in v1.18.3 + .. method:: get_ocgs() - * Changed in v1.22.5: Support list of *locked* OCGs. + * New in v1.18.3 - Mass status changes of optional content groups. **Permanently** sets the status of OCGs. + Details of all optional content groups. This is a dictionary of dictionaries like this (key is the OCG's :data:`xref`): - :arg int config: desired configuration layer, choose -1 for the default one. - :arg list on: list of :data:`xref` of OCGs to set ON. Replaces previous values. An empty list will cause no OCG being set to ON anymore. Should be specified if `basestate="ON"` is used. - :arg list off: list of :data:`xref` of OCGs to set OFF. Replaces previous values. An empty list will cause no OCG being set to OFF anymore. Should be specified if `basestate="OFF"` is used. - :arg str basestate: state of OCGs that are not mentioned in *on* or *off*. Possible values are "ON", "OFF" or "Unchanged". Upper / lower case possible. - :arg list rbgroups: a list of lists. Replaces previous values. Each sublist should contain two or more OCG xrefs. OCGs in the same sublist are handled like buttons in a radio button group: setting one to ON automatically sets all other group members to OFF. - :arg list locked: a list of OCG xref number that cannot be changed by the user interface. + >>> pprint(doc.get_ocgs()) + {13: {'on': True, + 'intent': ['View', 'Design'], + 'name': 'Circle', + 'usage': 'Artwork'}, + 14: {'on': True, + 'intent': ['View', 'Design'], + 'name': 'Square', + 'usage': 'Artwork'}, + 15: {'on': False, 'intent': ['View'], 'name': 'Square', 'usage': 'Artwork'}} + >>> - Values `None` will not change the corresponding PDF array. + .. method:: layer_ui_configs() - >>> doc.set_layer(-1, basestate="OFF") # only changes the base state - >>> pprint(doc.get_layer()) - {'basestate': 'OFF', 'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]} + * New in v1.18.3 + Show the visibility status of optional content that is modifiable by the user interface of supporting PDF viewers. - .. method:: get_ocgs() + * Only reports items contained in the currently selected layer configuration. - * New in v1.18.3 + * The meaning of the dictionary keys is as follows: + - *depth:* item's nesting level in the `/Order` array + - *locked:* true if cannot be changed via user interfaces + - *number:* running sequence number + - *on:* item state + - *text:* text string or name field of the originating OCG + - *type:* one of "label" (set by a text string), "checkbox" (set by a single OCG) or "radiobox" (set by a set of connected OCGs) - Details of all optional content groups. This is a dictionary of dictionaries like this (key is the OCG's :data:`xref`): + .. method:: set_layer_ui_config(number, action=0) - >>> pprint(doc.get_ocgs()) - {13: {'on': True, - 'intent': ['View', 'Design'], - 'name': 'Circle', - 'usage': 'Artwork'}, - 14: {'on': True, - 'intent': ['View', 'Design'], - 'name': 'Square', - 'usage': 'Artwork'}, - 15: {'on': False, 'intent': ['View'], 'name': 'Square', 'usage': 'Artwork'}} - >>> + * New in v1.18.3 - .. method:: layer_ui_configs() + Modify OC visibility status of content groups. This is analog to what supporting PDF viewers would offer. - * New in v1.18.3 + Please note that visibility is **not** a property stored with the OCG. It is not even information necessarily present in the PDF document at all. Instead, the current visibility is **temporarily** set using the user interface of some supporting PDF consumer software. The same type of functionality is offered by this method. - Show the visibility status of optional content that is modifiable by the user interface of supporting PDF viewers. + To make **permanent** changes, use :meth:`Document.set_layer`. - * Only reports items contained in the currently selected layer configuration. + :arg int,str number: either the sequence number of the item in list :meth:`Document.layer_configs` or the "text" of one of these items. + :arg int action: `PDF_OC_ON` = set on (default), `PDF_OC_TOGGLE` = toggle on/off, `PDF_OC_OFF` = set off. - * The meaning of the dictionary keys is as follows: - - *depth:* item's nesting level in the `/Order` array - - *locked:* true if cannot be changed via user interfaces - - *number:* running sequence number - - *on:* item state - - *text:* text string or name field of the originating OCG - - *type:* one of "label" (set by a text string), "checkbox" (set by a single OCG) or "radiobox" (set by a set of connected OCGs) - .. method:: set_layer_ui_config(number, action=0) + .. method:: authenticate(password) - * New in v1.18.3 + Decrypts the document with the string *password*. If successful, document data can be accessed. For PDF documents, the "owner" and the "user" have different privileges, and hence different passwords may exist for these authorization levels. The method will automatically establish the appropriate (owner or user) access rights for the provided password. - Modify OC visibility status of content groups. This is analog to what supporting PDF viewers would offer. + :arg str password: owner or user password. - Please note that visibility is **not** a property stored with the OCG. It is not even information necessarily present in the PDF document at all. Instead, the current visibility is **temporarily** set using the user interface of some supporting PDF consumer software. The same type of functionality is offered by this method. + :rtype: int + :returns: a positive value if successful, zero otherwise (the string does not match either password). If positive, the indicator :attr:`Document.is_encrypted` is set to *False*. **Positive** return codes carry the following information detail: - To make **permanent** changes, use :meth:`Document.set_layer`. + * 1 => authenticated, but the PDF has neither owner nor user passwords. + * 2 => authenticated with the **user** password. + * 4 => authenticated with the **owner** password. + * 6 => authenticated and both passwords are equal -- probably a rare situation. - :arg int,str number: either the sequence number of the item in list :meth:`Document.layer_configs` or the "text" of one of these items. - :arg int action: `PDF_OC_ON` = set on (default), `PDF_OC_TOGGLE` = toggle on/off, `PDF_OC_OFF` = set off. + .. note:: + The document may be protected by an owner, but **not** by a user password. Detect this situation via `doc.authenticate("") == 2`. This allows opening and reading the document without authentication, but, depending on the :attr:`Document.permissions` value, other actions may be prohibited. PyMuPDF (like MuPDF) in this case **ignores those restrictions**. So, -- in contrast to any PDF viewers -- you can for example extract text and add or modify content, even if the respective permission flags `PDF_PERM_COPY`, `PDF_PERM_MODIFY`, `PDF_PERM_ANNOTATE`, etc. are set off! It is your responsibility building a legally compliant application where applicable. - .. method:: authenticate(password) + .. method:: get_page_numbers(label, only_one=False) - Decrypts the document with the string *password*. If successful, document data can be accessed. For PDF documents, the "owner" and the "user" have different privileges, and hence different passwords may exist for these authorization levels. The method will automatically establish the appropriate (owner or user) access rights for the provided password. + * New in v 1.18.6 - :arg str password: owner or user password. + PDF only: Return a list of page numbers that have the specified label -- note that labels may not be unique in a PDF. This implies a sequential search through **all page numbers** to compare their labels. - :rtype: int - :returns: a positive value if successful, zero otherwise (the string does not match either password). If positive, the indicator :attr:`Document.is_encrypted` is set to *False*. **Positive** return codes carry the following information detail: + .. note:: Implementation detail -- pages are **not loaded** for this purpose. - * 1 => authenticated, but the PDF has neither owner nor user passwords. - * 2 => authenticated with the **user** password. - * 4 => authenticated with the **owner** password. - * 6 => authenticated and both passwords are equal -- probably a rare situation. + :arg str label: the label to look for, e.g. "vii" (Roman number 7). + :arg bool only_one: stop after first hit. Useful e.g. if labelling is known to be unique, or there are many pages, etc. The default will check every page number. + :rtype: list + :returns: list of page numbers that have this label. Empty if none found, no labels defined, etc. - .. note:: - The document may be protected by an owner, but **not** by a user password. Detect this situation via `doc.authenticate("") == 2`. This allows opening and reading the document without authentication, but, depending on the :attr:`Document.permissions` value, other actions may be prohibited. PyMuPDF (like MuPDF) in this case **ignores those restrictions**. So, -- in contrast to any PDF viewers -- you can for example extract text and add or modify content, even if the respective permission flags `PDF_PERM_COPY`, `PDF_PERM_MODIFY`, `PDF_PERM_ANNOTATE`, etc. are set off! It is your responsibility building a legally compliant application where applicable. + .. method:: get_page_labels() - .. method:: get_page_numbers(label, only_one=False) + * New in v1.18.7 - * New in v 1.18.6 + PDF only: Extract the list of page label definitions. Typically used for modifications before feeding it into :meth:`Document.set_page_labels`. - PDF only: Return a list of page numbers that have the specified label -- note that labels may not be unique in a PDF. This implies a sequential search through **all page numbers** to compare their labels. + :returns: a list of dictionaries as defined in :meth:`Document.set_page_labels`. - .. note:: Implementation detail -- pages are **not loaded** for this purpose. + .. method:: set_page_labels(labels) - :arg str label: the label to look for, e.g. "vii" (Roman number 7). - :arg bool only_one: stop after first hit. Useful e.g. if labelling is known to be unique, or there are many pages, etc. The default will check every page number. - :rtype: list - :returns: list of page numbers that have this label. Empty if none found, no labels defined, etc. + * New in v1.18.6 + PDF only: Add or update the page label definitions of the PDF. - .. method:: get_page_labels() + :arg list labels: a list of dictionaries. Each dictionary defines a label building rule and a 0-based "start" page number. That start page is the first for which the label definition is valid. Each dictionary has up to 4 items and looks like `{'startpage': int, 'prefix': str, 'style': str, 'firstpagenum': int}` and has the following items. - * New in v1.18.7 + - `startpage`: (int) the first page number (0-based) to apply the label rule. This key **must be present**. The rule is applied to all subsequent pages until either end of document or superseded by the rule with the next larger page number. + - `prefix`: (str) an arbitrary string to start the label with, e.g. "A-". Default is "". + - `style`: (str) the numbering style. Available are "D" (decimal), "r"/"R" (Roman numbers, lower / upper case), and "a"/"A" (lower / upper case alphabetical numbering: "a" through "z", then "aa" through "zz", etc.). Default is "". If "", no numbering will take place and the pages in that range will receive the same label consisting of the `prefix` value. If prefix is also omitted, then the label will be "". + - `firstpagenum`: (int) start numbering with this value. Default is 1, smaller values are ignored. - PDF only: Extract the list of page label definitions. Typically used for modifications before feeding it into :meth:`Document.set_page_labels`. + For example:: - :returns: a list of dictionaries as defined in :meth:`Document.set_page_labels`. + [{'startpage': 6, 'prefix': 'A-', 'style': 'D', 'firstpagenum': 10}, + {'startpage': 10, 'prefix': '', 'style': 'D', 'firstpagenum': 1}] - .. method:: set_page_labels(labels) + will generate the labels "A-10", "A-11", "A-12", "A-13", "1", "2", "3", ... for pages 6, 7 and so on until end of document. Pages 0 through 5 will have the label "". - * New in v1.18.6 - PDF only: Add or update the page label definitions of the PDF. + .. method:: make_bookmark(loc) - :arg list labels: a list of dictionaries. Each dictionary defines a label building rule and a 0-based "start" page number. That start page is the first for which the label definition is valid. Each dictionary has up to 4 items and looks like `{'startpage': int, 'prefix': str, 'style': str, 'firstpagenum': int}` and has the following items. + * New in v.1.17.3 - - `startpage`: (int) the first page number (0-based) to apply the label rule. This key **must be present**. The rule is applied to all subsequent pages until either end of document or superseded by the rule with the next larger page number. - - `prefix`: (str) an arbitrary string to start the label with, e.g. "A-". Default is "". - - `style`: (str) the numbering style. Available are "D" (decimal), "r"/"R" (Roman numbers, lower / upper case), and "a"/"A" (lower / upper case alphabetical numbering: "a" through "z", then "aa" through "zz", etc.). Default is "". If "", no numbering will take place and the pages in that range will receive the same label consisting of the `prefix` value. If prefix is also omitted, then the label will be "". - - `firstpagenum`: (int) start numbering with this value. Default is 1, smaller values are ignored. + Return a page pointer in a reflowable document. After re-layouting the document, the result of this method can be used to find the new location of the page. - For example:: + .. note:: Do not confuse with items of a table of contents, TOC. - [{'startpage': 6, 'prefix': 'A-', 'style': 'D', 'firstpagenum': 10}, - {'startpage': 10, 'prefix': '', 'style': 'D', 'firstpagenum': 1}] + :arg list,tuple loc: page location. Must be a valid *(chapter, pno)*. - will generate the labels "A-10", "A-11", "A-12", "A-13", "1", "2", "3", ... for pages 6, 7 and so on until end of document. Pages 0 through 5 will have the label "". + :rtype: pointer + :returns: a long integer in pointer format. To be used for finding the new location of the page after re-layouting the document. Do not touch or re-assign. - .. method:: make_bookmark(loc) + .. method:: find_bookmark(bookmark) - * New in v.1.17.3 - - Return a page pointer in a reflowable document. After re-layouting the document, the result of this method can be used to find the new location of the page. + * New in v.1.17.3 - .. note:: Do not confuse with items of a table of contents, TOC. + Return the new page location after re-layouting the document. - :arg list,tuple loc: page location. Must be a valid *(chapter, pno)*. + :arg pointer bookmark: created by :meth:`Document.make_bookmark`. - :rtype: pointer - :returns: a long integer in pointer format. To be used for finding the new location of the page after re-layouting the document. Do not touch or re-assign. + :rtype: tuple + :returns: the new (chapter, pno) of the page. - .. method:: find_bookmark(bookmark) + .. method:: chapter_page_count(chapter) - * New in v.1.17.3 - - Return the new page location after re-layouting the document. + * New in v.1.17.0 - :arg pointer bookmark: created by :meth:`Document.make_bookmark`. + Return the number of pages of a chapter. - :rtype: tuple - :returns: the new (chapter, pno) of the page. + :arg int chapter: the 0-based chapter number. + :rtype: int + :returns: number of pages in chapter. Relevant only for document types with chapter support (EPUB currently). - .. method:: chapter_page_count(chapter) - * New in v.1.17.0 - - Return the number of pages of a chapter. + .. method:: next_location(page_id) - :arg int chapter: the 0-based chapter number. + * New in v.1.17.0 - :rtype: int - :returns: number of pages in chapter. Relevant only for document types with chapter support (EPUB currently). + Return the location of the following page. + :arg tuple page_id: the current page id. This must be a tuple *(chapter, pno)* identifying an existing page. - .. method:: next_location(page_id) + :returns: The tuple of the following page, i.e. either *(chapter, pno + 1)* or *(chapter + 1, 0)*, **or** the empty tuple *()* if the argument was the last page. Relevant only for document types with chapter support (EPUB currently). - * New in v.1.17.0 - Return the location of the following page. + .. method:: prev_location(page_id) - :arg tuple page_id: the current page id. This must be a tuple *(chapter, pno)* identifying an existing page. + * New in v.1.17.0 - :returns: The tuple of the following page, i.e. either *(chapter, pno + 1)* or *(chapter + 1, 0)*, **or** the empty tuple *()* if the argument was the last page. Relevant only for document types with chapter support (EPUB currently). + Return the locator of the preceding page. + :arg tuple page_id: the current page id. This must be a tuple *(chapter, pno)* identifying an existing page. - .. method:: prev_location(page_id) + :returns: The tuple of the preceding page, i.e. either *(chapter, pno - 1)* or the last page of the preceding chapter, **or** the empty tuple *()* if the argument was the first page. Relevant only for document types with chapter support (EPUB currently). - * New in v.1.17.0 - - Return the locator of the preceding page. - :arg tuple page_id: the current page id. This must be a tuple *(chapter, pno)* identifying an existing page. + .. method:: load_page(page_id=0) - :returns: The tuple of the preceding page, i.e. either *(chapter, pno - 1)* or the last page of the preceding chapter, **or** the empty tuple *()* if the argument was the first page. Relevant only for document types with chapter support (EPUB currently). + * Changed in v1.17.0: For document types supporting a so-called "chapter structure" (like EPUB), pages can also be loaded via the combination of chapter number and relative page number, instead of the absolute page number. This should **significantly speed up access** for large documents. + Create a :ref:`Page` object for further processing (like rendering, text searching, etc.). - .. method:: load_page(page_id=0) + :arg int,tuple page_id: *(Changed in v1.17.0)* - * Changed in v1.17.0: For document types supporting a so-called "chapter structure" (like EPUB), pages can also be loaded via the combination of chapter number and relative page number, instead of the absolute page number. This should **significantly speed up access** for large documents. + Either a 0-based page number, or a tuple *(chapter, pno)*. For an **integer**, any `-∞ < page_id < page_count` is acceptable. While page_id is negative, :attr:`page_count` will be added to it. For example: to load the last page, you can use *doc.load_page(-1)*. After this you have page.number = doc.page_count - 1. - Create a :ref:`Page` object for further processing (like rendering, text searching, etc.). + For a tuple, *chapter* must be in range :attr:`Document.chapter_count`, and *pno* must be in range :meth:`Document.chapter_page_count` of that chapter. Both values are 0-based. Using this notation, :attr:`Page.number` will equal the given tuple. Relevant only for document types with chapter support (EPUB currently). - :arg int,tuple page_id: *(Changed in v1.17.0)* + :rtype: :ref:`Page` - Either a 0-based page number, or a tuple *(chapter, pno)*. For an **integer**, any `-∞ < page_id < page_count` is acceptable. While page_id is negative, :attr:`page_count` will be added to it. For example: to load the last page, you can use *doc.load_page(-1)*. After this you have page.number = doc.page_count - 1. + .. note:: - For a tuple, *chapter* must be in range :attr:`Document.chapter_count`, and *pno* must be in range :meth:`Document.chapter_page_count` of that chapter. Both values are 0-based. Using this notation, :attr:`Page.number` will equal the given tuple. Relevant only for document types with chapter support (EPUB currently). + Documents also follow the Python sequence protocol with page numbers as indices: *doc.load_page(n) == doc[n]*. - :rtype: :ref:`Page` + For **absolute page numbers** only, expressions like *"for page in doc: ..."* and *"for page in reversed(doc): ..."* will successively yield the document's pages. Refer to :meth:`Document.pages` which allows processing pages as with slicing. - .. note:: + You can also use index notation with the new chapter-based page identification: use *page = doc[(5, 2)]* to load the third page of the sixth chapter. - Documents also follow the Python sequence protocol with page numbers as indices: *doc.load_page(n) == doc[n]*. + To maintain a consistent API, for document types not supporting a chapter structure (like PDFs), :attr:`Document.chapter_count` is 1, and pages can also be loaded via tuples *(0, pno)*. See this [#f3]_ footnote for comments on performance improvements. - For **absolute page numbers** only, expressions like *"for page in doc: ..."* and *"for page in reversed(doc): ..."* will successively yield the document's pages. Refer to :meth:`Document.pages` which allows processing pages as with slicing. + .. method:: reload_page(page) - You can also use index notation with the new chapter-based page identification: use *page = doc[(5, 2)]* to load the third page of the sixth chapter. + * New in v1.16.10 - To maintain a consistent API, for document types not supporting a chapter structure (like PDFs), :attr:`Document.chapter_count` is 1, and pages can also be loaded via tuples *(0, pno)*. See this [#f3]_ footnote for comments on performance improvements. + PDF only: Provide a new copy of a page after finishing and updating all pending changes. - .. method:: reload_page(page) + :arg page: page object. + :type page: :ref:`Page` - * New in v1.16.10 + :rtype: :ref:`Page` - PDF only: Provide a new copy of a page after finishing and updating all pending changes. + :returns: a new copy of the same page. All pending updates (e.g. to annotations or widgets) will be finalized and a fresh copy of the page will be loaded. - :arg page: page object. - :type page: :ref:`Page` + .. note:: In a typical use case, a page :ref:`Pixmap` should be taken after annotations / widgets have been added or changed. To force all those changes being reflected in the page structure, this method re-instates a fresh copy while keeping the object hierarchy "document -> page -> annotations/widgets" intact. - :rtype: :ref:`Page` - :returns: a new copy of the same page. All pending updates (e.g. to annotations or widgets) will be finalized and a fresh copy of the page will be loaded. + .. method:: resolve_names() - .. note:: In a typical use case, a page :ref:`Pixmap` should be taken after annotations / widgets have been added or changed. To force all those changes being reflected in the page structure, this method re-instates a fresh copy while keeping the object hierarchy "document -> page -> annotations/widgets" intact. + PDF only: Convert destination names into a Python dict. + Only available in PyMuPDF's "rebased" implementation. - .. method:: resolve_names() + :returns: + A dictionary with the following layout: - PDF only: Convert destination names into a Python dict. - - Only available in PyMuPDF's "rebased" implementation. + * *key*: (str) the name. + * *value*: (dict) with the following layout: + * "page": target page number (0-based). If no page number found -1. + * "to": (x, y) target point on page. Currently in PDF coordinates, + i.e. point (0,0) is the bottom-left of the page. + * "zoom": (float) the zoom factor. + * "dest": (str) only present if the target location on the page has + not been provided as "/XYZ" or if no page number was found. + Examples:: - :returns: - A dictionary with the following layout: - - * *key*: (str) the name. - * *value*: (dict) with the following layout: - * "page": target page number (0-based). If no page number found -1. - * "to": (x, y) target point on page. Currently in PDF coordinates, - i.e. point (0,0) is the bottom-left of the page. - * "zoom": (float) the zoom factor. - * "dest": (str) only present if the target location on the page has - not been provided as "/XYZ" or if no page number was found. - Examples:: - - { - '__bookmark_1': {'page': 0, 'to': (0.0, 541.0), 'zoom': 0.0}, - '__bookmark_2': {'page': 0, 'to': (0.0, 481.45), 'zoom': 0.0}, - } + { + '__bookmark_1': {'page': 0, 'to': (0.0, 541.0), 'zoom': 0.0}, + '__bookmark_2': {'page': 0, 'to': (0.0, 481.45), 'zoom': 0.0}, + } - or:: + or:: - { - '21154a7c20684ceb91f9c9adc3b677c40': {'page': -1, 'dest': '/XYZ 15.75 1486 0'}, - ... - } + { + '21154a7c20684ceb91f9c9adc3b677c40': {'page': -1, 'dest': '/XYZ 15.75 1486 0'}, + ... + } - All names found in the catalog under keys "/Dests" and "/Names/Dests" are - included. + All names found in the catalog under keys "/Dests" and "/Names/Dests" are + included. - * New in v1.23.6 + * New in v1.23.6 - .. method:: page_cropbox(pno) + .. method:: page_cropbox(pno) - * New in v1.17.7 + * New in v1.17.7 - PDF only: Return the unrotated page rectangle -- **without loading the page** (via :meth:`Document.load_page`). This is meant for internal purpose requiring best possible performance. + PDF only: Return the unrotated page rectangle -- **without loading the page** (via :meth:`Document.load_page`). This is meant for internal purpose requiring best possible performance. - :arg int pno: 0-based page number. + :arg int pno: 0-based page number. - :returns: :ref:`Rect` of the page like :meth:`Page.rect`, but ignoring any rotation. + :returns: :ref:`Rect` of the page like :meth:`Page.rect`, but ignoring any rotation. - .. method:: page_xref(pno) + .. method:: page_xref(pno) - * New in v1.17.7 + * New in v1.17.7 - PDF only: Return the :data:`xref` of the page -- **without loading the page** (via :meth:`Document.load_page`). This is meant for internal purpose requiring best possible performance. + PDF only: Return the :data:`xref` of the page -- **without loading the page** (via :meth:`Document.load_page`). This is meant for internal purpose requiring best possible performance. - :arg int pno: 0-based page number. + :arg int pno: 0-based page number. - :returns: :data:`xref` of the page like :attr:`Page.xref`. + :returns: :data:`xref` of the page like :attr:`Page.xref`. - .. method:: pages(start=None, [stop=None, [step=None]]) + .. method:: pages(start=None, [stop=None, [step=None]]) - * New in v1.16.4 + * New in v1.16.4 - A generator for a range of pages. Parameters have the same meaning as in the built-in function *range()*. Intended for expressions of the form *"for page in doc.pages(start, stop, step): ..."*. + A generator for a range of pages. Parameters have the same meaning as in the built-in function *range()*. Intended for expressions of the form *"for page in doc.pages(start, stop, step): ..."*. - :arg int start: start iteration with this page number. Default is zero, allowed values are `-∞ < start < page_count`. While this is negative, :attr:`page_count` is added **before** starting the iteration. - :arg int stop: stop iteration at this page number. Default is :attr:`page_count`, possible are `-∞ < stop <= page_count`. Larger values are **silently replaced** by the default. Negative values will cyclically emit the pages in reversed order. As with the built-in *range()*, this is the first page **not** returned. - :arg int step: stepping value. Defaults are 1 if start < stop and -1 if start > stop. Zero is not allowed. + :arg int start: start iteration with this page number. Default is zero, allowed values are `-∞ < start < page_count`. While this is negative, :attr:`page_count` is added **before** starting the iteration. + :arg int stop: stop iteration at this page number. Default is :attr:`page_count`, possible are `-∞ < stop <= page_count`. Larger values are **silently replaced** by the default. Negative values will cyclically emit the pages in reversed order. As with the built-in *range()*, this is the first page **not** returned. + :arg int step: stepping value. Defaults are 1 if start < stop and -1 if start > stop. Zero is not allowed. - :returns: a generator iterator over the document's pages. Some examples: + :returns: a generator iterator over the document's pages. Some examples: - * "doc.pages()" emits all pages. - * "doc.pages(4, 9, 2)" emits pages 4, 6, 8. - * "doc.pages(0, None, 2)" emits all pages with even numbers. - * "doc.pages(-2)" emits the last two pages. - * "doc.pages(-1, -1)" emits all pages in reversed order. - * "doc.pages(-1, -10)" always emits 10 pages in reversed order, starting with the last page -- **repeatedly** if the document has less than 10 pages. So for a 4-page document the following page numbers are emitted: 3, 2, 1, 0, 3, 2, 1, 0, 3, 2, 1, 0, 3. + * "doc.pages()" emits all pages. + * "doc.pages(4, 9, 2)" emits pages 4, 6, 8. + * "doc.pages(0, None, 2)" emits all pages with even numbers. + * "doc.pages(-2)" emits the last two pages. + * "doc.pages(-1, -1)" emits all pages in reversed order. + * "doc.pages(-1, -10)" always emits 10 pages in reversed order, starting with the last page -- **repeatedly** if the document has less than 10 pages. So for a 4-page document the following page numbers are emitted: 3, 2, 1, 0, 3, 2, 1, 0, 3, 2, 1, 0, 3. - .. index:: - pair: from_page; Document.convert_to_pdf - pair: to_page; Document.convert_to_pdf - pair: rotate; Document.convert_to_pdf + .. index:: + pair: from_page; Document.convert_to_pdf + pair: to_page; Document.convert_to_pdf + pair: rotate; Document.convert_to_pdf - .. method:: convert_to_pdf(from_page=-1, to_page=-1, rotate=0) + .. method:: convert_to_pdf(from_page=-1, to_page=-1, rotate=0) - Create a PDF version of the current document and write it to memory. **All document types** are supported. The parameters have the same meaning as in :meth:`insert_pdf`. In essence, you can restrict the conversion to a page subset, specify page rotation, and revert page sequence. + Create a PDF version of the current document and write it to memory. **All document types** are supported. The parameters have the same meaning as in :meth:`insert_pdf`. In essence, you can restrict the conversion to a page subset, specify page rotation, and revert page sequence. - :arg int from_page: first page to copy (0-based). Default is first page. + :arg int from_page: first page to copy (0-based). Default is first page. - :arg int to_page: last page to copy (0-based). Default is last page. + :arg int to_page: last page to copy (0-based). Default is last page. - :arg int rotate: rotation angle. Default is 0 (no rotation). Should be *n * 90* with an integer n (not checked). + :arg int rotate: rotation angle. Default is 0 (no rotation). Should be *n * 90* with an integer n (not checked). - :rtype: bytes - :returns: a Python *bytes* object containing a PDF file image. It is created by internally using `tobytes(garbage=4, deflate=True)`. See :meth:`tobytes`. You can output it directly to disk or open it as a PDF. Here are some examples:: + :rtype: bytes + :returns: a Python *bytes* object containing a PDF file image. It is created by internally using `tobytes(garbage=4, deflate=True)`. See :meth:`tobytes`. You can output it directly to disk or open it as a PDF. Here are some examples:: - >>> # convert an XPS file to PDF - >>> xps = fitz.open("some.xps") - >>> pdfbytes = xps.convert_to_pdf() - >>> - >>> # either do this --> - >>> pdf = fitz.open("pdf", pdfbytes) - >>> pdf.save("some.pdf") - >>> - >>> # or this --> - >>> pdfout = open("some.pdf", "wb") - >>> pdfout.tobytes(pdfbytes) - >>> pdfout.close() + >>> # convert an XPS file to PDF + >>> xps = fitz.open("some.xps") + >>> pdfbytes = xps.convert_to_pdf() + >>> + >>> # either do this --> + >>> pdf = fitz.open("pdf", pdfbytes) + >>> pdf.save("some.pdf") + >>> + >>> # or this --> + >>> pdfout = open("some.pdf", "wb") + >>> pdfout.tobytes(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.convert_to_pdf() # make a 1-page PDF of it - imgpdf=fitz.open("pdf", pdfbytes) - doc.insert_pdf(imgpdf) # insert the image PDF - >>> doc.save("allmyimages.pdf") + >>> # 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.convert_to_pdf() # make a 1-page PDF of it + imgpdf=fitz.open("pdf", pdfbytes) + doc.insert_pdf(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. + .. 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. However, image transparency is ignored. If you need that (like for a watermark), use :meth:`Page.insert_image` instead. Otherwise, this method is recommended for its much better performance. - * XPS: appearance very good. Links work fine, outlines (bookmarks) are lost, but can easily be recovered [#f2]_. - * EPUB, CBZ, FB2: similar to XPS. - * SVG: medium. Roughly comparable to `svglib `_. + * Image files: perfect, no issues detected. However, image transparency is ignored. If you need that (like for a watermark), use :meth:`Page.insert_image` instead. Otherwise, this method is recommended for its much better performance. + * XPS: appearance very good. Links work fine, outlines (bookmarks) are lost, but can easily be recovered [#f2]_. + * EPUB, CBZ, FB2: similar to XPS. + * SVG: medium. Roughly comparable to `svglib `_. - .. method:: get_toc(simple=True) + .. method:: get_toc(simple=True) - Creates a table of contents (TOC) out of the document's outline chain. + Creates a table of contents (TOC) out of the document's outline chain. - :arg bool simple: Indicates whether a simple or a detailed TOC is required. If *False*, each item of the list also contains a dictionary with :ref:`linkDest` details for each outline entry. + :arg bool simple: Indicates whether a simple or a detailed TOC is required. If *False*, each item of the list also contains a dictionary with :ref:`linkDest` details for each outline entry. - :rtype: list + :rtype: list - :returns: a list of lists. Each entry has the form *[lvl, title, page, dest]*. Its entries have the following meanings: + :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 source page number (*int*). `-1` if no destination or outside document. - * *dest* -- (*dict*) included only if *simple=False*. Contains details of the TOC item as follows: + * *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 source page number (*int*). `-1` if no destination or outside document. + * *dest* -- (*dict*) included only if *simple=False*. Contains details of the TOC item as follows: - - kind: destination kind, see :ref:`linkDest Kinds`. - - file: filename if kind is :data:`LINK_GOTOR` or :data:`LINK_LAUNCH`. - - page: target page, 0-based, :data:`LINK_GOTOR` or :data:`LINK_GOTO` only. - - to: position on target page (:ref:`Point`). - - zoom: (float) zoom factor on target page. - - xref: :data:`xref` of the item (0 if no PDF). - - color: item color in PDF RGB format `(red, green, blue)`, or omitted (always omitted if no PDF). - - bold: true if bold item text or omitted. PDF only. - - italic: true if italic item text, or omitted. PDF only. - - collapse: true if sub-items are folded, or omitted. PDF only. - - nameddest: target name if kind=4. PDF only. (New in 1.23.7.) + - kind: destination kind, see :ref:`linkDest Kinds`. + - file: filename if kind is :data:`LINK_GOTOR` or :data:`LINK_LAUNCH`. + - page: target page, 0-based, :data:`LINK_GOTOR` or :data:`LINK_GOTO` only. + - to: position on target page (:ref:`Point`). + - zoom: (float) zoom factor on target page. + - xref: :data:`xref` of the item (0 if no PDF). + - color: item color in PDF RGB format `(red, green, blue)`, or omitted (always omitted if no PDF). + - bold: true if bold item text or omitted. PDF only. + - italic: true if italic item text, or omitted. PDF only. + - collapse: true if sub-items are folded, or omitted. PDF only. + - nameddest: target name if kind=4. PDF only. (New in 1.23.7.) - .. method:: xref_get_keys(xref) + .. method:: xref_get_keys(xref) - * New in v1.18.7 + * New in v1.18.7 - PDF only: Return the PDF dictionary keys of the :data:`dictionary` object provided by its xref number. + PDF only: Return the PDF dictionary keys of the :data:`dictionary` object provided by its xref number. - :arg int xref: the :data:`xref`. *(Changed in v1.18.10)* Use `-1` to access the special dictionary "PDF trailer". + :arg int xref: the :data:`xref`. *(Changed in v1.18.10)* Use `-1` to access the special dictionary "PDF trailer". - :returns: a tuple of dictionary keys present in object :data:`xref`. Examples: + :returns: a tuple of dictionary keys present in object :data:`xref`. Examples: - >>> from pprint import pprint - >>> import fitz - >>> doc=fitz.open("pymupdf.pdf") - >>> xref = doc.page_xref(0) # xref of page 0 - >>> pprint(doc.xref_get_keys(xref)) # primary level keys of a page - ('Type', 'Contents', 'Resources', 'MediaBox', 'Parent') - >>> pprint(doc.xref_get_keys(-1)) # primary level keys of the trailer - ('Type', 'Index', 'Size', 'W', 'Root', 'Info', 'ID', 'Length', 'Filter') - >>> + >>> from pprint import pprint + >>> import fitz + >>> doc=fitz.open("pymupdf.pdf") + >>> xref = doc.page_xref(0) # xref of page 0 + >>> pprint(doc.xref_get_keys(xref)) # primary level keys of a page + ('Type', 'Contents', 'Resources', 'MediaBox', 'Parent') + >>> pprint(doc.xref_get_keys(-1)) # primary level keys of the trailer + ('Type', 'Index', 'Size', 'W', 'Root', 'Info', 'ID', 'Length', 'Filter') + >>> - .. method:: xref_get_key(xref, key) - - * New in v1.18.7 - - PDF only: Return type and value of a PDF dictionary key of a :data:`dictionary` object given by its xref. - - :arg int xref: the :data:`xref`. *Changed in v1.18.10:* Use `-1` to access the special dictionary "PDF trailer". - - :arg str key: the desired PDF key. Must **exactly** match (case-sensitive) one of the keys contained in :meth:`Document.xref_get_keys`. - - :rtype: tuple - - :returns: A tuple (type, value) of strings, where type is one of "xref", "array", "dict", "int", "float", "null", "bool", "name", "string" or "unknown" (should not occur). Independent of "type", the value of the key is **always** formatted as a string -- see the following example -- and (almost always) a faithful reflection of what is stored in the PDF. In most cases, the format of the value string also gives a clue about the key type: - - * A "name" always starts with a "/" slash. - * An "xref" always ends with " 0 R". - * An "array" is always enclosed in "[...]" brackets. - * A "dict" is always enclosed in "<<...>>" brackets. - * A "bool", resp. "null" always equal either "true", "false", resp. "null". - * "float" and "int" are represented by their string format -- and are thus not always distinguishable. - * A "string" is converted to UTF-8 and may therefore deviate from what is stored in the PDF. For example, the PDF key "Author" may have a value of "" in the file, but the method will return `('string', 'Jorj X. McKie')`. - - >>> for key in doc.xref_get_keys(xref): - print(key, "=" , doc.xref_get_key(xref, key)) - Type = ('name', '/Page') - Contents = ('xref', '1297 0 R') - Resources = ('xref', '1296 0 R') - MediaBox = ('array', '[0 0 612 792]') - Parent = ('xref', '1301 0 R') - >>> # - >>> # Now same thing for the PDF trailer. - >>> # It has no xref, so -1 must be used instead. - >>> # - >>> for key in doc.xref_get_keys(-1): - print(key, "=", doc.xref_get_key(-1, key)) - Type = ('name', '/XRef') - Index = ('array', '[0 8802]') - Size = ('int', '8802') - W = ('array', '[1 3 1]') - Root = ('xref', '8799 0 R') - Info = ('xref', '8800 0 R') - ID = ('array', '[]') - Length = ('int', '21111') - Filter = ('name', '/FlateDecode') - >>> + .. method:: xref_get_key(xref, key) + + * New in v1.18.7 + + PDF only: Return type and value of a PDF dictionary key of a :data:`dictionary` object given by its xref. + + :arg int xref: the :data:`xref`. *Changed in v1.18.10:* Use `-1` to access the special dictionary "PDF trailer". + + :arg str key: the desired PDF key. Must **exactly** match (case-sensitive) one of the keys contained in :meth:`Document.xref_get_keys`. + + :rtype: tuple + + :returns: A tuple (type, value) of strings, where type is one of "xref", "array", "dict", "int", "float", "null", "bool", "name", "string" or "unknown" (should not occur). Independent of "type", the value of the key is **always** formatted as a string -- see the following example -- and (almost always) a faithful reflection of what is stored in the PDF. In most cases, the format of the value string also gives a clue about the key type: + + * A "name" always starts with a "/" slash. + * An "xref" always ends with " 0 R". + * An "array" is always enclosed in "[...]" brackets. + * A "dict" is always enclosed in "<<...>>" brackets. + * A "bool", resp. "null" always equal either "true", "false", resp. "null". + * "float" and "int" are represented by their string format -- and are thus not always distinguishable. + * A "string" is converted to UTF-8 and may therefore deviate from what is stored in the PDF. For example, the PDF key "Author" may have a value of "" in the file, but the method will return `('string', 'Jorj X. McKie')`. + + >>> for key in doc.xref_get_keys(xref): + print(key, "=" , doc.xref_get_key(xref, key)) + Type = ('name', '/Page') + Contents = ('xref', '1297 0 R') + Resources = ('xref', '1296 0 R') + MediaBox = ('array', '[0 0 612 792]') + Parent = ('xref', '1301 0 R') + >>> # + >>> # Now same thing for the PDF trailer. + >>> # It has no xref, so -1 must be used instead. + >>> # + >>> for key in doc.xref_get_keys(-1): + print(key, "=", doc.xref_get_key(-1, key)) + Type = ('name', '/XRef') + Index = ('array', '[0 8802]') + Size = ('int', '8802') + W = ('array', '[1 3 1]') + Root = ('xref', '8799 0 R') + Info = ('xref', '8800 0 R') + ID = ('array', '[]') + Length = ('int', '21111') + Filter = ('name', '/FlateDecode') + >>> - .. method:: xref_set_key(xref, key, value) + .. method:: xref_set_key(xref, key, value) - * New in v1.18.7, changed in v 1.18.13 - * Changed in v1.19.4: remove a key "physically" if set to "null". + * New in v1.18.7, changed in v 1.18.13 + * Changed in v1.19.4: remove a key "physically" if set to "null". - PDF only: Set (add, update, delete) the value of a PDF key for the :data:`dictionary` object given by its xref. - - .. caution:: This is an expert function: if you do not know what you are doing, there is a high risk to render (parts of) the PDF unusable. Please do consult :ref:`AdobeManual` about object specification formats (page 18) and the structure of special dictionary types like page objects. + PDF only: Set (add, update, delete) the value of a PDF key for the :data:`dictionary` object given by its xref. - :arg int xref: the :data:`xref`. *Changed in v1.18.13:* To update the PDF trailer, specify -1. - :arg str key: the desired PDF key (without leading "/"). Must not be empty. Any valid PDF key -- whether already present in the object (which will be overwritten) -- or new. It is possible to use PDF path notation like `"Resources/ExtGState"` -- which sets the value for key `"/ExtGState"` as a sub-object of `"/Resources"`. - :arg str value: the value for the key. It must be a non-empty string and, depending on the desired PDF object type, the following rules must be observed. There is some syntax checking, but **no type checking** and no checking if it makes sense PDF-wise, i.e. **no semantics checking**. Upper / lower case is important! + .. caution:: This is an expert function: if you do not know what you are doing, there is a high risk to render (parts of) the PDF unusable. Please do consult :ref:`AdobeManual` about object specification formats (page 18) and the structure of special dictionary types like page objects. - * **xref** -- must be provided as `"nnn 0 R"` with a valid :data:`xref` number nnn of the PDF. The suffix "`0 R`" is required to be recognizable as an xref by PDF applications. - * **array** -- a string like `"[a b c d e f]"`. The brackets are required. Array items must be separated by at least one space (not commas like in Python). An empty array `"[]"` is possible and *equivalent* to removing the key. Array items may be any PDF objects, like dictionaries, xrefs, other arrays, etc. Like in Python, array items may be of different types. - * **dict** -- a string like `"<< ... >>"`. The brackets are required and must enclose a valid PDF dictionary definition. The empty dictionary `"<<>>"` is possible and *equivalent* to removing the key. - * **int** -- an integer formatted **as a string**. - * **float** -- a float formatted **as a string**. Scientific notation (with exponents) is **not allowed by PDF**. - * **null** -- the string `"null"`. This is the PDF equivalent to Python's `None` and causes the key to be ignored -- however not necessarily removed, resp. removed on saves with garbage collection. *Changed in v1.19.4:* If the key is no path hierarchy (i.e. contains no slash "/"), then it will be completely removed. - * **bool** -- one of the strings `"true"` or `"false"`. - * **name** -- a valid PDF name with a leading slash like this: `"/PageLayout"`. See page 16 of the :ref:`AdobeManual`. - * **string** -- a valid PDF string. **All PDF strings must be enclosed by brackets**. Denote the empty string as `"()"`. Depending on its content, the possible brackets are - - - "(...)" for ASCII-only text. Reserved PDF characters must be backslash-escaped and non-ASCII characters must be provided as 3-digit backslash-escaped octals -- including leading zeros. Example: 12 = 0x0C must be encoded as `\014`. - - "<...>" for hex-encoded text. Every character must be represented by two hex-digits (lower or upper case). - - - If in doubt, we **strongly recommend** to use :meth:`get_pdf_str`! This function automatically generates the right brackets, escapes, and overall format. It will for example do conversions like these: + :arg int xref: the :data:`xref`. *Changed in v1.18.13:* To update the PDF trailer, specify -1. + :arg str key: the desired PDF key (without leading "/"). Must not be empty. Any valid PDF key -- whether already present in the object (which will be overwritten) -- or new. It is possible to use PDF path notation like `"Resources/ExtGState"` -- which sets the value for key `"/ExtGState"` as a sub-object of `"/Resources"`. + :arg str value: the value for the key. It must be a non-empty string and, depending on the desired PDF object type, the following rules must be observed. There is some syntax checking, but **no type checking** and no checking if it makes sense PDF-wise, i.e. **no semantics checking**. Upper / lower case is important! - >>> # because of the € symbol, the following yields UTF-16BE BOM - >>> fitz.get_pdf_str("Pay in $ or €.") - '' - >>> # escapes for brackets and non-ASCII - >>> fitz.get_pdf_str("Prices in EUR (USD also accepted). Areas are in m².") - '(Prices in EUR \\(USD also accepted\\). Areas are in m\\262.)' + * **xref** -- must be provided as `"nnn 0 R"` with a valid :data:`xref` number nnn of the PDF. The suffix "`0 R`" is required to be recognizable as an xref by PDF applications. + * **array** -- a string like `"[a b c d e f]"`. The brackets are required. Array items must be separated by at least one space (not commas like in Python). An empty array `"[]"` is possible and *equivalent* to removing the key. Array items may be any PDF objects, like dictionaries, xrefs, other arrays, etc. Like in Python, array items may be of different types. + * **dict** -- a string like `"<< ... >>"`. The brackets are required and must enclose a valid PDF dictionary definition. The empty dictionary `"<<>>"` is possible and *equivalent* to removing the key. + * **int** -- an integer formatted **as a string**. + * **float** -- a float formatted **as a string**. Scientific notation (with exponents) is **not allowed by PDF**. + * **null** -- the string `"null"`. This is the PDF equivalent to Python's `None` and causes the key to be ignored -- however not necessarily removed, resp. removed on saves with garbage collection. *Changed in v1.19.4:* If the key is no path hierarchy (i.e. contains no slash "/"), then it will be completely removed. + * **bool** -- one of the strings `"true"` or `"false"`. + * **name** -- a valid PDF name with a leading slash like this: `"/PageLayout"`. See page 16 of the :ref:`AdobeManual`. + * **string** -- a valid PDF string. **All PDF strings must be enclosed by brackets**. Denote the empty string as `"()"`. Depending on its content, the possible brackets are + - "(...)" for ASCII-only text. Reserved PDF characters must be backslash-escaped and non-ASCII characters must be provided as 3-digit backslash-escaped octals -- including leading zeros. Example: 12 = 0x0C must be encoded as `\014`. + - "<...>" for hex-encoded text. Every character must be represented by two hex-digits (lower or upper case). - .. method:: get_page_pixmap(pno: int, *, matrix: matrix_like = Identity, dpi=None, colorspace: Colorspace = csRGB, clip: rect_like = None, alpha: bool = False, annots: bool = True) + - If in doubt, we **strongly recommend** to use :meth:`get_pdf_str`! This function automatically generates the right brackets, escapes, and overall format. It will for example do conversions like these: - Creates a pixmap from page *pno* (zero-based). Invokes :meth:`Page.get_pixmap`. + >>> # because of the € symbol, the following yields UTF-16BE BOM + >>> fitz.get_pdf_str("Pay in $ or €.") + '' + >>> # escapes for brackets and non-ASCII + >>> fitz.get_pdf_str("Prices in EUR (USD also accepted). Areas are in m².") + '(Prices in EUR \\(USD also accepted\\). Areas are in m\\262.)' - All parameters except `pno` are *keyword-only.* - :arg int pno: page number, 0-based in `-∞ < pno < page_count`. + .. method:: get_page_pixmap(pno: int, *, matrix: matrix_like = Identity, dpi=None, colorspace: Colorspace = csRGB, clip: rect_like = None, alpha: bool = False, annots: bool = True) - :rtype: :ref:`Pixmap` + Creates a pixmap from page *pno* (zero-based). Invokes :meth:`Page.get_pixmap`. - .. method:: get_page_xobjects(pno) + All parameters except `pno` are *keyword-only.* - * New in v1.16.13 - * Changed in v1.18.11 + :arg int pno: page number, 0-based in `-∞ < pno < page_count`. - PDF only: Return a list of all XObjects referenced by a page. + :rtype: :ref:`Pixmap` - :arg int pno: page number, 0-based, `-∞ < pno < page_count`. + .. method:: get_page_xobjects(pno) - :rtype: list - :returns: a list of (non-image) XObjects. These objects typically represent pages *embedded* (not copied) from other PDFs. For example, :meth:`Page.show_pdf_page` will create this type of object. An item of this list has the following layout: `(xref, name, invoker, bbox)`, where + * New in v1.16.13 + * Changed in v1.18.11 - * **xref** (*int*) is the XObject's :data:`xref`. - * **name** (*str*) is the symbolic name to reference the XObject. - * **invoker** (*int*) the :data:`xref` of the invoking XObject or zero if the page directly invokes it. - * **bbox** (:ref:`Rect`) the boundary box of the XObject's location on the page **in untransformed coordinates**. To get actual, non-rotated page coordinates, multiply with the page's transformation matrix :attr:`Page.transformation_matrix`. *Changed in v.18.11:* the bbox is now formatted as :ref:`Rect`. + PDF only: Return a list of all XObjects referenced by a page. + :arg int pno: page number, 0-based, `-∞ < pno < page_count`. - .. method:: get_page_images(pno, full=False) + :rtype: list + :returns: a list of (non-image) XObjects. These objects typically represent pages *embedded* (not copied) from other PDFs. For example, :meth:`Page.show_pdf_page` will create this type of object. An item of this list has the following layout: `(xref, name, invoker, bbox)`, where - PDF only: Return a list of all images (directly or indirectly) referenced by the page. + * **xref** (*int*) is the XObject's :data:`xref`. + * **name** (*str*) is the symbolic name to reference the XObject. + * **invoker** (*int*) the :data:`xref` of the invoking XObject or zero if the page directly invokes it. + * **bbox** (:ref:`Rect`) the boundary box of the XObject's location on the page **in untransformed coordinates**. To get actual, non-rotated page coordinates, multiply with the page's transformation matrix :attr:`Page.transformation_matrix`. *Changed in v.18.11:* the bbox is now formatted as :ref:`Rect`. - :arg int pno: page number, 0-based, `-∞ < pno < page_count`. - :arg bool full: whether to also include the referencer's :data:`xref` (which is zero if this is the page). - :rtype: list + .. method:: get_page_images(pno, full=False) - :returns: a list of images **referenced** by this page. Each item looks like + PDF only: Return a list of all images (directly or indirectly) referenced by the page. - `(xref, smask, width, height, bpc, colorspace, alt. colorspace, name, filter, referencer)` + :arg int pno: page number, 0-based, `-∞ < pno < page_count`. + :arg bool full: whether to also include the referencer's :data:`xref` (which is zero if this is the page). - Where + :rtype: list - * **xref** (*int*) is the image object number - * **smask** (*int*) is the object number of its soft-mask image - * **width** and **height** (*ints*) are the image dimensions - * **bpc** (*int*) denotes the number of bits per component (normally 8) - * **colorspace** (*str*) a string naming the colorspace (like **DeviceRGB**) - * **alt. colorspace** (*str*) is any alternate colorspace depending on the value of **colorspace** - * **name** (*str*) is the symbolic name by which the image is referenced - * **filter** (*str*) is the decode filter of the image (:ref:`AdobeManual`, pp. 22). - * **referencer** (*int*) the :data:`xref` of the referencer. Zero if directly referenced by the page. Only present if *full=True*. + :returns: a list of images **referenced** by this page. Each item looks like - .. note:: In general, this is not the list of images that are **actually displayed**. This method only parses several PDF objects to collect references to embedded images. It does not analyse the page's :data:`contents`, where all the actual image display commands are defined. To get this information, please use :meth:`Page.get_image_info`. Also have a look at the discussion in section :ref:`textpagedict`. + `(xref, smask, width, height, bpc, colorspace, alt. colorspace, name, filter, referencer)` + Where - .. method:: get_page_fonts(pno, full=False) + * **xref** (*int*) is the image object number + * **smask** (*int*) is the object number of its soft-mask image + * **width** and **height** (*ints*) are the image dimensions + * **bpc** (*int*) denotes the number of bits per component (normally 8) + * **colorspace** (*str*) a string naming the colorspace (like **DeviceRGB**) + * **alt. colorspace** (*str*) is any alternate colorspace depending on the value of **colorspace** + * **name** (*str*) is the symbolic name by which the image is referenced + * **filter** (*str*) is the decode filter of the image (:ref:`AdobeManual`, pp. 22). + * **referencer** (*int*) the :data:`xref` of the referencer. Zero if directly referenced by the page. Only present if *full=True*. - PDF only: Return a list of all fonts (directly or indirectly) referenced by the page. + .. note:: In general, this is not the list of images that are **actually displayed**. This method only parses several PDF objects to collect references to embedded images. It does not analyse the page's :data:`contents`, where all the actual image display commands are defined. To get this information, please use :meth:`Page.get_image_info`. Also have a look at the discussion in section :ref:`textpagedict`. - :arg int pno: page number, 0-based, `-∞ < pno < page_count`. - :arg bool full: whether to also include the referencer's :data:`xref`. If *True*, the returned items are one entry longer. Use this option if you need to know, whether the page directly references the font. In this case the last entry is 0. If the font is referenced by an `/XObject` of the page, you will find its :data:`xref` here. - :rtype: list + .. method:: get_page_fonts(pno, full=False) - :returns: a list of fonts referenced by this page. Each entry looks like + PDF only: Return a list of all fonts (directly or indirectly) referenced by the page. - **(xref, ext, type, basefont, name, encoding, referencer)**, + :arg int pno: page number, 0-based, `-∞ < pno < page_count`. + :arg bool full: whether to also include the referencer's :data:`xref`. If *True*, the returned items are one entry longer. Use this option if you need to know, whether the page directly references the font. In this case the last entry is 0. If the font is referenced by an `/XObject` of the page, you will find its :data:`xref` here. - where + :rtype: list - * **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 :ref:`FontExtensions`) - * **type** (*str*) is the font type (like "Type1" or "TrueType" etc.) - * **basefont** (*str*) is the base font name, - * **name** (*str*) is the symbolic name, by which the font is referenced - * **encoding** (*str*) the font's character encoding if different from its built-in encoding (:ref:`AdobeManual`, p. 254): - * **referencer** (*int* optional) the :data:`xref` of the referencer. Zero if directly referenced by the page, otherwise the xref of an XObject. Only present if *full=True*. + :returns: a list of fonts referenced by this page. Each entry looks like - Example:: + **(xref, ext, type, basefont, name, encoding, referencer)**, - >>> pprint(doc.get_page_fonts(0, full=False)) - [(12, 'ttf', 'TrueType', 'FNUUTH+Calibri-Bold', 'R8', ''), - (13, 'ttf', 'TrueType', 'DOKBTG+Calibri', 'R10', ''), - (14, 'ttf', 'TrueType', 'NOHSJV+Calibri-Light', 'R12', ''), - (15, 'ttf', 'TrueType', 'NZNDCL+CourierNewPSMT', 'R14', ''), - (16, 'ttf', 'Type0', 'MNCSJY+SymbolMT', 'R17', 'Identity-H'), - (17, 'cff', 'Type1', 'UAEUYH+Helvetica', 'R20', 'WinAnsiEncoding'), - (18, 'ttf', 'Type0', 'ECPLRU+Calibri', 'R23', 'Identity-H'), - (19, 'ttf', 'Type0', 'TONAYT+CourierNewPSMT', 'R27', 'Identity-H')] + where - .. note:: - * This list has no duplicate entries: the combination of :data:`xref`, *name* and *referencer* is unique. - * In general, this is a superset of the fonts actually in use by this page. The PDF creator may e.g. have specified some global list, of which each page only makes partial use. + * **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 :ref:`FontExtensions`) + * **type** (*str*) is the font type (like "Type1" or "TrueType" etc.) + * **basefont** (*str*) is the base font name, + * **name** (*str*) is the symbolic name, by which the font is referenced + * **encoding** (*str*) the font's character encoding if different from its built-in encoding (:ref:`AdobeManual`, p. 254): + * **referencer** (*int* optional) the :data:`xref` of the referencer. Zero if directly referenced by the page, otherwise the xref of an XObject. Only present if *full=True*. - .. method:: get_page_text(pno, output="text", flags=3, textpage=None, sort=False) + Example:: - Extracts the text of a page given its page number *pno* (zero-based). Invokes :meth:`Page.get_text`. + >>> pprint(doc.get_page_fonts(0, full=False)) + [(12, 'ttf', 'TrueType', 'FNUUTH+Calibri-Bold', 'R8', ''), + (13, 'ttf', 'TrueType', 'DOKBTG+Calibri', 'R10', ''), + (14, 'ttf', 'TrueType', 'NOHSJV+Calibri-Light', 'R12', ''), + (15, 'ttf', 'TrueType', 'NZNDCL+CourierNewPSMT', 'R14', ''), + (16, 'ttf', 'Type0', 'MNCSJY+SymbolMT', 'R17', 'Identity-H'), + (17, 'cff', 'Type1', 'UAEUYH+Helvetica', 'R20', 'WinAnsiEncoding'), + (18, 'ttf', 'Type0', 'ECPLRU+Calibri', 'R23', 'Identity-H'), + (19, 'ttf', 'Type0', 'TONAYT+CourierNewPSMT', 'R27', 'Identity-H')] - :arg int pno: page number, 0-based, any value `-∞ < pno < page_count`. + .. note:: + * This list has no duplicate entries: the combination of :data:`xref`, *name* and *referencer* is unique. + * In general, this is a superset of the fonts actually in use by this page. The PDF creator may e.g. have specified some global list, of which each page only makes partial use. - For other parameter refer to the page method. + .. method:: get_page_text(pno, output="text", flags=3, textpage=None, sort=False) - :rtype: str + Extracts the text of a page given its page number *pno* (zero-based). Invokes :meth:`Page.get_text`. - .. index:: - pair: fontsize; Document.layout - pair: rect; Document.layout - pair: width; Document.layout - pair: height; Document.layout + :arg int pno: page number, 0-based, any value `-∞ < pno < page_count`. - .. method:: layout(rect=None, width=0, height=0, fontsize=11) + For other parameter refer to the page method. - 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 :attr:`is_reflowable`. + :rtype: str - :arg rect_like rect: desired page size. Must be finite, not empty and start at point (0, 0). - :arg float width: use it together with *height* as alternative to *rect*. - :arg float height: use it together with *width* as alternative to *rect*. - :arg float fontsize: the desired default fontsize. + .. index:: + pair: fontsize; Document.layout + pair: rect; Document.layout + pair: width; Document.layout + pair: height; Document.layout - .. method:: select(s) + .. method:: layout(rect=None, width=0, height=0, fontsize=11) - PDF only: Keeps only those pages of the document whose numbers occur in the list. Empty sequences or elements outside `range(doc.page_count)` will cause a *ValueError*. For more details see remarks at the bottom or this chapter. + 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 :attr:`is_reflowable`. - :arg sequence s: The sequence (see :ref:`SequenceTypes`) 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. + :arg rect_like rect: desired page size. Must be finite, not empty and start at point (0, 0). + :arg float width: use it together with *height* as alternative to *rect*. + :arg float height: use it together with *width* as alternative to *rect*. + :arg float fontsize: the desired default fontsize. - .. note:: + .. method:: select(s) - * 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 or meeting some other criteria and so forth. + PDF only: Keeps only those pages of the document whose numbers occur in the list. Empty sequences or elements outside `range(doc.page_count)` will cause a *ValueError*. For more details see remarks at the bottom or this chapter. - * On a technical level, the method will always create a new :data:`pagetree`. + :arg sequence s: The sequence (see :ref:`SequenceTypes`) 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. - * When dealing with only a few pages, methods :meth:`copy_page`, :meth:`move_page`, :meth:`delete_page` are easier to use. In fact, they are also **much faster** -- by at least one order of magnitude when the document has many pages. + .. note:: + * 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 or meeting some other criteria and so forth. - .. method:: set_metadata(m) + * On a technical level, the method will always create a new :data:`pagetree`. - PDF only: Sets or updates the metadata of the document as specified in *m*, a Python dictionary. + * When dealing with only a few pages, methods :meth:`copy_page`, :meth:`move_page`, :meth:`delete_page` are easier to use. In fact, they are also **much faster** -- by at least one order of magnitude when the document has many pages. - :arg dict m: 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. - *(Changed in v1.18.4)* Empty values or "none" are no longer written, but completely omitted. + .. method:: set_metadata(m) - .. method:: get_xml_metadata() + PDF only: Sets or updates the metadata of the document as specified in *m*, a Python dictionary. - PDF only: Get the document XML metadata. + :arg dict m: 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. - :rtype: str - :returns: XML metadata of the document. Empty string if not present or not a PDF. + *(Changed in v1.18.4)* Empty values or "none" are no longer written, but completely omitted. - .. method:: set_xml_metadata(xml) + .. method:: get_xml_metadata() - PDF only: Sets or updates XML metadata of the document. + PDF only: Get the document XML metadata. - :arg str xml: the new XML metadata. Should be XML syntax, however no checking is done by this method and any string is accepted. + :rtype: str + :returns: XML metadata of the document. Empty string if not present or not a PDF. + .. method:: set_xml_metadata(xml) - .. method:: set_pagelayout(value) + PDF only: Sets or updates XML metadata of the document. - * New in v1.22.2 + :arg str xml: the new XML metadata. Should be XML syntax, however no checking is done by this method and any string is accepted. - PDF only: Set the `/PageLayout`. - :arg str value: one of the strings "SinglePage", "OneColumn", "TwoColumnLeft", "TwoColumnRight", "TwoPageLeft", "TwoPageRight". Lower case is supported. + .. method:: set_pagelayout(value) + * New in v1.22.2 - .. method:: set_pagemode(value) + PDF only: Set the `/PageLayout`. - * New in v1.22.2 + :arg str value: one of the strings "SinglePage", "OneColumn", "TwoColumnLeft", "TwoColumnRight", "TwoPageLeft", "TwoPageRight". Lower case is supported. - PDF only: Set the `/PageMode`. - :arg str value: one of the strings "UseNone", "UseOutlines", "UseThumbs", "FullScreen", "UseOC", "UseAttachments". Lower case is supported. + .. method:: set_pagemode(value) + * New in v1.22.2 - .. method:: set_markinfo(value) + PDF only: Set the `/PageMode`. - * New in v1.22.2 + :arg str value: one of the strings "UseNone", "UseOutlines", "UseThumbs", "FullScreen", "UseOC", "UseAttachments". Lower case is supported. - PDF only: Set the `/MarkInfo` values. - :arg dict value: a dictionary like this one: `{"Marked": False, "UserProperties": False, "Suspects": False}`. This dictionary contains information about the usage of Tagged PDF conventions. For details please see the `PDF specifications `_. + .. method:: set_markinfo(value) + * New in v1.22.2 - .. method:: set_toc(toc, collapse=1) + PDF only: Set the `/MarkInfo` values. - PDF only: Replaces the **complete current outline** tree (table of contents) with the one provided as the argument. After successful execution, the new outline tree can be accessed as usual via :meth:`Document.get_toc` or via :attr:`Document.outline`. Like with other output-oriented methods, changes become permanent only via :meth:`save` (incremental save supported). Internally, this method consists of the following two steps. For a demonstration see example below. + :arg dict value: a dictionary like this one: `{"Marked": False, "UserProperties": False, "Suspects": False}`. This dictionary contains information about the usage of Tagged PDF conventions. For details please see the `PDF specifications `_. - - Step 1 deletes all existing bookmarks. - - Step 2 creates a new TOC from the entries contained in *toc*. + .. method:: set_toc(toc, collapse=1) - :arg sequence toc: + PDF only: Replaces the **complete current outline** tree (table of contents) with the one provided as the argument. After successful execution, the new outline tree can be accessed as usual via :meth:`Document.get_toc` or via :attr:`Document.outline`. Like with other output-oriented methods, changes become permanent only via :meth:`save` (incremental save supported). Internally, this method consists of the following two steps. For a demonstration see example below. - A list / tuple with **all bookmark entries** that should form the new table of contents. Output variants of :meth:`get_toc` are acceptable. To completely remove the table of contents specify an empty sequence or None. Each item must be a list with the following format. + - Step 1 deletes all existing bookmarks. - * [lvl, title, page [, dest]] where + - Step 2 creates a new TOC from the entries contained in *toc*. - - **lvl** is the hierarchy level (int > 0) of the item, which **must be 1** for the first item and at most 1 larger than the previous one. + :arg sequence toc: - - **title** (str) is the title to be displayed. It is assumed to be UTF-8-encoded (relevant for multibyte code points only). + A list / tuple with **all bookmark entries** that should form the new table of contents. Output variants of :meth:`get_toc` are acceptable. To completely remove the table of contents specify an empty sequence or None. Each item must be a list with the following format. - - **page** (int) is the target page number **(attention: 1-based)**. Must be in valid range if positive. Set it to -1 if there is no target, or the target is external. + * [lvl, title, page [, dest]] where - - **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 the page. Use a dictionary (like the one given as output by `get_toc(False)`) for a detailed control of the bookmark's properties, see :meth:`Document.get_toc` for a description. + - **lvl** is the hierarchy level (int > 0) of the item, which **must be 1** for the first item and at most 1 larger than the previous one. - :arg int collapse: *(new in v1.16.9)* controls the hierarchy level beyond which outline entries should initially show up collapsed. The default 1 will hence only display level 1, higher levels must be unfolded using the PDF viewer. To unfold everything, specify either a large integer, 0 or None. + - **title** (str) is the title to be displayed. It is assumed to be UTF-8-encoded (relevant for multibyte code points only). - :rtype: int - :returns: the number of inserted, resp. deleted items. - - Changed in v1.23.8: Destination 'to' coordinates should now be in the - same coordinate system as those returned by `get_toc()` (internally they - are now transformed with `page.cropbox` and `page.rotation_matrix`). So - for example `set_toc(get_toc())` now gives unchanged destination 'to' - coordinates. + - **page** (int) is the target page number **(attention: 1-based)**. Must be in valid range if positive. Set it to -1 if there is no target, or the target is external. - .. method:: outline_xref(idx) + - **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 the page. Use a dictionary (like the one given as output by `get_toc(False)`) for a detailed control of the bookmark's properties, see :meth:`Document.get_toc` for a description. - * New in v1.17.7 + :arg int collapse: *(new in v1.16.9)* controls the hierarchy level beyond which outline entries should initially show up collapsed. The default 1 will hence only display level 1, higher levels must be unfolded using the PDF viewer. To unfold everything, specify either a large integer, 0 or None. - PDF only: Return the :data:`xref` of the outline item. This is mainly used for internal purposes. + :rtype: int + :returns: the number of inserted, resp. deleted items. - arg int idx: index of the item in list :meth:`Document.get_toc`. + Changed in v1.23.8: Destination 'to' coordinates should now be in the + same coordinate system as those returned by `get_toc()` (internally they + are now transformed with `page.cropbox` and `page.rotation_matrix`). So + for example `set_toc(get_toc())` now gives unchanged destination 'to' + coordinates. - :returns: :data:`xref`. + .. method:: outline_xref(idx) - .. method:: del_toc_item(idx) + * New in v1.17.7 - * New in v1.17.7 - * Changed in v1.18.14: no longer remove the item's text, but show it grayed-out. + PDF only: Return the :data:`xref` of the outline item. This is mainly used for internal purposes. - PDF only: Remove this TOC item. This is a high-speed method, which **disables** the respective item, but leaves the overall TOC structure intact. Physically, the item still exists in the TOC tree, but is shown grayed-out and will no longer point to any destination. + arg int idx: index of the item in list :meth:`Document.get_toc`. - This also implies that you can reassign the item to a new destination using :meth:`Document.set_toc_item`, when required. + :returns: :data:`xref`. - :arg int idx: the index of the item in list :meth:`Document.get_toc`. + .. method:: del_toc_item(idx) + * New in v1.17.7 + * Changed in v1.18.14: no longer remove the item's text, but show it grayed-out. - .. method:: set_toc_item(idx, dest_dict=None, kind=None, pno=None, uri=None, title=None, to=None, filename=None, zoom=0) + PDF only: Remove this TOC item. This is a high-speed method, which **disables** the respective item, but leaves the overall TOC structure intact. Physically, the item still exists in the TOC tree, but is shown grayed-out and will no longer point to any destination. - * New in v1.17.7 - * Changed in v1.18.6 + This also implies that you can reassign the item to a new destination using :meth:`Document.set_toc_item`, when required. - PDF only: Changes the TOC item identified by its index. Change the item **title**, **destination**, **appearance** (color, bold, italic) or collapsing sub-items -- or to remove the item altogether. + :arg int idx: the index of the item in list :meth:`Document.get_toc`. - Use this method if you need specific changes for selected entries only and want to avoid replacing the complete TOC. This is beneficial especially when dealing with large table of contents. - :arg int idx: the index of the entry in the list created by :meth:`Document.get_toc`. - :arg dict dest_dict: the new destination. A dictionary like the last entry of an item in `doc.get_toc(False)`. Using this as a template is recommended. When given, **all other parameters are ignored** -- except title. - :arg int kind: the link kind, see :ref:`linkDest Kinds`. If :data:`LINK_NONE`, then all remaining parameter will be ignored, and the TOC item will be removed -- same as :meth:`Document.del_toc_item`. If None, then only the title is modified and the remaining parameters are ignored. All other values will lead to making a new destination dictionary using the subsequent arguments. - :arg int pno: the 1-based page number, i.e. a value 1 <= pno <= doc.page_count. Required for LINK_GOTO. - :arg str uri: the URL text. Required for LINK_URI. - :arg str title: the desired new title. None if no change. - :arg point_like to: (optional) points to a coordinate on the target page. Relevant for LINK_GOTO. If omitted, a point near the page's top is chosen. - :arg str filename: required for LINK_GOTOR and LINK_LAUNCH. - :arg float zoom: use this zoom factor when showing the target page. + .. method:: set_toc_item(idx, dest_dict=None, kind=None, pno=None, uri=None, title=None, to=None, filename=None, zoom=0) - **Example use:** Change the TOC of the SWIG manual to achieve this: + * New in v1.17.7 + * Changed in v1.18.6 - Collapse everything below top level and show the chapter on Python support in red, bold and italic:: + PDF only: Changes the TOC item identified by its index. Change the item **title**, **destination**, **appearance** (color, bold, italic) or collapsing sub-items -- or to remove the item altogether. - >>> import fitz - >>> doc=fitz.open("SWIGDocumentation.pdf") - >>> toc = doc.get_toc(False) # we need the detailed TOC - >>> # list of level 1 indices and their titles - >>> lvl1 = [(i, item[1]) for i, item in enumerate(toc) if item[0] == 1] - >>> for i, title in lvl1: - d = toc[i][3] # get the destination dict - d["collapse"] = True # collapse items underneath - if "Python" in title: # show the 'Python' chapter - d["color"] = (1, 0, 0) # in red, - d["bold"] = True # bold and - d["italic"] = True # italic - doc.set_toc_item(i, dest_dict=d) # update this toc item - >>> doc.save("NEWSWIG.pdf",garbage=3,deflate=True) + Use this method if you need specific changes for selected entries only and want to avoid replacing the complete TOC. This is beneficial especially when dealing with large table of contents. - In the previous example, we have changed only 42 of the 1240 TOC items of the file. + :arg int idx: the index of the entry in the list created by :meth:`Document.get_toc`. + :arg dict dest_dict: the new destination. A dictionary like the last entry of an item in `doc.get_toc(False)`. Using this as a template is recommended. When given, **all other parameters are ignored** -- except title. + :arg int kind: the link kind, see :ref:`linkDest Kinds`. If :data:`LINK_NONE`, then all remaining parameter will be ignored, and the TOC item will be removed -- same as :meth:`Document.del_toc_item`. If None, then only the title is modified and the remaining parameters are ignored. All other values will lead to making a new destination dictionary using the subsequent arguments. + :arg int pno: the 1-based page number, i.e. a value 1 <= pno <= doc.page_count. Required for LINK_GOTO. + :arg str uri: the URL text. Required for LINK_URI. + :arg str title: the desired new title. None if no change. + :arg point_like to: (optional) points to a coordinate on the target page. Relevant for LINK_GOTO. If omitted, a point near the page's top is chosen. + :arg str filename: required for LINK_GOTOR and LINK_LAUNCH. + :arg float zoom: use this zoom factor when showing the target page. - .. method:: can_save_incrementally() + **Example use:** Change the TOC of the SWIG manual to achieve this: - * New in v1.16.0 + Collapse everything below top level and show the chapter on Python support in red, bold and italic:: - Check whether the document can be saved incrementally. Use it to choose the right option without encountering exceptions. + >>> import fitz + >>> doc=fitz.open("SWIGDocumentation.pdf") + >>> toc = doc.get_toc(False) # we need the detailed TOC + >>> # list of level 1 indices and their titles + >>> lvl1 = [(i, item[1]) for i, item in enumerate(toc) if item[0] == 1] + >>> for i, title in lvl1: + d = toc[i][3] # get the destination dict + d["collapse"] = True # collapse items underneath + if "Python" in title: # show the 'Python' chapter + d["color"] = (1, 0, 0) # in red, + d["bold"] = True # bold and + d["italic"] = True # italic + doc.set_toc_item(i, dest_dict=d) # update this toc item + >>> doc.save("NEWSWIG.pdf",garbage=3,deflate=True) - .. method:: scrub(attached_files=True, clean_pages=True, embedded_files=True, hidden_text=True, javascript=True, metadata=True, redactions=True, redact_images=0, remove_links=True, reset_fields=True, reset_responses=True, thumbnails=True, xml_metadata=True) + In the previous example, we have changed only 42 of the 1240 TOC items of the file. - * New in v1.16.14 - - PDF only: Remove potentially sensitive data from the PDF. This function is inspired by the similar "Sanitize" function in Adobe Acrobat products. The process is configurable by a number of options. + .. method:: can_save_incrementally() - :arg bool attached_files: Search for 'FileAttachment' annotations and remove the file content. - :arg bool clean_pages: Remove any comments from page painting sources. If this option is set to *False*, then this is also done for *hidden_text* and *redactions*. - :arg bool embedded_files: Remove embedded files. - :arg bool hidden_text: Remove OCRed text and invisible text [#f7]_. - :arg bool javascript: Remove JavaScript sources. - :arg bool metadata: Remove PDF standard metadata. - :arg bool redactions: Apply redaction annotations. - :arg int redact_images: how to handle images if applying redactions. One of 0 (ignore), 1 (blank out overlaps) or 2 (remove). - :arg bool remove_links: Remove all links. - :arg bool reset_fields: Reset all form fields to their defaults. - :arg bool reset_responses: Remove all responses from all annotations. - :arg bool thumbnails: Remove thumbnail images from pages. - :arg bool xml_metadata: Remove XML metadata. + * New in v1.16.0 + Check whether the document can be saved incrementally. Use it to choose the right option without encountering exceptions. - .. method:: save(outfile, garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, incremental=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None) + .. method:: scrub(attached_files=True, clean_pages=True, embedded_files=True, hidden_text=True, javascript=True, metadata=True, redactions=True, redact_images=0, remove_links=True, reset_fields=True, reset_responses=True, thumbnails=True, xml_metadata=True) - * Changed in v1.18.7 - * Changed in v1.19.0 + * New in v1.16.14 - PDF only: Saves the document in its **current state**. + PDF only: Remove potentially sensitive data from the PDF. This function is inspired by the similar "Sanitize" function in Adobe Acrobat products. The process is configurable by a number of options. - :arg str,Path,fp outfile: The file path, `pathlib.Path` or file object to save to. A file object must have been created before via `open(...)` or `io.BytesIO()`. Choosing `io.BytesIO()` is similar to :meth:`Document.tobytes` below, which equals the `getvalue()` output of an internally created `io.BytesIO()`. + :arg bool attached_files: Search for 'FileAttachment' annotations and remove the file content. + :arg bool clean_pages: Remove any comments from page painting sources. If this option is set to *False*, then this is also done for *hidden_text* and *redactions*. + :arg bool embedded_files: Remove embedded files. + :arg bool hidden_text: Remove OCRed text and invisible text [#f7]_. + :arg bool javascript: Remove JavaScript sources. + :arg bool metadata: Remove PDF standard metadata. + :arg bool redactions: Apply redaction annotations. + :arg int redact_images: how to handle images if applying redactions. One of 0 (ignore), 1 (blank out overlaps) or 2 (remove). + :arg bool remove_links: Remove all links. + :arg bool reset_fields: Reset all form fields to their defaults. + :arg bool reset_responses: Remove all responses from all annotations. + :arg bool thumbnails: Remove thumbnail images from pages. + :arg bool xml_metadata: Remove XML metadata. - :arg int garbage: Do garbage collection. Positive values exclude "incremental". - * 0 = none - * 1 = remove unused (unreferenced) objects. - * 2 = in addition to 1, compact the :data:`xref` table. - * 3 = in addition to 2, merge duplicate objects. - * 4 = in addition to 3, check :data:`stream` objects for duplication. This may be slow because such data are typically large. + .. method:: save(outfile, garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, incremental=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None) - :arg bool clean: Clean and sanitize content streams [#f1]_. Corresponds to "mutool clean -sc". + * Changed in v1.18.7 + * Changed in v1.19.0 - :arg bool deflate: Deflate (compress) uncompressed streams. - :arg bool deflate_images: *(new in v1.18.3)* Deflate (compress) uncompressed image streams [#f4]_. - :arg bool deflate_fonts: *(new in v1.18.3)* Deflate (compress) uncompressed fontfile streams [#f4]_. + PDF only: Saves the document in its **current state**. - :arg bool incremental: Only save changes to the PDF. Excludes "garbage" and "linear". Can only be used if *outfile* is a string or a `pathlib.Path` and equal to :attr:`Document.name`. Cannot be used for files that are decrypted or repaired and also in some other cases. To be sure, check :meth:`Document.can_save_incrementally`. If this is false, saving to a new file is required. + :arg str,Path,fp outfile: The file path, `pathlib.Path` or file object to save to. A file object must have been created before via `open(...)` or `io.BytesIO()`. Choosing `io.BytesIO()` is similar to :meth:`Document.tobytes` below, which equals the `getvalue()` output of an internally created `io.BytesIO()`. - :arg bool ascii: convert binary data to ASCII. + :arg int garbage: Do garbage collection. Positive values exclude "incremental". - :arg int expand: Decompress objects. Generates versions that can be better read by some other programs and will lead to larger files. + * 0 = none + * 1 = remove unused (unreferenced) objects. + * 2 = in addition to 1, compact the :data:`xref` table. + * 3 = in addition to 2, merge duplicate objects. + * 4 = in addition to 3, check :data:`stream` objects for duplication. This may be slow because such data are typically large. - * 0 = none - * 1 = images - * 2 = fonts - * 255 = all + :arg bool clean: Clean and sanitize content streams [#f1]_. Corresponds to "mutool clean -sc". - :arg bool linear: Save a linearised version of the document. This option creates a file format for improved performance for Internet access. Excludes "incremental". + :arg bool deflate: Deflate (compress) uncompressed streams. + :arg bool deflate_images: *(new in v1.18.3)* Deflate (compress) uncompressed image streams [#f4]_. + :arg bool deflate_fonts: *(new in v1.18.3)* Deflate (compress) uncompressed fontfile streams [#f4]_. - :arg bool pretty: Prettify the document source for better readability. PDF objects will be reformatted to look like the default output of :meth:`Document.xref_object`. + :arg bool incremental: Only save changes to the PDF. Excludes "garbage" and "linear". Can only be used if *outfile* is a string or a `pathlib.Path` and equal to :attr:`Document.name`. Cannot be used for files that are decrypted or repaired and also in some other cases. To be sure, check :meth:`Document.can_save_incrementally`. If this is false, saving to a new file is required. - :arg bool no_new_id: Suppress the update of the file's `/ID` field. If the file happens to have no such field at all, also suppress creation of a new one. Default is `False`, so every save will lead to an updated file identification. + :arg bool ascii: convert binary data to ASCII. - :arg int permissions: *(new in v1.16.0)* Set the desired permission levels. See :ref:`PermissionCodes` for possible values. Default is granting all. + :arg int expand: Decompress objects. Generates versions that can be better read by some other programs and will lead to larger files. - :arg int encryption: *(new in v1.16.0)* set the desired encryption method. See :ref:`EncryptionMethods` for possible values. + * 0 = none + * 1 = images + * 2 = fonts + * 255 = all - :arg str owner_pw: *(new in v1.16.0)* set the document's owner password. *(Changed in v1.18.3)* If not provided, the user password is taken if provided. The string length must not exceed 40 characters. + :arg bool linear: Save a linearised version of the document. This option creates a file format for improved performance for Internet access. Excludes "incremental". - :arg str user_pw: *(new in v1.16.0)* set the document's user password. The string length must not exceed 40 characters. + :arg bool pretty: Prettify the document source for better readability. PDF objects will be reformatted to look like the default output of :meth:`Document.xref_object`. - .. note:: The method does not check, whether a file of that name already exists, will hence not ask for confirmation, and overwrite the file. It is your responsibility as a programmer to handle this. + :arg bool no_new_id: Suppress the update of the file's `/ID` field. If the file happens to have no such field at all, also suppress creation of a new one. Default is `False`, so every save will lead to an updated file identification. - .. method:: ez_save(*args, **kwargs) + :arg int permissions: *(new in v1.16.0)* Set the desired permission levels. See :ref:`PermissionCodes` for possible values. Default is granting all. - * New in v1.18.11 + :arg int encryption: *(new in v1.16.0)* set the desired encryption method. See :ref:`EncryptionMethods` for possible values. - PDF only: The same as :meth:`Document.save` but with the changed defaults `deflate=True, garbage=3`. + :arg str owner_pw: *(new in v1.16.0)* set the document's owner password. *(Changed in v1.18.3)* If not provided, the user password is taken if provided. The string length must not exceed 40 characters. - .. method:: saveIncr() + :arg str user_pw: *(new in v1.16.0)* set the document's user password. The string length must not exceed 40 characters. - PDF only: saves the document incrementally. This is a convenience abbreviation for *doc.save(doc.name, incremental=True, encryption=PDF_ENCRYPT_KEEP)*. + .. warning:: The method does not check, whether a file of that name already exists, will hence not ask for confirmation, and overwrite the file. It is your responsibility as a programmer to handle this. .. note:: - Saving incrementally may be required if the document contains verified signatures which would be invalidated by saving to a new file. + **File size reduction** + 1. Use the adequate save options like `garbage=3` or `4`, `deflate=True`. Do not use "expand", "clean" or "incremental". + This is a "lossless" file size reduction. - .. method:: tobytes(garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None) + 2. "Lossy" file size reduction in essence must give up something with respect to images, like (a) remove all images (b) replace images by their grayscale versions (c) reduce image resolutions. - * Changed in v1.18.7 - * Changed in v1.19.0 + .. method:: ez_save(*args, **kwargs) - PDF only: Writes the **current content of the document** to a bytes object instead of to a file. Obviously, you should be wary about memory requirements. The meanings of the parameters exactly equal those in :meth:`save`. Chapter :ref:`FAQ` contains an example for using this method as a pre-processor to `pdfrw `_. + * New in v1.18.11 - *(Changed in v1.16.0)* for extended encryption support. + PDF only: The same as :meth:`Document.save` but with the changed defaults `deflate=True, garbage=3`. - :rtype: bytes - :returns: a bytes object containing the complete document. + .. method:: saveIncr() - .. method:: search_page_for(pno, text, quads=False) + PDF only: saves the document incrementally. This is a convenience abbreviation for *doc.save(doc.name, incremental=True, encryption=PDF_ENCRYPT_KEEP)*. - Search for "text" on page number "pno". Works exactly like the corresponding :meth:`Page.search_for`. Any integer `-∞ < pno < page_count` is acceptable. + .. note:: - .. index:: - pair: append; Document.insert_pdf - pair: join; Document.insert_pdf - pair: merge; Document.insert_pdf - pair: from_page; Document.insert_pdf - pair: to_page; Document.insert_pdf - pair: start_at; Document.insert_pdf - pair: rotate; Document.insert_pdf - pair: links; Document.insert_pdf - pair: annots; Document.insert_pdf - pair: show_progress; Document.insert_pdf + Saving incrementally may be required if the document contains verified signatures which would be invalidated by saving to a new file. - .. method:: insert_pdf(docsrc, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, show_progress=0, final=1) - * Changed in v1.19.3 - as a fix to issue `#537 `_, form fields are always excluded. + .. method:: tobytes(garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None) - 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*. Value -1 indicates default values. All pages thus copied will be rotated as specified. Links and annotations can be excluded in the target, see below. All page numbers are 0-based. + * Changed in v1.18.7 + * Changed in v1.19.0 - :arg docsrc: An opened PDF *Document* which must not be the current document. However, it may refer to the same underlying file. - :type docsrc: *Document* + PDF only: Writes the **current content of the document** to a bytes object instead of to a file. Obviously, you should be wary about memory requirements. The meanings of the parameters exactly equal those in :meth:`save`. Chapter :ref:`FAQ` contains an example for using this method as a pre-processor to `pdfrw `_. - :arg int from_page: First page number in *docsrc*. Default is zero. + *(Changed in v1.16.0)* for extended encryption support. - :arg int to_page: Last page number in *docsrc* to copy. Defaults to last page. + :rtype: bytes + :returns: a bytes object containing the complete document. - :arg int start_at: First copied page, will become page number *start_at* in the target. Default -1 appends the page range to the end. If zero, the page range will be inserted before current first page. + .. method:: search_page_for(pno, text, quads=False) - :arg int rotate: All copied pages will be rotated by the provided value (degrees, integer multiple of 90). + Search for "text" on page number "pno". Works exactly like the corresponding :meth:`Page.search_for`. Any integer `-∞ < pno < page_count` is acceptable. - :arg bool links: Choose whether (internal and external) links should be included in the copy. Default is *True*. Internal links to outside the copied page range are **always excluded**. - :arg bool annots: *(new in v1.16.1)* choose whether annotations should be included in the copy. *(Fixed in v1.19.3)* Form fields can never be copied. - :arg int show_progress: *(new in v1.17.7)* specify an interval size greater zero to see progress messages on `sys.stdout`. After each interval, a message like `Inserted 30 of 47 pages.` will be printed. - :arg int final: *(new in v1.18.0)* controls whether the list of already copied objects should be **dropped** after this method, default *True*. Set it to 0 except for the last one of multiple insertions from the same source PDF. This saves target file size and speeds up execution considerably. + .. index:: + pair: append; Document.insert_pdf + pair: join; Document.insert_pdf + pair: merge; Document.insert_pdf + pair: from_page; Document.insert_pdf + pair: to_page; Document.insert_pdf + pair: start_at; Document.insert_pdf + pair: rotate; Document.insert_pdf + pair: links; Document.insert_pdf + pair: annots; Document.insert_pdf + pair: show_progress; Document.insert_pdf - .. note:: + .. method:: insert_pdf(docsrc, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, show_progress=0, final=1) - 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. + * Changed in v1.19.3 - as a fix to issue `#537 `_, form fields are always excluded. - 2. *docsrc* TOC entries **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 `join.py `_ in the *examples* directory: it can join PDF documents and at the same time piece together respective parts of the tables of contents. + 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*. Value -1 indicates default values. All pages thus copied will be rotated as specified. Links and annotations can be excluded in the target, see below. All page numbers are 0-based. + :arg docsrc: An opened PDF *Document* which must not be the current document. However, it may refer to the same underlying file. + :type docsrc: *Document* - .. index:: - pair: append; Document.insert_file - pair: join; Document.insert_file - pair: merge; Document.insert_file - pair: from_page; Document.insert_file - pair: to_page; Document.insert_file - pair: start_at; Document.insert_file - pair: rotate; Document.insert_file - pair: links; Document.insert_file - pair: annots; Document.insert_file - pair: show_progress; Document.insert_file + :arg int from_page: First page number in *docsrc*. Default is zero. - .. method:: insert_file(infile, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, show_progress=0, final=1) + :arg int to_page: Last page number in *docsrc* to copy. Defaults to last page. - * New in v1.22.0 + :arg int start_at: First copied page, will become page number *start_at* in the target. Default -1 appends the page range to the end. If zero, the page range will be inserted before current first page. - PDF only: Add an arbitrary supported document to the current PDF. Opens "infile" as a document, converts it to a PDF and then invokes :meth:`Document.insert_pdf`. Parameters are the same as for that method. Among other things, this features an easy way to append images as full pages to an output PDF. + :arg int rotate: All copied pages will be rotated by the provided value (degrees, integer multiple of 90). - :arg multiple infile: the input document to insert. May be a filename specification as is valid for creating a :ref:`Document` or a :ref:`Pixmap`. + :arg bool links: Choose whether (internal and external) links should be included in the copy. Default is *True*. Internal links to outside the copied page range are **always excluded**. + :arg bool annots: *(new in v1.16.1)* choose whether annotations should be included in the copy. *(Fixed in v1.19.3)* Form fields can never be copied. + :arg int show_progress: *(new in v1.17.7)* specify an interval size greater zero to see progress messages on `sys.stdout`. After each interval, a message like `Inserted 30 of 47 pages.` will be printed. + :arg int final: *(new in v1.18.0)* controls whether the list of already copied objects should be **dropped** after this method, default *True*. Set it to 0 except for the last one of multiple insertions from the same source PDF. This saves target file size and speeds up execution considerably. + .. note:: - .. index:: - pair: width; Document.new_page - pair: height; Document.new_page + 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. - .. method:: new_page(pno=-1, width=595, height=842) + 2. *docsrc* TOC entries **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 `join.py `_ in the *examples* directory: it can join PDF documents and at the same time piece together respective parts of the tables of contents. - PDF only: Insert an empty page. - :arg int pno: page number in front of which the new page should be inserted. Must be in *1 < pno <= page_count*. Special values -1 and *doc.page_count* insert **after** the last page. + .. index:: + pair: append; Document.insert_file + pair: join; Document.insert_file + pair: merge; Document.insert_file + pair: from_page; Document.insert_file + pair: to_page; Document.insert_file + pair: start_at; Document.insert_file + pair: rotate; Document.insert_file + pair: links; Document.insert_file + pair: annots; Document.insert_file + pair: show_progress; Document.insert_file - :arg float width: page width. - :arg float height: page height. + .. method:: insert_file(infile, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, show_progress=0, final=1) - :rtype: :ref:`Page` - :returns: the created page object. + * New in v1.22.0 - .. index:: - pair: fontsize; Document.insert_page - pair: width; Document.insert_page - pair: height; Document.insert_page - pair: fontname; Document.insert_page - pair: fontfile; Document.insert_page - pair: color; Document.insert_page + PDF only: Add an arbitrary supported document to the current PDF. Opens "infile" as a document, converts it to a PDF and then invokes :meth:`Document.insert_pdf`. Parameters are the same as for that method. Among other things, this features an easy way to append images as full pages to an output PDF. - .. method:: insert_page(pno, text=None, fontsize=11, width=595, height=842, fontname="helv", fontfile=None, color=None) + :arg multiple infile: the input document to insert. May be a filename specification as is valid for creating a :ref:`Document` or a :ref:`Pixmap`. - PDF only: Insert a new page and insert some text. Convenience function which combines :meth:`Document.new_page` and (parts of) :meth:`Page.insert_text`. - :arg int pno: page number (0-based) **in front of which** to insert. Must be in `range(-1, doc.page_count + 1)`. Special values -1 and `doc.page_count` insert **after** the last page. + .. index:: + pair: width; Document.new_page + pair: height; Document.new_page - Changed in v1.14.12 - This is now a positional parameter + .. method:: new_page(pno=-1, width=595, height=842) - For the other parameters, please consult the aforementioned methods. + PDF only: Insert an empty page. - :rtype: int - :returns: the result of :meth:`Page.insert_text` (number of successfully inserted lines). + :arg int pno: page number in front of which the new page should be inserted. Must be in *1 < pno <= page_count*. Special values -1 and *doc.page_count* insert **after** the last page. - .. method:: delete_page(pno=-1) + :arg float width: page width. + :arg float height: page height. - PDF only: Delete a page given by its 0-based number in `-∞ < pno < page_count - 1`. + :rtype: :ref:`Page` + :returns: the created page object. - * Changed in v1.18.14: support Python's `del` statement. + .. index:: + pair: fontsize; Document.insert_page + pair: width; Document.insert_page + pair: height; Document.insert_page + pair: fontname; Document.insert_page + pair: fontfile; Document.insert_page + pair: color; Document.insert_page - :arg int pno: the page to be deleted. Negative number count backwards from the end of the document (like with indices). Default is the last page. + .. method:: insert_page(pno, text=None, fontsize=11, width=595, height=842, fontname="helv", fontfile=None, color=None) - .. method:: delete_pages(*args, **kwds) + PDF only: Insert a new page and insert some text. Convenience function which combines :meth:`Document.new_page` and (parts of) :meth:`Page.insert_text`. - * Changed in v1.18.13: more flexibility specifying pages to delete. - * Changed in v1.18.14: support Python's `del` statement. + :arg int pno: page number (0-based) **in front of which** to insert. Must be in `range(-1, doc.page_count + 1)`. Special values -1 and `doc.page_count` insert **after** the last page. - PDF only: Delete multiple pages given as 0-based numbers. + Changed in v1.14.12 + This is now a positional parameter - **Format 1:** Use keywords. Represents the old format. A contiguous range of pages is removed. - * "from_page": first page to delete. Zero if omitted. - * "to_page": last page to delete. Last page in document if omitted. Must not be less then "from_page". + For the other parameters, please consult the aforementioned methods. - **Format 2:** Two page numbers as positional parameters. Handled like Format 1. + :rtype: int + :returns: the result of :meth:`Page.insert_text` (number of successfully inserted lines). - **Format 3:** One positional integer parameter. Equivalent to :meth:`Page.delete_page`. + .. method:: delete_page(pno=-1) - **Format 4:** One positional parameter of type *list*, *tuple* or *range()* of page numbers. The items of this sequence may be in any order and may contain duplicates. + PDF only: Delete a page given by its 0-based number in `-∞ < pno < page_count - 1`. - **Format 5:** *(New in v1.18.14)* Using the Python `del` statement and index / slice notation is now possible. + * Changed in v1.18.14: support Python's `del` statement. - .. note:: + :arg int pno: the page to be deleted. Negative number count backwards from the end of the document (like with indices). Default is the last page. - *(Changed in v1.14.17, optimized in v1.17.7)* In an effort to maintain a valid PDF structure, this method and :meth:`delete_page` will also deactivate items in the table of contents which point to deleted pages. "Deactivation" here means, that the bookmark will point to nowhere and the title will be shown grayed-out by supporting PDF viewers. The overall TOC structure is left intact. + .. method:: delete_pages(*args, **kwds) - It will also remove any **links on remaining pages** which point to a deleted one. This action may have an extended response time for documents with many pages. + * Changed in v1.18.13: more flexibility specifying pages to delete. + * Changed in v1.18.14: support Python's `del` statement. - Following examples will all delete pages 500 through 519: - - * `doc.delete_pages(500, 519)` - * `doc.delete_pages(from_page=500, to_page=519)` - * `doc.delete_pages((500, 501, 502, ... , 519))` - * `doc.delete_pages(range(500, 520))` - * `del doc[500:520]` - * `del doc[(500, 501, 502, ... , 519)]` - * `del doc[range(500, 520)]` + PDF only: Delete multiple pages given as 0-based numbers. - For the :ref:`AdobeManual` the above takes about 0.6 seconds, because the remaining 1290 pages must be cleaned from invalid links. + **Format 1:** Use keywords. Represents the old format. A contiguous range of pages is removed. + * "from_page": first page to delete. Zero if omitted. + * "to_page": last page to delete. Last page in document if omitted. Must not be less then "from_page". - In general, the performance of this method is dependent on the number of remaining pages -- **not** on the number of deleted pages: in the above example, **deleting all pages except** those 20, will need much less time. + **Format 2:** Two page numbers as positional parameters. Handled like Format 1. + **Format 3:** One positional integer parameter. Equivalent to :meth:`Page.delete_page`. - .. method:: copy_page(pno, to=-1) + **Format 4:** One positional parameter of type *list*, *tuple* or *range()* of page numbers. The items of this sequence may be in any order and may contain duplicates. - PDF only: Copy a page reference within the document. + **Format 5:** *(New in v1.18.14)* Using the Python `del` statement and index / slice notation is now possible. - :arg int pno: the page to be copied. Must be in range `0 <= pno < page_count`. + .. note:: - :arg int to: the page number in front of which to copy. The default inserts **after** the last page. + *(Changed in v1.14.17, optimized in v1.17.7)* In an effort to maintain a valid PDF structure, this method and :meth:`delete_page` will also deactivate items in the table of contents which point to deleted pages. "Deactivation" here means, that the bookmark will point to nowhere and the title will be shown grayed-out by supporting PDF viewers. The overall TOC structure is left intact. - .. note:: Only a new **reference** to the page object will be created -- not a new page object, all copied pages will have identical attribute values, including the :attr:`Page.xref`. This implies that any changes to one of these copies will appear on all of them. + It will also remove any **links on remaining pages** which point to a deleted one. This action may have an extended response time for documents with many pages. - .. method:: fullcopy_page(pno, to=-1) + Following examples will all delete pages 500 through 519: - * New in v1.14.17 + * `doc.delete_pages(500, 519)` + * `doc.delete_pages(from_page=500, to_page=519)` + * `doc.delete_pages((500, 501, 502, ... , 519))` + * `doc.delete_pages(range(500, 520))` + * `del doc[500:520]` + * `del doc[(500, 501, 502, ... , 519)]` + * `del doc[range(500, 520)]` - PDF only: Make a full copy (duplicate) of a page. + For the :ref:`AdobeManual` the above takes about 0.6 seconds, because the remaining 1290 pages must be cleaned from invalid links. - :arg int pno: the page to be duplicated. Must be in range `0 <= pno < page_count`. + In general, the performance of this method is dependent on the number of remaining pages -- **not** on the number of deleted pages: in the above example, **deleting all pages except** those 20, will need much less time. - :arg int to: the page number in front of which to copy. The default inserts **after** the last page. - .. note:: + .. method:: copy_page(pno, to=-1) - * In contrast to :meth:`copy_page`, this method creates a new page object (with a new :data:`xref`), which can be changed independently from the original. + PDF only: Copy a page reference within the document. - * Any Popup and "IRT" ("in response to") annotations are **not copied** to avoid potentially incorrect situations. + :arg int pno: the page to be copied. Must be in range `0 <= pno < page_count`. - .. method:: move_page(pno, to=-1) + :arg int to: the page number in front of which to copy. The default inserts **after** the last page. - PDF only: Move (copy and then delete original) a page within the document. + .. note:: Only a new **reference** to the page object will be created -- not a new page object, all copied pages will have identical attribute values, including the :attr:`Page.xref`. This implies that any changes to one of these copies will appear on all of them. - :arg int pno: the page to be moved. Must be in range `0 <= pno < page_count`. + .. method:: fullcopy_page(pno, to=-1) - :arg int to: the page number in front of which to insert the moved page. The default moves **after** the last page. + * New in v1.14.17 + PDF only: Make a full copy (duplicate) of a page. - .. method:: need_appearances(value=None) + :arg int pno: the page to be duplicated. Must be in range `0 <= pno < page_count`. - * New in v1.17.4 + :arg int to: the page number in front of which to copy. The default inserts **after** the last page. - PDF only: Get or set the */NeedAppearances* property of Form PDFs. Quote: *"(Optional) A flag specifying whether to construct appearance streams and appearance dictionaries for all widget annotations in the document ... Default value: false."* This may help controlling the behavior of some readers / viewers. + .. note:: - :arg bool value: set the property to this value. If omitted or `None`, inquire the current value. + * In contrast to :meth:`copy_page`, this method creates a new page object (with a new :data:`xref`), which can be changed independently from the original. - :rtype: bool - :returns: - * None: not a Form PDF, or property not defined. - * True / False: the value of the property (either just set or existing for inquiries). Has no effect if no Form PDF. + * Any Popup and "IRT" ("in response to") annotations are **not copied** to avoid potentially incorrect situations. + .. method:: move_page(pno, to=-1) + PDF only: Move (copy and then delete original) a page within the document. - .. method:: get_sigflags() + :arg int pno: the page to be moved. Must be in range `0 <= pno < page_count`. - PDF only: Return whether the document contains signature fields. This is an optional PDF property: if not present (return value -1), no conclusions can be drawn -- the PDF creator may just not have bothered using it. + :arg int to: the page number in front of which to insert the moved page. The default moves **after** the last page. - :rtype: int - :returns: - * -1: not a Form PDF / no signature fields recorded / no *SigFlags* found. - * 1: at least one signature field exists. - * 3: contains signatures that may be invalidated if the file is saved (written) in a way that alters its previous contents, as opposed to an incremental update. - .. index:: - pair: filename; Document.embfile_add - pair: ufilename; Document.embfile_add - pair: desc; Document.embfile_add + .. method:: need_appearances(value=None) - .. method:: embfile_add(name, buffer, filename=None, ufilename=None, desc=None) + * New in v1.17.4 - * Changed in v1.14.16: The sequence of positional parameters "name" and "buffer" has been changed to comply with the call pattern of other functions. + PDF only: Get or set the */NeedAppearances* property of Form PDFs. Quote: *"(Optional) A flag specifying whether to construct appearance streams and appearance dictionaries for all widget annotations in the document ... Default value: false."* This may help controlling the behavior of some readers / viewers. - 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). + :arg bool value: set the property to this value. If omitted or `None`, inquire the current value. - :arg str name: entry identifier, **must not already exist**. - :arg bytes,bytearray,BytesIO buffer: file contents. + :rtype: bool + :returns: + * None: not a Form PDF, or property not defined. + * True / False: the value of the property (either just set or existing for inquiries). Has no effect if no Form PDF. - *(Changed in v1.14.13)* *io.BytesIO* is now also supported. - :arg str filename: optional filename. Documentation only, will be set to *name* if `None`. - :arg str ufilename: optional unicode filename. Documentation only, will be set to *filename* if `None`. - :arg str desc: optional description. Documentation only, will be set to *name* if `None`. - :rtype: int - :returns: *(Changed in v1.18.13)* The method now returns the :data:`xref` of the inserted file. In addition, the file object now will be automatically given the PDF keys `/CreationDate` and `/ModDate` based on the current date-time. + .. method:: get_sigflags() + PDF only: Return whether the document contains signature fields. This is an optional PDF property: if not present (return value -1), no conclusions can be drawn -- the PDF creator may just not have bothered using it. - .. method:: embfile_count() + :rtype: int + :returns: + * -1: not a Form PDF / no signature fields recorded / no *SigFlags* found. + * 1: at least one signature field exists. + * 3: contains signatures that may be invalidated if the file is saved (written) in a way that alters its previous contents, as opposed to an incremental update. - * Changed in v1.14.16: This is now a method. In previous versions, this was a property. + .. index:: + pair: filename; Document.embfile_add + pair: ufilename; Document.embfile_add + pair: desc; Document.embfile_add - PDF only: Return the number of embedded files. + .. method:: embfile_add(name, buffer, filename=None, ufilename=None, desc=None) - .. method:: embfile_get(item) + * Changed in v1.14.16: The sequence of positional parameters "name" and "buffer" has been changed to comply with the call pattern of other functions. - 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. + 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). - :arg int,str item: index or name of entry. An integer must be in `range(embfile_count())`. + :arg str name: entry identifier, **must not already exist**. + :arg bytes,bytearray,BytesIO buffer: file contents. - :rtype: bytes + *(Changed in v1.14.13)* *io.BytesIO* is now also supported. - .. method:: embfile_del(item) + :arg str filename: optional filename. Documentation only, will be set to *name* if `None`. + :arg str ufilename: optional unicode filename. Documentation only, will be set to *filename* if `None`. + :arg str desc: optional description. Documentation only, will be set to *name* if `None`. - * Changed in v1.14.16: Items can now be deleted by index, too. + :rtype: int + :returns: *(Changed in v1.18.13)* The method now returns the :data:`xref` of the inserted file. In addition, the file object now will be automatically given the PDF keys `/CreationDate` and `/ModDate` based on the current date-time. - PDF only: Remove an entry from `/EmbeddedFiles`. As always, physical deletion of the embedded file content (and file space regain) will occur only when the document is saved to a new file with a suitable garbage option. - :arg int/str item: index or name of entry. + .. method:: embfile_count() - .. warning:: When specifying an entry name, this function will only **delete the first item** with that name. Be aware that PDFs not created with PyMuPDF may contain duplicate names. So you may want to take appropriate precautions. + * Changed in v1.14.16: This is now a method. In previous versions, this was a property. - .. method:: embfile_info(item) + PDF only: Return the number of embedded files. - * Changed in v1.18.13 + .. method:: embfile_get(item) - PDF only: Retrieve information of an embedded file given by its number or by its name. + 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. - :arg int/str item: index or name of entry. An integer must be in `range(embfile_count())`. + :arg int,str item: index or name of entry. An integer must be in `range(embfile_count())`. - :rtype: dict - :returns: a dictionary with the following keys: + :rtype: bytes - * *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 - * *creationDate* -- *(New in v1.18.13)* (*str*) date-time of item creation in PDF format - * *modDate* -- *(New in v1.18.13)* (*str*) date-time of last change in PDF format - * *collection* -- *(New in v1.18.13)* (*int*) :data:`xref` of the associated PDF portfolio item if any, else zero. - * *checksum* -- *(New in v1.18.13)* (*str*) a hashcode of the stored file content as a hexadecimal string. Should be MD5 according to PDF specifications, but be prepared to see other hashing algorithms. + .. method:: embfile_del(item) - .. method:: embfile_names() + * Changed in v1.14.16: Items can now be deleted by index, too. - * New in v1.14.16 + PDF only: Remove an entry from `/EmbeddedFiles`. As always, physical deletion of the embedded file content (and file space regain) will occur only when the document is saved to a new file with a suitable garbage option. - PDF only: Return a list of embedded file names. The sequence of the names equals the physical sequence in the document. + :arg int/str item: index or name of entry. - :rtype: list + .. warning:: When specifying an entry name, this function will only **delete the first item** with that name. Be aware that PDFs not created with PyMuPDF may contain duplicate names. So you may want to take appropriate precautions. - .. index:: - pair: filename; Document.embfile_upd - pair: ufilename; Document.embfile_upd - pair: desc; Document.embfile_upd + .. method:: embfile_info(item) - .. method:: embfile_upd(item, buffer=None, filename=None, ufilename=None, desc=None) + * Changed in v1.18.13 - PDF only: Change an embedded file given its entry number or name. All parameters are optional. Letting them default leads to a no-operation. + PDF only: Retrieve information of an embedded file given by its number or by its name. - :arg int/str item: index or name of entry. An integer must be in `range(embfile_count())`. - :arg bytes,bytearray,BytesIO buffer: the new file content. + :arg int/str item: index or name of entry. An integer must be in `range(embfile_count())`. - *(Changed in v1.14.13)* *io.BytesIO* is now also supported. + :rtype: dict + :returns: a dictionary with the following keys: - :arg str filename: the new filename. - :arg str ufilename: the new unicode filename. - :arg str desc: the new description. + * *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 + * *creationDate* -- *(New in v1.18.13)* (*str*) date-time of item creation in PDF format + * *modDate* -- *(New in v1.18.13)* (*str*) date-time of last change in PDF format + * *collection* -- *(New in v1.18.13)* (*int*) :data:`xref` of the associated PDF portfolio item if any, else zero. + * *checksum* -- *(New in v1.18.13)* (*str*) a hashcode of the stored file content as a hexadecimal string. Should be MD5 according to PDF specifications, but be prepared to see other hashing algorithms. - *(Changed in v1.18.13)* The method now returns the :data:`xref` of the file object. + .. method:: embfile_names() - :rtype: int - :returns: xref of the file object. Automatically, its `/ModDate` PDF key will be updated with the current date-time. + * New in v1.14.16 + PDF only: Return a list of embedded file names. The sequence of the names equals the physical sequence in the document. - .. method:: close() + :rtype: list - Release objects and space allocations associated with the document. If created from a file, also closes *filename* (releasing control to the OS). Explicitly closing a document is equivalent to deleting it, `del doc`, or assigning it to something else like `doc = None`. + .. index:: + pair: filename; Document.embfile_upd + pair: ufilename; Document.embfile_upd + pair: desc; Document.embfile_upd - .. method:: xref_object(xref, compressed=False, ascii=False) + .. method:: embfile_upd(item, buffer=None, filename=None, ufilename=None, desc=None) - * New in v1.16.8 - * Changed in v1.18.10 + PDF only: Change an embedded file given its entry number or name. All parameters are optional. Letting them default leads to a no-operation. - PDF only: Return the definition source of a PDF object. + :arg int/str item: index or name of entry. An integer must be in `range(embfile_count())`. + :arg bytes,bytearray,BytesIO buffer: the new file content. - :arg int xref: the object's :data:`xref`. *Changed in v1.18.10:* A value of `-1` returns the PDF trailer source. - :arg bool compressed: whether to generate a compact output with no line breaks or spaces. - :arg bool ascii: whether to ASCII-encode binary data. + *(Changed in v1.14.13)* *io.BytesIO* is now also supported. - :rtype: str - :returns: The object definition source. + :arg str filename: the new filename. + :arg str ufilename: the new unicode filename. + :arg str desc: the new description. - .. method:: pdf_catalog() + *(Changed in v1.18.13)* The method now returns the :data:`xref` of the file object. - * New in v1.16.8 + :rtype: int + :returns: xref of the file object. Automatically, its `/ModDate` PDF key will be updated with the current date-time. - PDF only: Return the :data:`xref` number of the PDF catalog (or root) object. Use that number with :meth:`Document.xref_object` to see its source. + .. method:: close() - .. method:: pdf_trailer(compressed=False) + Release objects and space allocations associated with the document. If created from a file, also closes *filename* (releasing control to the OS). Explicitly closing a document is equivalent to deleting it, `del doc`, or assigning it to something else like `doc = None`. - * New in v1.16.8 + .. method:: xref_object(xref, compressed=False, ascii=False) - PDF only: Return the trailer source of the PDF, which is usually located at the PDF file's end. This is :meth:`Document.xref_object` with an *xref* argument of -1. + * New in v1.16.8 + * Changed in v1.18.10 + PDF only: Return the definition source of a PDF object. - .. method:: xref_stream(xref) + :arg int xref: the object's :data:`xref`. *Changed in v1.18.10:* A value of `-1` returns the PDF trailer source. + :arg bool compressed: whether to generate a compact output with no line breaks or spaces. + :arg bool ascii: whether to ASCII-encode binary data. - * New in v1.16.8 + :rtype: str + :returns: The object definition source. - PDF only: Return the **decompressed** contents of the :data:`xref` stream object. + .. method:: pdf_catalog() - :arg int xref: :data:`xref` number. + * New in v1.16.8 - :rtype: bytes - :returns: the (decompressed) stream of the object. + PDF only: Return the :data:`xref` number of the PDF catalog (or root) object. Use that number with :meth:`Document.xref_object` to see its source. - .. method:: xref_stream_raw(xref) - * New in v1.16.8 + .. method:: pdf_trailer(compressed=False) - PDF only: Return the **unmodified** (esp. **not decompressed**) contents of the :data:`xref` stream object. Otherwise equal to :meth:`Document.xref_stream`. + * New in v1.16.8 - :rtype: bytes - :returns: the (original, unmodified) stream of the object. + PDF only: Return the trailer source of the PDF, which is usually located at the PDF file's end. This is :meth:`Document.xref_object` with an *xref* argument of -1. - .. method:: update_object(xref, obj_str, page=None) - * New in v1.16.8 + .. method:: xref_stream(xref) - PDF only: Replace object definition of :data:`xref` with the provided string. The xref may also be new, in which case this instruction completes the object definition. If a page object is also given, its links and annotations will be reloaded afterwards. + * New in v1.16.8 - :arg int xref: :data:`xref` number. + PDF only: Return the **decompressed** contents of the :data:`xref` stream object. - :arg str obj_str: a string containing a valid PDF object definition. + :arg int xref: :data:`xref` number. - :arg page: a page object. If provided, indicates, that annotations of this page should be refreshed (reloaded) to reflect changes incurred with links and / or annotations. - :type page: :ref:`Page` + :rtype: bytes + :returns: the (decompressed) stream of the object. - :rtype: int - :returns: zero if successful, otherwise an exception will be raised. + .. method:: xref_stream_raw(xref) + * New in v1.16.8 - .. method:: update_stream(xref, data, new=False, compress=True) + PDF only: Return the **unmodified** (esp. **not decompressed**) contents of the :data:`xref` stream object. Otherwise equal to :meth:`Document.xref_stream`. - * New in v.1.16.8 - * Changed in v1.19.2: added parameter "compress" - * Changed in v1.19.6: deprecated parameter "new". Now confirms that the object is a PDF dictionary object. + :rtype: bytes + :returns: the (original, unmodified) stream of the object. - Replace the stream of an object identified by *xref*, which must be a PDF dictionary. If the object is no :data:`stream`, it will be turned into one. The function automatically performs a compress operation ("deflate") where beneficial. + .. method:: update_object(xref, obj_str, page=None) - :arg int xref: :data:`xref` number. + * New in v1.16.8 - :arg bytes|bytearray|BytesIO stream: the new content of the stream. + PDF only: Replace object definition of :data:`xref` with the provided string. The xref may also be new, in which case this instruction completes the object definition. If a page object is also given, its links and annotations will be reloaded afterwards. - *(Changed in v1.14.13:)* *io.BytesIO* objects are now also supported. + :arg int xref: :data:`xref` number. - :arg bool new: *deprecated* and ignored. Will be removed some time after v1.20.0. - :arg bool compress: whether to compress the inserted stream. If `True` (default), the stream will be inserted using `/FlateDecode` compression (if beneficial), otherwise the stream will inserted as is. + :arg str obj_str: a string containing a valid PDF object definition. - :raises ValueError: if *xref* does not represent a PDF :data:`dict`. An empty dictionary ``<<>>`` is accepted. So if you just created the xref and want to give it a stream, first execute `doc.update_object(xref, "<<>>")`, and then insert the stream data with this method. + :arg page: a page object. If provided, indicates, that annotations of this page should be refreshed (reloaded) to reflect changes incurred with links and / or annotations. + :type page: :ref:`Page` - The method is primarily (but not exclusively) intended to manipulate streams containing PDF operator syntax (see pp. 643 of the :ref:`AdobeManual`) as it is the case for e.g. page content streams. + :rtype: int + :returns: zero if successful, otherwise an exception will be raised. - If you update a contents stream, consider using save parameter *clean=True* to ensure consistency between PDF operator source and the object structure. - Example: Let us assume that you no longer want a certain image appear on a page. This can be achieved by deleting the respective reference in its contents source(s) -- and indeed: the image will be gone after reloading the page. But the page's :data:`resources` object would still show the image as being referenced by the page. This save option will clean up any such mismatches. + .. method:: update_stream(xref, data, new=False, compress=True) + * New in v.1.16.8 + * Changed in v1.19.2: added parameter "compress" + * Changed in v1.19.6: deprecated parameter "new". Now confirms that the object is a PDF dictionary object. - .. method:: Document.xref_copy(source, target, *, keep=None) + Replace the stream of an object identified by *xref*, which must be a PDF dictionary. If the object is no :data:`stream`, it will be turned into one. The function automatically performs a compress operation ("deflate") where beneficial. - * New in v1.19.5 + :arg int xref: :data:`xref` number. - PDF Only: Make *target* xref an exact copy of *source*. If *source* is a :data:`stream`, then these data are also copied. + :arg bytes|bytearray|BytesIO stream: the new content of the stream. - :arg int source: the source :data:`xref`. It must be an existing **dictionary** object. - :arg int target: the target xref. Must be an existing **dictionary** object. If the xref has just been created, make sure to initialize it as a PDF dictionary with the minimum specification ``<<>>``. - :arg list keep: an optional list of top-level keys in *target*, that should not be removed in preparation of the copy process. + *(Changed in v1.14.13:)* *io.BytesIO* objects are now also supported. - .. note:: + :arg bool new: *deprecated* and ignored. Will be removed some time after v1.20.0. + :arg bool compress: whether to compress the inserted stream. If `True` (default), the stream will be inserted using `/FlateDecode` compression (if beneficial), otherwise the stream will inserted as is. - * This method has much in common with Python's *dict* method `copy()`. - * Both xref numbers must represent existing dictionaries. - * Before data is copied from *source*, all *target* dictionary keys are deleted. You can specify exceptions from this in the *keep* list. If *source* however has a same-named key, its value will still replace the target. - * If *source* is a :data:`stream` object, then these data will also be copied over, and *target* will be converted to a stream object. - * A typical use case is to replace or remove an existing image without using redaction annotations. Example scripts can be seen `here `_. + :raises ValueError: if *xref* does not represent a PDF :data:`dict`. An empty dictionary ``<<>>`` is accepted. So if you just created the xref and want to give it a stream, first execute `doc.update_object(xref, "<<>>")`, and then insert the stream data with this method. - .. method:: Document.extract_image(xref) + The method is primarily (but not exclusively) intended to manipulate streams containing PDF operator syntax (see pp. 643 of the :ref:`AdobeManual`) as it is the case for e.g. page content streams. - PDF Only: Extract data and meta information of an image stored in the document. The output can directly be used to be stored as an image file, as input for PIL, :ref:`Pixmap` creation, etc. This method avoids using pixmaps wherever possible to present the image in its original format (e.g. as JPEG). + If you update a contents stream, consider using save parameter *clean=True* to ensure consistency between PDF operator source and the object structure. - :arg int xref: :data:`xref` of an image object. If this is not in `range(1, doc.xref_length())`, or the object is no image or other errors occur, `None` is returned and no exception is raised. + Example: Let us assume that you no longer want a certain image appear on a page. This can be achieved by deleting the respective reference in its contents source(s) -- and indeed: the image will be gone after reloading the page. But the page's :data:`resources` object would still show the image as being referenced by the page. This save option will clean up any such mismatches. - :rtype: dict - :returns: a dictionary with the following keys - * *ext* (*str*) image type (e.g. *'jpeg'*), usable as image file extension - * *smask* (*int*) :data:`xref` number of a stencil (/SMask) image or zero - * *width* (*int*) image width - * *height* (*int*) image height - * *colorspace* (*int*) the image's *colorspace.n* number. - * *cs-name* (*str*) the image's *colorspace.name*. - * *xres* (*int*) resolution in x direction. Please also see :data:`resolution`. - * *yres* (*int*) resolution in y direction. Please also see :data:`resolution`. - * *image* (*bytes*) image data, usable as image file content + .. method:: Document.xref_copy(source, target, *, keep=None) - >>> d = doc.extract_image(1373) - >>> d - {'ext': 'png', 'smask': 2934, 'width': 5, 'height': 629, 'colorspace': 3, 'xres': 96, - 'yres': 96, 'cs-name': 'DeviceRGB', - 'image': b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x05\ ...'} - >>> imgout = open(f"image.{d['ext']}", "wb") - >>> imgout.write(d["image"]) - 102 - >>> imgout.close() + * New in v1.19.5 - .. note:: There is a functional overlap with *pix = fitz.Pixmap(doc, xref)*, followed by a *pix.tobytes()*. Main differences are that extract_image, **(1)** does not always deliver PNG image formats, **(2)** is **very** much faster with non-PNG images, **(3)** usually results in much less disk storage for extracted images, **(4)** returns `None` in error cases (generates no exception). Look at the following example images within the same PDF. + PDF Only: Make *target* xref an exact copy of *source*. If *source* is a :data:`stream`, then these data are also copied. - * xref 1268 is a PNG -- Comparable execution time and identical output:: + :arg int source: the source :data:`xref`. It must be an existing **dictionary** object. + :arg int target: the target xref. Must be an existing **dictionary** object. If the xref has just been created, make sure to initialize it as a PDF dictionary with the minimum specification ``<<>>``. + :arg list keep: an optional list of top-level keys in *target*, that should not be removed in preparation of the copy process. - In [23]: %timeit pix = fitz.Pixmap(doc, 1268);pix.tobytes() - 10.8 ms ± 52.4 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) - In [24]: len(pix.tobytes()) - Out[24]: 21462 + .. note:: - In [25]: %timeit img = doc.extract_image(1268) - 10.8 ms ± 86 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) - In [26]: len(img["image"]) - Out[26]: 21462 + * This method has much in common with Python's *dict* method `copy()`. + * Both xref numbers must represent existing dictionaries. + * Before data is copied from *source*, all *target* dictionary keys are deleted. You can specify exceptions from this in the *keep* list. If *source* however has a same-named key, its value will still replace the target. + * If *source* is a :data:`stream` object, then these data will also be copied over, and *target* will be converted to a stream object. + * A typical use case is to replace or remove an existing image without using redaction annotations. Example scripts can be seen `here `_. - * xref 1186 is a JPEG -- :meth:`Document.extract_image` is **many times faster** and produces a **much smaller** output (2.48 MB vs. 0.35 MB):: + .. method:: Document.extract_image(xref) - In [27]: %timeit pix = fitz.Pixmap(doc, 1186);pix.tobytes() - 341 ms ± 2.86 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) - In [28]: len(pix.tobytes()) - Out[28]: 2599433 + PDF Only: Extract data and meta information of an image stored in the document. The output can directly be used to be stored as an image file, as input for PIL, :ref:`Pixmap` creation, etc. This method avoids using pixmaps wherever possible to present the image in its original format (e.g. as JPEG). - In [29]: %timeit img = doc.extract_image(1186) - 15.7 µs ± 116 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each) - In [30]: len(img["image"]) - Out[30]: 371177 + :arg int xref: :data:`xref` of an image object. If this is not in `range(1, doc.xref_length())`, or the object is no image or other errors occur, `None` is returned and no exception is raised. + :rtype: dict + :returns: a dictionary with the following keys - .. method:: Document.extract_font(xref, info_only=False, named=None) + * *ext* (*str*) image type (e.g. *'jpeg'*), usable as image file extension + * *smask* (*int*) :data:`xref` number of a stencil (/SMask) image or zero + * *width* (*int*) image width + * *height* (*int*) image height + * *colorspace* (*int*) the image's *colorspace.n* number. + * *cs-name* (*str*) the image's *colorspace.name*. + * *xres* (*int*) resolution in x direction. Please also see :data:`resolution`. + * *yres* (*int*) resolution in y direction. Please also see :data:`resolution`. + * *image* (*bytes*) image data, usable as image file content - * Changed in v1.19.4: return a dictionary if `named == True`. + >>> d = doc.extract_image(1373) + >>> d + {'ext': 'png', 'smask': 2934, 'width': 5, 'height': 629, 'colorspace': 3, 'xres': 96, + 'yres': 96, 'cs-name': 'DeviceRGB', + 'image': b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x05\ ...'} + >>> imgout = open(f"image.{d['ext']}", "wb") + >>> imgout.write(d["image"]) + 102 + >>> imgout.close() - PDF Only: Return an embedded font file's data and appropriate file extension. This can be used to store the font as an external file. The method does not throw exceptions (other than via checking for PDF and valid :data:`xref`). + .. note:: There is a functional overlap with *pix = fitz.Pixmap(doc, xref)*, followed by a *pix.tobytes()*. Main differences are that extract_image, **(1)** does not always deliver PNG image formats, **(2)** is **very** much faster with non-PNG images, **(3)** usually results in much less disk storage for extracted images, **(4)** returns `None` in error cases (generates no exception). Look at the following example images within the same PDF. - :arg int xref: PDF object number of the font to extract. - :arg bool info_only: only return font information, not the buffer. To be used for information-only purposes, avoids allocation of large buffer areas. - :arg bool named: If true, a dictionary with the following keys is returned: 'name' (font base name), 'ext' (font file extension), 'type' (font type), 'content' (font file content). + * xref 1268 is a PNG -- Comparable execution time and identical output:: - :rtype: tuple,dict - :returns: a tuple `(basename, ext, type, content)`, where *ext* is a 3-byte suggested file extension (*str*), *basename* is the font's name (*str*), *type* is the font's type (e.g. "Type1") and *content* is a bytes object containing the font file's content (or *b""*). For possible extension values and their meaning see :ref:`FontExtensions`. Return details on error: + In [23]: %timeit pix = fitz.Pixmap(doc, 1268);pix.tobytes() + 10.8 ms ± 52.4 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) + In [24]: len(pix.tobytes()) + Out[24]: 21462 - * `("", "", "", b"")` -- invalid xref or xref is not a (valid) font object. - * `(basename, "n/a", "Type1", b"")` -- *basename* is not embedded and thus cannot be extracted. This is the case for e.g. the :ref:`Base-14-Fonts` and Type 3 fonts. + In [25]: %timeit img = doc.extract_image(1268) + 10.8 ms ± 86 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) + In [26]: len(img["image"]) + Out[26]: 21462 - Example: + * xref 1186 is a JPEG -- :meth:`Document.extract_image` is **many times faster** and produces a **much smaller** output (2.48 MB vs. 0.35 MB):: - >>> # store font as an external file - >>> name, ext, _, content = doc.extract_font(4711) - >>> # assuming content is not None: - >>> ofile = open(name + "." + ext, "wb") - >>> ofile.write(content) - >>> ofile.close() + In [27]: %timeit pix = fitz.Pixmap(doc, 1186);pix.tobytes() + 341 ms ± 2.86 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) + In [28]: len(pix.tobytes()) + Out[28]: 2599433 - .. warning:: The basename is returned unchanged from the PDF. So it may contain characters (such as blanks) which may disqualify it as a filename for your operating system. Take appropriate action. + In [29]: %timeit img = doc.extract_image(1186) + 15.7 µs ± 116 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each) + In [30]: len(img["image"]) + Out[30]: 371177 + + + .. method:: Document.extract_font(xref, info_only=False, named=None) + + * Changed in v1.19.4: return a dictionary if `named == True`. + + PDF Only: Return an embedded font file's data and appropriate file extension. This can be used to store the font as an external file. The method does not throw exceptions (other than via checking for PDF and valid :data:`xref`). + + :arg int xref: PDF object number of the font to extract. + :arg bool info_only: only return font information, not the buffer. To be used for information-only purposes, avoids allocation of large buffer areas. + :arg bool named: If true, a dictionary with the following keys is returned: 'name' (font base name), 'ext' (font file extension), 'type' (font type), 'content' (font file content). + + :rtype: tuple,dict + :returns: a tuple `(basename, ext, type, content)`, where *ext* is a 3-byte suggested file extension (*str*), *basename* is the font's name (*str*), *type* is the font's type (e.g. "Type1") and *content* is a bytes object containing the font file's content (or *b""*). For possible extension values and their meaning see :ref:`FontExtensions`. Return details on error: + + * `("", "", "", b"")` -- invalid xref or xref is not a (valid) font object. + * `(basename, "n/a", "Type1", b"")` -- *basename* is not embedded and thus cannot be extracted. This is the case for e.g. the :ref:`Base-14-Fonts` and Type 3 fonts. + + Example: + + >>> # store font as an external file + >>> name, ext, _, content = doc.extract_font(4711) + >>> # assuming content is not None: + >>> ofile = open(name + "." + ext, "wb") + >>> ofile.write(content) + >>> ofile.close() + + .. warning:: The basename is returned unchanged from the PDF. So it may contain characters (such as blanks) which may disqualify it as a filename for your operating system. Take appropriate action. + + .. note:: + * The returned *basename* in general is **not** the original file name, but it probably has some similarity. + * If parameter `named == True`, a dictionary with the following keys is returned: `{'name': 'T1', 'ext': 'n/a', 'type': 'Type3', 'content': b''}`. - .. note:: - * The returned *basename* in general is **not** the original file name, but it probably has some similarity. - * If parameter `named == True`, a dictionary with the following keys is returned: `{'name': 'T1', 'ext': 'n/a', 'type': 'Type3', 'content': b''}`. + .. method:: xref_xml_metadata() - .. method:: xref_xml_metadata() + * New in v1.16.8 - * New in v1.16.8 + PDF only: Return the :data:`xref` of the document's XML metadata. - PDF only: Return the :data:`xref` of the document's XML metadata. + .. method:: has_links() - .. method:: has_links() + .. method:: has_annots() - .. method:: has_annots() + * New in v1.18.7 - * New in v1.18.7 + PDF only: Check whether there are links, resp. annotations anywhere in the document. - PDF only: Check whether there are links, resp. annotations anywhere in the document. + :returns: *True* / *False*. As opposed to fields, which are also stored in a central place of a PDF document, the existence of links / annotations can only be detected by parsing each page. These methods are tuned to do this efficiently and will immediately return, if the answer is *True* for a page. For PDFs with many thousand pages however, an answer may take some time [#f6]_ if no link, resp. no annotation is found. - :returns: *True* / *False*. As opposed to fields, which are also stored in a central place of a PDF document, the existence of links / annotations can only be detected by parsing each page. These methods are tuned to do this efficiently and will immediately return, if the answer is *True* for a page. For PDFs with many thousand pages however, an answer may take some time [#f6]_ if no link, resp. no annotation is found. + .. method:: subset_fonts() - .. method:: subset_fonts() + * New in v1.18.7, changed in v1.18.9 - * New in v1.18.7, changed in v1.18.9 + PDF only: Investigate eligible fonts for their use by text in the document. If a font is supported and a size reduction is possible, that font is replaced by a version with a character subset. - PDF only: Investigate eligible fonts for their use by text in the document. If a font is supported and a size reduction is possible, that font is replaced by a version with a character subset. + Use this method immediately before saving the document. The following features and restrictions apply for the time being: - Use this method immediately before saving the document. The following features and restrictions apply for the time being: + * Package `fontTools `_ **must be installed**. It is required for creating the font subsets. If not installed, the method raises an `ImportError` exception. + * Supported font types only include embedded OTF, TTF and WOFF that are **not already subsets**. + * **Changed in v1.18.9:** A subset font directly replaces its original -- text remains untouched and **is not rewritten.** It thus should retain all its properties, like spacing, hiddenness, control by Optional Content, etc. - * Package `fontTools `_ **must be installed**. It is required for creating the font subsets. If not installed, the method raises an `ImportError` exception. - * Supported font types only include embedded OTF, TTF and WOFF that are **not already subsets**. - * **Changed in v1.18.9:** A subset font directly replaces its original -- text remains untouched and **is not rewritten.** It thus should retain all its properties, like spacing, hiddenness, control by Optional Content, etc. + The greatest benefit can be achieved when creating new PDFs using large fonts like is typical for Asian scripts. In these cases, the set of actually used unicodes mostly is small compared to the number of glyphs in the font. Using this feature can easily reduce the embedded font binary by two orders of magnitude -- from several megabytes to a low two-digit kilobyte amount. - The greatest benefit can be achieved when creating new PDFs using large fonts like is typical for Asian scripts. In these cases, the set of actually used unicodes mostly is small compared to the number of glyphs in the font. Using this feature can easily reduce the embedded font binary by two orders of magnitude -- from several megabytes to a low two-digit kilobyte amount. + .. method:: journal_enable() - .. method:: journal_enable() + * New in v1.19.0 - * New in v1.19.0 + PDF only: Enable journalling. Use this before you start logging operations. - PDF only: Enable journalling. Use this before you start logging operations. + .. method:: journal_start_op(name) - .. method:: journal_start_op(name) + * New in v1.19.0 - * New in v1.19.0 + PDF only: Start journalling an *"operation"* identified by a string "name". Updates will fail for a journal-enabled PDF, if no operation has been started. - PDF only: Start journalling an *"operation"* identified by a string "name". Updates will fail for a journal-enabled PDF, if no operation has been started. + .. method:: journal_stop_op() - .. method:: journal_stop_op() + * New in v1.19.0 - * New in v1.19.0 + PDF only: Stop the current operation. The updates between start and stop of an operation belong to the same unit of work and will be undone / redone together. - PDF only: Stop the current operation. The updates between start and stop of an operation belong to the same unit of work and will be undone / redone together. + .. method:: journal_position() - .. method:: journal_position() + * New in v1.19.0 - * New in v1.19.0 + PDF only: Return the numbers of the current operation and the total operation count. - PDF only: Return the numbers of the current operation and the total operation count. + :returns: a tuple `(step, steps)` containing the current operation number and the total number of operations in the journal. If **step** is 0, we are at the top of the journal. If **step** equals **steps**, we are at the bottom. Updating the PDF with anything other than undo or redo will automatically remove all journal entries after the current one and the new update will become the new last entry in the journal. The updates corresponding to the removed journal entries will be permanently lost. - :returns: a tuple `(step, steps)` containing the current operation number and the total number of operations in the journal. If **step** is 0, we are at the top of the journal. If **step** equals **steps**, we are at the bottom. Updating the PDF with anything other than undo or redo will automatically remove all journal entries after the current one and the new update will become the new last entry in the journal. The updates corresponding to the removed journal entries will be permanently lost. + .. method:: journal_op_name(step) - .. method:: journal_op_name(step) + * New in v1.19.0 - * New in v1.19.0 + PDF only: Return the name of operation number *step.* - PDF only: Return the name of operation number *step.* + .. method:: journal_can_do() - .. method:: journal_can_do() + * New in v1.19.0 - * New in v1.19.0 + PDF only: Show whether forward ("redo") and / or backward ("undo") executions are possible from the current journal position. - PDF only: Show whether forward ("redo") and / or backward ("undo") executions are possible from the current journal position. + :returns: a dictionary `{"undo": bool, "redo": bool}`. The respective method is available if its value is `True`. - :returns: a dictionary `{"undo": bool, "redo": bool}`. The respective method is available if its value is `True`. + .. method:: journal_undo() - .. method:: journal_undo() + * New in v1.19.0 - * New in v1.19.0 + PDF only: Revert (undo) the current step in the journal. This moves towards the journal's top. - PDF only: Revert (undo) the current step in the journal. This moves towards the journal's top. + .. method:: journal_redo() - .. method:: journal_redo() + * New in v1.19.0 - * New in v1.19.0 + PDF only: Re-apply (redo) the current step in the journal. This moves towards the journal's bottom. - PDF only: Re-apply (redo) the current step in the journal. This moves towards the journal's bottom. + .. method:: journal_save(filename) - .. method:: journal_save(filename) + * New in v1.19.0 - * New in v1.19.0 + PDF only: Save the journal to a file. - PDF only: Save the journal to a file. + :arg str,fp filename: either a filename as string or a file object opened as "wb" (or an `io.BytesIO()` object). - :arg str,fp filename: either a filename as string or a file object opened as "wb" (or an `io.BytesIO()` object). + .. method:: journal_load(filename) - .. method:: journal_load(filename) + * New in v1.19.0 - * New in v1.19.0 + PDF only: Load journal from a file. Enables journalling for the document. If journalling is already enabled, an exception is raised. - PDF only: Load journal from a file. Enables journalling for the document. If journalling is already enabled, an exception is raised. + :arg str,fp filename: the filename (str) of the journal or a file object opened as "rb" (or an `io.BytesIO()` object). - :arg str,fp filename: the filename (str) of the journal or a file object opened as "rb" (or an `io.BytesIO()` object). + .. method:: save_snapshot() - .. method:: save_snapshot() + * New in v1.19.0 - * New in v1.19.0 + PDF only: Saves a "snapshot" of the document. This is a PDF document with a special, incremental-save format compatible with journalling -- therefore no save options are available. Saving a snapshot is not possible for new documents. - PDF only: Saves a "snapshot" of the document. This is a PDF document with a special, incremental-save format compatible with journalling -- therefore no save options are available. Saving a snapshot is not possible for new documents. + This is a normal PDF document with no usage restrictions whatsoever. If it is not being changed in any way, it can be used together with its journal to undo / redo operations or continue updating. - This is a normal PDF document with no usage restrictions whatsoever. If it is not being changed in any way, it can be used together with its journal to undo / redo operations or continue updating. + .. attribute:: outline - .. attribute:: outline + Contains the first :ref:`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*. - Contains the first :ref:`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: :ref:`Outline` - :type: :ref:`Outline` + .. attribute:: is_closed - .. attribute:: is_closed + *False* if document is still open. If closed, most other attributes and methods will have been deleted / disabled. In addition, :ref:`Page` objects referring to this document (i.e. created with :meth:`Document.load_page`) and their dependent objects will no longer be usable. For reference purposes, :attr:`Document.name` still exists and will contain the filename of the original document (if applicable). - *False* if document is still open. If closed, most other attributes and methods will have been deleted / disabled. In addition, :ref:`Page` objects referring to this document (i.e. created with :meth:`Document.load_page`) and their dependent objects will no longer be usable. For reference purposes, :attr:`Document.name` still exists and will contain the filename of the original document (if applicable). + :type: bool - :type: bool + .. attribute:: is_dirty - .. attribute:: is_dirty + *True* if this is a PDF document and contains unsaved changes, else *False*. - *True* if this is a PDF document and contains unsaved changes, else *False*. + :type: bool - :type: bool + .. attribute:: is_pdf - .. attribute:: is_pdf + *True* if this is a PDF document, else *False*. - *True* if this is a PDF document, else *False*. + :type: bool - :type: bool + .. attribute:: is_form_pdf - .. attribute:: is_form_pdf + *False* if this is not a PDF or has no form fields, otherwise the number of root form fields (fields with no ancestors). - *False* if this is not a PDF or has no form fields, otherwise the number of root form fields (fields with no ancestors). + *(Changed in v1.16.4)* Returns the total number of (root) form fields. - *(Changed in v1.16.4)* Returns the total number of (root) form fields. + :type: bool,int - :type: bool,int + .. attribute:: is_reflowable - .. attribute:: is_reflowable + *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 :meth:`layout`. - *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 :meth:`layout`. + :type: bool - :type: bool + .. attribute:: is_repaired - .. attribute:: is_repaired + * New in v1.18.2 - * New in v1.18.2 + *True* if PDF has been repaired during open (because of major structure issues). Always *False* for non-PDF documents. If true, more details have been stored in `TOOLS.mupdf_warnings()`, and :meth:`Document.can_save_incrementally` will return *False*. - *True* if PDF has been repaired during open (because of major structure issues). Always *False* for non-PDF documents. If true, more details have been stored in `TOOLS.mupdf_warnings()`, and :meth:`Document.can_save_incrementally` will return *False*. + :type: bool - :type: bool + .. attribute:: is_fast_webaccess - .. attribute:: is_fast_webaccess + * New in v1.22.2 - * New in v1.22.2 + *True* if PDF is in linearized format. *False* for non-PDF documents. - *True* if PDF is in linearized format. *False* for non-PDF documents. + :type: bool - :type: bool + .. attribute:: markinfo - .. attribute:: markinfo + * New in v1.22.2 - * New in v1.22.2 + A dictionary indicating the `/MarkInfo` value. If not specified, the empty dictionary is returned. If not a PDF, `None` is returned. - A dictionary indicating the `/MarkInfo` value. If not specified, the empty dictionary is returned. If not a PDF, `None` is returned. + :type: dict - :type: dict + .. attribute:: pagemode - .. attribute:: pagemode + * New in v1.22.2 - * New in v1.22.2 + A string containing the `/PageMode` value. If not specified, the default "UseNone" is returned. If not a PDF, `None` is returned. - A string containing the `/PageMode` value. If not specified, the default "UseNone" is returned. If not a PDF, `None` is returned. + :type: str - :type: str + .. attribute:: pagelayout - .. attribute:: pagelayout + * New in v1.22.2 - * New in v1.22.2 + A string containing the `/PageLayout` value. If not specified, the default "SinglePage" is returned. If not a PDF, `None` is returned. - A string containing the `/PageLayout` value. If not specified, the default "SinglePage" is returned. If not a PDF, `None` is returned. + :type: str - :type: str + .. attribute:: version_count - .. attribute:: version_count + * New in v1.22.2 - * New in v1.22.2 + An integer counting the number of versions present in the document. Zero if not a PDF, otherwise the number of incremental saves plus one. - An integer counting the number of versions present in the document. Zero if not a PDF, otherwise the number of incremental saves plus one. + :type: int - :type: int + .. attribute:: needs_pass - .. attribute:: needs_pass + Indicates whether the document is password-protected against access. This indicator remains unchanged -- **even after the document has been authenticated**. Precludes incremental saves if true. - Indicates whether the document is password-protected against access. This indicator remains unchanged -- **even after the document has been authenticated**. Precludes incremental saves if true. + :type: bool - :type: bool + .. attribute:: is_encrypted - .. attribute:: is_encrypted + This indicator initially equals :attr:`Document.needs_pass`. After successful authentication, it is set to *False* to reflect the situation. - This indicator initially equals :attr:`Document.needs_pass`. After successful authentication, it is set to *False* to reflect the situation. + :type: bool - :type: bool + .. attribute:: permissions - .. attribute:: permissions + * Changed in v1.16.0: This is now an integer comprised of bit indicators. Was a dictionary previously. - * Changed in v1.16.0: This is now an integer comprised of bit indicators. Was a dictionary previously. + Contains the permissions to access the document. This is an integer containing bool values in respective bit positions. For example, if *doc.permissions & fitz.PDF_PERM_MODIFY > 0*, you may change the document. See :ref:`PermissionCodes` for details. - Contains the permissions to access the document. This is an integer containing bool values in respective bit positions. For example, if *doc.permissions & fitz.PDF_PERM_MODIFY > 0*, you may change the document. See :ref:`PermissionCodes` for details. + :type: int - :type: int + .. attribute:: metadata - .. attribute:: metadata + Contains the document's meta data as a Python dictionary or `None` (if *is_encrypted=True* and *needPass=True*). Keys are *format*, *encryption*, *title*, *author*, *subject*, *keywords*, *creator*, *producer*, *creationDate*, *modDate*, *trapped*. All item values are strings or `None`. - Contains the document's meta data as a Python dictionary or `None` (if *is_encrypted=True* and *needPass=True*). Keys are *format*, *encryption*, *title*, *author*, *subject*, *keywords*, *creator*, *producer*, *creationDate*, *modDate*, *trapped*. All item values are strings or `None`. + Except *format* and *encryption*, for PDF documents, the key names correspond in an obvious way to the PDF keys */Creator*, */Producer*, */CreationDate*, */ModDate*, */Title*, */Author*, */Subject*, */Trapped* and */Keywords* respectively. - Except *format* and *encryption*, for PDF documents, the key names correspond in an obvious way to the PDF keys */Creator*, */Producer*, */CreationDate*, */ModDate*, */Title*, */Author*, */Subject*, */Trapped* and */Keywords* respectively. + - *format* contains the document format (e.g. 'PDF-1.6', 'XPS', 'EPUB'). - - *format* contains the document format (e.g. 'PDF-1.6', 'XPS', 'EPUB'). + - *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** *needs_pass=False*. In such cases not all permissions will probably have been granted. Check :attr:`Document.permissions` for details. - - *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** *needs_pass=False*. In such cases not all permissions will probably have been granted. Check :attr:`Document.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:", where - - 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:", where + - is the 12 character ISO timestamp *YYYYMMDDhhmmss* (*YYYY* - year, *MM* - month, *DD* - day, *hh* - hour, *mm* - minute, *ss* - second), and - - is the 12 character ISO timestamp *YYYYMMDDhhmmss* (*YYYY* - year, *MM* - month, *DD* - day, *hh* - hour, *mm* - minute, *ss* - second), and + - is a time zone value (time interval relative to GMT) containing a sign ('+' or '-'), the hour (*hh*), and the minute (*'mm'*, note the apostrophes!). - - is a time zone value (time interval relative to GMT) containing a sign ('+' or '-'), the hour (*hh*), and the minute (*'mm'*, note the apostrophes!). + - 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. - - 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 - :type: dict + .. Attribute:: name - .. Attribute:: name + Contains the *filename* or *filetype* value with which *Document* was created. - Contains the *filename* or *filetype* value with which *Document* was created. + :type: str - :type: str + .. Attribute:: page_count - .. Attribute:: page_count + Contains the number of pages of the document. May return 0 for documents with no pages. Function `len(doc)` will also deliver this result. - 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 - :type: int + .. Attribute:: chapter_count - .. Attribute:: chapter_count + * New in v1.17.0 - * New in v1.17.0 - - Contains the number of chapters in the document. Always at least 1. Relevant only for document types with chapter support (EPUB currently). Other documents will return 1. + Contains the number of chapters in the document. Always at least 1. Relevant only for document types with chapter support (EPUB currently). Other documents will return 1. - :type: int + :type: int - .. Attribute:: last_location + .. Attribute:: last_location - * New in v1.17.0 + * New in v1.17.0 - Contains (chapter, pno) of the document's last page. Relevant only for document types with chapter support (EPUB currently). Other documents will return `(0, page_count - 1)` and `(0, -1)` if it has no pages. + Contains (chapter, pno) of the document's last page. Relevant only for document types with chapter support (EPUB currently). Other documents will return `(0, page_count - 1)` and `(0, -1)` if it has no pages. - :type: int + :type: int - .. Attribute:: FormFonts + .. Attribute:: FormFonts - A list of form field font names defined in the */AcroForm* object. `None` if not a PDF. + A list of form field font names defined in the */AcroForm* object. `None` if not a PDF. - :type: list + :type: list .. NOTE:: For methods that change the structure of a PDF (:meth:`insert_pdf`, :meth:`select`, :meth:`copy_page`, :meth:`delete_page` and others), be aware that objects or properties in your program may have been invalidated or orphaned. Examples are :ref:`Page` objects and their children (links, annotations, widgets), variables holding old page counts, tables of content and the like. Remember to keep such variables up to date or delete orphaned objects. Also refer to :ref:`ReferenialIntegrity`. diff --git a/docs/footer.rst b/docs/footer.rst index 08be54e41..bbce184ed 100644 --- a/docs/footer.rst +++ b/docs/footer.rst @@ -12,17 +12,6 @@ var a = document.getElementById('feedbackLinkBottom'); a.setAttribute("href", "https://artifex.com/contributor/feedback.php?utm_source=rtd-pymupdf&utm_medium=rtd&utm_content=footer-link&url="+url_string); - Prism.plugins.NormalizeWhitespace.setDefaults({ - 'remove-trailing': true, - 'remove-indent': true, - 'left-trim': true, - 'right-trim': true, - 'break-lines': 100, - 'indent': 0, - 'remove-initial-line-feed': false, - 'tabs-to-spaces': 4, - 'spaces-to-tabs': 4 - });

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.

diff --git a/docs/header.rst b/docs/header.rst index b2167db93..b96a9d41b 100644 --- a/docs/header.rst +++ b/docs/header.rst @@ -13,83 +13,62 @@ +.. |pdf_only_class| raw:: html +
This class is for PDF only.
-.. raw:: html - +.. raw:: html - - - +