upgrade to v1.16.18

Author: JorjMcKie

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: PyMuPDF
-Version: 1.16.17
+Version: 1.16.18
 Author: Ruikai Liu
 Author-email: [email protected]
 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: March 31, 2020
+        Release date: April 22, 2020
 
         Authors
         =======

README.md

@@ -1,8 +1,8 @@
-# PyMuPDF 1.16.17
+# PyMuPDF 1.16.18
 
 ![logo](https://github.com/pymupdf/PyMuPDF/blob/master/demo/pymupdf.jpg)
 
-Release date: March 31, 2020
+Release date: April 22, 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.16.17 of PyMuPDF (formerly python-fitz)**, a Python binding with support for [MuPDF 1.16.*](http://mupdf.com/) - "a lightweight PDF, XPS, and E-book viewer".
+This is **version 1.16.18 of PyMuPDF (formerly python-fitz)**, a Python binding with support for [MuPDF 1.16.*](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/changes.rst

@@ -1,6 +1,19 @@
 Change Logs
 ===============
 
+Changes in Version 1.16.18
+---------------------------
+This version introduces several new features around PDF text output. The motivation is to simplify this task, while at the same time offering extending features.
+
+One major achievement is using MuPDF's capabilities to dynamically choosing fallback fonts whenever a character cannot be found in the predefined one. This seemlessly works for Base-14 fonts in combination with CJK fonts (China, Japan, Korea).
+
+* **Fixed** issue `#493 <https://github.com/pymupdf/PyMuPDF/issues/493>`_. ``Pixmap(doc, xref)`` should now again correctly resemble the loaded image object.
+* **Fixed** issue `#488 <https://github.com/pymupdf/PyMuPDF/issues/488>`_. Widget names are now modifyable.
+* **Added** new class :ref:`Font` which represents a font.
+* **Added** new class :ref:`TextWriter` which serves as a container for text to be written on a page.
+* **Added** :meth:`Page.writeText` to write one or more :ref:`TextWriter` objects to the page.
+
+
 Changes in Version 1.16.17
 ---------------------------
 

docs/classes.rst

@@ -9,6 +9,7 @@ Classes
    colorspace.rst
    displaylist.rst
    document.rst
+   font.rst
    identity.rst
    irect.rst
    link.rst
@@ -22,5 +23,6 @@ Classes
    rect.rst
    shape.rst
    textpage.rst
+   textwriter.rst
    tools.rst
    widget.rst

docs/conf.py

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

docs/font.rst

@@ -0,0 +1,125 @@
+.. _Font:
+
+================
+Font
+================
+
+*(New in v1.16.18)* This class represents a font as defined in MuPDF (*fz_font_s* structure). It is required for the new class :ref:`TextWriter` and the new :meth:`Page.writeText`. Currently, it has no connection to how fonts are used in methods ``insertText`` or insertTextbox``, respectively.
+
+A Font object also contains useful general information, like the font bbox, the number of defined glyphs, glyph names or the bbox of a single glyph.
+
+**Class API**
+
+.. class:: Font
+
+   .. method:: __init__(self, fontname=None, fontfile=None,
+                  fontbuffer=None, script=0, language=None, ordering=-1, is_bold=0,
+                  is_italic=0, is_serif=0)
+
+      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".
+      :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.
+      :arg str language: one of the values "zh-Hant" (traditional Chinese), "zh-Hans" (simplified Chinese), "ja" (Japanese) and "ko" (Korean). Otherwise, all ISO 639 codes from the subsets 1, 2, 3 and 5 are also possible, but are currently documentary only.
+      :arg int ordering: an alternative selector for one of the CJK fonts.
+      :arg bool is_bold: look for a bold font.
+      :arg bool is_italic: look for an italic font.
+      :arg bool is_serif: look for a serifed font.
+
+      :returns: a MuPDF font if successful. This is the overall logic, how an appropriate font is located::
+
+         if fontfile:
+            create font from it ignoring other arguments
+            if not successful -> exception
+         if fonbuffer:
+            create font from it ignoring other arguments
+            if not successful -> exception
+         if ordering >= 0:
+            load **"universal"** font ignoring other parameters
+            # this will always be successful
+         if fontname:
+            create a Base14 font, or resp. **"universal"** font, ignoring other parameters
+            # note: values "Arial", "Times", "Times Roman" are also possible
+            if not successful -> exception
+         Finally try to load a "NOTO" font using *script* and *language* parameters.
+         if not successful:
+            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**.
+
+        Actually, you would rarely ever need another font than **"Droid Sans Fallback Regular"**. **Except** that this font file is relatively large and adds about 1.65 MB (compressed) to your PDF file size. If you do not need CJK support, stick with specifying "helv", "tiro" etc., and you will get away with about 35 KB compressed.
+
+        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).
+
+        **All fonts mentioned here** also support Greek and Cyrillic letters.
+
+        *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.
+
+   .. method:: has_glyph(chr, language=None, script=0)
+
+      Check whether the unicode *chr* exists in the font or some fallback. May be used to check whether any "TOFU" symbols will appear on output.
+
+      :arg int chr: the unicode of the character (i.e. *ord()*).
+      :arg str language: the language -- currently unused.
+      :arg int script: the UCDN script number.
+      :returns: *True* or *False*.
+
+   .. method:: glyph_advance(chr, language=None, script=0, wmode=0)
+
+      Calculate the "width" of the character's glyph (visual representation).
+
+      :arg int chr: the unicode number of the character. Use ``ord(c)``, not the character itself. Again, this should normally work even if a character is not supported by that font, because fallback fonts will be checked where necessary.
+
+      The other parameters are not in use currently. This especially means that only horizontal text writing is supported.
+
+      :returns: a float representing the glyph's width relative to **fontsize 1**.
+
+   .. method:: glyph_name_to_unicode(name)
+
+      Return the unicode for a given glyph name. Use it in conjunction with ``chr()`` if you want to output e.g. a certain symbol.
+
+      :arg str name: The name of the glyph.
+
+      :returns: The unicode integer, or 65533 = 0xFFFD if the name is unknown. Examples: ``font.glyph_name_to_unicode("Sigma") = 931``, ``font.glyph_name_to_unicode("sigma") = 963``. Refer to e.g. `this <https://github.com/adobe-type-tools/agl-aglfn/blob/master/glyphlist.txt>`_ publication for a list of glyph names and their unicode numbers.
+
+   .. method:: unicode_to_glyph_name(chr, language=None, script=0, wmode=0)
+
+      Show the name of the character's glyph.
+
+      :arg int chr: the unicode number of the character. Use ``ord(c)``, not the character itself.
+
+      :returns: a string representing the glyph's name. E.g. ``font.glyph_name(ord("#")) = "numbersign"``. Depending on how this font was built, the string may be empty, ".notfound" or some generated name.
+
+   .. method:: text_length(text, fontsize=11)
+
+      Calculate the length of a unicode string.
+
+      :arg str text: a text string -- UTF-8 encoded. For Python 2, you must use unicode here.
+
+      :arg float fontsize: the fontsize.
+
+      :returns: a float representing the length of the string when stored in the PDF. Internally :meth:`glyph_advance` is used on a by-character level. If the font does not have a character, it will automatically be looked up in a fallback font.
+
+   .. attribute:: flags
+
+      A dictionary with various font properties, each represented as bools.
+
+   .. attribute:: name
+
+      Name of the font. May be "" or "(null)".
+
+   .. attribute:: glyph_count
+
+      The number of glyphs defined in the font.
+
+.. rubric:: Footnotes
+
+.. [#f1] MuPDF does not support all fontfiles with this feature and will raise exceptions like *"mupdf: FT_New_Memory_Face((null)): unknown file format"*, if encounters issues.

docs/page.rst

@@ -74,14 +74,15 @@ This is available for PDF documents only. There are basically two groups of meth
 :meth:`Page.links`               return a generator of the links on the page
 :meth:`Page.load_annot`          PDF only: load an annotation identified by its name
 :meth:`Page.loadLinks`           return the first link on a page
-:meth:`Page.newShape`            PDF only: start a new :ref:`Shape`
+:meth:`Page.newShape`            PDF only: create a new :ref:`Shape`
 :meth:`Page.searchFor`           search for a string
 :meth:`Page.setCropBox`          PDF only: modify the visible page
 :meth:`Page.setMediaBox`         PDF only: modify the mediabox
 :meth:`Page.setRotation`         PDF only: set page rotation
 :meth:`Page.showPDFpage`         PDF only: display PDF page image
 :meth:`Page.updateLink`          PDF only: modify a link
 :meth:`Page.widgets`             return a generator over the fields on the page
+:meth:`Page.writeText`           write one or more :ref:`Textwriter` objects
 :attr:`Page.CropBox`             the page's :data:`CropBox`
 :attr:`Page.CropBoxPosition`     displacement of the :data:`CropBox`
 :attr:`Page.firstAnnot`          first :ref:`Annot` on the page
@@ -394,6 +395,23 @@ This is available for PDF documents only. There are basically two groups of meth
       :returns: a :ref:`Widget` for each iteration.
 
 
+   .. method:: writeText(rect=None, writers=None, overlay=True, color=None, opacity=None, keep_proportion=True, rotate=0)
+
+      *(New in version 1.16.18)*
+      
+      PDF only: Write the text of one or more :ref:`Textwriter` ojects to the page.
+
+      :arg rect_like rect: where to place the text. If omitted, the rectangle union of the text writers is used.
+      :arg sequence writers: a non-empty tuple / list of :ref:`TextWriter` objects or a single :ref:`TextWriter`.
+      :arg float opacity: set transparency, overwrites resp. value in the text writers.
+      :arg sequ color: set the text color, overwrites  resp. value in the text writers.
+      :arg bool overlay: put the text in foreground or background.
+      :arg bool keep_proportion: maintain the aspect ratio.
+      :arg float rotate: rotate the text by an arbitrary angle.
+
+      .. note:: Parameters overlay, keep_proportion and rotate have the same meaning as in :ref:`showPDFpage`.
+
+
    .. index::
       pair: border_width; insertText
       pair: color; insertText
@@ -932,6 +950,7 @@ This is available for PDF documents only. There are basically two groups of meth
       :rtype: :ref:`Shape`
       :returns: a new :ref:`Shape` to use for compound drawings. See description there.
 
+
    .. index::
       pair: flags; searchFor
       pair: hit_max; searchFor

docs/textwriter.rst

@@ -0,0 +1,93 @@
+.. _TextWriter:
+
+================
+TextWriter
+================
+
+*(New in v1.16.18)* This class represents a MuPDF *text* object. It can be thought of as a store of text spans -- each span having its own position, font and font size. It is an elegant alternative for writing text to PDF pages, when compared with methods :meth:`Page.insertText` and friends:
+
+* **Improved text positioning:** The position of the last inserted character is returned, as well as the combined rectangle of text stored so far.
+* **Automatic fallback fonts:** If a character is not represented by the chosen font, alternative fonts are automatically checked. This significantly reduces the risk of seeing unprintable symbols in the output, so-called "TOFUs". PyMuPDF now also comes with a **"universal"** font, which supports **all Latin** characters (incuding Cyrillic and Greek), and **all CJK** characters (Chinese, Japanese, Korean).
+* **Reusability:** A TextWriter exists independent from any page. The same text can be written multiple times, to the same or other pages, same or different PDFs, choosing different colors or transparency.
+* **Transparency support:** Parameter *opacity* is supported. This offers a handy way to write watermark-style text.
+* **Justified text:** Supported for any font -- not just simple fonts as in :meth:`Page.insertText`.
+
+Using this object entails three steps:
+
+1. When **created**, a TextWriter object requires a fixed **page rectangle** in relation to which it calculates text positions. Pages with different dimensions cannot use this TextWriter object.
+2. Store text in the TextWriter using method either :meth:`TextWriter.append` or :meth:`TextWriter.fillTextbox`.
+3. Output the stored text on any PDF page with the same rectangle. This is the only point, where pages are referenced.
+
+TextWriters do not support text rotation. But the new method :meth:`Page.writeText` is able to combine one or more TextWriters and jointly write them to **any rectangle** and with **any rotation angle** -- much like :meth:`Page.showPDFpage`.
+
+**Class API**
+
+.. class:: TextWriter
+
+   .. method:: __init__(self, rect, opacity=1, color=None)
+
+      :arg rect-like rect: rectangle internally used for text positioning computations.
+      :arg float opacity: sets the transparency for the text to store here. Values outside the interval ``[0, 1)`` will be ignored. A value of e.g. 0.5 means 50% transparency.
+      :arg float,sequ color: the color of the text. All colors are specified as floats *0 <= color <= 1*. A single float represents some gray level, a sequence implies the colorspace via its length.
+
+
+   .. method:: append(pos, text, font=None, fontsize=11, language=None)
+
+      Add new text, usually (but not necessarily) representing a text span.
+
+      :arg point_like pos: start position of the text, the bottom left point of the first character.
+      :arg str text: a string (Python 2: unicode is mandatory!) of arbitrary length. It will be written starting at position "pos".
+      :arg font: a :ref:`Font`. If omitted, ``fitz.Font("helv")`` will be used.
+      :arg float fontsize: the fontsize, a positive number, default 11.
+      :arg str language: the language to use, e.g. "en" for English. Meaningful values should be compliant with the ISO 639 standards 1, 2, 3 or 5. Reserved for future use: currently has no effect as far as we know.
+
+      :returns: :attr:`textRect` and :attr:`lastPoint` after this text has been added.
+
+
+   .. method:: fillTextbox(rect, text, font="helv", fontsize=11, align=0, warn=True)
+
+      Fill a given rectangle with text. This is a convenience method to use instead of :meth:`append` (which is internally invoked).
+
+      :arg rect_like rect: the area to fill. No part of the text will appear outside of this.
+      :arg str,sequ text: the text. Can be specified as a (UTF-8) string or a list / tuple of strings. A string will first be converted to a list using *splitlines()*. Every list item will begin on a new line (forced line breaks).
+      :arg font: the :ref:`Font`
+      :arg float fontsize: the fontsize.
+      :arg int align: text alignment. Use one of TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT or TEXT_ALIGN_JUSTIFY.
+      :arg bool warn: print a warning if the area is too small, or raise an exception.
+
+   .. method:: writeText(page, opacity=None, color=None, overlay=True)
+
+      Write the accumulated text to the page.
+
+      :arg page: write to this :ref:`Page`.
+      :arg float opacity: overwrite the value of the TextWriter for this output.
+      :arg sequ color: overwrite the value of the TextWriter for this output.
+      :arg bool overlay: put in foreground (default) or background.
+
+
+   .. attribute:: textRect
+
+      The area currently occupied. This value changes when more text is added.
+
+   .. attribute:: lastPoint
+
+      The "cursor position" after the last written character.
+
+   .. attribute:: opacity
+
+      The text opacity (modifyable).
+
+   .. attribute:: color
+
+      The text color (modifyable).
+
+   .. attribute:: rect
+
+      The rectangle for which this TextWriter was created. Must not be modified.
+
+.. note::
+
+  1. Opacity and color apply to **all the text** in this object. 
+  2. If you need different colors / transpareny, you must create a separate TextWriter. Whenever you determine the color should change, simply append the text to the respective TextWriter using the previously returned :attr:`lastPoint` as position for the new text.
+  3. Appending items can occur in arbitrary order: only the position parameter controls where text appears.
+  4. Font and fontsize can freely vary within the same TextWriter. This can be used to let text with different properties appear on the same displayed line: just specify *pos* accordingly, and e.g. set it to :attr:`lastPoint` of the previously added item.

docs/version.rst

@@ -1,6 +1,6 @@
 Covered Version
 --------------------
 
-This documentation covers PyMuPDF v1.16.17 features as of **2020-03-31 08:53:33**.
+This documentation covers PyMuPDF v1.16.18 features as of **2020-04-22 14:00:00**.
 
 .. note:: The major and minor versions of **PyMuPDF** and **MuPDF** will always be the same. Only the third qualifier (patch level) may be different from that of MuPDF.