upload v1.17.2

Author: JorjMcKie

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: PyMuPDF
-Version: 1.17.1
+Version: 1.17.2
 Author: Ruikai Liu
 Author-email: [email protected]
 Maintainer: Jorj X. McKie
@@ -20,7 +20,7 @@ Description:
         Introduction
         ============
 
-        This is **version 1.17.1 of PyMuPDF**, a Python binding for `MuPDF <http://mupdf.com/>`_ - "a lightweight PDF and XPS viewer".
+        This is **version 1.17.2 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,4 +1,4 @@
-# PyMuPDF 1.17.1
+# PyMuPDF 1.17.2
 
 ![logo](https://github.com/pymupdf/PyMuPDF/blob/master/demo/pymupdf.jpg)
 
@@ -14,15 +14,15 @@ On **[PyPI](https://pypi.org/project/PyMuPDF)** since August 2016: [![](https://
 
 # Introduction
 
-This is **version 1.17.1 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.2 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.
 
-With PyMuPDF you can access files with extensions like ".pdf", ".xps", ".oxps", ".cbz", ".fb2" or ".epub". About 10 popular image formats are also supported via the document interface.
+With PyMuPDF you can access files with extensions like ".pdf", ".xps", ".oxps", ".cbz", ".fb2" or ".epub". In addition, about 10 popular image formats can also be opened and handled like documents.
 
 
 # Usage and Documentation
-For all supported document types (i.e. including images) you can
+For all supported document types (i.e. **_including images_**) you can
 * decrypt the document
 * access meta information, links and bookmarks
 * render pages in raster formats (PNG and some others), or the vector format SVG
@@ -32,14 +32,14 @@ For all supported document types (i.e. including images) you can
 
 > To some degree, PyMuPDF can therefore be used as an [image converter](https://github.com/pymupdf/PyMuPDF/wiki/How-to-Convert-Images): it can read a range of input formats and can produce **Portable Network Graphics (PNG)**, **Portable Anymaps** (**PNM**, etc.), **Portable Arbitrary Maps (PAM)**, **Adobe Postscript** and **Adobe Photoshop** documents, making the use of other graphics packages obselete in these cases. But interfacing with e.g. PIL/Pillow for image input and output is easy as well.
 
-**PDF files** can be created, joined or split up. Pages can be inserted, deleted, re-arranged or modified in many ways (including annotations and form fields).
+**PDF documents** can be created, joined or split up. Pages can be inserted, deleted, re-arranged or modified in many ways (including annotations and form fields).
 
 * Images and fonts can be extracted or inserted.
 * Embedded files are fully supported.
 * PDFs can be reformatted to support double-sided printing, posterizing, applying logos or watermarks
 * Password protection is fully supported: decryption, encryption, encryption method selection, permmission level and user / owner password setting.
 * Low-level PDF structures can be accessed and modified.
-* PyMuPDF can also be used as a **module in the command line** using ``"python -m fitz ..."``. This is a versatile utility, which we will further develop over time. It currently supports PDF document
+* PyMuPDF can also be used as a **module in the command line** using ``"python -m fitz ..."``. This is a versatile utility, which we will further develop going forward. It currently supports PDF document
 
     - **encryption / decryption / optimization**
     - creating **sub-documents**

docs/annot.rst

@@ -141,7 +141,7 @@ There is a parent-child relationship between an annotation and its page. If the
 
       :arg rect_like rect: the new rectangle of the annotation (finite and not empty). E.g. using a value of *annot.rect + (5, 5, 5, 5)* will shift the annot position 5 pixels to the right and downwards.
 
-      .. note:: You need not invoke :meth:`Annot.update` for activation of the effect.
+      .. note:: You **need not** invoke :meth:`Annot.update` for activation of the effect.
 
 
    .. method:: setRotation(angle)
@@ -196,9 +196,10 @@ There is a parent-child relationship between an annotation and its page. If the
       pair: text_color; update
       pair: border_color; update
       pair: fill_color; update
+      pair: cross_out; update
       pair: rotate; update
 
-   .. method:: update(opacity=None, blend_mode=None, fontsize=0, text_color=None, border_color=None, fill_color=None, rotate=-1)
+   .. method:: update(opacity=None, blend_mode=None, fontsize=0, text_color=None, border_color=None, fill_color=None, cross_out=True, rotate=-1)
 
       Synchronize the appearance of an annotation with its properties after any changes. 
 
@@ -223,6 +224,7 @@ There is a parent-child relationship between an annotation and its page. If the
           * 'FreeText' annotations: If you set (or leave) this to *None*, then **no rectangle at all** will be drawn around the text, and the border color will be ignored. This will leave anything "under" the text visible.
           * 'Line', 'Polyline', 'Polygon' annotations: use it to give applicable line end symbols a fill color other than that of the annotation *(changed in v1.16.16)*.
 
+      :arg bool cross_out: *(new in v1.17.2)* add two diagonal lines to the annotation rectangle. 'Redact' annotations only. If not desired, *False* must be specified even if the annotation was created with *False*.
       :arg int rotate: new rotation value. Default (-1) means no change. Supports 'FreeText' and several other annotation types (see `Annot.setRotation`), [#f1]_. Only choose 0, 90, 180, or 270 degrees for 'FreeText'. Otherwise any integer is acceptable.
 
       :rtype: bool

docs/changes.rst

@@ -1,6 +1,12 @@
 Change Logs
 ===============
 
+Changes in Version 1.17.2
+---------------------------
+* **Fixed** issue `#533 <https://github.com/pymupdf/PyMuPDF/issues/533>`_.
+* **Added** options to modify 'Redact' annotation appearance. Implements `#535 <https://github.com/pymupdf/PyMuPDF/issues/535>`_.
+
+
 Changes in Version 1.17.1
 ---------------------------
 * **Fixed** issue `#520 <https://github.com/pymupdf/PyMuPDF/issues/520>`_.

docs/conf.py

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

docs/document.rst

@@ -17,6 +17,7 @@ For addional details on **embedded files** refer to Appendix 3.
 ======================================= ==========================================================
 :meth:`Document.authenticate`           gain access to an encrypted document
 :meth:`Document.can_save_incrementally` check if incremental save is possible
+:meth:`Document.chapterPageCount`       number of pages in chapter
 :meth:`Document.close`                  close the document
 :meth:`Document.convertToPDF`           write a PDF version to memory
 :meth:`Document.copyPage`               PDF only: copy a page reference
@@ -63,6 +64,7 @@ For addional details on **embedded files** refer to Appendix 3.
 :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`
+:attr:`Document.chapterCount`           number of chapters
 :attr:`Document.FormFonts`              PDF only: list of global widget fonts
 :attr:`Document.isClosed`               has document been closed?
 :attr:`Document.isEncrypted`            document (still) encrypted?
@@ -151,13 +153,23 @@ For addional details on **embedded files** refer to Appendix 3.
         * bit 2 set => **owner** password authenticated
 
 
+    .. method:: chapterPageCount(chapter)
+
+      *(New in v.1.17.0)* Return the number of pages of a chapter.
+
+      :arg int chapter: the 0-based chapter number.
+
+      :rtype: int
+      :returns: number of pages in chapter. Relevant only for document types whith chapter support (EPUB currently).
+
+
     .. method:: nextLocation(page_id)
 
       *(New in v.1.17.0)* Return the locator of the following page.
 
       :arg tuple page_id: the current page id. This must be a tuple *(chapter, pno)* identifying an existing page.
 
-      :returns: The tuple of the following page, i.e. either *(chapter, pno + 1)* or *(chapter + 1, 0)*, **or** the empty tuple *()* if the argument was the last page.
+      :returns: The tuple of the following page, i.e. either *(chapter, pno + 1)* or *(chapter + 1, 0)*, **or** the empty tuple *()* if the argument was the last page. Relevant only for document types whith chapter support (EPUB currently).
 
 
     .. method:: previousLocation(page_id)
@@ -166,7 +178,7 @@ For addional details on **embedded files** refer to Appendix 3.
 
       :arg tuple page_id: the current page id. This must be a tuple *(chapter, pno)* identifying an existing page.
 
-      :returns: The tuple of the preceeding page, i.e. either *(chapter, pno - 1)* or the last page of the receeding chapter, **or** the empty tuple *()* if the argument was the first page.
+      :returns: The tuple of the preceeding page, i.e. either *(chapter, pno - 1)* or the last page of the receeding chapter, **or** the empty tuple *()* if the argument was the first page. Relevant only for document types whith chapter support (EPUB currently).
 
 
     .. method:: loadPage(page_id=0)
@@ -179,7 +191,7 @@ For addional details on **embedded files** refer to Appendix 3.
 
           Either a 0-based page number, or a tuple *(chapter, pno)*. For an integer, any *-inf < page_id < pageCount* is acceptable. While page_id is negative, :attr:`pageCount` will be added to it. For example: to load the last page, you can use *doc.loadPage(-1)*. After this you have page.number = doc.pageCount - 1.
 
-          For a tuple, *chapter* must be in range :attr:`Document.chapterCount`, and *pno* must be in range :meth:`Document.chapterPageCount` of that chapter. Both values are 0-based. With this notation, :attr:`Page.number` will equal the given tuple.
+          For a tuple, *chapter* must be in range :attr:`Document.chapterCount`, and *pno* must be in range :meth:`Document.chapterPageCount` of that chapter. Both values are 0-based. With this notation, :attr:`Page.number` will equal the given tuple. Relevant only for document types whith chapter support (EPUB currently).
 
       :rtype: :ref:`Page`
 
@@ -684,11 +696,11 @@ For addional details on **embedded files** refer to Appendix 3.
 
     .. method:: getSigFlags()
 
-      PDF only: Return whether the document contains signature fields.
+      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.
 
       :rtype: int
       :returns:
-         * -1: not a Form PDF or no signature fields exist.
+         * -1: not a Form PDF / no signature fields recorded / no *SigFlags* found.
          * 1: at least one signature field exists.
          * 3:  contains signatures that may be invalidated if the file is saved (written) in a way that alters its previous contents, as opposed to an incremental update.
 
@@ -932,6 +944,20 @@ For addional details on **embedded files** refer to Appendix 3.
 
       :type: int
 
+    .. Attribute:: chapterCount
+      
+      *(New in version 1.17.0)*
+      Contains the number of chapters in the document. Always at least 1. Relevant only for document types with chapter support (EPUB currently). Other documents will return 1.
+
+      :type: int
+
+    .. Attribute:: lastLocation
+
+      *(New in version 1.17.0)*
+      Contains (chapter, pno) of the document's last page. Relevant only for document types with chapter support (EPUB currently). Other documents will return *(0, len(doc) - 1)* and *(0, -1)* if it has no pages.
+
+      :type: int
+
     .. Attribute:: FormFonts
 
       A list of form field font names defined in the */AcroForm* object. *None* if not a PDF.

docs/functions.rst

@@ -42,14 +42,15 @@ Yet others are handy, general-purpose utilities.
 :meth:`getPDFnow`                    return the current timestamp in PDF format
 :meth:`getPDFstr`                    return PDF-compatible string
 :meth:`getTextlength`                return string length for a given font & fontsize
-:meth:`Page._cleanContents`          PDF only: clean the page's :data:`contents` objects
+:meth:`Page.cleanContents`           PDF only: clean the page's :data:`contents` objects
 :meth:`Page._getContents`            PDF only: return a list of content numbers
 :meth:`Page._setContents`            PDF only: set page's :data:`contents` to some :data:`xref`
 :meth:`Page.getDisplayList`          create the page's display list
 :meth:`Page.getTextBlocks`           extract text blocks as a Python list
 :meth:`Page.getTextWords`            extract text words as a Python list
 :meth:`Page.run`                     run a page through a device
-:meth:`Page._wrapContents`           wrap contents with stacking commands
+:meth:`Page.readContents`            PDF only: get complete, concatenated /Contents source
+:meth:`Page.wrapContents`            wrap contents with stacking commands
 :attr:`Page._isWrapped`              check whether contents wrapping is present
 :meth:`planishLine`                  matrix to map a line to the x-axis
 :meth:`PaperSize`                    return width, height for a known paper format
@@ -167,13 +168,13 @@ Yet others are handy, general-purpose utilities.
 
 -----
 
-   .. method:: ImageProperties(image)
+   .. method:: ImageProperties(stream)
 
       *(New in version 1.14.14)*
-      
+
       Return a number of basic properties for an image.
 
-      :arg bytes|bytearray|BytesIO|file image: an image either in memory or an **opened** file. A memory resident image maybe any of the formats *bytes*, *bytearray* or *io.BytesIO*.
+      :arg bytes|bytearray|BytesIO|file stream: an image either in memory or an **opened** file. A memory resident image maybe any of the formats *bytes*, *bytearray* or *io.BytesIO*.
 
       :returns: a dictionary with the following keys (an empty dictionary for any error):
 
@@ -185,7 +186,7 @@ Yet others are handy, general-purpose utilities.
          colorspace (int) colorspace.n (e.g. 3 = RGB)
          bpc        (int) bits per component (usually 8)
          format     (int) image format in *range(15)*
-         ext        (str) suggested image file extension for the format
+         ext        (str) image file extension indicating the format
          size       (int) length of the image in bytes
          ========== ====================================================
 
@@ -319,17 +320,17 @@ Yet others are handy, general-purpose utilities.
 
 -----
 
-   .. method:: Page._wrapContents
+   .. method:: Page.wrapContents
 
       Put string pair "q" / "Q" before, resp. after a page's */Contents* object(s) to ensure that any "geometry" changes are **local** only.
 
-      Use this method as an alternative, minimalistic version of :meth:`Page._cleanContents`. Its advantage is a small footprint in terms of processing time and impact on incremental saves.
+      Use this method as an alternative, minimalistic version of :meth:`Page.cleanContents`. Its advantage is a small footprint in terms of processing time and impact on incremental saves.
 
 -----
 
    .. attribute:: Page._isWrapped
 
-      Indicate whether :meth:`Page._wrapContents` may be required for object insertions in standard PDF geometry. Please note that this is a quick, basic check only: a value of *False* may still be a false alarm.
+      Indicate whether :meth:`Page.wrapContents` may be required for object insertions in standard PDF geometry. Please note that this is a quick, basic check only: a value of *False* may still be a false alarm.
 
 -----
 
@@ -381,14 +382,22 @@ Yet others are handy, general-purpose utilities.
 
 -----
 
-   .. method:: Page._cleanContents()
+   .. method:: Page.cleanContents()
 
       Clean and concatenate all :data:`contents` objects associated with this page. "Cleaning" includes syntactical corrections, standardizations and "pretty printing" of the contents stream. Discrepancies between :data:`contents` and :data:`resources` objects will also be corrected. See :meth:`Page._getContents` for more details.
 
       Changed in version 1.16.0 Annotations are no longer implicitely cleaned by this method. Use :meth:`Annot._cleanContents` separately.
 
       .. warning:: This is a complex function which may generate large amounts of new data and render other data unused. It is **not recommended** using it together with the **incremental save** option. Also note that the resulting singleton new */Contents* object is **uncompressed**. So you should save to a **new file** using options *"deflate=True, garbage=3"*.
 
+-----
+
+   .. method:: Page.readContents()
+
+      *New in version 1.17.0.*
+      Return the concatenation of all :data:`contents` objects associated with the page -- without cleaning or otherwise modifying them. Use this method whenever you need to parse this source in its entirety whithout having to bother how many separate contents objects exist.
+
+
 -----
 
    .. method:: Annot._cleanContents()

docs/page.rst

@@ -216,7 +216,7 @@ In a nutshell, this is what you can do with PyMuPDF:
       :rtype: :ref:`Annot`
       :returns: the created annotation. It is drawn with line color red, no fill color and line width 1.
 
-   .. method:: addRedactAnnot(quad, text=None, fontname=None, fontsize=11, align=TEXT_ALIGN_LEFT, fill=(1, 1, 1), text_color=(0, 0, 0))
+   .. method:: addRedactAnnot(quad, text=None, fontname=None, fontsize=11, align=TEXT_ALIGN_LEFT, fill=(1, 1, 1), text_color=(0, 0, 0), cross_out=True)
 
       PDF only: *(new in version 1.16.11)* Add a redaction annotation. A redaction annotation identifies content to be removed from the document. Adding such an annotation is the first of two steps. It makes visible what will be removed in the subsequent step, :meth:`Page.apply_redactions`.
 
@@ -230,12 +230,14 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :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 always (approximately) centered.
 
-      :arg sequence fill: *(New in v1.16.12)* the fill color of the rectangle after applying the redaction. The default is *white = (1, 1, 1)*, which is also taken if *None* is specified. *(Changed in v1.16.13)* To suppress any fill color, specify *False*. In this cases the rectangle remains transparent.
+      :arg sequence fill: *(New in v1.16.12)* the fill color of the rectangle **after applying** the redaction. The default is *white = (1, 1, 1)*, which is also taken if *None* is specified. *(Changed in v1.16.13)* To suppress a fill color alltogether, specify *False*. In this cases the rectangle remains transparent.
 
       :arg sequence text_color: *(New in v1.16.12)* the color of the replacing text. Default is *black = (0, 0, 0)*.
 
+      :arg bool cross_out: *(new in v1.17.2)* add two diagonal lines to the annotation rectangle.
+
       :rtype: :ref:`Annot`
-      :returns: the created annotation. The appearance of a redaction annotation cannot be changed (except for its rectangle). A redaction is displayed as a crossed-out transparent rectangle with red lines.
+      :returns: the created annotation. *(Changed in v1.17.2)* Its standard appearance looks like a red rectangle (no fill color), optionally showing two diagonal lines. Colors, line width, dashing, opacity and blend mode can now be set and applied via :meth:`Annot.update` like with other annotations.
 
       .. image:: images/img-redact.jpg