Replace lazyproperty with functools.cached_property (#4282)

## Summary
- Replace custom `lazyproperty` descriptor with stdlib
`functools.cached_property`
- Fix bug where 26 properties returning `None` were re-evaluated on
every access instead of caching — `lazyproperty.__get__` uses `if value
is None` to detect a cache miss, so any property that legitimately
returns `None` re-runs on every access
- Slight performance improvement on cached reads — `cached_property` is
a non-data descriptor, so after first access the `__dict__` entry
shadows the descriptor directly (plain dict lookup vs `__get__` call)
- Nothing in the codebase ever assigns to a lazyproperty-decorated
attribute, so dropping the write-protection from the data descriptor has
no behavioral impact

Author: KRRT7

CHANGELOG.md

@@ -1,6 +1,7 @@
-## 0.22.7-dev0
+## 0.22.7
 
 ### Fixes
+- **Replace `lazyproperty` with `functools.cached_property`**: Fix a bug where 26 properties returning `None` were re-evaluated on every access instead of caching. Also improves performance on cached reads.
 - **Preserve nested rows when reconstructing chunked tables**: `reconstruct_table_from_chunks()` now merges only top-level table rows (`tr`, `thead/tr`, `tbody/tr`, `tfoot/tr`) from each chunk so nested table structure is retained.
 
 ## 0.22.6

unstructured/__version__.py

@@ -1 +1 @@
-__version__ = "0.22.7-dev0"  # pragma: no cover
+__version__ = "0.22.7"  # pragma: no cover

unstructured/chunking/base.py

@@ -5,6 +5,7 @@
 import collections
 import copy
 import uuid
+from functools import cached_property
 from typing import Any, Callable, DefaultDict, Iterable, Iterator, cast
 
 import regex
@@ -23,7 +24,6 @@
     Title,
 )
 from unstructured.logger import logger
-from unstructured.utils import lazyproperty
 
 # ================================================================================================
 # MODEL
@@ -59,7 +59,7 @@ class TokenCounter:
     def __init__(self, tokenizer: str):
         self._tokenizer_name = tokenizer
 
-    @lazyproperty
+    @cached_property
     def _encoder(self):
         """Lazily initialize the tiktoken encoder."""
         import tiktoken
@@ -144,15 +144,15 @@ def new(cls, **kwargs: Any) -> Self:
         self._validate()
         return self
 
-    @lazyproperty
+    @cached_property
     def boundary_predicates(self) -> tuple[BoundaryPredicate, ...]:
         """The semantic-boundary detectors to be applied to break pre-chunks.
 
         Overridden by sub-typs to provide semantic-boundary isolation behaviors.
         """
         return ()
 
-    @lazyproperty
+    @cached_property
     def combine_text_under_n_chars(self) -> int:
         """Combine two consecutive text pre-chunks if first is smaller than this and both will fit.
 
@@ -162,7 +162,7 @@ def combine_text_under_n_chars(self) -> int:
         arg_value = self._kwargs.get("combine_text_under_n_chars")
         return arg_value if arg_value is not None else 0
 
-    @lazyproperty
+    @cached_property
     def hard_max(self) -> int:
         """The maximum size for a chunk (in characters or tokens depending on mode).
 
@@ -177,7 +177,7 @@ def hard_max(self) -> int:
         arg_value = self._kwargs.get("max_characters")
         return arg_value if arg_value is not None else CHUNK_MAX_CHARS_DEFAULT
 
-    @lazyproperty
+    @cached_property
     def include_orig_elements(self) -> bool:
         """When True, add original elements from pre-chunk to `.metadata.orig_elements` of chunk.
 
@@ -186,7 +186,7 @@ def include_orig_elements(self) -> bool:
         arg_value = self._kwargs.get("include_orig_elements")
         return True if arg_value is None else bool(arg_value)
 
-    @lazyproperty
+    @cached_property
     def inter_chunk_overlap(self) -> int:
         """Characters of overlap to add between chunks.
 
@@ -196,7 +196,7 @@ def inter_chunk_overlap(self) -> int:
         overlap_all_arg = self._kwargs.get("overlap_all")
         return self.overlap if overlap_all_arg else 0
 
-    @lazyproperty
+    @cached_property
     def overlap(self) -> int:
         """The number of characters to overlap text when splitting chunks mid-text.
 
@@ -206,7 +206,7 @@ def overlap(self) -> int:
         overlap_arg = self._kwargs.get("overlap")
         return overlap_arg or 0
 
-    @lazyproperty
+    @cached_property
     def soft_max(self) -> int:
         """A pre-chunk of this size or greater is considered full.
 
