diff --git a/changes.txt b/changes.txt index 75c11cfc9..6b064bf4a 100644 --- a/changes.txt +++ b/changes.txt @@ -49,7 +49,7 @@ Other: * Added support for radio button groups. * Added support for widget aliases. * Fixed builds with swig-4.5. -* Fixed `https://bugs.ghostscript.com/show_bug.cgi?id=709683`_ Path Traversal and Arbitrary File Write in PyMuPDF CLI Font Extraction (CVE-2026-82035) +* Fixed ``_ Path Traversal and Arbitrary File Write in PyMuPDF CLI Font Extraction (CVE-2026-82035) * Fixed ignoring aspect ratio for square images. * Fixed potential SEGV in pymupdf.Page.get_cdrawings() if callback raises exception. * Fixed use with python-3.15. @@ -406,7 +406,7 @@ Other: * Added miter_limit arg to insert_text*() to allow suppression of spikes caused by long miters. * Add Widget Support to `Document.insert_pdf()`. * Add `bibi` to span dicts. - * Add `synthetic' to char dict. + * Add `synthetic` to char dict. * Fixed Pyodide builds. diff --git a/docs/conf.py b/docs/conf.py index 4bc78ac0f..b02046ad1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -132,6 +132,14 @@ # If true, keep warnings as "system message" paragraphs in the built documents. keep_warnings = False + +# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings +suppress_warnings = [ + 'ref.any', + 'toc.not_included', + 'ref.ref', + ] + # Localization vars gettext_uuid = True diff --git a/docs/document.rst b/docs/document.rst index bf5c4969f..3db5ccf41 100644 --- a/docs/document.rst +++ b/docs/document.rst @@ -643,35 +643,35 @@ For details on **embedded files** refer to Appendix 3. .. note:: - Like an OCG, an OCMD has a visibility state ON or OFF, and it can be used like an OCG. In contrast to an OCG, the OCMD state is determined by evaluating the state of one or more OCGs via special forms of **boolean expressions.** If the expression evaluates to true, the OCMD state is ON and OFF for false. + Like an OCG, an OCMD has a visibility state ON or OFF, and it can be used like an OCG. In contrast to an OCG, the OCMD state is determined by evaluating the state of one or more OCGs via special forms of **boolean expressions.** If the expression evaluates to true, the OCMD state is ON and OFF for false. - There are two ways to formulate OCMD visibility: + There are two ways to formulate OCMD visibility: - 1. Use the combination of *ocgs* and *policy*: The *policy* value is interpreted as follows: + 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. + - 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. - Suppose you want two PDF objects be displayed exactly one at a time (if one is ON, then the other one must be OFF): + 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. + 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. - 2. Use the **visibility expression** *ve*: This is a list of two or more items. The **first item** is a logical keyword: one of the strings **"and"**, **"or"**, or **"not"**. The **second** and all subsequent items must either be an integer or another list. An integer must be the :data:`xref` number of an OCG. A list must again have at least two items starting with one of the boolean keywords. This syntax is a bit awkward, but quite powerful: + 2. Use the **visibility expression** *ve*: This is a list of two or more items. The **first item** is a logical keyword: one of the strings **"and"**, **"or"**, or **"not"**. The **second** and all subsequent items must either be an integer or another list. An integer must be the :data:`xref` number of an OCG. A list must again have at least two items starting with one of the boolean keywords. This syntax is a bit awkward, but quite powerful: - - Each list must start with a logical keyword. - - If the keyword 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 keyword may be either integers or again a list. An *integer* must be the xref of an OCG. A *list* must conform to the previous rules. + - Each list must start with a logical keyword. + - If the keyword 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 keyword may be either integers or again a list. An *integer* must be the xref of an OCG. A *list* must conform to the previous rules. - **Examples:** + **Examples:** - - `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. + - `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 224 of :ref:`AdobeManual`. Also do have a look at example scripts `here `_. + For more details and examples see page 224 of :ref:`AdobeManual`. Also do have a look at example scripts `here `_. - Visibility expressions, `/VE`, are part of PDF specification version 1.6. So not all PDF viewers / readers may already support this feature and hence will react in some standard way for those cases. + Visibility expressions, `/VE`, are part of PDF specification version 1.6. So not all PDF viewers / readers may already support this feature and hence will react in some standard way for those cases. .. method:: get_ocmd(xref) @@ -746,12 +746,13 @@ For details on **embedded files** refer to Appendix 3. * Only reports items contained in the currently selected layer configuration. * The meaning of the dictionary keys is as follows: - - *depth:* item's nesting level in the `/Order` array - - *locked:* true if cannot be changed via user interfaces - - *number:* running sequence number - - *on:* item state - - *text:* text string or name field of the originating OCG - - *type:* one of "label" (set by a text string), "checkbox" (set by a single OCG) or "radiobox" (set by a set of connected OCGs) + + - *depth:* item's nesting level in the `/Order` array + - *locked:* true if cannot be changed via user interfaces + - *number:* running sequence number + - *on:* item state + - *text:* text string or name field of the originating OCG + - *type:* one of "label" (set by a text string), "checkbox" (set by a single OCG) or "radiobox" (set by a set of connected OCGs) .. method:: set_layer_ui_config(number, action=0) @@ -822,8 +823,8 @@ For details on **embedded files** refer to Appendix 3. For example:: - [{'startpage': 6, 'prefix': 'A-', 'style': 'D', 'firstpagenum': 10}, - {'startpage': 10, 'prefix': '', 'style': 'D', 'firstpagenum': 1}] + [{'startpage': 6, 'prefix': 'A-', 'style': 'D', 'firstpagenum': 10}, + {'startpage': 10, 'prefix': '', 'style': 'D', 'firstpagenum': 1}] will generate the labels "A-10", "A-11", "A-12", "A-13", "1", "2", "3", ... for pages 6, 7 and so on until end of document. Pages 0 through 5 will have the label "". @@ -947,31 +948,31 @@ For details on **embedded files** refer to Appendix 3. :: - options.bitonal_image_recompress_method = FZ_RECOMPRESS_NEVER - options.bitonal_image_recompress_quality = None - options.bitonal_image_subsample_method = FZ_SUBSAMPLE_AVERAGE - options.bitonal_image_subsample_threshold = 0 - options.bitonal_image_subsample_to = 0 - options.color_lossless_image_recompress_method = FZ_RECOMPRESS_NEVER - options.color_lossless_image_recompress_quality = None - options.color_lossless_image_subsample_method = FZ_SUBSAMPLE_AVERAGE - options.color_lossless_image_subsample_threshold = 0 - options.color_lossless_image_subsample_to = 0 - options.color_lossy_image_recompress_method = FZ_RECOMPRESS_NEVER - options.color_lossy_image_recompress_quality = None - options.color_lossy_image_subsample_method = FZ_SUBSAMPLE_AVERAGE - options.color_lossy_image_subsample_threshold = 0 - options.color_lossy_image_subsample_to = 0 - options.gray_lossless_image_recompress_method = FZ_RECOMPRESS_NEVER - options.gray_lossless_image_recompress_quality = None - options.gray_lossless_image_subsample_method = FZ_SUBSAMPLE_AVERAGE - options.gray_lossless_image_subsample_threshold = 0 - options.gray_lossless_image_subsample_to = 0 - options.gray_lossy_image_recompress_method = FZ_RECOMPRESS_NEVER - options.gray_lossy_image_recompress_quality = None - options.gray_lossy_image_subsample_method = FZ_SUBSAMPLE_AVERAGE - options.gray_lossy_image_subsample_threshold = 0 - options.gray_lossy_image_subsample_to = 0 + options.bitonal_image_recompress_method = FZ_RECOMPRESS_NEVER + options.bitonal_image_recompress_quality = None + options.bitonal_image_subsample_method = FZ_SUBSAMPLE_AVERAGE + options.bitonal_image_subsample_threshold = 0 + options.bitonal_image_subsample_to = 0 + options.color_lossless_image_recompress_method = FZ_RECOMPRESS_NEVER + options.color_lossless_image_recompress_quality = None + options.color_lossless_image_subsample_method = FZ_SUBSAMPLE_AVERAGE + options.color_lossless_image_subsample_threshold = 0 + options.color_lossless_image_subsample_to = 0 + options.color_lossy_image_recompress_method = FZ_RECOMPRESS_NEVER + options.color_lossy_image_recompress_quality = None + options.color_lossy_image_subsample_method = FZ_SUBSAMPLE_AVERAGE + options.color_lossy_image_subsample_threshold = 0 + options.color_lossy_image_subsample_to = 0 + options.gray_lossless_image_recompress_method = FZ_RECOMPRESS_NEVER + options.gray_lossless_image_recompress_quality = None + options.gray_lossless_image_subsample_method = FZ_SUBSAMPLE_AVERAGE + options.gray_lossless_image_subsample_threshold = 0 + options.gray_lossless_image_subsample_to = 0 + options.gray_lossy_image_recompress_method = FZ_RECOMPRESS_NEVER + options.gray_lossy_image_recompress_quality = None + options.gray_lossy_image_subsample_method = FZ_SUBSAMPLE_AVERAGE + options.gray_lossy_image_subsample_threshold = 0 + options.gray_lossy_image_subsample_to = 0 The ``*_recompress_method`` attributes may be one of the values **FZ_RECOMPRESS_NEVER (0), FZ_RECOMPRESS_SAME (1), FZ_RECOMPRESS_LOSSLESS (2), FZ_RECOMPRESS_JPEG (3), FZ_RECOMPRESS_J2K (4), FZ_RECOMPRESS_FAX (5)**. Value FZ_RECOMPRESS_NEVER will skip this image type altogether and FZ_RECOMPRESS_SAME will not change the type. The other values will execute type conversions (as far as technically possible). @@ -1022,10 +1023,11 @@ For details on **embedded files** refer to Appendix 3. * *value*: (dict) with the following layout: * "page": target page number (0-based). If no page number found -1. * "to": (x, y) target point on page. Currently in PDF coordinates, - i.e. point (0,0) is the bottom-left of the page. + i.e. point (0,0) is the bottom-left of the page. * "zoom": (float) the zoom factor. * "dest": (str) only present if the target location on the page has - not been provided as "/XYZ" or if no page number was found. + not been provided as "/XYZ" or if no page number was found. + Examples:: { @@ -1530,20 +1532,20 @@ For details on **embedded files** refer to Appendix 3. Collapse everything below top level and show the chapter on Python support in red, bold and italic:: - >>> import pymupdf - >>> doc=pymupdf.open("SWIGDocumentation.pdf") - >>> toc = doc.get_toc(False) # we need the detailed TOC - >>> # list of level 1 indices and their titles - >>> lvl1 = [(i, item[1]) for i, item in enumerate(toc) if item[0] == 1] - >>> for i, title in lvl1: - d = toc[i][3] # get the destination dict - d["collapse"] = True # collapse items underneath - if "Python" in title: # show the 'Python' chapter - d["color"] = (1, 0, 0) # in red, - d["bold"] = True # bold and - d["italic"] = True # italic - doc.set_toc_item(i, dest_dict=d) # update this toc item - >>> doc.save("NEWSWIG.pdf",garbage=3,deflate=True) + >>> import pymupdf + >>> doc=pymupdf.open("SWIGDocumentation.pdf") + >>> toc = doc.get_toc(False) # we need the detailed TOC + >>> # list of level 1 indices and their titles + >>> lvl1 = [(i, item[1]) for i, item in enumerate(toc) if item[0] == 1] + >>> for i, title in lvl1: + d = toc[i][3] # get the destination dict + d["collapse"] = True # collapse items underneath + if "Python" in title: # show the 'Python' chapter + d["color"] = (1, 0, 0) # in red, + d["bold"] = True # bold and + d["italic"] = True # italic + doc.set_toc_item(i, dest_dict=d) # update this toc item + >>> doc.save("NEWSWIG.pdf",garbage=3,deflate=True) In the previous example, we have changed only 42 of the 1240 TOC items of the file. @@ -1660,7 +1662,7 @@ For details on **embedded files** refer to Appendix 3. See: :ref:`Compressing Files ` for full details on this parameter. :arg bool raise_on_repair: *(new in v1.27.0)* If true we raise an exception if the save caused a repair. - This is useful because repairs can cause changes to be lost. + This is useful because repairs can cause changes to be lost. Also see `Document.repair()`. @@ -1671,14 +1673,14 @@ For details on **embedded files** refer to Appendix 3. .. note:: - **File size reduction** + **File size reduction** - 1. Use the save options like `garbage=3|4, deflate=True, use_objstms=True|1`. Do not touch the default values `expand=False|0, clean=False|0, incremental=False|0, linear=False|0`. - This is a "lossless" file size reduction. There is a convenience version of this method with these values set by default, :meth:`Document.ez_save` -- please see below. + 1. Use the save options like `garbage=3|4, deflate=True, use_objstms=True|1`. Do not touch the default values `expand=False|0, clean=False|0, incremental=False|0, linear=False|0`. + This is a "lossless" file size reduction. There is a convenience version of this method with these values set by default, :meth:`Document.ez_save` -- please see below. - 2. "Lossy" file size reduction in essence must give up something with respect to images, like (a) remove all images (b) replace images by their grayscale versions (c) reduce image resolutions. Find examples in the `PyMuPDF Utilities "replace-image" folder `_. + 2. "Lossy" file size reduction in essence must give up something with respect to images, like (a) remove all images (b) replace images by their grayscale versions (c) reduce image resolutions. Find examples in the `PyMuPDF Utilities "replace-image" folder `_. - See: :ref:`Compressing Files ` for more. + See: :ref:`Compressing Files ` for more. @@ -1856,23 +1858,23 @@ For details on **embedded files** refer to Appendix 3. .. note:: - *(Changed in v1.14.17, optimized in v1.17.7)* In an effort to maintain a valid PDF structure, this method and :meth:`delete_page` will also deactivate items in the table of contents which point to deleted pages. "Deactivation" here means, that the bookmark will point to nowhere and the title will be shown grayed-out by supporting PDF viewers. The overall TOC structure is left intact. + *(Changed in v1.14.17, optimized in v1.17.7)* In an effort to maintain a valid PDF structure, this method and :meth:`delete_page` will also deactivate items in the table of contents which point to deleted pages. "Deactivation" here means, that the bookmark will point to nowhere and the title will be shown grayed-out by supporting PDF viewers. The overall TOC structure is left intact. - It will also remove any **links on remaining pages** which point to a deleted one. This action may have an extended response time for documents with many pages. + It will also remove any **links on remaining pages** which point to a deleted one. This action may have an extended response time for documents with many pages. - Following examples will all delete pages 500 through 519: + Following examples will all delete pages 500 through 519: - * `doc.delete_pages(500, 519)` - * `doc.delete_pages(from_page=500, to_page=519)` - * `doc.delete_pages((500, 501, 502, ... , 519))` - * `doc.delete_pages(range(500, 520))` - * `del doc[500:520]` - * `del doc[(500, 501, 502, ... , 519)]` - * `del doc[range(500, 520)]` + * `doc.delete_pages(500, 519)` + * `doc.delete_pages(from_page=500, to_page=519)` + * `doc.delete_pages((500, 501, 502, ... , 519))` + * `doc.delete_pages(range(500, 520))` + * `del doc[500:520]` + * `del doc[(500, 501, 502, ... , 519)]` + * `del doc[range(500, 520)]` - For the :ref:`AdobeManual` the above takes about 0.6 seconds, because the remaining 1290 pages must be cleaned from invalid links. + For the :ref:`AdobeManual` the above takes about 0.6 seconds, because the remaining 1290 pages must be cleaned from invalid links. - In general, the performance of this method is dependent on the number of remaining pages -- **not** on the number of deleted pages: in the above example, **deleting all pages except** those 20, will need much less time. + In general, the performance of this method is dependent on the number of remaining pages -- **not** on the number of deleted pages: in the above example, **deleting all pages except** those 20, will need much less time. .. method:: copy_page(pno, to=-1) @@ -1920,8 +1922,8 @@ For details on **embedded files** refer to Appendix 3. :rtype: bool :returns: - * None: not a Form PDF, or property not defined. - * True / False: the value of the property (either just set or existing for inquiries). Has no effect if no Form PDF. + * None: not a Form PDF, or property not defined. + * True / False: the value of the property (either just set or existing for inquiries). Has no effect if no Form PDF. @@ -1931,9 +1933,9 @@ For details on **embedded files** refer to Appendix 3. :rtype: int :returns: - * -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. + * -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. .. index:: pair: filename; Document.embfile_add @@ -2179,7 +2181,8 @@ For details on **embedded files** refer to Appendix 3. .. note:: There is a functional overlap with *pix = pymupdf.Pixmap(doc, xref)*, followed by a *pix.tobytes()*. Main differences are that extract_image, **(1)** does not always deliver PNG image formats, **(2)** is **very** much faster with non-PNG images, **(3)** usually results in much less disk storage for extracted images, **(4)** returns `None` in error cases (generates no exception). Look at the following example images within the same PDF. - * xref 1268 is a PNG -- Comparable execution time and identical output:: + * xref 1268 is a PNG -- Comparable execution time and identical output:: text + In [23]: %timeit pix = pymupdf.Pixmap(doc, 1268);pix.tobytes() 10.8 ms ± 52.4 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) @@ -2191,7 +2194,7 @@ For details on **embedded files** refer to Appendix 3. In [26]: len(img["image"]) Out[26]: 21462 - * xref 1186 is a JPEG -- :meth:`Document.extract_image` is **many times faster** and produces a **much smaller** output (2.48 MB vs. 0.35 MB):: + * xref 1186 is a JPEG -- :meth:`Document.extract_image` is **many times faster** and produces a **much smaller** output (2.48 MB vs. 0.35 MB):: text In [27]: %timeit pix = pymupdf.Pixmap(doc, 1186);pix.tobytes() 341 ms ± 2.86 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) @@ -2232,8 +2235,8 @@ For details on **embedded files** refer to Appendix 3. .. warning:: The basename is returned unchanged from the PDF. So it may contain characters (such as blanks) which may disqualify it as a filename for your operating system. Take appropriate action. .. note:: - * The returned *basename* in general is **not** the original file name, but it probably has some similarity. - * If parameter `named == True`, a dictionary with the following keys is returned: `{'name': 'T1', 'ext': 'n/a', 'type': 'Type3', 'content': b''}`. + * The returned *basename* in general is **not** the original file name, but it probably has some similarity. + * If parameter `named == True`, a dictionary with the following keys is returned: `{'name': 'T1', 'ext': 'n/a', 'type': 'Type3', 'content': b''}`. .. method:: xref_xml_metadata() diff --git a/docs/font.rst b/docs/font.rst index 53580aea2..a5d34025e 100644 --- a/docs/font.rst +++ b/docs/font.rst @@ -43,15 +43,15 @@ A ``Font`` object also contains useful general information, like the font bbox, .. class:: Font .. index:: - pair: Font, fontfile - pair: Font, fontbuffer - pair: Font, script - pair: Font, ordering - pair: Font, is_bold - pair: Font, is_italic - pair: Font, is_serif - pair: Font, fontname - pair: Font, language + pair: Font; fontfile + pair: Font; fontbuffer + pair: Font; script + pair: Font; ordering + pair: Font; is_bold + pair: Font; is_italic + pair: Font; is_serif + pair: Font; fontname + pair: Font; language .. method:: __init__(self, fontname=None, fontfile=None, fontbuffer=None, script=0, language=None, ordering=-1, is_bold=0, @@ -132,9 +132,9 @@ A ``Font`` object also contains useful general information, like the font bbox, =========== =========================== ======= ============================= .. index:: - pair: Font.has_glyph, language - pair: Font.has_glyph, script - pair: Font.has_glyph, fallback + pair: Font.has_glyph; language + pair: Font.has_glyph; script + pair: Font.has_glyph; fallback .. method:: has_glyph(chr, language=None, script=0, fallback=False) @@ -183,9 +183,9 @@ A ``Font`` object also contains useful general information, like the font bbox, .. note:: This method only returns meaningful data for fonts having a CMAP (character map, charmap, the `/ToUnicode` PDF key). Otherwise, this array will have length 1 and contain zero only. .. index:: - pair: Font.glyph_advance, language - pair: Font.glyph_advance, script - pair: Font.glyph_advance, wmode + pair: Font.glyph_advance; language + pair: Font.glyph_advance; script + pair: Font.glyph_advance; wmode .. method:: glyph_advance(chr, language=None, script=0, wmode=0) @@ -211,8 +211,8 @@ A ``Font`` object also contains useful general information, like the font bbox, True .. index:: - pair: Font.glyph_bbox, language - pair: Font.glyph_bbox, script + pair: Font.glyph_bbox; language + pair: Font.glyph_bbox; script .. method:: glyph_bbox(chr, language=None, script=0) @@ -234,7 +234,7 @@ A ``Font`` object also contains useful general information, like the font bbox, .. note:: *(Changed in v1.18.0)* This method and :meth:`Font.glyph_name_to_unicode` no longer depend on a font and instead retrieve information from the **Adobe Glyph List**. Also available as `pymupdf.unicode_to_glyph_name()` and resp. `pymupdf.glyph_name_to_unicode()`. .. index:: - pair: text_length, fontsize + pair: text_length; fontsize .. method:: text_length(text, fontsize=11) @@ -258,7 +258,7 @@ A ``Font`` object also contains useful general information, like the font bbox, For multi-character strings, the method offers a huge performance advantage compared to the previous implementation: instead of about 0.5 microseconds for each character, only 12.5 nanoseconds are required for the second and subsequent ones. .. index:: - pair: char_lengths, fontsize + pair: char_lengths; fontsize .. method:: char_lengths(text, fontsize=11) diff --git a/docs/index.rst b/docs/index.rst index 1b6720709..a788dbe1a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -91,6 +91,7 @@ This documentation covers all versions up to |version|. znames.rst | + ---- diff --git a/docs/installation.rst b/docs/installation.rst index 55894c551..7e5838b64 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -226,8 +226,8 @@ Notes Build and install from a local PyMuPDF source tree --------------------------------------------------------- -Initial setup: - +Initial setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Install C/C++ development tools as described above. * Enter a Python venv and update pip, as described above. @@ -241,41 +241,59 @@ Initial setup: Or download and extract a `.zip` or `.tar.gz` source release from https://github.com/pymupdf/PyMuPDF/releases. -Then one can build PyMuPDF in two ways: -* Build and install PyMuPDF with default MuPDF version:: +pymupdf vs pymupdf-lite +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The default is to build/install pymupdf-lite. To build/install pymupdf instead: - cd PyMuPDF && pip install . +* Set PYMUPDF_SETUP_PATH_LAYOUT to the absolute path of a local checkout of pymupdf-layout. +* Set PYMUPDF_SETUP_PATH_4LLM to the absolute path of a local checkout of pymupdf4llm. - This will automatically download a specific hard-coded MuPDF source - release, and build it into PyMuPDF. +* For example:: -* Or build and install PyMuPDF using a local MuPDF source tree: + git clone https://github.com/ArtifexSoftware/pymupdf_layout.git + git clone https://github.com/pymupdf/pymupdf4llm.git + export PYMUPDF_SETUP_PATH_LAYOUT=`pwd`/pymupdf_layout + export PYMUPDF_SETUP_PATH_4LLM=`pwd`/pymupdf4llm + - * Clone the MuPDF git repository:: +Build/install commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - git clone --recursive https://git.ghostscript.com/mupdf.git +To install:: - * - Build PyMuPDF, specifying the location of the local MuPDF tree with the - environmental variables `PYMUPDF_SETUP_MUPDF_BUILD`:: + pip install ./PyMuPDF - cd PyMuPDF && PYMUPDF_SETUP_MUPDF_BUILD=../mupdf pip install . +To build a wheel:: -Also, one can build for different Python versions in the same PyMuPDF tree: + pip wheel ./PyMuPDF -* - PyMuPDF will build for the version of Python that is being used to run - `pip`. To run `pip` with a specific Python version, use `python -m pip` - instead of `pip`. +**Note that one needs to specify `./PyMuPDF` not `PyMuPDF` - the latter will download/install pre-built wheels from pypi.org.** + + +Variations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - So for example on Windows one can build different versions with:: +Using a specific MuPDF. - cd PyMuPDF && py -3.14 -m pip install . +* By default the build will automatically download a specific hard-coded MuPDF source release, + and build it into pymupdf/pymupdf-lite. - or:: +* To instead use a local MuPDF checkout, + set PYMUPDF_SETUP_MUPDF_BUILD to the absolute path of the MuPDF checkout. - cd PyMuPDF && py -3.12-32 -m pip install . + +Building for a non-default Python version. + +* By default the build will be for `pip`'s Python version. +* To build for a specific Python version, use `python -m pip`. +* For example on Windows:: + + py -3.14 -m pip install ./PyMuPDF + + Or:: + + py -3.12-32 -m pip install ./PyMuPDF Running tests @@ -290,7 +308,7 @@ suite:: Notes about using a non-default MuPDF -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using a non-default build of MuPDF by setting environmental variable `PYMUPDF_SETUP_MUPDF_BUILD` can cause various things to go wrong and so is @@ -355,13 +373,13 @@ Enabling Integrated OCR Support Enabling integrated OCR support requires installing at least one OCR engine, such as RapidOCR or Tesseract. See also: :ref:`OCR Engine Comparison `. RapidOCR -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See the instructions on the `RapidOCR GitHub repository `_. Tesseract -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PyMuPDF already contains the Tesseract engine to support OCR functions. All it is missing is the `Language Support Data `_ that will be taken from the system installation of Tesseract. diff --git a/docs/page.rst b/docs/page.rst index 36986e5fa..914268655 100644 --- a/docs/page.rst +++ b/docs/page.rst @@ -296,7 +296,6 @@ In a nutshell, this is what you can do with PyMuPDF: :rtype: :ref:`Annot` :returns: the created annotation. It is drawn with line (stroke) color red = (1, 0, 0), line width 1, fill color is supported. - --------- Redactions ~~~~~~~~~~~ @@ -376,7 +375,6 @@ In a nutshell, this is what you can do with PyMuPDF: |history_end| - --------- .. method:: add_polyline_annot(points) diff --git a/docs/pymupdf-office/index.rst b/docs/pymupdf-office/index.rst index 1786bae2c..733940483 100644 --- a/docs/pymupdf-office/index.rst +++ b/docs/pymupdf-office/index.rst @@ -10,7 +10,7 @@ PyMuPDF Office -============= +============== Enhance |PyMuPDF| capability with **Office** document support. diff --git a/docs/resources.rst b/docs/resources.rst index 9e2b4f91e..a4baf06e0 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -13,6 +13,7 @@ For **Office** file support `try PyMuPDF Office `. | + ---- @@ -22,6 +23,7 @@ Find out about **PyMuPDF Utilities** The :title:`GitHub` repository `PyMuPDF-Utilities `_ contains a full range of examples, demonstrations and use cases. | + ---- @@ -36,4 +38,4 @@ We recommend the pdf2docx_ library which uses |PyMuPDF| and the **python-docx** -.. include:: footer.rst \ No newline at end of file +.. include:: footer.rst diff --git a/docs/story-class.rst b/docs/story-class.rst index cfa3d75b0..65be712c3 100644 --- a/docs/story-class.rst +++ b/docs/story-class.rst @@ -167,8 +167,9 @@ Story * position: An `ElementPosition` with an extra `.page_num` member. - Typically called multiple times as we generate elements that - are headings or have an id. + + Typically called multiple times as we generate elements that + are headings or have an id. :arg pagefn: None, or a callable taking `(page_num, mediabox, dev, after)`; called at start (`after=0`) and end (`after=1`) of each page. @@ -213,8 +214,9 @@ Story If true, we add unique ids to all header tags that don't already have an id. This can help automatic generation of tables of contents. - Returns: - None. + + Returns: + None. .. method:: write_with_links(rectfn, positionfn=None, pagefn=None) diff --git a/docs/tools.rst b/docs/tools.rst index 2347af6ec..0036e34ad 100644 --- a/docs/tools.rst +++ b/docs/tools.rst @@ -135,15 +135,15 @@ This class is a collection of utility methods and attributes, mainly around memo Control whether MuPDF errors should be displayed as |PyMuPDF| messages. :arg value: - * If `None`, the current setting is left unchanged. - * Otherwise changes the current setting to `bool(value)`; - if ``True``, future MuPDF errors will be shown as :ref:`Messages`. - * Regardless of this setting, MuPDF errors will always be stored in the warnings store. - * Upon import of |PyMuPDF| this value is ``True``. + * If `None`, the current setting is left unchanged. + * Otherwise changes the current setting to `bool(value)`; + if ``True``, future MuPDF errors will be shown as :ref:`Messages`. + * Regardless of this setting, MuPDF errors will always be stored in the warnings store. + * Upon import of |PyMuPDF| this value is ``True``. - :returns: The current setting as ``True`` or ``False``. + :returns: The current setting as ``True`` or ``False``. - * New in version 1.16.8 + * New in version 1.16.8 .. method:: mupdf_display_warnings(value=None) @@ -151,15 +151,15 @@ This class is a collection of utility methods and attributes, mainly around memo Control whether MuPDF warnings should be displayed as |PyMuPDF| messages. :arg value: - * If `None`, the current setting is left unchanged. - * Otherwise changes the current setting to `bool(value)`; - if ``True``, future MuPDF warnings will be shown as :ref:`Messages`. - * Regardless of this setting, MuPDF warnings will always be stored in the warnings store. - * Upon import of |PyMuPDF| this value is ``True``. + * If `None`, the current setting is left unchanged. + * Otherwise changes the current setting to `bool(value)`; + if ``True``, future MuPDF warnings will be shown as :ref:`Messages`. + * Regardless of this setting, MuPDF warnings will always be stored in the warnings store. + * Upon import of |PyMuPDF| this value is ``True``. - :returns: The current setting as ``True`` or ``False``. + :returns: The current setting as ``True`` or ``False``. - * New in version 1.16.8 + * New in version 1.16.8 .. method:: mupdf_warnings(reset=True) diff --git a/docs/widget.rst b/docs/widget.rst index b6b39f19a..1657fd705 100644 --- a/docs/widget.rst +++ b/docs/widget.rst @@ -204,11 +204,11 @@ Like annotations, widgets also lose connection to their page when the page becom .. note:: 1. For **adding** or **changing** one of the above scripts, - just put the appropriate JavaScript source code in the widget attribute. - To **remove** a script, set the respective attribute to ``None``. + just put the appropriate JavaScript source code in the widget attribute. + To **remove** a script, set the respective attribute to ``None``. 2. Button fields only support :attr:`script`. - Other script entries will automatically be set to ``None``. + Other script entries will automatically be set to ``None``. 3. It is worthwhile to look at `this `_ diff --git a/setup.py b/setup.py index a88f6d2d9..abb11ae75 100755 --- a/setup.py +++ b/setup.py @@ -944,6 +944,8 @@ def int_or_0(text): # Add single README file. ret.append( (f'{g_root}/README.md', '$dist-info/README.md') ) + ret.append( (f'{g_root}/COPYING', '$dist-info/licenses/GNU_AFFERO_GPL_3.0.txt') ) + return ret @@ -1489,6 +1491,7 @@ def platform_release_tuple(): requires_dist = g_requires_dist, requires_python = '>=3.11', license = 'Dual Licensed - GNU AFFERO GPL 3.0 or Artifex Commercial License', + #license_expression = 'AGPL-3.0-only OR LicenseRef-Artifex-Commercial-License', project_url = [ ('Documentation, https://pymupdf.readthedocs.io/'), ('Source, https://github.com/pymupdf/pymupdf'),