Make cache public (#3976)

* pulic cache

* changelog

* Apply suggestions from code review

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

---------

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Changed
 
 - Breaking change: `DOMNode.has_pseudo_class` now accepts a single name only https://github.com/Textualize/textual/pull/3970
+- Made `textual.cache` (formerly `textual._cache`) public https://github.com/Textualize/textual/pull/3976
 
 ### Added
 

docs/api/cache.md

@@ -0,0 +1 @@
+::: textual.cache

mkdocs-nav.yml

@@ -175,6 +175,7 @@ nav:
       - "api/await_complete.md"
       - "api/await_remove.md"
       - "api/binding.md"
+      - "api/cache.md"
       - "api/color.md"
       - "api/command.md"
       - "api/containers.md"

src/textual/cache.py

@@ -1,14 +1,9 @@
 """
 
-A LRU (Least Recently Used) Cache container.
+Containers to implement caching.
 
-Use when you want to cache slow operations and new keys are a good predictor
-of subsequent keys.
+These are used in Textual to avoid recalculating expensive operations, such as rendering.
 
-Note that stdlib's @lru_cache is implemented in C and faster! It's best to use
-@lru_cache where you are caching things that are fairly quick and called many times.
-Use LRUCache where you want increased flexibility and you are caching slow operations
-where the overhead of the cache is a small fraction of the total processing time.
 """
 
 from __future__ import annotations
@@ -34,6 +29,11 @@ class LRUCache(Generic[CacheKey, CacheValue]):
 
     Each entry is stored as [PREV, NEXT, KEY, VALUE] where PREV is a reference
     to the previous entry, and NEXT is a reference to the next value.
+
+    Note that stdlib's @lru_cache is implemented in C and faster! It's best to use
+    @lru_cache where you are caching things that are fairly quick and called many times.
+    Use LRUCache where you want increased flexibility and you are caching slow operations
+    where the overhead of the cache is a small fraction of the total processing time.
     """
 
     __slots__ = [
@@ -46,6 +46,11 @@ class LRUCache(Generic[CacheKey, CacheValue]):
     ]
 
     def __init__(self, maxsize: int) -> None:
+        """Initialize a LRUCache.
+
+        Args:
+            maxsize: Maximum size of the cache, before old items are discarded.
+        """
         self._maxsize = maxsize
         self._cache: Dict[CacheKey, list[object]] = {}
         self._full = False
@@ -208,8 +213,6 @@ class FIFOCache(Generic[CacheKey, CacheValue]):
     It is most suitable for a cache with a relatively low maximum size that is not expected to
     do many lookups.
 
-    Args:
-        maxsize: Maximum size of the cache.
     """
 
     __slots__ = [
@@ -220,6 +223,11 @@ class FIFOCache(Generic[CacheKey, CacheValue]):
     ]
 
     def __init__(self, maxsize: int) -> None:
+        """Initialize a FIFOCache.
+
+        Args:
+            maxsize: Maximum size of cache before discarding items.
+        """
         self._maxsize = maxsize
         self._cache: dict[CacheKey, CacheValue] = {}
         self.hits = 0

src/textual/css/stylesheet.py

@@ -14,7 +14,7 @@ from rich.padding import Padding
 from rich.panel import Panel
 from rich.text import Text
 
-from .._cache import LRUCache
+from ..cache import LRUCache
 from ..dom import DOMNode
 from ..widget import Widget
 from .errors import StylesheetError

src/textual/fuzzy.py

@@ -13,7 +13,7 @@ import rich.repr
 from rich.style import Style
 from rich.text import Text
 
-from ._cache import LRUCache
+from .cache import LRUCache
 
 
 @rich.repr.auto

src/textual/strip.py

@@ -16,8 +16,8 @@ from rich.measure import Measurement
 from rich.segment import Segment
 from rich.style import Style, StyleType
 
-from ._cache import FIFOCache
 from ._segment_tools import index_to_cell_position
+from .cache import FIFOCache
 from .color import Color
 from .constants import DEBUG
 from .filter import LineFilter

src/textual/suggester.py

@@ -10,7 +10,7 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from typing import Iterable
 
-from ._cache import LRUCache
+from .cache import LRUCache
 from .dom import DOMNode
 from .message import Message
 

src/textual/widget.py

@@ -42,7 +42,6 @@ from typing_extensions import Self
 from . import constants, errors, events, messages
 from ._animator import DEFAULT_EASING, Animatable, BoundAnimator, EasingFunction
 from ._arrange import DockArrangeResult, arrange
-from ._cache import FIFOCache
 from ._compose import compose
 from ._context import NoActiveAppError, active_app
 from ._easing import DEFAULT_SCROLL_EASING
@@ -52,6 +51,7 @@ from ._styles_cache import StylesCache
 from .actions import SkipAction
 from .await_remove import AwaitRemove
 from .box_model import BoxModel
+from .cache import FIFOCache
 from .css.query import NoMatches, WrongType
 from .css.scalar import ScalarOffset
 from .dom import DOMNode, NoScreen

src/textual/widgets/_data_table.py

@@ -16,11 +16,11 @@ from rich.text import Text, TextType
 from typing_extensions import Literal, Self, TypeAlias
 
 from .. import events
-from .._cache import LRUCache
 from .._segment_tools import line_crop
 from .._two_way_dict import TwoWayDict
 from .._types import SegmentLines
 from ..binding import Binding, BindingType
+from ..cache import LRUCache
 from ..color import Color
 from ..coordinate import Coordinate
 from ..geometry import Region, Size, Spacing, clamp

src/textual/widgets/_log.py

@@ -10,8 +10,8 @@ from rich.style import Style
 from rich.text import Text
 
 from .. import work
-from .._cache import LRUCache
 from .._line_split import line_split
+from ..cache import LRUCache
 from ..geometry import Size
 from ..reactive import var
 from ..scroll_view import ScrollView

src/textual/widgets/_rich_log.py

@@ -12,7 +12,7 @@ from rich.protocol import is_renderable
 from rich.segment import Segment
 from rich.text import Text
 
-from .._cache import LRUCache
+from ..cache import LRUCache
 from ..geometry import Region, Size
 from ..reactive import var
 from ..scroll_view import ScrollView

src/textual/widgets/_tree.py

@@ -10,11 +10,11 @@ from rich.style import NULL_STYLE, Style
 from rich.text import Text, TextType
 
 from .. import events
-from .._cache import LRUCache
 from .._immutable_sequence_view import ImmutableSequenceView
 from .._loop import loop_last
 from .._segment_tools import line_pad
 from ..binding import Binding, BindingType
+from ..cache import LRUCache
 from ..geometry import Region, Size, clamp
 from ..message import Message
 from ..reactive import reactive, var

tests/test_cache.py

@@ -2,7 +2,7 @@ from __future__ import annotations, unicode_literals
 
 import pytest
 
-from textual._cache import FIFOCache, LRUCache
+from textual.cache import FIFOCache, LRUCache
 
 
 def test_lru_cache():