Font and Image lists, plus several bug fixes

- list fonts and images per PDF page
- new Pixmap constructors
- setToC now supports GoToR, Launch and URI entries
- Pixmap now correctly handles unsupported colorspaces

doc/html/_sources/changes.txt

@@ -2,24 +2,34 @@
 
     PageBreak
 
-This version of PyMuPDF is based on MuPDF library source code version 1.9a published on April 21, 2016.
-
-Please have a look at MuPDF's website to see which changes and enhancements are contained herein.
-
 Changes in Version 1.9.2
 =========================
-This version is based on MuPDF v1.9a, too. Changes compared to version 1.9.1 are:
+This version is also based on MuPDF v1.9a. Changes compared to version 1.9.1:
 
-* :ref:`Document` now accepts all of the following formats (``Document`` and ``open`` are synonyms) ``open()``, ``open(filename)``, ``open(filename, None)``, ``open(filetype, stream)``, ``open(filetype, stream = area)``. Type of memory area ``stream`` may be ``str`` (Python 2), ``bytes`` (Python 3) or ``bytearray`` (Python 2 and 3). Thus, e.g. ``stream = open("file.pdf", "rb").read()`` may be used directly, without first converting it to ``bytearray``.
+* ``fitz.open()`` (no parameters) creates a new empty **PDF** document. If saved afterwards, it must be given a ``.pdf`` extension.
+* :ref:`Document` now accepts all of the following formats (``Document`` and ``open`` are synonyms):
 
-* New method ``Document.insertPDF()`` (PDFs only) inserts a range of pages from another PDF.
+  - ``open()``,
+  - ``open(filename)`` (equivalent to ``open(filename, None)``),
+  - ``open(filetype, area)`` (equivalent to ``open(filetype, stream = area)``).
 
-* ``Document`` objects ``doc`` now support the ``len()`` function: ``len(doc) == doc.pageCount``.
+  Type of memory area ``stream`` may be ``str`` (Python 2), ``bytes`` (Python 3) or ``bytearray`` (Python 2 and 3). Thus, e.g. ``stream = open("file.pdf", "rb").read()`` may be used directly (without first converting it to bytearray).
+* New method ``Document.insertPDF()`` (PDFs only) inserts a range of pages from another PDF.
+* ``Document`` objects doc now support the ``len()`` function: ``len(doc) == doc.pageCount``.
+* New method ``Document.getPageImageList()`` creates a list of images used on a page.
+* New method ``Document.getPageFontList()`` creates a list of fonts referenced by a page.
+* New pixmap constructor ``fitz.Pixmap(doc, xref)`` creates a pixmap based on an opened PDF document and an XREF number of the image.
+* New pixmap constructor ``fitz.Pixmap(cspace, spix)`` creates a pixmap as a copy of another one ``spix`` with the colorspace converted to ``cspace``. This works for all colorspace combinations.
+* Pixmap constructor ``fitz.Pixmap(colorspace, width, height, samples)`` now allows ``samples`` to also be ``str`` (Python 2) or ``bytes`` (Python 3), not only ``bytearray``.
 
 
 Changes in Version 1.9.1
 =========================
-Changes compared to version 1.8.0:
+This version of PyMuPDF is based on MuPDF library source code version 1.9a published on April 21, 2016.
+
+Please have a look at MuPDF's website to see which changes and enhancements are contained herein.
+
+Changes in version 1.9.1 compared to version 1.8.0 are the following:
 
 * New methods ``getRectArea()`` for both ``fitz.Rect`` and ``fitz.IRect``
 * Pixmaps can now be created directly from files using the new constructor ``fitz.Pixmap(filename)``.

doc/html/_sources/functions.txt

@@ -2,23 +2,22 @@
 
     PageBreak
 
