version 1.18.13

Author: JorjMcKie

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: PyMuPDF
-Version: 1.18.12
+Version: 1.18.13
 Author: Jorj McKie
 Author-email: [email protected]
 License: GNU AFFERO GPL 3.0
@@ -10,7 +10,7 @@ Home-page: https://github.com/pymupdf/PyMuPDF
 Download-url: https://github.com/pymupdf/PyMuPDF
 Summary: PyMuPDF is a Python binding for the document renderer and toolkit MuPDF
 Description:
-        Release date: April 10, 2021
+        Release date: April 29, 2021
 
         Authors
         =======
@@ -21,7 +21,7 @@ Description:
         Introduction
         ============
 
-        PyMuPDF (current version 1.18.12) is a Python binding with support for `MuPDF <http://mupdf.com/>`_ (current version 1.18.*), a lightweight PDF, XPS, and E-book viewer, renderer and toolkit, which is maintained and developed by Artifex Software, Inc.
+        PyMuPDF (current version 1.18.13) is a Python binding with support for `MuPDF <http://mupdf.com/>`_ (current version 1.18.*), a lightweight PDF, XPS, and E-book viewer, renderer and toolkit, which is maintained and developed by Artifex Software, Inc.
 
         MuPDF can access files in PDF, XPS, OpenXPS, CBZ, EPUB and FB2 (e-books) formats, and it is known for its top performance and high rendering quality.
 

README.md

