upload v1.18.1

Author: JorjMcKie

README.md

@@ -62,17 +62,16 @@ Our **documentation**, written using Sphinx, is available in various formats fro
 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. Please submit an issue to request one of them.
+> Starting immediately, we **_defer uploading Python 2.7 / 3.5 wheels_** until explicitely requested. Please submit an issue.
 
 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.
 
 Before you can do that, you must first build MuPDF. For most platforms, the MuPDF sources contain prepared procedures for achieving this. Please observe the following general steps:
 
 * Be sure to download the **_official MuPDF source release_** from [here](https://mupdf.com/downloads/archive). Do not use MuPDF's [GitHub repo](https://github.com/ArtifexSoftware/mupdf). It contains their development source for future versions.
 
-* This repo's [fitz](https://github.com/pymupdf/PyMuPDF/tree/master/fitz) folder contains one or more files whose names start with a single underscore `"_"`. These files contain configuration data and other fixes or extensions. Each of them must be copy-renamed to their correct target location within the downloaded MuPDF. Currently, these files are:
-  - fitz configuration file `_config.h` copy-replace to: `mupdf/include/mupdf/fitz/config.h`. It contains configuration data like e.g. which fonts to support.
-  - font support file `_pdf-font-add.c` copy-replace to: `mupdf/source/pdf/pdf-font-add.c`.
+* This repo's [fitz](https://github.com/pymupdf/PyMuPDF/tree/master/fitz) folder contains one or more files whose names start with a single underscore `"_"`. These files contain configuration data and potentially other fixes. Copy-rename each of them to their correct target location within the downloaded MuPDF source. Currently, these files are:
+  - **Optional:** fitz configuration file `_config.h` copy-replace to: `mupdf/include/mupdf/fitz/config.h`. It contains configuration data like e.g. which fonts to support. If omitting this change, the binary extension module will be over 30 MB (compared to around 11 MB). Does not impact functionality.
 
   - Now MuPDF can be generated.
 

docs/annot.rst

@@ -18,6 +18,7 @@ There is a parent-child relationship between an annotation and its page. If the
 :meth:`Annot.setBlendMode`      set the annotation's blend mode
 :meth:`Annot.delete_responses`  delete all responding annotions
 :meth:`Annot.fileGet`           return attached file content
+:meth:`Annot.soundGet`          return the sound of an audio annotation
 :meth:`Annot.fileInfo`          return attached file information
 :meth:`Annot.fileUpd`           set attached file new content
 :meth:`Annot.getPixmap`         image of the annotation as a pixmap
@@ -310,9 +311,28 @@ There is a parent-child relationship between an annotation and its page. If the
 
       :arg str desc: new description of the file content.
 
+   .. method:: soundGet()
+
+      Return the embedded sound of an audio annotation.
+
+      :rtype: dict
+      :returns: the sound audio file and accompanying properties. These are the possible dictionary keys, of which "rate" and "stream" are always present.
+
+        =========== =======================================================
+        Key         Description
+        =========== =======================================================
+        rate        (float, requ.) samples per second
+        channels    (int, opt.) number of sound channels
+        bps         (int, opt.) bits per sample value per channel
+        encoding    (str, opt.) encoding format: Raw, Signed, muLaw, ALaw
+        compression (str, opt.) name of compression filter
+        stream      (bytes, requ.) the sound file content
+        =========== =======================================================
+
+
    .. attribute:: opacity
 
-      The annotation's transparency. If set, it is a value in range *[0, 1]*. The PDF default is *1.0*. However, in an effort to tell the difference, we return *-1.0* if not set.
+      The annotation's transparency. If set, it is a value in range *[0, 1]*. The PDF default is 1. However, in an effort to tell the difference, we return *-1.0* if not set.
 
       :rtype: float
 

docs/changes.rst

@@ -1,6 +1,14 @@
 Change Logs
 ===============
 
+Changes in Version 1.18.1
+---------------------------
+* **Fixed** issue `#692 <https://github.com/pymupdf/PyMuPDF/issues/692>`_. PyMuPDF now detects and recovers from more cyclic resource dependencies in PDF pages and for the first time reports them in the MuPDF warnings store.
+* **Fixed** issue `#686 <https://github.com/pymupdf/PyMuPDF/issues/686>`_.
+* **Added** opacity options for the :ref:`Shape` class: Stroke and fill colors can now be set to some transparency value. This means that all :ref:`Page` draw methods, methods :meth:`Page.insertText`, :meth:`Page.insertTextbox`, :meth:`Shape.finish`, :meth:`Shape.insertText`, and :meth:`Shape.insertTextbox` support two new parameters: *stroke_opacity* and *fill_opacity*.
+* **Added** new parameter ``mask`` to :meth:`Page.insertImage` for optionally providing an external image mask. Resolves issue `#685 <https://github.com/pymupdf/PyMuPDF/issues/685>`_.
+* **Added** :meth:`Annot.soundGet` for extracting the sound of an audio annotation.
+
 Changes in Version 1.18.0
 ---------------------------
 This is first PyMuPDF version supporting MuPDF v1.18. The goal here is on extending PyMuPDF's own functionality -- apart from bug fixing. Subsequent PyMuPDF patches may address features new in MuPDF.

docs/conf.py

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

docs/installation.rst

@@ -25,7 +25,7 @@ On occasion, vital hot fixes or functional enhancements must be applied to MuPDF
 
 Any such files are contained in the *fitz* directory of the `PyMuPDF homepage <https://github.com/pymupdf/PyMuPDF/tree/master/fitz>`_ -- their names all start with an underscore *"_"*. Currently (v1.16.x), these files and their copy destinations are the following:
 
-* *_config.h* -- PyMuPDF's configuration to control the binary file size and the inclusion of MuPDF features, see next section. This file must renamed and replace MuPDF file */include/mupdf/fitz/config.h*. This file controls the size of the PyMuPDF binary by cutting away unneeded fonts from MuPDF.
+* *_config.h* -- **(Optional)** PyMuPDF's configuration to control the binary file size. Copy-rename it to */include/mupdf/fitz/config.h*. This reduces the size of the PyMuPDF binary extension module to around 11 MB. If omitting this change, that size will be over 30 MB -- without impacting functionality.
 
 **Generate MuPDF**
 
@@ -37,7 +37,7 @@ Step 3: Build / Setup PyMuPDF
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Adjust the setup.py script as necessary. E.g. make sure that:
 
-  * the include directory is correctly set in sync with your directory structure
+  * the include directories are correctly set in sync with your directory structure
   * the object code libraries are correctly defined
 
 Now perform a *python setup.py install*.
@@ -50,9 +50,11 @@ Now perform a *python setup.py install*.
 Option 2: Install from Binaries
 --------------------------------
 You can install PyMuPDF from Python wheels. The wheels are *self-contained*, i.e. you will **not need any other software** nor download / install MuPDF to run PyMuPDF scripts.
-This installation option is available for all MS Windows and the most **popular 64-bit** Mac OSX and Linux platforms for Python versions 2.7 and 3.5 through 3.8.
+This installation option is available for all MS Windows and the most **popular 64-bit** Mac OSX and Linux platforms for Python versions 3.6 through 3.9.
 Windows binaries are provided for Python **32-bit and 64-bit** versions.
 
+.. note:: For the time being, wheels for Python versions 2.7 and 3.5 are generated as well, but not uploaded to PyPI until explicitely requested via an issue. Starting year 2021, support for these wheel versions will be dropped entirely.
+
 **Overview of wheel names (PyMuPDF version is x.xx.xx):**
 
 .. literalinclude:: wheelnames.txt