Update tasks/planned_changes

docs/devel/tasks.md

@@ -9,6 +9,7 @@ Also see the issues panel and inline `TODO`/`FIXME` marks in source code.
 ### Main Code
 * Add a matrix-based rendering method, and perhaps a support method around it for common transformations (crop, margins, rotate, mirror, ...).
 * Add helpers for interruptible rendering.
+* Consider adding a page object index property backed by a view of released pages on document level (`list[None | weakref.ReferenceType[PdfPage]]`) that is updated on page order changes, despite a certain risk that the page view might not match the actual state if changes are not tracked properly. (To implement this safely, PDFium would need to provide a page indexing function natively)
 
 ### Setup Infrastructure
 * craft_packages: add means to skip platforms for which artefacts are missing.

docs/source/planned_changes.md

@@ -10,5 +10,9 @@ You may search for `TODO(v5)` to find the code spots in question.
 ```
 
 The following API breaking changes are in consideration for the next major release:
-- `PdfDocument.get_toc()` / `PdfOutlineItem`: The parameters `is_closed` (bool) and `n_kids` (abs int)
-  will be replaced by `count` (int), where the state corresponds to the value's sign.
+
+- The `PdfDocument.get_toc()` / `PdfOutlineItem` API will be changed.
+  * The parameters `is_closed` (bool) and `n_kids` (abs int) will be replaced by `count` (int),
+    where the state corresponds to the value's sign.
+  * Instead of loading bookmark info into namedtuples in a predefined fashion, a wrapper
+    around the raw pdfium object with on-demand properties shall be returned.

src/pypdfium2/_helpers/_internal/bases.py

@@ -73,7 +73,6 @@ def _close_template(close_func, raw, uuid, parent, *args, **kwargs):
 
 
     def close(self):
-        # TODO? issue a warning if needs_free=False ?
         if (self.raw is None):
             logger.warning(f"Duplicate close call suppressed on {self}.")
             return

src/pypdfium2/_helpers/document.py

@@ -163,6 +163,7 @@ def init_forms(self, config=None):
         self.formenv = PdfFormEnv(raw, config, self)
 
 
+    # ?TODO(v5) consider cached property
     def get_formtype(self):
         """
         Returns:
@@ -172,6 +173,7 @@ def get_formtype(self):
         return pdfium_c.FPDF_GetFormType(self)
 
 
+    # ?TODO(v5) consider cached property
     def get_pagemode(self):
         """
         Returns:
@@ -180,6 +182,7 @@ def get_pagemode(self):
         return pdfium_c.FPDFDoc_GetPageMode(self)
 
 
+    # ?TODO(v5) consider cached property
     def is_tagged(self):
         """
         Returns:
@@ -466,6 +469,7 @@ def page_as_xobject(self, index, dest_pdf):
         )
 
 
+    # TODO(v5) consider switching to a wrapper around the raw bookmark with on-demand cached properties
     def _get_bookmark(self, bookmark, level):
 
         n_bytes = pdfium_c.FPDFBookmark_GetTitle(bookmark, None, 0)
@@ -474,7 +478,6 @@ def _get_bookmark(self, bookmark, level):
         title = buffer.raw[:n_bytes-2].decode('utf-16-le')
 
         # TODO(v5) just expose count as-is rather than using two variables and doing extra work
-        # it's also more obvious if the number's sign just corresponds to the state (- closed, + open), rather than the current inversion with is_closed
         count = pdfium_c.FPDFBookmark_GetCount(bookmark)
         is_closed = True if count < 0 else None if count == 0 else False
         n_kids = abs(count)
@@ -500,6 +503,7 @@ def _get_bookmark(self, bookmark, level):
         )
 
 
+    # TODO(v5) change outline API (see above)
     def get_toc(
             self,
             max_depth = 15,
@@ -724,6 +728,7 @@ def _open_pdf(input_data, password, autoclose):
     return pdf, to_hold, to_close
 
 
+# TODO(v5) change outline API (see above)
 PdfOutlineItem = namedtuple("PdfOutlineItem", "level title is_closed n_kids page_index view_mode view_pos")
 """
 Bookmark information.