docs: document per-bundle read-bound gap, fix stale docstrings

- unbounded_source.py: add the missing per-bundle read-bound limitation to
  the out-of-scope list (process() reads until no-data/EOF; a saturated
  source keeps one bundle running without committing watermark/checkpoint,
  unlike Java's OutputAndTimeBoundedSplittableProcessElementInvoker).
- unbounded_source_test.py: correct two stale docstrings/messages that still
  described the DoFn as defined inside ReadFromUnboundedSource.expand; it is
  now the module-level _ReadFromUnboundedSourceDoFn with a module-level
  _PROVIDER.

Author: Eliaaazzz

sdks/python/apache_beam/io/unbounded_source.py

@@ -44,6 +44,16 @@ class MySource(UnboundedSource):
 deterministic reader close on EOF / split / exception, and bundle finalization.
 
 Out of scope for this PoC (tracked under #19137):
+  * Per-bundle read bound. ``process()`` reads every record the reader makes
+    available and only yields control on a no-data poll (self-checkpoint) or
+    EOF. A genuinely saturated source that always has data will therefore
+    keep one bundle running indefinitely -- the watermark advances on the
+    in-bundle estimator but is not committed downstream, and no checkpoint /
+    finalize is cut, until the source idles. Java bounds each SDF call via
+    ``OutputAndTimeBoundedSplittableProcessElementInvoker`` (a max element
+    count / wall-clock per invocation); the equivalent forced-defer is W2
+    work. Self-terminating finite sources (and any source that periodically
+    returns no-data) are unaffected.
   * Record-id-based deduplication (Java's ``ValueWithRecordId``).
   * Backlog-byte reporting (``restriction_size`` is a constant 1; per-restriction
     progress is binary 0.0 / 1.0).

sdks/python/apache_beam/io/unbounded_source_test.py

@@ -889,11 +889,12 @@ def test_poll_interval_must_be_positive(self):
 
 
 class CloudpicklePicklabilityTest(unittest.TestCase):
-  """The DoFn class is defined inside ``ReadFromUnboundedSource.expand`` so it
-  can close over the source-specific provider. Beam's default pickler is
-  cloudpickle; stdlib pickle would fail on a closure-defined class. This is a
-  regression guard for cross-runner portability (Dataflow / Flink portable
-  workers also use cloudpickle).
+  """``_ReadFromUnboundedSourceDoFn`` and ``_PROVIDER`` are module-level (not
+  nested in ``ReadFromUnboundedSource.expand``) specifically so stdlib pickle --
+  not just cloudpickle -- can serialise them. Beam's default pickler is
+  cloudpickle, but some runners fall back to stdlib pickle, which fails on
+  closure-defined classes. This is a regression guard for cross-runner
+  portability (Dataflow / Flink portable workers also use cloudpickle).
   """
   def test_transform_round_trips_through_cloudpickle(self):
     from apache_beam.internal import pickler
@@ -1043,7 +1044,8 @@ def test_dofn_finally_closes_reader_on_generator_close(self):
           _wait_for_marker(marker),
           'DoFn finally did not invoke reader.close() when the generator '
           'was closed (GeneratorExit) -- reader leaked. Private-chain '
-          'close in unbounded_source.py:expand finally may be broken.')
+          'close in _ReadFromUnboundedSourceDoFn.process finally may be '
+          'broken.')
     finally:
       if os.path.exists(marker):
         os.unlink(marker)