Add __bool__, __iter__ and __len__ to TableFinder

changes.txt

@@ -34,6 +34,7 @@ Other:
 * Retrospectively marked #4918 fixed in 1.28.0.
 * Retrospectively marked #4158 fixed in 1.27.2.2
 * Warning for use of deprecated `fitz` API now uses `warnings.warn()` with `FutureWarning`.
+* Added `__len__`, `__bool__` and `__iter__` to `TableFinder`. `len(tabs)`, `bool(tabs)` and `for t in tabs` now work directly. Note that a `TableFinder` with no tables is now falsy.
 
 
 **Changes in version 1.28.2** (2026-08-06)

docs/page.rst

@@ -2428,6 +2428,18 @@ The `TableFinder` class is returned by :meth:`Page.find_tables` and has related
 
       :type: :ref:`Page`
 
+   .. method:: __len__()
+
+      The number of tables found. Same as ``len(tables)``.
+
+   .. method:: __bool__()
+
+      *True* if at least one table was found. This means a `TableFinder` without tables is falsy, so ``if page.find_tables():`` skips pages without tables.
+
+   .. method:: __iter__()
+
+      Iterate over the :class:`Table` objects, same as iterating over :attr:`tables`.
+
 
 .. class:: Table
 

src/table.py

@@ -2359,6 +2359,9 @@ def get_edges(self) -> list:
 
         return filter_edges(edges, min_length=settings.edge_min_length)
 
+    def __bool__(self):
+        return bool(self.tables)
+
     def __getitem__(self, i):
         tcount = len(self.tables)
         if i >= tcount:
@@ -2367,6 +2370,12 @@ def __getitem__(self, i):
             i += tcount
         return self.tables[i]
 
+    def __iter__(self):
+        return iter(self.tables)
+
+    def __len__(self):
+        return len(self.tables)
+
 
 """
 Start of PyMuPDF interface code.

tests/test_tables.py

@@ -750,6 +750,18 @@ def test_battery_file():
     assert len(tabs.tables) == 0
 
 
+def test_table_finder_len_bool_iter():
+    """TableFinder supports len(), truth testing and iteration over its tables."""
+    for name, count in (("test_3179.pdf", 3), ("battery-file-22.pdf", 0)):
+        doc = pymupdf.open(os.path.join(scriptdir, "resources", name))
+        tabs = doc[0].find_tables()
+        assert len(tabs) == count
+        assert bool(tabs) is (count > 0)
+        items = list(tabs)
+        assert len(items) == count
+        assert all(a is b for a, b in zip(items, tabs.tables))
+
+
 def test_markdown():
     """Confirm correct markdown output."""
     filename = os.path.join(scriptdir, "resources", "strict-yes-no.pdf")