upload docu for v1.17.5

Author: JorjMcKie

docs/changes.rst

@@ -1,6 +1,17 @@
 Change Logs
 ===============
 
+Changes in Version 1.17.5
+---------------------------
+* **Fixed** issue `#561 <https://github.com/pymupdf/PyMuPDF/issues/561>`_ -- second go: certain :ref:`TextWriter` usages with many alternating fonts did not work correctly.
+* **Fixed** issue `#566 <https://github.com/pymupdf/PyMuPDF/issues/566>`_.
+* **Fixed** issue `#568 <https://github.com/pymupdf/PyMuPDF/issues/568>`_.
+* **Fixed** -- opacity is now correctly taken from the :ref:`TextWriter` object, if not given in :meth:`TextWriter.writeText`.
+* **Added** a new global attribute :attr:`fitz_fontdescriptors`. Contains information about usable fonts from repository `pymupdf-fonts <https://github.com/pymupdf/pymupdf-fonts>`_.
+* **Added** :meth:`Font.valid_codepoints` which returns an array of unicode codepoints for which the font has a glyph.
+* **Added** option ``text_as_path`` to :meth:`Page.getSVGimage`. this implements `#580 <https://github.com/pymupdf/PyMuPDF/issues/580>`_. Generates much smaller SVG files with parseable text if set to *False*.
+
+
 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.

docs/conf.py

@@ -17,13 +17,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    "sphinx.ext.autodoc",
-    # "sphinx.ext.todo",
-    "sphinx.ext.coverage",
-    "sphinx.ext.ifconfig",
-    # "sphinx.ext.imgmath",
-]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.coverage", "sphinx.ext.ifconfig"]
+if sys.platform == "win32":
+    extensions.extend(["sphinx.ext.autodoc", "rst2pdf.pdfbuilder"])
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -46,7 +42,7 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = "1.17.4"
+release = "1.17.5"
 
 # The short X.Y version
 version = release
@@ -222,7 +218,7 @@
 pdf_documents = [("index", "PyMuPDF", "PyMuPDF Manual", "Jorj McKie")]
 
 # A comma-separated list of custom stylesheets. Example:
-pdf_stylesheets = ["sphinx", "bahnschrift"]
+pdf_stylesheets = ["sphinx", "bahnschrift", "a4"]
 
 # Create a compressed PDF
 pdf_compressed = True

docs/font.rst

@@ -18,11 +18,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".
+      :arg str fontname: one of the :ref:`Base-14-Fonts` or CJK fontnames. Also possible are a select few other names like (watch the correct spelling): "Arial", "Times", "Times Roman".
 
-         *(Changed in v1.17.4)*
+         *(Changed in v1.17.5)*
 
-         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.
+         If you have installed `pymupdf-fonts <https://pypi.org/project/pymupdf-fonts/>`_, there are also new "reserved" fontnames available, which are listed in :attr:`fitz_fonts` and in the table further down.
 
       :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]_.
@@ -54,7 +54,10 @@ A Font object also contains useful general information, like the font bbox, the
 
       .. note::
 
-        With the usual abbreviations "helv", "tiro", etc., you will create fonts with the expected names "Helvetica", "Times-Roman" and so on.
+        With the usual reserved names "helv", "tiro", etc., you will create fonts with the expected names "Helvetica", "Times-Roman" and so on. **However**, and in contrast to :meth:`Page.insertFont` and friends,
+
+         * a font file will **always** be embedded in your PDF,
+         * Greek and Cyrillic characters are supported without needing the *encoding* parameter.
 
         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**.
 
@@ -64,30 +67,75 @@ A Font object also contains useful general information, like the font bbox, the
 
         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).
 