-=============================
-Other Functions
-=============================
-
-The following lists miscellaneous functions. Some of them are directly available under the binding name, i.e. can be invoked as ``fitz.function``. Others represent low-level code to be used by experienced users.
-
-============================================ ===================================================
-**Function**                                 **Short Description**
-============================================ ===================================================
-:meth:`getPointDistance`                     calculates the distance between two points
-:meth:`Document._getPageObjNumber`           returns a pages XREF and generation number
-:meth:`Document._getObjectString`            returns the string representing an object
-:meth:`Document._getNewXref`                 creates and returns a new entry in the XREF
-:meth:`Document._updateObject`               inserts or updates a PDF object
-:meth:`Document._getXrefLength`              returns the length of the PDF XREF
-:meth:`Document._getOLRootNumber`            returns / creates the outline root XREF
-============================================ ===================================================
+============
+Functions
+============
+The following are miscellaneous functions either directly available under the binding name, i.e. can be invoked as ``fitz.function``, or to be used by the experienced PDF programmer.
+
+==================================== ==============================================
+**Function**                         **Short Description**
+==================================== ==============================================
+:meth:`getPointDistance`             calculates the distance between to points
+:meth:`Document._getPageObjNumber()` returns a pages XREF and generation number
+:meth:`Document._getObjectString()`  returns the string representing an object
+:meth:`Document._getNewXref()`       creates and returns a new entry in the XREF
+:meth:`Document._updateObject()`     inserts or updates a PDF object
+:meth:`Document._getXrefLength()`    returns the length of the PDF XREF
+:meth:`Document._getOLRootNumber()`  returns / creates the outline root XREF
+==================================== ==============================================
 
 
    .. method:: getPointDistance(p1, p2, unit = "pt")
@@ -40,38 +39,38 @@ The following lists miscellaneous functions. Some of them are directly available
 
       PDF documents only: Returns the XREF and generation number for a given page.
 
-      :param `pno`: Page number (zero-based).
-      :type `pno`: int
+      :param `pno`: Page number (zero-baed).
+      :type `pno`: int.
 
       :rtype: list
-      :returns: a list ``[xref, gen]`` of integers.
+      :returns: XREF and generation number of page ``pno`` as a list ``[xref, gen]``.
 
    .. method:: Document._getObjectString(xref)
 
       PDF documents only: Returns the string representing an arbitrary object.
 
-      :param `xref`: xref number.
-      :type `xref`: int
+      :param `xref`: XREF number.
+      :type `xref`: int.
 
       :rtype: string
-      :returns: a string that defines the object identified by its xref entry.
+      :returns: the string defining the object identified by ``xref``.
 
    .. method:: Document._getNewXref()
 
-      PDF documents only: Increases the XREF by one entry and returns the XREF number.
+      PDF documents only: Increases the XREF by one entry and returns the entry's number.
 
       :rtype: int
       :returns: the number of the new XREF entry.
 
    .. method:: Document._updateObject(xref, obj_str)
 
-      PDF documents only: Associates the object identified by string ``obj_str`` with the XREF number ``xref``. If the XREF entry already pointed to an object, then the new object will replace it.
+      PDF documents only: Associates the object identified by string ``obj_str`` with the XREF number ``xref``. If ``xref`` already pointed to an object, it will be replaced by the new object.
 
-      :param `xref`: xref number.
-      :type `xref`: int
+      :param `xref`: XREF number.
+      :type `xref`: int.
 
       :param `obj_str`: a string containing a valid PDF object definition.
-      :type `obj_str`: str
+      :type `obj_str`: str.
 
       :rtype: int
       :returns: zero if successful, otherwise an exception will be raised.
@@ -85,44 +84,41 @@ The following lists miscellaneous functions. Some of them are directly available
 
    .. method:: Document._getOLRootNumber()
 
-      PDF documents only: Returns the XREF number of the /Outlines root object (this is **not** the first outline entry!). If this object does not exist, a new one will be created.
+      PDF documents only:  Returns the XREF number of the /Outlines root object (this is **not** the first outline entry!). If this object does not exist, a new one will be created.
 
       :rtype: int
