fix: rename isolate_tables chunking option to isolate_table (#4355)

Renames the option added in 0.22.30 for naming consistency. Bumps
version to 0.22.31 and adds a CHANGELOG entry noting the rename.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Renames the chunking option `isolate_tables` to `isolate_table` for
naming consistency with no behavior change. Updates docs/tests/messages
and bumps to 0.22.31.

- **Migration**
- Update calls to `chunk_elements(...)` and `chunk_by_title(...)` to
pass `isolate_table=` instead of `isolate_tables=`.
- Validation message now references `isolate_table` (e.g.,
"'skip_table_chunking=True' requires 'isolate_table=True'").

<sup>Written for commit ecdbed1.
Summary will update on new commits. <a
href="https://cubic.dev/pr/Unstructured-IO/unstructured/pull/4355?utm_source=github">Review
in cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: badGarnet

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.22.31
+
+### Enhancements
+
+- **Rename `isolate_tables` chunking option to `isolate_table`**: the option added in 0.22.30 has been renamed for naming consistency. Callers passing `isolate_tables=` must update to `isolate_table=`.
+
 ## 0.22.30
 
 ### Enhancements

test_unstructured/chunking/test_base.py

@@ -130,14 +130,14 @@ def it_knows_whether_to_skip_table_chunking(self, kwargs: dict[str, Any], expect
     @pytest.mark.parametrize(
         ("kwargs", "expected_value"),
         [
-            ({"isolate_tables": True}, True),
-            ({"isolate_tables": False}, False),
-            ({"isolate_tables": None}, True),
+            ({"isolate_table": True}, True),
+            ({"isolate_table": False}, False),
+            ({"isolate_table": None}, True),
             ({}, True),
         ],
     )
-    def it_knows_whether_to_isolate_tables(self, kwargs: dict[str, Any], expected_value: bool):
-        assert ChunkingOptions(**kwargs).isolate_tables is expected_value
+    def it_knows_whether_to_isolate_table(self, kwargs: dict[str, Any], expected_value: bool):
+        assert ChunkingOptions(**kwargs).isolate_table is expected_value
 
     @pytest.mark.parametrize(
         ("skip", "isolate"),
@@ -151,9 +151,9 @@ def it_knows_whether_to_isolate_tables(self, kwargs: dict[str, Any], expected_va
     def it_rejects_skip_table_chunking_when_isolation_is_disabled(self, skip: Any, isolate: Any):
         with pytest.raises(
             ValueError,
-            match="'skip_table_chunking=True' requires 'isolate_tables=True'",
+            match="'skip_table_chunking=True' requires 'isolate_table=True'",
         ):
-            ChunkingOptions(skip_table_chunking=skip, isolate_tables=isolate)._validate()
+            ChunkingOptions(skip_table_chunking=skip, isolate_table=isolate)._validate()
 
     @pytest.mark.parametrize("n_chars", [-1, -42])
     def it_rejects_new_after_n_chars_for_n_less_than_zero(self, n_chars: int):

test_unstructured/chunking/test_basic.py

@@ -287,19 +287,19 @@ def it_supports_the_skip_table_chunking_option(
     @pytest.mark.parametrize(
         ("kwargs", "expected_value"),
         [
-            ({"isolate_tables": True}, True),
-            ({"isolate_tables": False}, False),
-            ({"isolate_tables": None}, True),
+            ({"isolate_table": True}, True),
+            ({"isolate_table": False}, False),
+            ({"isolate_table": None}, True),
             ({}, True),
         ],
     )
-    def it_supports_the_isolate_tables_option(
+    def it_supports_the_isolate_table_option(
         self, kwargs: dict[str, Any], expected_value: bool, _chunk_elements_: Mock
     ):
         chunk_elements([], **kwargs)
 
         _, opts = _chunk_elements_.call_args.args
-        assert opts.isolate_tables is expected_value
+        assert opts.isolate_table is expected_value
 
     # -- fixtures --------------------------------------------------------------------------------
 

test_unstructured/chunking/test_table_isolation.py

@@ -239,25 +239,25 @@ def it_never_produces_a_composite_element_that_lists_a_table_in_orig_elements(
 
 
 class DescribeTableIsolationDisabled:
-    """When `isolate_tables=False`, the pre-#4307 behavior is restored."""
+    """When `isolate_table=False`, the pre-#4307 behavior is restored."""
 
     def it_lets_a_table_share_a_pre_chunk_with_adjacent_text_when_disabled(self):
-        opts = ChunkingOptions(max_characters=500, isolate_tables=False)
+        opts = ChunkingOptions(max_characters=500, isolate_table=False)
         builder = PreChunkBuilder(opts=opts)
         builder.add_element(Text("Short preamble."))
 
         assert builder.will_fit(Table("Heading\nCell text"))
 
     def it_lets_text_follow_a_table_in_the_same_pre_chunk_when_disabled(self):
-        opts = ChunkingOptions(max_characters=500, isolate_tables=False)
+        opts = ChunkingOptions(max_characters=500, isolate_table=False)
         builder = PreChunkBuilder(opts=opts)
         builder.add_element(Table("Heading\nCell text"))
 
         assert builder.will_fit(Text("Follow-up paragraph."))
 
     def it_combines_a_table_pre_chunk_with_text_neighbors_when_disabled(self):
         opts = ChunkingOptions(
-            max_characters=500, combine_text_under_n_chars=500, isolate_tables=False
+            max_characters=500, combine_text_under_n_chars=500, isolate_table=False
         )
         stream = [
             PreChunk([Text("Hello world.")], overlap_prefix="", opts=opts),
@@ -284,7 +284,7 @@ def it_wraps_a_table_into_a_composite_element_with_neighbors_when_disabled(self)
         chunks = chunk_elements(
             elements,
             max_characters=500,
-            isolate_tables=False,
+            isolate_table=False,
         )
 
         assert len(chunks) == 1

test_unstructured/chunking/test_title.py

@@ -612,19 +612,19 @@ def it_supports_the_skip_table_chunking_option(
     @pytest.mark.parametrize(
         ("kwargs", "expected_value"),
         [
-            ({"isolate_tables": True}, True),
-            ({"isolate_tables": False}, False),
-            ({"isolate_tables": None}, True),
+            ({"isolate_table": True}, True),
+            ({"isolate_table": False}, False),
+            ({"isolate_table": None}, True),
             ({}, True),
         ],
     )
-    def it_supports_the_isolate_tables_option(
+    def it_supports_the_isolate_table_option(
         self, kwargs: dict[str, Any], expected_value: bool, _chunk_by_title_: Mock
     ):
         chunk_by_title([], **kwargs)
 
         _, opts = _chunk_by_title_.call_args.args
-        assert opts.isolate_tables is expected_value
+        assert opts.isolate_table is expected_value
 
     # -- fixtures --------------------------------------------------------------------------------
 

unstructured/__version__.py

@@ -1 +1 @@
-__version__ = "0.22.30"  # pragma: no cover
+__version__ = "0.22.31"  # pragma: no cover

unstructured/chunking/base.py

@@ -125,7 +125,7 @@ class ChunkingOptions:
     repeat_table_headers
         Default: `True`. When `True`, repeated table-header behavior is enabled for chunked table
         continuations. Specify `False` to opt out and preserve legacy table-chunk behavior.
-    isolate_tables
+    isolate_table
         Default: `True`. When `True`, `Table` and `TableChunk` elements are always staged in
         their own pre-chunk and never combined with adjacent non-table elements. Specify
         `False` to allow tables to share pre-chunks with adjacent elements (the pre-#4307
@@ -215,14 +215,14 @@ def skip_table_chunking(self) -> bool:
         return False if arg_value is None else bool(arg_value)
 
     @cached_property
-    def isolate_tables(self) -> bool:
+    def isolate_table(self) -> bool:
         """When True, `Table`/`TableChunk` elements are staged in their own pre-chunk.
 
         Default value is `True`. When `False`, table-family elements are allowed to share a
         pre-chunk with adjacent non-table elements (and may be merged by `PreChunkCombiner`),
         restoring the pre-#4307 behavior.
         """
-        arg_value = self._kwargs.get("isolate_tables")
+        arg_value = self._kwargs.get("isolate_table")
         return True if arg_value is None else bool(arg_value)
 
     @cached_property
@@ -366,13 +366,13 @@ def _validate(self) -> None:
         if new_after_n_chars is not None and new_after_n_chars < 0:
             raise ValueError(f"'new_after_n_chars' argument must be >= 0, got {new_after_n_chars}")
 
-        # -- `skip_table_chunking` requires `isolate_tables` because the pass-through path only
+        # -- `skip_table_chunking` requires `isolate_table` because the pass-through path only
         # -- fires when the pre-chunk contains a single `Table` element. With isolation disabled,
         # -- tables can fold into `CompositeElement` alongside neighbors and the skip would be
         # -- silently ignored, breaking the contract.
-        if self.skip_table_chunking and not self.isolate_tables:
+        if self.skip_table_chunking and not self.isolate_table:
             raise ValueError(
-                "'skip_table_chunking=True' requires 'isolate_tables=True' (the default);"
+                "'skip_table_chunking=True' requires 'isolate_table=True' (the default);"
                 " tables cannot be passed through unchanged while also sharing a pre-chunk with"
                 " adjacent elements"
             )
@@ -531,7 +531,7 @@ def add_element(self, element: Element) -> None:
         """Add `element` to this section."""
         # -- do not prefix a table-only pre-chunk with narrative overlap from the prior chunk --
         if (
-            self._opts.isolate_tables
+            self._opts.isolate_table
             and len(self._elements) == 0
             and _element_is_table_family(element)
         ):
@@ -564,7 +564,7 @@ def flush(self) -> Iterator[PreChunk]:
         overlap_for_next = pre_chunk.overlap_tail
         # -- table tails must not prefix the following narrative pre-chunk (overlap_all) --
         if (
-            self._opts.isolate_tables
+            self._opts.isolate_table
             and len(elements) == 1
             and _element_is_table_family(elements[0])
         ):
@@ -584,7 +584,7 @@ def will_fit(self, element: Element) -> bool:
         - A text-element will not fit when together with the elements already present it would
           exceed the hard-max (aka. max_characters/max_tokens).
         """
-        if self._opts.isolate_tables:
+        if self._opts.isolate_table:
             # -- a `Table` can only start a pre-chunk; it is never appended to a non-empty
             # -- pre-chunk --
             if _element_is_table_family(element):
@@ -675,7 +675,7 @@ def __eq__(self, other: Any) -> bool:
 
     def can_combine(self, pre_chunk: PreChunk) -> bool:
         """True when `pre_chunk` can be combined with this one without exceeding size limits."""
-        if self._opts.isolate_tables and _table_isolation_forbids_side_by_side_merge(
+        if self._opts.isolate_table and _table_isolation_forbids_side_by_side_merge(
             self._elements, pre_chunk._elements
         ):
             return False

unstructured/chunking/basic.py

@@ -34,7 +34,7 @@ def chunk_elements(
     tokenizer: Optional[str] = None,
     repeat_table_headers: Optional[bool] = None,
     skip_table_chunking: Optional[bool] = None,
-    isolate_tables: Optional[bool] = None,
+    isolate_table: Optional[bool] = None,
 ) -> list[Element]:
     """Combine sequential `elements` into chunks, respecting specified text-length limits.
 
@@ -85,7 +85,7 @@ def chunk_elements(
     skip_table_chunking
         Default: `False`. When `True`, `Table` elements are passed through unchanged without
         being split into `TableChunk` elements, regardless of their size.
-    isolate_tables
+    isolate_table
         Default: `True`. When `True`, `Table` and `TableChunk` elements are always staged in
         their own pre-chunk and never combined with adjacent non-table elements. Specify
         `False` to allow tables to share pre-chunks with adjacent elements (the pre-#4307
@@ -103,7 +103,7 @@ def chunk_elements(
         tokenizer=tokenizer,
         repeat_table_headers=repeat_table_headers,
         skip_table_chunking=skip_table_chunking,
-        isolate_tables=isolate_tables,
+        isolate_table=isolate_table,
     )
 
     return _chunk_elements(elements, opts)

unstructured/chunking/dispatch.py

@@ -74,7 +74,7 @@ def add_chunking_strategy(func: Callable[_P, list[Element]]) -> Callable[_P, lis
             + "\n\t\tskip_table_chunking"
             + "\n\t\t\tDefault: False. When True, Table elements are passed through"
             + "\n\t\t\tunchanged without being split into TableChunk elements."
-            + "\n\t\tisolate_tables"
+            + "\n\t\tisolate_table"
             + "\n\t\t\tDefault: True. When True, Table/TableChunk elements are always"
             + "\n\t\t\tstaged in their own pre-chunk. Set to False to allow tables to"
             + "\n\t\t\tshare pre-chunks with adjacent non-table elements."

unstructured/chunking/title.py

@@ -35,7 +35,7 @@ def chunk_by_title(
     tokenizer: Optional[str] = None,
     repeat_table_headers: Optional[bool] = None,
     skip_table_chunking: Optional[bool] = None,
-    isolate_tables: Optional[bool] = None,
+    isolate_table: Optional[bool] = None,
 ) -> list[Element]:
     """Uses title elements to identify sections within the document for chunking.
 
@@ -92,7 +92,7 @@ def chunk_by_title(
     skip_table_chunking
         Default: `False`. When `True`, `Table` elements are passed through unchanged without
         being split into `TableChunk` elements, regardless of their size.
-    isolate_tables
+    isolate_table
         Default: `True`. When `True`, `Table` and `TableChunk` elements are always staged in
         their own pre-chunk and never combined with adjacent non-table elements. Specify
         `False` to allow tables to share pre-chunks with adjacent elements (the pre-#4307
@@ -111,7 +111,7 @@ def chunk_by_title(
         tokenizer=tokenizer,
         repeat_table_headers=repeat_table_headers,
         skip_table_chunking=skip_table_chunking,
-        isolate_tables=isolate_tables,
+        isolate_table=isolate_table,
     )
     return _chunk_by_title(elements, opts)