@@ -238,7 +238,7 @@ def soft_max(self) -> int:
         # -- otherwise, give them what they asked for --
         return new_after_n_chars_arg
 
-    @lazyproperty
+    @cached_property
     def split(self) -> Callable[[str], tuple[str, str]]:
         """A text-splitting function suitable for splitting the text of an oversized pre-chunk.
 
@@ -247,7 +247,7 @@ def split(self) -> Callable[[str], tuple[str, str]]:
         """
         return _TextSplitter(self)
 
-    @lazyproperty
+    @cached_property
     def text_separator(self) -> str:
         """The string to insert between elements when concatenating their text for a chunk.
 
@@ -257,7 +257,7 @@ def text_separator(self) -> str:
         """
         return "\n\n"
 
-    @lazyproperty
+    @cached_property
     def text_splitting_separators(self) -> tuple[str, ...]:
         """Sequence of text-splitting target strings to be used in order of preference."""
         text_splitting_separators_arg = self._kwargs.get("text_splitting_separators")
@@ -267,13 +267,13 @@ def text_splitting_separators(self) -> tuple[str, ...]:
             else tuple(text_splitting_separators_arg)
         )
 
-    @lazyproperty
+    @cached_property
     def token_counter(self) -> TokenCounter | None:
         """The token counter for token-based chunking, or None for character-based chunking."""
         tokenizer = self._kwargs.get("tokenizer")
         return TokenCounter(tokenizer) if tokenizer else None
 
-    @lazyproperty
+    @cached_property
     def use_token_counting(self) -> bool:
         """True when token-based chunking is configured, False for character-based."""
         return self._kwargs.get("max_tokens") is not None
@@ -401,7 +401,7 @@ def _iter_pre_chunks(self) -> Iterator[PreChunk]:
         # -- processed
         yield from pre_chunk_builder.flush()
 
-    @lazyproperty
+    @cached_property
     def _boundary_predicates(self) -> tuple[BoundaryPredicate, ...]:
         """The semantic-boundary detectors to be applied to break pre-chunks."""
         return self._opts.boundary_predicates
@@ -600,7 +600,7 @@ def iter_chunks(self) -> Iterator[CompositeElement | Table | TableChunk]:
         else:
             yield from _Chunker.iter_chunks(self._elements, self._text, self._opts)
 
-    @lazyproperty
+    @cached_property
     def overlap_tail(self) -> str:
         """The portion of this chunk's text to be repeated as a prefix in the next chunk.
 
@@ -629,7 +629,7 @@ def _iter_text_segments(self) -> Iterator[str]:
                     if text:
                         yield text
 
-    @lazyproperty
+    @cached_property
     def _text(self) -> str:
         """The concatenated text of all elements in this pre-chunk, including any overlap.
 
@@ -686,7 +686,7 @@ def _iter_chunks(self) -> Iterator[CompositeElement]:
             s, remainder = split(remainder)
             yield CompositeElement(text=s, metadata=self._continuation_metadata)
 
-    @lazyproperty
+    @cached_property
     def _all_metadata_values(self) -> dict[str, list[Any]]:
         """Collection of all populated metadata values across elements.
 
@@ -721,7 +721,7 @@ def iter_populated_fields(metadata: ElementMetadata) -> Iterator[tuple[str, Any]
 
         return dict(field_values)
 
-    @lazyproperty
+    @cached_property
     def _consolidated_metadata(self) -> ElementMetadata:
         """Metadata applicable to this pre-chunk as a single chunk.
 
@@ -737,7 +737,7 @@ def _consolidated_metadata(self) -> ElementMetadata:
             consolidated_metadata.orig_elements = self._orig_elements
         return consolidated_metadata
 
-    @lazyproperty
+    @cached_property
     def _continuation_metadata(self) -> ElementMetadata:
         """Metadata applicable to the second and later text-split chunks of the pre-chunk.
 
@@ -751,7 +751,7 @@ def _continuation_metadata(self) -> ElementMetadata:
         continuation_metadata.is_continuation = True
         return continuation_metadata
 
-    @lazyproperty
+    @cached_property
     def _meta_kwargs(self) -> dict[str, Any]:
         """The consolidated metadata values as a dict suitable for constructing ElementMetadata.
 
@@ -788,7 +788,7 @@ def iter_kwarg_pairs() -> Iterator[tuple[str, Any]]:
 
         return dict(iter_kwarg_pairs())
 
