upload v1.17.4

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: PyMuPDF
-Version: 1.17.3
+Version: 1.17.4
 Author: Ruikai Liu
 Author-email: lrk700@gmail.com
 Maintainer: Jorj X. McKie
@@ -9,7 +9,7 @@ Home-page: https://github.com/pymupdf/PyMuPDF
 Download-url: https://github.com/pymupdf/PyMuPDF
 Summary: PyMuPDF is a Python binding for the PDF rendering library MuPDF
 Description:
-        Release date: July 6, 2020
+        Release date: July 31, 2020
 
         Authors
         =======
@@ -20,7 +20,7 @@ Description:
         Introduction
         ============
 
-        This is **version 1.17.3 of PyMuPDF**, a Python binding for `MuPDF <http://mupdf.com/>`_ - "a lightweight PDF and XPS viewer".
+        This is **version 1.17.4 of PyMuPDF**, a Python binding for `MuPDF <http://mupdf.com/>`_ - "a lightweight PDF and XPS viewer".
 
         MuPDF can access files in PDF, XPS, OpenXPS, epub, comic and fiction book formats, and it is known for both, its top performance and high rendering quality.
 

README.md

@@ -1,8 +1,8 @@
-# PyMuPDF 1.17.3
+# PyMuPDF 1.17.4
 
 ![logo](https://github.com/pymupdf/PyMuPDF/blob/master/demo/pymupdf.jpg)
 
-Release date: July 6, 2020
+Release date: July 31, 2020
 
 **Travis-CI:** [![Build Status](https://travis-ci.org/JorjMcKie/py-mupdf.svg?branch=master)](https://travis-ci.org/JorjMcKie/py-mupdf)
 
@@ -14,7 +14,7 @@ On **[PyPI](https://pypi.org/project/PyMuPDF)** since August 2016: [![](https://
 
 # Introduction
 
-This is **version 1.17.3 of PyMuPDF**, a Python binding with support for [MuPDF 1.17.*](http://mupdf.com/) - "a lightweight PDF, XPS, and E-book viewer".
+This is **version 1.17.4 of PyMuPDF**, a Python binding with support for [MuPDF 1.17.*](http://mupdf.com/) - "a lightweight PDF, XPS, and E-book viewer".
 
 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.
 

docs/annot.rst

@@ -67,7 +67,7 @@ There is a parent-child relationship between an annotation and its page. If the
 
       :rtype: :ref:`Pixmap`
 
-      .. note:: If the annotation has just been created or modified
+      .. note:: If the annotation has just been created or modified, you should reload the page first via *page = doc.reload_page(page)*.
 
    .. method:: setInfo(info=None, content=None, title=None, creationDate=None, modDate=None, subject=None)
 

docs/changes.rst

@@ -1,6 +1,18 @@
 Change Logs
 ===============
 
+Changes in Version 1.17.4
+---------------------------
+* **Fixed** issue `#561 <https://github.com/pymupdf/PyMuPDF/issues/561>`_. Handling of more than 10 :ref:`Font` objects on one page should now work correctly.
+* **Fixed** issue `#562 <https://github.com/pymupdf/PyMuPDF/issues/562>`_. Annotation pixmaps are no longer derived from the page pixmap, thus avoiding unintended inclusion of page content.
+* **Fixed** issue `#559 <https://github.com/pymupdf/PyMuPDF/issues/559>`_. This **MuPDF** bug is being temporarily fixed with a pre-version of MuPDF's next release.
+* **Added** utility function :meth:`repair_mono_font` for correcting displayed character spacing for some mono-spaced fonts.
+* **Added** utility method :meth:`Document.need_appearances` for fine-controlling Form PDF behavior. Addresses issue `#563 <https://github.com/pymupdf/PyMuPDF/issues/563>`_.
+* **Added** utility function :meth:`sRGB_to_pdf` to recover the PDF color triple for a given color integer in sRGB format.
+* **Added** utility function :meth:`sRGB_to_rgb` to recover the (R, G, B) color triple for a given color integer in sRGB format.
+* **Added** utility function :meth:`make_table` which delivers table cells for a given rectangle and desired numbers of columns and rows.
+* **Added** support for optional fonts in repository `pymupdf-fonts <https://github.com/pymupdf/pymupdf-fonts>`_.
+
 Changes in Version 1.17.3
 ---------------------------
 * **Fixed** an undocumented issue, which prevented fully cleaning a PDF page when using :meth:`Page.cleanContents`.

docs/conf.py

@@ -12,7 +12,7 @@
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = "2.0"
+# needs_sphinx = "3.1"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -46,7 +46,7 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = "1.17.3"
+release = "1.17.4"
 
 # The short X.Y version
 version = release
@@ -207,7 +207,7 @@
 latex_show_pagerefs = False
 
 # If true, show URL addresses after external links.
-latex_show_urls = True
+# latex_show_urls = True
 # latex_use_xindy = True
 # Documents to append as an appendix to all manuals.
 # latex_appendices = []

docs/document.rst

@@ -53,7 +53,8 @@ For details on **embedded files** refer to Appendix 3.
 :meth:`Document.loadPage`               read a page
 :meth:`Document.makeBookmark`           create a page pointer in reflowable documents
 :meth:`Document.metadataXML`            PDF only: :data:`xref` of XML metadata
-:meth:`Document.movePage`               PDF only: move a page to another location
+:meth:`Document.movePage`               PDF only: move a page to different location in doc
+:meth:`Document.need_appearances`       PDF only: get/set */NeedAppearances* property
 :meth:`Document.newPage`                PDF only: insert a new empty page
 :meth:`Document.nextLocation`           return (chapter, pno) of following page
 :meth:`Document.pages`                  iterator over a page range
@@ -70,10 +71,10 @@ For details on **embedded files** refer to Appendix 3.
 :meth:`Document.setToC`                 PDF only: set the table of contents (TOC)
 :meth:`Document.updateObject`           PDF only: replace object source
 :meth:`Document.updateStream`           PDF only: replace stream source
-:meth:`Document.write`                  PDF only: writes the document to memory
+:meth:`Document.write`                  PDF only: writes document to memory
 :meth:`Document.xrefObject`             PDF only: object source at the :data:`xref`
-:meth:`Document.xrefStream`             PDF only: stream source at the :data:`xref`
-:meth:`Document.xrefStreamRaw`          PDF only: raw stream source at the :data:`xref`
+:meth:`Document.xrefStream`             PDF only: decompressed stream source at :data:`xref`
+:meth:`Document.xrefStreamRaw`          PDF only: raw stream source at :data:`xref`
 :attr:`Document.chapterCount`           number of chapters
 :attr:`Document.FormFonts`              PDF only: list of global widget fonts
 :attr:`Document.isClosed`               has document been closed?
@@ -719,7 +720,11 @@ For details on **embedded files** refer to Appendix 3.
 
       :arg int to: the page number in front of which to copy. The default inserts **after** the last page.
 
-      .. note:: In contrast to :meth:`copyPage`, this method creates a completely identical new page object -- with the exception of :attr:`Page.xref` of course, which will be different. So changes to a copy will only show there.
+      .. note::
+
+          * In contrast to :meth:`copyPage`, this method creates a new page object (with a new :data:`xref`), which can be changed independently from the original.
+
+          * Any Popup and "IRT" ("in response to") annotations are **not copied** to avoid potentially incorrect situations.
 
     .. method:: movePage(pno, to=-1)
 
@@ -729,9 +734,26 @@ For details on **embedded files** refer to Appendix 3.
 
       :arg int to: the page number in front of which to insert the moved page. The default moves **after** the last page.
 
+
+    .. method:: need_appearances(value=None)
+
+      *(New in v1.17.4)*
+
+      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.
+
+      :arg bool value: set the property to this value. If omitted or *None*, inquire the current value.
+
+      :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).
+
+         Once set, the property cannot be removed again (which is no problem).
+
+
     .. method:: getSigFlags()
 
-      PDF only: Return whether the document contains signature fields. This is an optional PDF property: if not present, no conclusions can be drawn, because the PDF creator may just not have bothered to use it.
+      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 to use it.
 
       :rtype: int
       :returns:

docs/faq.rst

@@ -1046,7 +1046,9 @@ In v1.14.0, annotation handling has been considerably extended:
 How to Add and Modify Annotations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In PyMuPDF, new annotations are added via :ref:`Page` methods. To keep code duplication effort small, we only offer a minimal set of options here. For example, to add a 'Circle' annotation, only the containing rectangle can be specified. The result is a circle (or ellipsis) with white interior, black border and a line width of 1, exactly fitting into the rectangle. To adjust the annot's appearance, :ref:`Annot` methods must then be used. After having made all required changes, the annot's :meth:`Annot.update` methods must be invoked to finalize all your changes.
+In PyMuPDF, new annotations can be added added via :ref:`Page` methods. Once an annotation exists, it can be modified to a large extent using methods of the :ref:`Annot` class.
+
+In contrast to many other tools, initial insert of annotations happens with a minimum number of properties. We leave it to the programmer to e.g. set attributes like author, creation date or subject.
 
 As an overview for these capabilities, look at the following script that fills a PDF page with most of the available annotations. Look in the next sections for more special situations:
 

docs/font.rst

@@ -19,6 +19,11 @@ A Font object also contains useful general information, like the font bbox, the
       Font constructor. The large number of parameters are used to locate font, which most closely resembles the requirements. Not all parameters are ever required -- see the below pseudo code explaining the logic how the parameters are evaluated.
 
       :arg str fontname: one of the :ref:`Base-14-Fonts` or CJK fontnames. Also possible are a select few of other names like (watch the correct spelling): "Arial", "Times", "Times Roman".
+
+         *(Changed in v1.17.4)*
+
+         If you have installed `pymupdf-fonts <https://pypi.org/project/pymupdf-fonts/>`_, you can also use the following new "reserved" fontnames: "figo", "figbo", "figit", "figbi", "fimo", and "fimbo". This will provide one of the "FiraGo" or resp. "FiraMono" fonts, created by Mozilla.org.
+
       :arg str filename: the filename of a fontfile somewhere on your system [#f1]_.
       :arg bytes,bytearray,io.BytesIO fontbuffer: a fontfile loaded in memory [#f1]_.
       :arg in script: the number of a UCDN script. Currently supported in PyMuPDF are numbers 24, and 32 through 35.
@@ -48,7 +53,7 @@ A Font object also contains useful general information, like the font bbox, the
             look for fallback font
 
       .. note::
-      
+
         With the usual abbreviations "helv", "tiro", etc., you will create fonts with the expected names "Helvetica", "Times-Roman" and so on.
 
         Using *ordering >= 0*, or fontnames starting with "china", "japan" or "korea" will always create the same **"universal"** font **"Droid Sans Fallback Regular"**. This font supports **all CJK and all Latin characters**.
@@ -57,11 +62,22 @@ A Font object also contains useful general information, like the font bbox, the
 
         If you **know** you have a mixture of CJK and Latin text, consider just using ``Font(ordering=0)`` because this supports everything and also significantly (by a factor of two to three) speeds up execution: MuPDF will always find any character in this single font and need not check fallbacks.
 
-        But if you do specify a Base-14 fontname, you will still be able to also write CJK characters! MuPDF automatically detects this situation and silently falls back to the universal font (which will then of course also be included in your PDF).
+        But if you do specify a Base-14 fontname, you will still be able to also write CJK characters! MuPDF automatically detects this situation and silently falls back to the universal font (which will then of course also be embedded in your PDF).
 
-        **All fonts mentioned here** also support Greek and Cyrillic letters.
+        *(New in v1.17.4)* Optionally, a set of new "reserved" fontnames becomes available if you install `pymupdf-fonts <https://pypi.org/project/pymupdf-fonts/>`_. The currently available fonts are from the Fira fonts family created by Mozilla. "Fira Mono" is a nice mono-spaced sans font set and FiraGO is another non-serifed "universal" font, set which supports all European languages (including Cyrillic and Greek) plus Thai, Arabian, Hewbrew and Devanagari -- however none of the CJK languages. The size of a FiraGO font is only a quarter of the "Droid Sans Fallback" size (compressed 400 KB vs. 1.65 MB) -- and the style variants bold and italic are available..The following table maps a fontname to the corresponding font:
 
-        *Monospaced* fonts are an issue: They are written with a too large width, e.g. ``" a"`` instead of ``"a"``. This applies to "cour" variants as well as most other mono fonts. The only exception we know of so far is ``consola.ttf``. If you want to output monospaced text, we recommend using the Consolas font for the time being.
+            =========== =======================================
+            Fontname    Font
+            =========== =======================================
+            figo        FiraGO Regular
+            figbo       FiraGO Bold
+            figit       FiraGO Italic
+            figbi       FiraGO Bold Italic
+            fimo        Fira Mono Regular
+            fimbo       Fira Mono Bold
+            =========== =======================================
+
+        **All fonts mentioned here** also support Greek and Cyrillic letters.
 
    .. method:: has_glyph(chr, language=None, script=0)
 

docs/functions.rst

@@ -55,6 +55,9 @@ Yet others are handy, general-purpose utilities.
 :meth:`planishLine`                  matrix to map a line to the x-axis
 :meth:`PaperSize`                    return width, height for a known paper format
 :meth:`PaperRect`                    return rectangle for a known paper format
+:meth:`sRGB_to_pdf`                  return PDF RGB color tuple from a sRGB integer
+:meth:`sRGB_to_rgb`                  return (R, G, B) color tuple from a sRGB integer
+:meth:`make_table`                   return list of table cells for a given rectangle
 :attr:`paperSizes`                   dictionary of pre-defined paper formats
 ==================================== ==============================================================
 
@@ -87,6 +90,49 @@ Yet others are handy, general-purpose utilities.
       fitz.Rect(0.0, 0.0, 792.0, 612.0)
       >>>
 
+-----
+
+   .. method:: sRGB_to_pdf(srgb)
+
+      *New in v1.17.4*
+
+      Convenience function returning a PDF color triple (red, green, blue) for a given sRGB color integer as it occurs in :meth:`Page.getText` dictionaries "dict" and "rawdict".
+
+      :arg int srgb: an integer of format RRGGBB, where each color component is an integer in range(255).
+
+      :returns: a tuple (red, green, blue) with float items in intervall *0 <= item <= 1* representing the same color.
+
+-----
+
+   .. method:: sRGB_to_rgb(srgb)
+
+      *New in v1.17.4*
+
+      Convenience function returning a color (red, green, blue) for a given sRGB color integer .
+
+      :arg int srgb: an integer of format RRGGBB, where each color component is an integer in range(255).
+
+      :returns: a tuple (red, green, blue) with integer items in intervall *0 <= item <= 255* representing the same color.
+
+-----
+
+   .. method:: make_table(rect=(0, 0, 1, 1), cols=1, rows=1)
+
+      *New in v1.17.4*
+
+      Convenience function returning a list of <rows x cols> :ref:`Rect` objects representing equal sized table cells for the given rectangle.
+
+      :arg rect_like rect: the rectangle to contain the table.
+      :arg int cols: the desired number of columns.
+      :arg int rows: the desired number of rows.
+      :returns: a list of :ref:`Rect` objects of equal size, whose union equals *rect*::
+
+         [
+            [cell00, cell01, ...]  # row 0
+            ...
+            [...]  # last row
+         ]
+
 -----
 
    .. method:: planishLine(p1, p2)