Docs clarifications

docs/devel/changelog_staging.md

@@ -5,3 +5,5 @@
 
 # Changelog for next release
 - Disruption: `PdfPage.insert_text()` does not generate page content automatically anymore. The new `PdfPage.generate_content()` method now needs to be called to apply changes, to avoid generating content repeatedly.
+- Added helpers to capture pages as XObjects, to get page objects for an XObject, to transform page objects, and to insert page objects into a page.
+  This may be used to implement a custom N-up compositor, for instance.

src/pypdfium2/_helpers/matrix.py

@@ -25,7 +25,7 @@ def __eq__(self, matrix):
 
     def get(self):
         """
-        Get the matrix as tuple of the form [a, b, c, d, e, f].
+        Get the matrix as tuple of the form (a, b, c, d, e, f).
         """
         return (self.a, self.b, self.c, self.d, self.e, self.f)
 

src/pypdfium2/_helpers/page.py

@@ -180,6 +180,8 @@ def insert_object(self, pageobj):
         Position and form are defined by the object's matrix.
         If it is the identity matrix, the object will appear as-is on the bottom left corner of the page.
         
+        The page object must not belong to a page yet. If it belongs to a PDF, this page must be part of that PDF.
+        
         Note:
             You may want to call :meth:`.generate_content` once you finished adding new content to the page.
         

src/pypdfium2/_helpers/pageobject.py

@@ -18,6 +18,7 @@ class PdfPageObject:
             Reference to the page this pageobject belongs to. May be :data:`None` if the object does not belong to a page yet.
         pdf (PdfDocument):
             Reference to the document this pageobject belongs to. May be :data:`None` if the object does not belong to a document yet.
+            This attribute is always set if :attr:`.page` is set.
         level (int):
             Nesting level signifying the number of parent Form XObjects. Zero if the object is not nested in a Form XObject.
         type (int):
@@ -68,7 +69,7 @@ def get_matrix(self):
     def set_matrix(self, matrix):
         """
         Parameters:
-            matrix (PdfMatrix): The new matrix of the page object.
+            matrix (PdfMatrix): The new matrix the page object shall have.
         """
         if not isinstance(matrix, PdfMatrix):
             raise ValueError("*matrix* must be a PdfMatrix object")