-      :returns: XREF number of the /Outlines root object.
-
+      :returns: XREF number of the **/Outlines** root object.
 
 Example
 --------
-This demonstrates how some of the above functions could be used to update a pages rotation:
+This demonstrates how some of the above functions could be used to update a page's rotation:
 ::
  >>> import fitz
- >>> doc = fitz.open("PyMuPDF.pdf")              # open document
- >>> pix = doc.getPagePixmap(5)                  # get pixmap of page 6
- >>> pix.w                                       # show its dimensions: 596 x 842
+ >>> doc = fitz.open("PyMuPDF.pdf") # open document
+ >>> pix = doc.getPagePixmap(5) # get pixmap of page 6
+ >>> pix.w # show its dimensions: 596 x 842
  596
  >>> pix.h
  842
- >>> pix = None                                  # delete pixmap
- >>> doc._getPageObjNumber(5)                    # get XREF of that page
+ >>> pix = None # delete pixmap
+ >>> doc._getPageObjNumber(5) # get XREF of that page
  [213, 0]
- >>> p_str = doc._getObjectString(213)           # get string of its object
+ >>> p_str = doc._getObjectString(213) # get string of its object
  >>> p_str
  '<</Type/Page/Contents 214 0 R/Resources 212 0 R/MediaBox[0 0 595.276 841.89]
  /Parent 1257 0 R/Annots[209 0 R 210 0 R]>>'
- >>> p_str_new = p_str[:-2] + "/Rotate 90>>"     # insert a rotation
+ >>> p_str_new = p_str[:-2] + "/Rotate 90>>" # insert a rotation
  >>> p_str_new
  '<</Type/Page/Contents 214 0 R/Resources 212 0 R/MediaBox[0 0 595.276 841.89]
  /Parent 1257 0 R/Annots[209 0 R 210 0 R]/Rotate 90>>'
  >>>
- >>> doc._updateObject(213, p_str_new)           # update the page object
+ >>> doc._updateObject(213, p_str_new) # update the page object
  0
- >>> doc._getObjectString(213)                   # get string again to demo the effect
+ >>> doc._getObjectString(213) # get string again to demo the effect
  '<</Type/Page/Contents 214 0 R/Resources 212 0 R/MediaBox[0 0 595.276 841.89]
  /Parent 1257 0 R/Annots[209 0 R 210 0 R]/Rotate 90>>'
- >>> pix = doc.getPagePixmap(5)                  # get pixmap of this page again
- >>> pix.w                                       # dimension is now indeed 842 x 596
+ >>> pix = doc.getPagePixmap(5) # get pixmap of this page again
+ >>> pix.w # dimension is now indeed 842 x 596
  842
  >>> pix.h
  596
- >>>
-

doc/html/_sources/identity.txt

@@ -16,5 +16,4 @@ If you need a do-nothing matrix as a starting point, use ``fitz.Matrix(1, 1)`` o
 ::
  >>> fitz.Matrix(0).preTranslate(2, 5)
  fitz.Matrix(1.0, 0.0, -0.0, 1.0, 2.0, 5.0)
- >>>
 

doc/html/_sources/linkdest.txt

@@ -9,7 +9,6 @@ linkDest
 ================
 Class representing the `dest` property of an outline entry or a link. Describes the link to which such entries point.
 
-
 =========================== ====================================
 **Attribute**               **Short Description**
 =========================== ====================================
@@ -33,19 +32,19 @@ Class representing the `dest` property of an outline entry or a link. Describes
 
    .. attribute:: dest
 
-      Target destination name if specified (only if :attr:`linkDest.kind` == :data:`LINK_GOTOR`).
+      Target destination name if :attr:`linkDest.kind` is :data:`LINK_GOTOR` and :attr:`linkDest.page` is ``-1``.
 
       :rtype: string
 
    .. attribute:: fileSpec
 
