From 807ecf5bc269d82b89f94b82024617657bf862b0 Mon Sep 17 00:00:00 2001 From: "Jorj X. McKie" Date: Wed, 16 Oct 2024 10:47:06 -0400 Subject: [PATCH] Update functions.rst This documentation change clarifies the use of Page method `clean_contents()`. --- docs/functions.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/functions.rst b/docs/functions.rst index 3a7a1c0aa..6ebcb7d00 100644 --- a/docs/functions.rst +++ b/docs/functions.rst @@ -601,8 +601,7 @@ Yet others are handy, general-purpose utilities. In versions 1.24.1+ of PyMuPDF the method was improved and is being executed automatically as required, so you should no longer need to concern yourself with it. - This method obsoletes the use of :meth:`Page.clean_contents` in most cases. - The advantage this method is a small footprint in terms of processing time and a low impact on the data size of incremental saves. + We discourage using :meth:`Page.clean_contents` to achieve this. ----- @@ -641,7 +640,7 @@ Yet others are handy, general-purpose utilities. .. method:: Page.get_contents() - PDF only: Retrieve a list of :data:`xref` of :data:`contents` objects of a page. May be empty or contain multiple integers. If the page is cleaned (:meth:`Page.clean_contents`), it will be one entry at most. The "source" of each `/Contents` object can be individually read by :meth:`Document.xref_stream` using an item of this list. Method :meth:`Page.read_contents` in contrast walks through this list and concatenates the corresponding sources into one `bytes` object. + PDF only: Retrieve a list of :data:`xref` of :data:`contents` objects of a page. May be empty or contain multiple integers. If the page is cleaned (:meth:`Page.clean_contents`), it will be no more than one entry. The "source" of each `/Contents` object can be individually read by :meth:`Document.xref_stream` using an item of this list. Method :meth:`Page.read_contents` in contrast walks through this list and concatenates the corresponding sources into one `bytes` object. :rtype: list[int] @@ -665,6 +664,8 @@ Yet others are handy, general-purpose utilities. .. warning:: This is a complex function which may generate large amounts of new data and render old 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"*. + Do not any longer use this method to ensure correct insertions on PDF pages. Since PyMuPDF version 1.24.2 this is taken care of automatically. + ----- .. method:: Page.read_contents()