upload v1.18.5

Author: JorjMcKie

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: PyMuPDF
-Version: 1.18.4
+Version: 1.18.5
 Author: Jorj McKie
 Author-email: [email protected]
 Maintainer: Jorj 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: November 30, 2020
+        Release date: December 20, 2020
 
         Authors
         =======
@@ -20,13 +20,13 @@ Description:
         Introduction
         ============
 
-        This is **version 1.18.4 of PyMuPDF**, a Python binding for `MuPDF <http://mupdf.com/>`_ - "a lightweight PDF and XPS viewer".
+        This is **version 1.18.5 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.
 
         With PyMuPDF you therefore can access files with extensions ``*.pdf``, ``*.xps``, ``*.oxps``, ``*.epub``, ``*.cbz`` or ``*.fb2`` from your Python scripts. A number of popular image formats is supported as well, including multi-page TIFF images.
 
-        PyMuPDF should run on all platforms that are supported by both, MuPDF and Python. These include, but are not limited to, Windows (XP/SP2 and up), Mac OSX and Linux, 32-bit or 64-bit. If you can generate MuPDF on a Python supported platform, then also PyMuPDF can be used there.
+        PyMuPDF should run on all platforms that are supported by both, MuPDF and Python 3.6+. These include, but are not limited to, Windows, Mac OSX and Linux, 32-bit or 64-bit. If you can generate MuPDF on a Python supported platform, then also PyMuPDF can be used there.
 
         PyMuPDF is hosted on `GitHub <https://github.com/pymupdf/PyMuPDF>`_ where you find up-to-date information of its features, our `issue tracker <https://github.com/pymupdf/PyMuPDF/issues>`_, `Wikis <https://github.com/pymupdf/PyMuPDF/wiki>`_ and much more.
 
@@ -66,6 +66,5 @@ Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: C
-Classifier: Programming Language :: Python :: 2.7
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Utilities

README.md