-        *(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:
+        *(New in v1.17.5)* Optionally, some new "reserved" fontnames become available if you install `pymupdf-fonts <https://pypi.org/project/pymupdf-fonts/>`_. **"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** it provides the style variants bold, italic, bold-italic.
+
+        **"Space Mono"** is another nice and small fixed-width font from Google Fonts, which supports Latin Extended characters.
 
-            =========== =======================================
-            Fontname    Font
-            =========== =======================================
-            figo        FiraGO Regular
-            figbo       FiraGO Bold
-            figit       FiraGO Italic
-            figbi       FiraGO Bold Italic
-            fimo        Fira Mono Regular
-            fimbo       Fira Mono Bold
-            =========== =======================================
+        The following table maps a fontname to the corresponding font:
 
-        **All fonts mentioned here** also support Greek and Cyrillic letters.
+            =========== =========================== ==============
+            Fontname    Font                        Added in
+            =========== =========================== ==============
+            figo        FiraGO Regular              v1.0.0
+            figbo       FiraGO Bold                 v1.0.0
+            figit       FiraGO Italic               v1.0.0
+            figbi       FiraGO Bold Italic          v1.0.0
+            fimo        Fira Mono Regular           v1.0.0
+            fimbo       Fira Mono Bold              v1.0.0
+            spacemo     Space Mono Regular          v1.0.1
+            spacembo    Space Mono Bold             v1.0.1
+            spacemit    Space Mono Italic           v1.0.1
+            spacembi    Space Mono Bold-Italic      v1.0.1
+            math        Noto Sans Math Regular      v1.0.2
+            music       Noto Music Regular          v1.0.2
+            symbol1     Noto Sans Symbols Regular   v1.0.2
+            symbol2     Noto Sans Symbols2 Regular  v1.0.2
+            =========== =========================== ==============
 
-   .. method:: has_glyph(chr, language=None, script=0)
+
+   .. method:: has_glyph(chr, language=None, script=0, fallback=False)
 
       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.
+      :arg bool fallback: *(new in v1.17.5)* perform an extended search in fallback fonts or restrict to current font (default).
       :returns: *True* or *False*.
 
+   .. method:: valid_codepoints()
+
+      *(New in v1.17.5)* Return an array of unicodes which are supported by this font.
+
+      :returns: an *array.array* [#f2]_ of length :attr:`Font.glyph_count` (or less). I.e. *chr()* of every item in this array will be found in the font without using fallbacks. This is an example display of the supported glyphs:
+
+         >>> import fitz
+         >>> font = fitz.Font("math")
+         >>> vuc = font.valid_codepoints()
+         >>> for i in vuc:
+               print("%04X %s (%s)" % (i, chr(i), font.unicode_to_glyph_name(i)))
+         0000
+         000D   (CR)
+         0020   (space)
+         0021 ! (exclam)
+         0022 " (quotedbl)
+         0023 # (numbersign)
+         0024 $ (dollar)
+         0025 % (percent)
+         ...
+         00AC ¬ (logicalnot)
+         00B1 ± (plusminus)
+         ...
+         21D0 ⇐ (arrowdblleft)
+         21D1 ⇑ (arrowdblup)
+         21D2 ⇒ (arrowdblright)
+         21D3 ⇓ (arrowdbldown)
+         21D4 ⇔ (arrowdblboth)
+         ...
+         221E ∞ (infinity)
+         ...
+
+
    .. method:: glyph_advance(chr, language=None, script=0, wmode=0)
 
       Calculate the "width" of the character's glyph (visual representation).
@@ -104,7 +152,11 @@ A Font object also contains useful general information, like the font bbox, the
 
       :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.
+      :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. Example:
+
+         >>> font = fitz.Font("helv")
+         >>> font.has_glyph(font.glyph_name_to_unicode("infinity"))
+         True
 
    .. method:: unicode_to_glyph_name(chr, language=None, script=0, wmode=0)
 
@@ -139,3 +191,5 @@ A Font object also contains useful general information, like the font bbox, the
 .. 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.
+
+.. [#f2] Builtin module *array* has been chosen for its speed and its compact representation of values with an identical type.

docs/functions.rst

@@ -173,6 +173,29 @@ Yet others are handy, general-purpose utilities.
 
       A dictionary of pre-defines paper formats. Used as basis for :meth:`PaperSize`.
 
+-----
+
+   .. attribute:: fitz_fontdescriptors
+
+      *(New in v1.17.5)*
+
+      A dictionary of usable fonts from repository `pymupdf-fonts <https://pypi.org/project/pymupdf-fonts/>`_. Items are keyed by their reserved fontname and provide information like this::
+
+         In [2]: fitz.fitz_fontdescriptors.keys()
+         Out[2]: dict_keys(['figbo', 'figo', 'figbi', 'figit', 'fimbo', 'fimo',
+         'spacembo', 'spacembi', 'spacemit', 'spacemo', 'math', 'music', 'symbol1',
+         'symbol2'])
+         In [3]: fitz.fitz_fontdescriptors["fimo"]
+         Out[3]:
+         {'name': 'Fira Mono Regular',
+         'size': 125712,
+         'mono': True,
+         'bold': False,
+         'italic': False,
+         'serif': True,
+         'glyphs': 1485}
+         
+
 -----
 
    .. method:: getPDFnow()

docs/page.rst

@@ -234,17 +234,19 @@ In a nutshell, this is what you can do with PyMuPDF:
       :arg str fontname: *(New in v1.16.12)* the font to use when *text* is given, otherwise ignored. The same rules apply as for :meth:`Page.insertTextbox` -- which is the method :meth:`Page.apply_redactions` internally invokes. The replacement text will be **vertically centered**, if this is one of the CJK or :ref:`Base-14-Fonts`.
 
          .. note::
-            For an **existing** font of the page, use its reference name as *fontname* (*item[4]* of its entry in :meth:`Page.getFontList`). To use a new, non-builtin font, proceed as follows::
+
+            * For an **existing** font of the page, use its reference name as *fontname* (this is *item[4]* of its entry in :meth:`Page.getFontList`).
+            * For a **new, non-builtin** font, proceed as follows::
 
                page.insertText(point,  # anywhere, but outside all redaction rectangles
-               "somthing",  # some non-empty string
-               fontname="newname",  # new, unused reference name
-               fontfile="...",  # desired font file
-               render_mode=3,  # makes the text invisible
+                   "somthing",  # some non-empty string
+                   fontname="newname",  # new, unused reference name
+                   fontfile="...",  # desired font file
+                   render_mode=3,  # makes the text invisible
                )
                page.addRedactAnnot(..., fontname="newname")
 
-      :arg float fontsize: *(New in v1.16.12)* the fontsize to use for the replacing text. If the text is too large to fit, several insertion attempts will be made, gradually reducing this value down to 4. If then the text will still not fit, no text insertion will take place at all.
+      :arg float fontsize: *(New in v1.16.12)* the fontsize to use for the replacing text. If the text is too large to fit, several insertion attempts will be made, gradually reducing the fontsize to no less than 4. If then the text will still not fit, no text insertion will take place at all.
 
       :arg int align: *(New in v1.16.12)* the horizontal alignment for the replacing text. See :meth:`insertTextbox` for available values. The vertical alignment is (approximately) centered if a PDF built-in font is used (CJK or :ref:`Base-14-Fonts`).
 
@@ -831,8 +833,8 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :rtype: :ref:`Rect`
       :returns: the boundary box of the image.
-         *(Changed in version 1.16.7)* If the page in fact does not display this image, an infinite rectangle is returned now. In previous versions, an exception was raised.
-         *(Changed in version 1.17.0)* Only images referenced directly by the page are considered. This means that images occurring in embedded PDF pages are ignored and an exception is raised.
+         *(Changed in v1.16.7)* -- If the page in fact does not display this image, an infinite rectangle is returned now. In previous versions, an exception was raised.
+         *(Changed in v.17.0)* -- Only images referenced directly by the page are considered. This means that images occurring in embedded PDF pages are ignored and an exception is raised.
 
       .. note::
 
@@ -842,11 +844,12 @@ In a nutshell, this is what you can do with PyMuPDF:
    .. index::
       pair: matrix; getSVGimage
 
-   .. method:: getSVGimage(matrix=fitz.Identity)
+   .. method:: getSVGimage(matrix=fitz.Identity, text_as_path=True)
 
       Create an SVG image from the page. Only full page images are currently supported.
 
      :arg matrix_like matrix: a matrix, default is :ref:`Identity`.
+     :arg bool text_as_path: *(new in v1.17.5)* -- controls how text is represented. *True* outputs each character as a series of elementary draw commands, which leads to a more precise text display in browsers, but a **very much larger** output for text-oriented pages. Display quality for *False* relies on the presence of the referenced fonts on the current system. For missing fonts, the internet browser will fall back to some default -- leading to unpleasant appearances. Choose *False* if you want to parse the text of the SVG.
 
      :returns: a UTF-8 encoded string that contains the image. Because SVG has XML syntax it can be saved in a text file with extension *.svg*.
 
@@ -1012,7 +1015,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :arg str text: Text to search for. Upper / lower case is ignored. The string may contain spaces.
 
-      :arg int hit_max: Maximum number of occurrences accepted.
+      :arg int hit_max: Maximum number of returned occurrences.
       :arg bool quads: Return :ref:`Quad` instead of :ref:`Rect` objects.
       :arg int flags: Control the data extracted by the underlying :ref:`TextPage`. Default is 0 (ligatures are dissolved, white space is replaced with space and excessive spaces are not suppressed).
 
@@ -1022,6 +1025,10 @@ In a nutshell, this is what you can do with PyMuPDF:
 
         .. note:: In this way, the effect supports multi-line text marker annotations.
 
+        .. note:: The number of returned objects will never exceed *hit_max*. Hence, if the returned list has this many items, you cannot know whether there really exist more on the page. So please make sure you provide a hit_max value which is large enough.
+
+        .. note:: Please also be aware of a trickier aspect: the search logic regards **contiguous multiple** occurrences of the search string as one: assuming your search string is "abc", and the page contains "abc" and "abcabc", then only **two** rectangles will be returned, one containing "abc", and a second one containing "abcabc".
+
 
    .. method:: setMediaBox(r)
 
@@ -1217,7 +1224,7 @@ This is an overview of homologous methods on the :ref:`Document` and on the :ref
 *Document.searchPageFor(pno, ...)*     :meth:`Page.searchFor`
 ====================================== =====================================
 
-The page number "pno"` is a 0-based integer *-inf < pno < pageCount*.
+The page number "pno" is a 0-based integer *-inf < pno < pageCount*.
 
 .. note::
 

docs/pixmap.rst

@@ -307,7 +307,9 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
 
    ..  method:: pillowData(*args, **kwargs)
 
-      Return the pixmap as a bytes object in the specified format using Pillow. For example ``stream = pix.pillowData(format="JPEG", optimize=True)``. For details on possible parameters see the Pillow documentation.
+      *(New in v1.17.3)*
+
+      Return an image as a bytes object in the specified format using Pillow. For example ``stream = pix.pillowData(format="JPEG", optimize=True)``. Also see above. For details on possible parameters see the Pillow documentation.
 
 
    .. attribute:: alpha

docs/version.rst

@@ -1,6 +1,6 @@
 Covered Version
 --------------------
 
-This documentation covers PyMuPDF v1.17.4 features as of **2020-07-20 18:09:40**.
+This documentation covers PyMuPDF v1.17.5 features as of **2020-08-06 06:31:06**.
 
 .. note:: The major and minor versions of **PyMuPDF** and **MuPDF** will always be the same. Only the third qualifier (patch level) may deviate from that of MuPDF.