-      Contains the filename (including any path specifications) this link points to, if applicable (only if :attr:`linkDest.kind` == :data:`LINK_GOTOR` or :attr:`linkDest.kind` == :data:`LINK_LAUNCH`).
+      Contains the filename and path this link points to, if :attr:`linkDest.kind` is :data:`LINK_GOTOR` or :data:`LINK_LAUNCH`.
 
       :rtype: string
 
    .. attribute:: flags
 
-      A one-byte bitfield consisting of indicators describing the validity and meaning of the different aspects of the destination. As far as possible, link destinations are constructed such that e.g. :attr:`linkDest.lt` and :attr:`linkDest.rb` can be treated as defining a bounding box, though the validity flags (see ``LINK_FLAG_*`` values) indicate which of the values were actually specified. Note that the numerical values for each of the LINK_FLAGs are powers of 2 and thus indicate the position of the bit to be tested. More than one bit can be ``True``, so do not test for the value of the integer.
+      A bitfield describing the validity and meaning of the different aspects of the destination. As far as possible, link destinations are constructed such that e.g. :attr:`linkDest.lt` and :attr:`linkDest.rb` can be treated as defining a bounding box. But the flags indicate which of the values were actually specified, see :ref:`linkDest Flags`.
 
       :rtype: int
 
@@ -57,13 +56,13 @@ Class representing the `dest` property of an outline entry or a link. Describes
 
    .. attribute:: isUri
 
-      Specifies whether this destination is an internet resource.
+      Specifies whether this destination is an internet resource (as opposed to e.g. a local file specification in URI format).
 
       :rtype: bool
 
    .. attribute:: kind
 
-      Indicates the type of this destination, like a place in this document, a URI, a file launch, an action or a place in another file. Look at index entries ``FZ_LINK_*`` to see the names and numerical values.
+      Indicates the type of this destination, like a place in this document, a URI, a file launch, an action or a place in another file. Look at :ref:`linkDest Kinds` to see the names and numerical values.
 
       :rtype: int
 
@@ -75,7 +74,7 @@ Class representing the `dest` property of an outline entry or a link. Describes
 
    .. attribute:: named
 
-      This destination refers to some named action to perform (e.g. a javascript, see Adobe PDF documentation).
+      This destination refers to some named action to perform (e.g. a javascript, see Adobe PDF documentation). Standard actions provided are ``NextPage``, ``PrevPage``, ``FirstPage``,  and ``LastPage``.
 
       :rtype: string
 
@@ -87,7 +86,7 @@ Class representing the `dest` property of an outline entry or a link. Describes
 
    .. attribute:: page
 
-      The page number (in this or the target document) this destination points to. Only set if :attr:`linkDest.kind` = :data:`LINK_GOTOR` or :attr:`linkDest.kind` = :data:`LINK_GOTO`. Can be ``-1`` if :attr:`linkDest.kind` = :data:`LINK_GOTOR`, in which case :attr:`linkDest.dest` determines where to go (to be resolved by target document).
+      The page number (in this or the target document) this destination points to. Only set if :attr:`linkDest.kind` is :data:`LINK_GOTOR` or :data:`LINK_GOTO`. May be ``-1`` if :attr:`linkDest.kind` is :data:`LINK_GOTOR`. In this case :attr:`linkDest.dest` contains the **name** of a destination in the target document.
 
       :rtype: int
 
@@ -102,4 +101,3 @@ Class representing the `dest` property of an outline entry or a link. Describes
       The name of the URI this destination points to.
 
       :rtype: string
-

doc/html/_sources/matrix.txt

@@ -204,7 +204,7 @@ This makes the following operations possible:
  >>>
  >>> m90p * m90p * m90p * m90p         # should be 360 degrees = fitz.Identity
  fitz.Matrix(1.0, -0.0, 0.0, 1.0, 0.0, 0.0)
- >>>
+
 
 Examples
 -------------