refactor title.py (#2657)

Minor refactor after conversation with @scanny

Updates docstring and how chunking options are accessed.
`self._kwargs.get()` should only be used in the `lazyproperty`
definition of an instance's attribute. Other calls should use
`self.<attribute>`

Author: Coniferish

CHANGELOG.md

@@ -1,4 +1,4 @@
-## 0.12.7-dev6
+## 0.12.7-dev7
 
 ### Enhancements
 

test_unstructured/chunking/test_title.py

@@ -642,19 +642,13 @@ def it_rejects_combine_text_under_n_chars_greater_than_maxchars(
             )
 
     def it_does_not_complain_when_specifying_new_after_n_chars_by_itself(self):
-        """Caller can specify `new_after_n_chars` arg without specifying any other options.
-
-        In particular, `combine_text_under_n_chars` value is adjusted down to the
-        `new_after_n_chars` value when the default for `combine_text_under_n_chars` exceeds the
-        value of `new_after_n_chars`.
-        """
+        """Caller can specify `new_after_n_chars` arg without specifying any other options."""
         try:
-            opts = _ByTitleChunkingOptions(new_after_n_chars=200)
+            opts = _ByTitleChunkingOptions.new(new_after_n_chars=200)
         except ValueError:
             pytest.fail("did not accept `new_after_n_chars` as option by itself")
 
         assert opts.soft_max == 200
-        assert opts.combine_text_under_n_chars == 200
 
     @pytest.mark.parametrize(
         ("multipage_sections", "expected_value"),

unstructured/__version__.py

@@ -1 +1 @@
-__version__ = "0.12.7-dev6"  # pragma: no cover
+__version__ = "0.12.7-dev7"  # pragma: no cover

unstructured/chunking/title.py

@@ -101,6 +101,10 @@ class _ByTitleChunkingOptions(ChunkingOptions):
 
     `by_title`-specific options:
 
+    combine_text_under_n_chars
+        A remedy to over-chunking caused by elements mis-identified as Title elements.
+        Every Title element would start a new chunk and this setting mitigates that, at the
+        expense of sometimes violating legitimate semantic boundaries.
     multipage_sections
         Indicates that page-boundaries should not be respected while chunking, i.e. elements
         appearing on two different pages can appear in the same chunk.
@@ -133,15 +137,9 @@ def combine_text_under_n_chars(self) -> int:
         - Defaults to `max_characters` when not specified.
         - Is reduced to `new_after_n_chars` when it exceeds that value.
         """
-        max_characters = self.hard_max
-        soft_max = self.soft_max
-        arg_value = self._kwargs.get("combine_text_under_n_chars")
-
         # -- `combine_text_under_n_chars` defaults to `max_characters` when not specified --
-        combine_text_under_n_chars = max_characters if arg_value is None else arg_value
-
-        # -- `new_after_n_chars` takes precendence on conflict with `combine_text_under_n_chars` --
-        return soft_max if combine_text_under_n_chars > soft_max else combine_text_under_n_chars
+        arg_value = self._kwargs.get("combine_text_under_n_chars")
+        return self.hard_max if arg_value is None else arg_value
 
     @lazyproperty
     def multipage_sections(self) -> bool:
@@ -154,22 +152,20 @@ def _validate(self) -> None:
         # -- start with base-class validations --
         super()._validate()
 
-        combine_text_under_n_chars_arg = self._kwargs.get("combine_text_under_n_chars")
-        if combine_text_under_n_chars_arg is not None:
-            # -- `combine_text_under_n_chars == 0` is valid (suppresses chunk combination)
-            # -- but a negative value is not
-            if combine_text_under_n_chars_arg < 0:
-                raise ValueError(
-                    f"'combine_text_under_n_chars' argument must be >= 0,"
-                    f" got {combine_text_under_n_chars_arg}"
-                )
-
-            # -- `combine_text_under_n_chars` > `max_characters` can produce behavior confusing to
-            # -- users. The chunking behavior would be no different than when
-            # -- `combine_text_under_n_chars == max_characters`, but if `max_characters` is left to
-            # -- default (500) then it can look like chunk-combining isn't working.
-            if combine_text_under_n_chars_arg > self.hard_max:
-                raise ValueError(
-                    f"'combine_text_under_n_chars' argument must not exceed `max_characters`"
-                    f" value, got {combine_text_under_n_chars_arg} > {self.hard_max}"
-                )
+        # -- `combine_text_under_n_chars == 0` is valid (suppresses chunk combination)
+        # -- but a negative value is not
+        if self.combine_text_under_n_chars < 0:
+            raise ValueError(
+                f"'combine_text_under_n_chars' argument must be >= 0,"
+                f" got {self.combine_text_under_n_chars}"
+            )
+
+        # -- `combine_text_under_n_chars` > `max_characters` can produce behavior confusing to
+        # -- users. The chunking behavior would be no different than when
+        # -- `combine_text_under_n_chars == max_characters`, but if `max_characters` is left to
+        # -- default (500) then it can look like chunk-combining isn't working.
+        if self.combine_text_under_n_chars > self.hard_max:
+            raise ValueError(
+                f"'combine_text_under_n_chars' argument must not exceed `max_characters`"
+                f" value, got {self.combine_text_under_n_chars} > {self.hard_max}"
+            )