@@ -1,8 +1,8 @@
-# PyMuPDF 1.18.4
+# PyMuPDF 1.18.5
 
 ![logo](https://github.com/pymupdf/PyMuPDF/blob/master/demo/pymupdf.jpg)
 
-Release date: November 30, 2020
+Release date: December 20, 2020
 
 **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: [![](https://
 
 # Introduction
 
-This is **version 1.18.4 of PyMuPDF**, a Python binding with support for [MuPDF 1.18.*](http://mupdf.com/) - "a lightweight PDF, XPS, and E-book viewer".
+This is **version 1.18.5 of PyMuPDF**, a Python binding with support for [MuPDF 1.18.*](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.
 
@@ -61,10 +61,7 @@ Our **documentation**, written using Sphinx, is available in various formats fro
 
 # Installation
 
-For Windows, Linux and Mac OSX platforms, there are wheels in the [download](https://pypi.org/project/PyMuPDF/#files) section of PyPI. This includes Python 64bit versions 3.6 through 3.9. For Windows only, 32bit versions are available too.
-
-> Wheels for **Python versions 2.7 and 3.5** will only be produced until the end of this year 2020. After that, you will need to build PyMuPDF from sources as explained below.
-> Starting immediately, we **_defer uploading Python 2.7 / 3.5 wheels_** until explicitely requested. Please submit an issue.
+For Windows, Linux and Mac OSX platforms, there are wheels in the [download](https://pypi.org/project/PyMuPDF/#files) section of PyPI. This includes Python 64bit versions **3.6 through 3.9**. For Windows only, 32bit versions are available too.
 
 If your platform is not supported with one of our wheels, you need to generate PyMuPDF yourself as follows. This requires the development version of Python.
 
@@ -77,10 +74,10 @@ Before you can do that, you must first build MuPDF. For most platforms, the MuPD
 
   - Now MuPDF can be generated.
 
-* Since PyMuPDF v1.14.17, the sources provided in this repository **no longer contain** the interface files ``fitz.py`` and ``fitz.wrap.c`` - they are instead generated **"on the fly"** by ``setup.py`` using the interface generator [SWIG](http://www.swig.org/). So you need SWIG on your system. Please refer to issue #312 for some background.
+* Please note that you will need the interface generator [SWIG](http://www.swig.org/) when building PyMuPDF from the sources of this repository (please refer to issue #312 for some background on this).
     - PyMuPDF wheels are being generated using **SWIG v4.0.1**.
 
-* If you do **not use SWIG**, please download the **sources from PyPI** - they continue to contain those generated files, so installation should work like any other Python extension generation on your system.
+* If you do **not use SWIG**, please download the **sources from PyPI** - they contain sources pre-processed by SWIG, so installation should work like any other Python extension generation on your system.
 
 Once this is done, adjust directories in ``setup.py`` and run ``python setup.py install``.
 

docs/annot.rst

@@ -31,6 +31,7 @@ There is a parent-child relationship between an annotation and its page. If the
 :meth:`Annot.set_border`           set annotation's border properties
 :meth:`Annot.set_blendmode`        set annotation's blend mode
 :meth:`Annot.set_colors`           set annotation's colors
+:meth:`Annot.set_flags`            set annotation's flags field
 :meth:`Annot.set_name`             set annotation's name field
 :meth:`Annot.set_oc`               set :data:`xref` to an :data:`OCG` / :data:`OCMD`
 :meth:`Annot.set_opacity`          change transparency
@@ -264,20 +265,22 @@ There is a parent-child relationship between an annotation and its page. If the
 
    .. method:: set_flags(flags)
 
-      Changes the annotation flags. Use the *|* operator to combine several.
+      Changes the annotation flags. Use the ``|`` operator to combine several.
 
       :arg int flags: an integer specifying the required flags.
 
    .. method:: set_colors(colors=None, stroke=None, fill=None)
 
-      Changes the "stroke" and "fill" colors for supported annotation types.
+      Changes the "stroke" and "fill" colors for supported annotation types -- not all annotations accept both.
 
       *Changed in version 1.16.9:* Allow colors to be directly set. These parameters are used if *colors* is not a dictionary.
 
       :arg dict colors: a dictionary containing color specifications. For accepted dictionary keys and values see below. The most practical way should be to first make a copy of the *colors* property and then modify this dictionary as required.
       :arg sequence stroke: see above.
       :arg sequence fill: see above.
 
+      *Changed in v1.18.5:* To completely remove a color specification, use an empty sequence like ``[]``. 
+
 
    .. method:: delete_responses()
 

docs/changes.rst

@@ -1,6 +1,23 @@
 Change Logs
 ===============
 
+Changes in Version 1.18.5
+-------------------------
+Apart from several fixes, this version also focusses on several minor, but important feature improvements. Among the latter is a more precise computation of proper line heights and insertion points for writing / inserting text. As opposed to using font-agnostic constants, these values are now taken from the font's properties.
+
+Also note that this is the first version which does no longer provide pregenerated wheels for Python versions older than 3.6. PIP also discontinues support for these by end of this year 2020.
+
+* **Fixed** issue `#771 <https://github.com/pymupdf/PyMuPDF/issues/771>`_. By using "small glyph heights" option, the full page text can be extracted.
+* **Fixed** issue `#768 <https://github.com/pymupdf/PyMuPDF/issues/768>`_.
+* **Fixed** issue `#750 <https://github.com/pymupdf/PyMuPDF/issues/750>`_.
+* **Fixed** issue `#739 <https://github.com/pymupdf/PyMuPDF/issues/739>`_. The "dict", "rawdict" and corresponding JSON output variants now have two new *span* keys: ``"ascender"`` and ``"descender"``. These floats represent special font properties which can be used to compute bboxes of spans or characters of **exactly fontsize height** (as opposed to the default line height). An example algorithm is shown in section "Span Dictionary" `here <https://pymupdf.readthedocs.io/en/latest/textpage.html#dictionary-structure-of-extractdict-and-extractrawdict>`_. Also improved the detection and correction of ill-specified ascender / descender values encountered in some fonts.
+* **Added** a new, experimental :meth:`Tools.set_small_glyph_heights` -- also in response to issue `#739 <https://github.com/pymupdf/PyMuPDF/issues/739>`_. This method sets or unsets a global parameter to **always compute bboxes with fontsize height**. If "on", text searching and all text extractions will returned rectangles, bboxes and quads with a smaller height.
+* **Fixed** issue `#728 <https://github.com/pymupdf/PyMuPDF/issues/728>`_.
+* **Changed** fill color logic of 'Polyline' annotations: this parameter now only pertains to line end symbols -- the annotation itself can no longer have a fill color. Also addresses issue `#727 <https://github.com/pymupdf/PyMuPDF/issues/727>`_.
+* **Changed** :meth:`Page.getImageBbox` to also compute the bbox if the image is contained in an XObject.
+* **Changed** :meth:`Shape.insertTextbox`, resp. :meth:`Page.insertTextbox`, resp. :meth:`TextWriter.fillTextbox` to respect font's properties "ascender" / "descender" when computing line height and insertion point. This should no longer lead to line overlaps for multi-line output. These methods used to ignore font specifics and used constant values instead.
+
+
 Changes in Version 1.18.4
 ---------------------------
 This version adds several features to support PDF Optional Content. Among other things, this includes OCMDs (Optional Content Membership Dictionaries) with the full scope of *"visibility expressions"* (PDF key ``/VE``), text insertions (including the :ref:`TextWriter` class) and drawings.

docs/conf.py

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

docs/document.rst

@@ -8,7 +8,7 @@ Document
 
 This class represents a document. It can be constructed from a file or from memory.
 
-Since version 1.9.0 there exists the alias *open* for this class, i.e. ``fitz.Document(...)`` and ``fitz.open(...)`` do exactly the same thing.
+There exists the alias *open* for this class, i.e. ``fitz.Document(...)`` and ``fitz.open(...)`` do exactly the same thing.
 
 For details on **embedded files** refer to Appendix 3.
 
@@ -262,39 +262,44 @@ For details on **embedded files** refer to Appendix 3.
 
       Create or update an :data:`OCMD` (optional content membership dictionary).
 
+      :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", "AnyOff", "AllOn", "AllOff" (mixed or lower case).
-      :arg int xref: :data:`xref` of an existing OCMD, which should be updated, or 0 for a new OCMD.
+      :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 entry for ``oc`` parameter in supporting objects.
+      :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::
 
-        This object type can be used like an :data:`OCG` to determine the visibility of a PDF object. Its purpose is to **compute a boolean value** from the states of some OCGs. This value is then interpreted as ON (true) or OFF (false).
-        
-        * Using the combination of *ocgs* and *policy*: The possible *policy* values are as follows:
+        The purpose of OCMDs is to more flexibly determine visibility. An OCMD actually is a boolean expression: it evaluates the current visibility of one or more optional content groups and then computes its own ON (true) or OFF (false) state.
+
+        There are two ways to formulate the OCMD's 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.
 
-          For example assume you want two PDF objects be displayed exactly one at a time (if one is ON, then the other one must be off): use an OCG for object 1 and an OCMD for object 2. Create the OCMD via ``set_ocmd(ocgs=[xref], policy="AllOff")``, where *xref* is the cross reference number of the OCG.
+          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.
 
-        * Using the visibility expression *ve*: This is a list of arbitrarily nested other lists. It uses a combination of the logical expressions **"and"**, **"or"**, **"not"**, and the :data:`xref` numbers of one or more existing OCGs. The arguments *ocgs* and *policy* need not be used. The syntax of this parameter is a bit awkward, but quite powerful:
+        2. Use the **visibility expression** *ve*: This is a list of a logical expression keyword (string) followed by integers or other lists. The possible logical expressions are **"and"**, **"or"**, and **"not"**. The integers must be :data:`xref` numbers of OCGs. The syntax of this parameter is a bit awkward, but quite powerful:
 
-          - Each list, including the top one, must have two or more items. The fist item must be a logical expression.
-          - If the first item is a **"not"**, then the list must have exactly two items.
-          - If the first item is **"and"** or **"or"**, any number of other items may follow.
-          - Items following the logical expression may be either integers or other lists. An *integer* must be the xref of an OCG. A list must conform to the rules layed out so far.
+          - Each list, including the top one, must start with a logical expression.
+          - If the first item 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 expression may be either integers or other lists. An *integer* must be the xref of an OCG. A *list* must conform to the rules above.
 
           **Examples:**
 
-          - ``ve=["or", 4, ["not", 5], ["and", 6, 7]]``. This delivers ON if 4 is ON, or 5 is OFF, or 6 and 7 are both ON.
-          - ``ve=["not", xref]`` has the same effect like previously using *ocgs* and *policy*.
+          - ``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.
+
+          For more details and examples see page 367 of :ref:`AdobeManual`. Also do have a look at example scripts `here <https://github.com/pymupdf/PyMuPDF-Utilities/tree/master/optional-content>`_.
 
-          For more details and examples see page 367 of :ref:`AdobeManual`.
+          Visibility expressions, ``/VE``, are part of the PDF version 1.6 specification. If you are using an older PDF consumer software, you hence may find it unsupported (i.e. ignored).
 
 
     .. method:: get_ocmd(xref)
@@ -305,7 +310,7 @@ For details on **embedded files** refer to Appendix 3.
 
       :arg int xref: the :data:`xref` of the OCMD.
       :rtype: dict
-      :returns: a dictionary with the keys *ocgs*, *policy* and *ve*.
+      :returns: a dictionary with the keys *xref*, *ocgs*, *policy* and *ve*.
 
 
     .. method:: get_oc_states(config=-1)
@@ -397,9 +402,9 @@ For details on **embedded files** refer to Appendix 3.
       Modify OC visibility status of content groups. This is analog to what supporting PDF viewers would offer.
 
       .. note::
-        Visibility is **not** a property of an OCG. Current visibility is not even an information that is necessarily present in the PDF document. Using this method, the user can **temporarily** modify visibility just as if doing so via a supporting PDF consumer software.
+        Visibility is **not** a property stored with the OCG. It is not even an 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.
 
-        To make permanent changes, use :meth:`Document.set_oc_states`.
+        To make **permanent** changes, use :meth:`Document.set_oc_states`.
 
       :arg in number: number as returned by :meth:`Document.layer_ui_configs`.
       :arg int action: 0 = set on (default), 1 = toggle on/off, 2 = set off.