-    @lazyproperty
+    @cached_property
     def _orig_elements(self) -> list[Element]:
         """The `.metadata.orig_elements` value for chunks formed from this pre-chunk."""
 
@@ -859,7 +859,7 @@ def _iter_chunks(self) -> Iterator[Table | TableChunk]:
         # -- otherwise, form splits with "synchronized" text and html --
         yield from self._iter_text_and_html_table_chunks()
 
-    @lazyproperty
+    @cached_property
     def _html(self) -> str:
         """The compactified HTML for this table when it has text-as-HTML.
 
@@ -871,7 +871,7 @@ def _html(self) -> str:
 
         return html_table.html
 
-    @lazyproperty
+    @cached_property
     def _html_table(self) -> HtmlTable | None:
         """The `lxml` HTML element object for this table.
 
@@ -975,7 +975,7 @@ def _metadata(self) -> ElementMetadata:
             metadata.orig_elements = self._orig_elements
         return metadata
 
-    @lazyproperty
+    @cached_property
     def _orig_elements(self) -> list[Element]:
         """The `.metadata.orig_elements` value for chunks formed from this pre-chunk.
 
@@ -990,14 +990,14 @@ def _orig_elements(self) -> list[Element]:
         orig_table.metadata.orig_elements = None
         return [orig_table]
 
-    @lazyproperty
+    @cached_property
     def _table_text(self) -> str:
         """The text in this table, not including any overlap-prefix or extra whitespace."""
         if not self._table.text:
             return ""
         return " ".join(self._table.text.split())
 
-    @lazyproperty
+    @cached_property
     def _text_with_overlap(self) -> str:
         """The text for this chunk, including the overlap-prefix when present."""
         overlap_prefix = self._overlap_prefix
@@ -1271,7 +1271,7 @@ def _get_token_overlap_tail(self, text: str, target_tokens: int) -> str:
 
         return text[pos:]
 
-    @lazyproperty
+    @cached_property
     def _patterns(self) -> tuple[tuple[regex.Pattern[str], int], ...]:
         """Sequence of (pattern, len) pairs to match against.
 

unstructured/chunking/dispatch.py

@@ -10,6 +10,7 @@
 import dataclasses as dc
 import functools
 import inspect
+from functools import cached_property
 from typing import Any, Callable, Iterable, Optional, Protocol
 
 from lxml.etree import tostring
@@ -19,7 +20,7 @@
 from unstructured.chunking.basic import chunk_elements
 from unstructured.chunking.title import chunk_by_title
 from unstructured.documents.elements import Element, Table, TableChunk
-from unstructured.utils import get_call_args_applying_defaults, lazyproperty
+from unstructured.utils import get_call_args_applying_defaults
 
 _P = ParamSpec("_P")
 
@@ -116,7 +117,7 @@ class _ChunkerSpec:
     chunker: Chunker
     """The "chunk_by_{x}() function that implements this chunking strategy."""
 
-    @lazyproperty
+    @cached_property
     def kw_arg_names(self) -> tuple[str, ...]:
         """Keyword arguments supported by this chunker.
 

unstructured/chunking/title.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+from functools import cached_property
 from typing import Iterable, Iterator, Optional
 
 from unstructured.chunking.base import (
@@ -17,7 +18,6 @@
     is_title,
 )
 from unstructured.documents.elements import Element
-from unstructured.utils import lazyproperty
 
 
 def chunk_by_title(
@@ -124,7 +124,7 @@ class _ByTitleChunkingOptions(ChunkingOptions):
         appearing on two different pages can appear in the same chunk.
     """
 
-    @lazyproperty
+    @cached_property
     def boundary_predicates(self) -> tuple[BoundaryPredicate, ...]:
         """The semantic-boundary detectors to be applied to break pre-chunks.
 
@@ -140,7 +140,7 @@ def iter_boundary_predicates() -> Iterator[BoundaryPredicate]:
 
         return tuple(iter_boundary_predicates())
 
-    @lazyproperty
+    @cached_property
     def combine_text_under_n_chars(self) -> int:
         """Combine consecutive text pre-chunks if former is smaller than this and both will fit.
 
@@ -152,7 +152,7 @@ def combine_text_under_n_chars(self) -> int:
         arg_value = self._kwargs.get("combine_text_under_n_chars")
         return self.hard_max if arg_value is None else arg_value
 
-    @lazyproperty
+    @cached_property
     def multipage_sections(self) -> bool:
         """When False, break pre-chunks on page-boundaries."""
         arg_value = self._kwargs.get("multipage_sections")