@@ -1,8 +1,8 @@
-# PyMuPDF 1.18.12
+# PyMuPDF 1.18.13
 
 ![logo](https://github.com/pymupdf/PyMuPDF/blob/master/demo/pymupdf.jpg)
 
-Release date: April 10, 2021
+Release date: April 30, 2021
 
 **Travis-CI:** [![Build Status](https://travis-ci.org/JorjMcKie/py-mupdf.svg?branch=master)](https://travis-ci.org/JorjMcKie/py-mupdf)
 
@@ -15,7 +15,7 @@ On **[PyPI](https://pypi.org/project/PyMuPDF)** since August 2016: [![Downloads]
 
 # Introduction
 
-PyMuPDF (current version 1.18.12) is a Python binding with support for [MuPDF](https://mupdf.com/) (current version 1.18.*), a lightweight PDF, XPS, and E-book viewer, renderer, and toolkit, which is maintained and developed by Artifex Software, Inc.
+PyMuPDF (current version 1.18.13) is a Python binding with support for [MuPDF](https://mupdf.com/) (current version 1.18.*), a lightweight PDF, XPS, and E-book viewer, renderer, and toolkit, which is maintained and developed by Artifex Software, Inc.
 
 MuPDF can access files in PDF, XPS, OpenXPS, CBZ, EPUB and FB2 (e-books) formats, and it is known for its top performance and high rendering quality.
 

changes.rst

@@ -15,10 +15,14 @@ Starting with version 1.18.11, the image transformation matrix is returned by so
 
 The transformation matrix contains information about how an image was transformed to fit into the rectangle (its "boundary box" = "bbox") on some document page. By inspecting the image's bbox on the page and this matrix, one can determine for example, whether and how the image is displayed scaled or rotated on a page.
 
-The relationship between image width and height and the bbox on a page is the following:
+The relationship between image dimension and its bbox on a page is the following:
+
+1. Using the original image's width and height,
+    - define the image rectangle ``imgrect = fitz.Rect(0, 0, width, height)``
+    - define the "shrink matrix" ``shrink = fitz.Matrix(1/width, 0, 0, 1/height, 0, 0)``.
 
-1. Using the original image's width and height, we can define the image rectangle ``imgrect = fitz.Rect(0, 0, width, height)`` and a "shrink matrix" ``shrink = fitz.Matrix(1/width, 0, 0, 1/height, 0, 0)``.
 2. Transforming the image rectangle with its shrink matrix, will result in the unit rectangle: ``imgrect * shrink = fitz.Rect(0, 0, 1, 1)``.
+
 3. Using the image **transformation matrix** "transform", the following steps will compute the bbox::
 
     imgrect = fitz.Rect(0, 0, width, height)

docs/app4.rst

@@ -1,8 +1,20 @@
 Change Logs
 ===============
 
-Changes in Version 1.18.11
----------------------------
+Changes in Version 1.18.13
+---------------------------
+* **Fixed** issue `#1014 <https://github.com/pymupdf/PyMuPDF/issues/1014>`_.
+* **Fixed** an internal memory leak when computing image bboxes -- :meth:`Page.get_image_bbox`.
+* **Added** support for low-level access and modification of the PDF trailer. Applies to :meth:`Document.xref_get_keys`, :meth:`Document.xref_get_key`, and :meth:`Document.xref_set_key`.
+* **Added** documentation for maintaining private entries in PDF metadata.
+* **Added** documentation for handling transparent image insertions, :meth:`Page.insert_image`.
+* **Added** :meth:`Page.get_image_rects`, an improved version of :meth:`Page.get_image_bbox`.
+* **Changed** :meth:`Page.insert_image` to also accept the xref of an existing image in the file. This allows "copying" images between pages, and extremely fast mutiple insertions.
+* **Changed** :meth:`Pixmap.setAlpha` to support new parameters for pre-multiplying colors with their alpha values and setting a specific color to fully transparent (e.g. white).
+* **Changed** :meth:`Document.embfile_add` to automatically set creation and modification date-time. Correspondingly, :meth:`Document.embfile_upd` automatically maintains modification date-time (``/ModDate`` PDF key), and :meth:`Document.embfile_info` correspondingly reports these data. In addition, the embedded file's associated "collection item" is included via its :data:`xref`. This supports the development of PDF portfolio applications.
+
+Changes in Version 1.18.11 / 1.18.12
+-------------------------------------
 * **Fixed** issue `#972 <https://github.com/pymupdf/PyMuPDF/issues/972>`_. Improved layout of source distribution material.
 * **Fixed** issue `#962 <https://github.com/pymupdf/PyMuPDF/issues/962>`_. Stabilized Linux distribution detection for generating PyMuPDF from sources.
 * **Added:** :meth:`Page.get_xobjects` delivers the result of :meth:`Document.get_page_xobjects`.

docs/changes.rst

@@ -42,7 +42,7 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = "1.18.12"
+release = "1.18.13"
 
 # The short X.Y version
 version = release

docs/conf.py

@@ -731,7 +731,7 @@ For details on **embedded files** refer to Appendix 3.
       :arg int xref: the :data:`xref`. *Changed in v1.18.10:* Use ``-1`` to access the special dictionary "PDF trailer" (it has no identifying xref).
       :arg str key: the desired PDF key. Must **exactly** match (case-sensitive) one of the keys contained in :meth:`Document.xref_get_keys`.
 
-      :returns: a tuple (type, value), where type is one of "xref", "array", "dict", "int", "float" "null", "bool", "float", "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 a faithful reflection of what is stored in the PDF. An argument like the return value can be used to modify the value of a key of :data:`xref`.
+      :returns: a tuple (type, value), where type is one of "xref", "array", "dict", "int", "float", "null", "bool", "float", "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 a faithful reflection of what is stored in the PDF. An argument like the returned value can be used to modify the value of a key of :data:`xref`.
 
           >>> for key in doc.xref_get_keys(xref):
                   print(key, "=" , doc.xref_get_key(xref, key))
@@ -757,26 +757,30 @@ For details on **embedded files** refer to Appendix 3.
 
     .. method:: xref_set_key(xref, key, value)
 
-      *(New in v 1.18.7)*
+      *(New in v 1.18.7, changed in v 1.18.13)*
 
-      PDF only: Set the value of a PDF key in the object given by an xref. 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 51) and the structure of special dictionary types like page objects.
+      PDF only: Set (add, update, delete) the value of a PDF key for the object given by an 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 51) and the structure of special dictionary types like page objects.
 
-      :arg int xref: the :data:`xref`. Note that changing the content of the **PDF trailer** in this way is currently not enabled for safety reasons.
+      :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, but no type checking and no checking of the PDF semantics. Upper or lower case are important!
+      :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 or lower case are important!
 
-          * **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 a xref.
-          * **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 need not be of the same type.
+          * **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.
+          * **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.
           * **bool** -- one of the strings ``"true"`` or ``"false"``.
-          * **name** -- a valid PDF name with a leading slash: ``"/PageLayout"``.
-          * **string** -- a valid PDF string. Denote the empty string as ``"()"``. Depending on its content, it must be enclosed in bracket types "(...)" or "<...>", and reserved PDF characters must be escaped. If in doubt, we **strongly recommend** to use :meth:`getPDFstr`! This function automatically generates the right brackets and determines the required format. E.g. it will do conversions like these:
+          * **name** -- a valid PDF name with a leading slash: ``"/PageLayout"``. See page 56 of the :ref:`AdobeManual`.
+          * **string** -- a valid PDF string. **All PDF strings** must be enclosed by some type of brackets. Denote the empty string as ``"()"``. Depending on its content, the possible bracket types are "(...)" or "<...>". Reserved PDF characters must be escaped. If in doubt, we **strongly recommend** to use :meth:`getPDFstr`! This function automatically generates the right brackets, escapes, and overall format. E.g. it will do conversions like these:
 
+            >>> # because of €, the following yields UTF-16BE BOM
             >>> fitz.getPDFstr("Pay in $ or €.")
             '<feff00500061007900200069006e002000240020006f0072002020ac002e>'
+            >>> # escapes for brackets and non-ASCII
             >>> fitz.getPDFstr("Prices in EUR (USD also accepted). Areas are in m².")
             '(Prices in EUR \\(USD also accepted\\). Areas are in m\\262.)'
 
@@ -1313,7 +1317,7 @@ For details on **embedded files** refer to Appendix 3.
       Changed in version 1.14.16
          The sequence of positional parameters "name" and "buffer" has been changed to comply with the layout of other functions.
 
-      :arg str name: entry identifier, must not already exist.
+      :arg str name: entry identifier, **must not already exist**.
       :arg bytes,bytearray,BytesIO buffer: file contents.
 
          *(Changed in version 1.14.13)* *io.BytesIO* is now also supported.
@@ -1322,6 +1326,9 @@ For details on **embedded files** refer to Appendix 3.
       :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:: embfile_count()
 
@@ -1334,7 +1341,7 @@ For details on **embedded files** refer to Appendix 3.
 
       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: bytes
 
@@ -1351,9 +1358,11 @@ For details on **embedded files** refer to Appendix 3.
 
     .. method:: embfile_info(item)
 
+      *(Changed in v1.18.13)*
+
       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 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:
@@ -1364,12 +1373,16 @@ For details on **embedded files** refer to Appendix 3.
           * *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_names()
 
       *(New in version 1.14.16)*
 
-      PDF only: Return a list of embedded file names. The sequence of names equals the physical sequence in the document.
+      PDF only: Return a list of embedded file names. The sequence of the names equals the physical sequence in the document.
 
       :rtype: list
 
@@ -1382,7 +1395,7 @@ For details on **embedded files** refer to Appendix 3.
 
       PDF only: Change an embedded file given its entry number or name. All parameters are optional. Letting them default leads to a no-operation.
 
-      :arg int/str item: index or name of entry. An integer must be in *range(0, embfile_count())*.
+      :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.
 
          *(Changed in version 1.14.13)* *io.BytesIO* is now also supported.
@@ -1391,16 +1404,11 @@ For details on **embedded files** refer to Appendix 3.
       :arg str ufilename: the new unicode filename.
       :arg str desc: the new description.
 
-    .. method:: embfile_setinfo(n, filename=None, ufilename=None, desc=None)
+      *(Changed in v1.18.13)*  The method now returns the :data:`xref` of the file object.
 
-      PDF only: Change embedded file meta information. All parameters are optional. Letting them default will lead to a no-operation.
-
-      :arg int,str n: index or name of entry. An integer must be in *range(embfile_count())*.
-      :arg str filename: sets the filename.
-      :arg str ufilename: sets the unicode filename.
-      :arg str desc: sets the description.
+      :rtype: int
+      :returns: xref of the file object. Automatically, its ``/ModDate`` PDF key will be updated with the current date-time.
 
-      .. note:: Deprecated subset of :meth:`embfile_upd`. Will be deleted in a future version.
 
     .. method:: close()