ENH: Add page_number property (#1856)

The property returns "-1" if the page is not attached to a document.

This behavior is chosen to keep the property consistent with `get_page_number` and `get_destination_page_number`

pypdf/_page.py

@@ -1721,6 +1721,23 @@ def compressContentStreams(self) -> None:  # deprecated
         )
         self.compress_content_streams()
 
+    @property
+    def page_number(self) -> int:
+        """
+        Read-only property which return the page number with the pdf file.
+
+        Returns:
+            int : page number ; -1 if the page is not attached to a pdf
+        """
+        if self.indirect_reference is None:
+            return -1
+        else:
+            try:
+                lst = self.indirect_reference.pdf.pages
+                return lst.index(self)
+            except ValueError:
+                return -1
+
     def _debug_for_extract(self) -> str:  # pragma: no cover
         out = ""
         for ope, op in ContentStream(

tests/test_page.py

@@ -261,13 +261,18 @@ def test_page_transformations():
 )
 def test_compress_content_streams(pdf_path, password):
     reader = PdfReader(pdf_path)
+
     writer = PdfWriter()
     if password:
         reader.decrypt(password)
+    for i, page in enumerate(reader.pages):
+        assert i == page.page_number
+
     assert isinstance(reader.pages[0].get_contents(), ContentStream)
     writer.clone_document_from_reader(reader)
     assert isinstance(writer.pages[0].get_contents(), ContentStream)
-    for page in writer.pages:
+    for i, page in enumerate(writer.pages):
+        assert i == page.page_number
         page.compress_content_streams()
 
     # test from reader should fail as adding_object out of
@@ -1119,6 +1124,13 @@ def test_merge_transformed_page_into_blank():
                 True,
                 True,
             )
+    blank = PageObject.create_blank_page(width=100, height=100)
+    assert blank.page_number == -1
+    inserted_blank = w.add_page(blank)
+    assert blank.page_number == -1  # the inserted page is a clone
+    assert inserted_blank.page_number == len(w.pages) - 1
+    del w._pages.get_object()["/Kids"][-1]
+    assert inserted_blank.page_number == -1
 
 
 def test_pages_printing():