nltcache 1.0.6__tar.gz

nltcache-1.0.6/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: nltcache
+Version: 1.0.6
+Summary: nltcache
+Author-email: niuliangtao <farfarfun@qq.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cachebox==5.0.1
+Requires-Dist: diskcache>=5.6.3
+Requires-Dist: nltlog>=1.0.9
+
+# funcache
+
+一个简洁的 Python 函数缓存装饰器库，提供多种缓存策略，涵盖内存缓存、磁盘缓存和 Pickle 文件缓存。
+
+## 安装
+
+```bash
+pip install funcache-tau
+```
+
+要求 Python >= 3.8。
+
+## 快速开始
+
+```python
+from funcache import lru_cache
+
+@lru_cache()
+def fibonacci(n):
+    if n < 2:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+print(fibonacci(50))
+```
+
+## 内存缓存
+
+基于 [cachebox](https://github.com/awolverp/cachebox) 实现，提供多种淘汰策略。
+
+### cache
+
+最简单的 LRU 缓存装饰器，默认 maxsize=1000，无需传参直接使用。
+
+```python
+from funcache import cache
+
+@cache
+def add(a, b):
+    return a + b
+```
+
+### lru_cache
+
+**LRU (Least Recently Used)** — 淘汰最久未被访问的缓存条目。
+
+```python
+from funcache import lru_cache
+
+@lru_cache(maxsize=500)
+def query(sql):
+    ...
+```
+
+### ttl_cache
+
+**TTL (Time To Live)** — 缓存条目在超过指定时间后自动过期。
+
+```python
+from funcache import ttl_cache
+
+@ttl_cache(maxsize=1000, ttl=300)  # 300 秒后过期
+def get_config(key):
+    ...
+```
+
+### vttl_cache
+
+**VTTL (Virtual TTL)** — 与 TTL 类似，但采用惰性淘汰策略，仅在访问时检查并移除过期条目。
+
+```python
+from funcache import vttl_cache
+
+@vttl_cache(maxsize=1000, ttl=60)
+def get_status(service):
+    ...
+```
+
+### lfu_cache
+
+**LFU (Least Frequently Used)** — 淘汰访问次数最少的缓存条目。
+
+```python
+from funcache import lfu_cache
+
+@lfu_cache(maxsize=1000)
+def translate(word):
+    ...
+```
+
+### fifo_cache
+
+**FIFO (First In First Out)** — 淘汰最早进入缓存的条目。
+
+```python
+from funcache import fifo_cache
+
+@fifo_cache(maxsize=1000)
+def process(data):
+    ...
+```
+
+### rr_cache
+
+**RR (Random Replacement)** — 随机淘汰一个缓存条目。
+
+```python
+from funcache import rr_cache
+
+@rr_cache(maxsize=1000)
+def compute(x):
+    ...
+```
+
+## 磁盘缓存
+
+### disk_cache
+
+基于 [diskcache](https://github.com/grantjenks/python-diskcache) 实现，将缓存持久化到本地磁盘，支持过期时间，适用于需要跨进程或重启后保留缓存的场景。
+
+```python
+from funcache import disk_cache
+
+@disk_cache(cache_key="query", expire=3600)  # 缓存 1 小时
+def search(query):
+    # 耗时的搜索操作
+    ...
+
+search("python cache")  # 首次执行，结果写入磁盘
+search("python cache")  # 命中缓存，直接返回
+```
+
+**参数说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cache_key` | `str` | *必填* | 用作缓存键的函数参数名 |
+| `cache_dir` | `str \| None` | `None` | 缓存目录，为 None 时自动生成 |
+| `is_cache` | `str` | `"cache"` | 控制是否启用缓存的布尔参数名 |
+| `expire` | `int` | `86400` | 缓存过期时间（秒），默认 1 天 |
+
+通过 `is_cache` 参数可以在运行时动态控制是否使用缓存：
+
+```python
+@disk_cache(cache_key="sql", is_cache="use_cache")
+def run_query(sql, use_cache=True):
+    ...
+
+run_query("SELECT ...", use_cache=False)  # 跳过缓存，直接执行
+```
+
+## Pickle 文件缓存
+
+### pkl_cache
+
+将函数结果序列化为 `.pkl` 文件存储到本地，适用于需要简单持久缓存但不想引入额外数据库的场景。
+
+```python
+from funcache import pkl_cache
+
+@pkl_cache(cache_key="filepath", cache_dir=".my_cache")
+def parse_file(filepath):
+    # 耗时的文件解析操作
+    ...
+
+parse_file("/data/large.csv")  # 首次执行，结果写入 .pkl 文件
+parse_file("/data/large.csv")  # 命中缓存
+```
+
+**参数说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cache_key` | `str` | *必填* | 用作缓存键的函数参数名 |
+| `cache_dir` | `str` | `".cache"` | 存储 pkl 文件的目录 |
+| `is_cache` | `str` | `"cache"` | 控制是否启用缓存的布尔参数名 |
+| `printf` | `bool` | `False` | 是否将缓存日志输出到 stdout |
+
+## 其他
+
+### cached_property
+
+重新导出自标准库 `functools.cached_property`，将方法结果缓存为实例属性。
+
+```python
+from funcache import cached_property
+
+class Config:
+    @cached_property
+    def settings(self):
+        # 仅在首次访问时执行
+        return load_settings()
+```
+
+## API 一览
+
+| 装饰器 | 存储位置 | 淘汰策略 | 支持过期 |
+|--------|---------|---------|---------|
+| `cache` | 内存 | LRU | - |
+| `lru_cache` | 内存 | LRU | - |
+| `lfu_cache` | 内存 | LFU | - |
+| `fifo_cache` | 内存 | FIFO | - |
+| `rr_cache` | 内存 | 随机 | - |
+| `ttl_cache` | 内存 | TTL | 是 |
+| `vttl_cache` | 内存 | VTTL (惰性) | 是 |
+| `disk_cache` | 磁盘 | - | 是 |
+| `pkl_cache` | 磁盘 (pkl) | - | - |
+| `cached_property` | 实例属性 | - | - |

nltcache-1.0.6/README.md

@@ -0,0 +1,208 @@
+# funcache
+
+一个简洁的 Python 函数缓存装饰器库，提供多种缓存策略，涵盖内存缓存、磁盘缓存和 Pickle 文件缓存。
+
+## 安装
+
+```bash
+pip install funcache-tau
+```
+
+要求 Python >= 3.8。
+
+## 快速开始
+
+```python
+from funcache import lru_cache
+
+@lru_cache()
+def fibonacci(n):
+    if n < 2:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+print(fibonacci(50))
+```
+
+## 内存缓存
+
+基于 [cachebox](https://github.com/awolverp/cachebox) 实现，提供多种淘汰策略。
+
+### cache
+
+最简单的 LRU 缓存装饰器，默认 maxsize=1000，无需传参直接使用。
+
+```python
+from funcache import cache
+
+@cache
+def add(a, b):
+    return a + b
+```
+
+### lru_cache
+
+**LRU (Least Recently Used)** — 淘汰最久未被访问的缓存条目。
+
+```python
+from funcache import lru_cache
+
+@lru_cache(maxsize=500)
+def query(sql):
+    ...
+```
+
+### ttl_cache
+
+**TTL (Time To Live)** — 缓存条目在超过指定时间后自动过期。
+
+```python
+from funcache import ttl_cache
+
+@ttl_cache(maxsize=1000, ttl=300)  # 300 秒后过期
+def get_config(key):
+    ...
+```
+
+### vttl_cache
+
+**VTTL (Virtual TTL)** — 与 TTL 类似，但采用惰性淘汰策略，仅在访问时检查并移除过期条目。
+
+```python
+from funcache import vttl_cache
+
+@vttl_cache(maxsize=1000, ttl=60)
+def get_status(service):
+    ...
+```
+
+### lfu_cache
+
+**LFU (Least Frequently Used)** — 淘汰访问次数最少的缓存条目。
+
+```python
+from funcache import lfu_cache
+
+@lfu_cache(maxsize=1000)
+def translate(word):
+    ...
+```
+
+### fifo_cache
+
+**FIFO (First In First Out)** — 淘汰最早进入缓存的条目。
+
+```python
+from funcache import fifo_cache
+
+@fifo_cache(maxsize=1000)
+def process(data):
+    ...
+```
+
+### rr_cache
+
+**RR (Random Replacement)** — 随机淘汰一个缓存条目。
+
+```python
+from funcache import rr_cache
+
+@rr_cache(maxsize=1000)
+def compute(x):
+    ...
+```
+
+## 磁盘缓存
+
+### disk_cache
+
+基于 [diskcache](https://github.com/grantjenks/python-diskcache) 实现，将缓存持久化到本地磁盘，支持过期时间，适用于需要跨进程或重启后保留缓存的场景。
+
+```python
+from funcache import disk_cache
+
+@disk_cache(cache_key="query", expire=3600)  # 缓存 1 小时
+def search(query):
+    # 耗时的搜索操作
+    ...
+
+search("python cache")  # 首次执行，结果写入磁盘
+search("python cache")  # 命中缓存，直接返回
+```
+
+**参数说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cache_key` | `str` | *必填* | 用作缓存键的函数参数名 |
+| `cache_dir` | `str \| None` | `None` | 缓存目录，为 None 时自动生成 |
+| `is_cache` | `str` | `"cache"` | 控制是否启用缓存的布尔参数名 |
+| `expire` | `int` | `86400` | 缓存过期时间（秒），默认 1 天 |
+
+通过 `is_cache` 参数可以在运行时动态控制是否使用缓存：
+
+```python
+@disk_cache(cache_key="sql", is_cache="use_cache")
+def run_query(sql, use_cache=True):
+    ...
+
+run_query("SELECT ...", use_cache=False)  # 跳过缓存，直接执行
+```
+
+## Pickle 文件缓存
+
+### pkl_cache
+
+将函数结果序列化为 `.pkl` 文件存储到本地，适用于需要简单持久缓存但不想引入额外数据库的场景。
+
+```python
+from funcache import pkl_cache
+
+@pkl_cache(cache_key="filepath", cache_dir=".my_cache")
+def parse_file(filepath):
+    # 耗时的文件解析操作
+    ...
+
+parse_file("/data/large.csv")  # 首次执行，结果写入 .pkl 文件
+parse_file("/data/large.csv")  # 命中缓存
+```
+
+**参数说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cache_key` | `str` | *必填* | 用作缓存键的函数参数名 |
+| `cache_dir` | `str` | `".cache"` | 存储 pkl 文件的目录 |
+| `is_cache` | `str` | `"cache"` | 控制是否启用缓存的布尔参数名 |
+| `printf` | `bool` | `False` | 是否将缓存日志输出到 stdout |
+
+## 其他
+
+### cached_property
+
+重新导出自标准库 `functools.cached_property`，将方法结果缓存为实例属性。
+
+```python
+from funcache import cached_property
+
+class Config:
+    @cached_property
+    def settings(self):
+        # 仅在首次访问时执行
+        return load_settings()
+```
+
+## API 一览
+
+| 装饰器 | 存储位置 | 淘汰策略 | 支持过期 |
+|--------|---------|---------|---------|
+| `cache` | 内存 | LRU | - |
+| `lru_cache` | 内存 | LRU | - |
+| `lfu_cache` | 内存 | LFU | - |
+| `fifo_cache` | 内存 | FIFO | - |
+| `rr_cache` | 内存 | 随机 | - |
+| `ttl_cache` | 内存 | TTL | 是 |
+| `vttl_cache` | 内存 | VTTL (惰性) | 是 |
+| `disk_cache` | 磁盘 | - | 是 |
+| `pkl_cache` | 磁盘 (pkl) | - | - |
+| `cached_property` | 实例属性 | - | - |

nltcache-1.0.6/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "nltcache"
+version = "1.0.6"
+description = "nltcache"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [ "cachebox==5.0.1", "diskcache>=5.6.3", "nltlog>=1.0.9",]
+[[project.authors]]
+name = "niuliangtao"
+email = "farfarfun@qq.com"
+
+[tool.setuptools]
+license-files = []

nltcache-1.0.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nltcache-1.0.6/src/nltcache/__init__.py

@@ -0,0 +1,26 @@
+from .box import (
+    cache,
+    fifo_cache,
+    lfu_cache,
+    lru_cache,
+    rr_cache,
+    ttl_cache,
+    vttl_cache,
+)
+from .core import PickleCache, cached_property, pkl_cache
+from .disk import DiskCache, disk_cache
+
+__all__ = [
+    "cache",
+    "lru_cache",
+    "ttl_cache",
+    "vttl_cache",
+    "lfu_cache",
+    "fifo_cache",
+    "rr_cache",
+    "PickleCache",
+    "pkl_cache",
+    "cached_property",
+    "disk_cache",
+    "DiskCache",
+]

nltcache-1.0.6/src/nltcache/_utils.py

@@ -0,0 +1,30 @@
+"""Internal utilities shared across funcache modules."""
+
+import inspect
+import os
+from typing import Any, Callable, Dict, Tuple
+
+
+def normalize_args(
+    func: Callable, args: Tuple[Any, ...], kwargs: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Convert positional arguments to keyword arguments based on function signature.
+
+    This merges positional args into a unified kwargs dict for consistent
+    cache key lookup by parameter name.
+    """
+    merged = dict(kwargs)
+    params = list(inspect.signature(func).parameters.items())
+    for i, (name, param) in enumerate(params):
+        if name not in merged:
+            merged[name] = args[i] if i < len(args) else param.default
+    return merged
+
+
+def ensure_gitignore(directory: str) -> None:
+    """Create a .gitignore with '*' in the given directory if one doesn't exist."""
+    os.makedirs(directory, exist_ok=True)
+    ignore_file = os.path.join(directory, ".gitignore")
+    if not os.path.exists(ignore_file):
+        with open(ignore_file, "w") as f:
+            f.write("*")

nltcache-1.0.6/src/nltcache/box.py

@@ -0,0 +1,66 @@
+from typing import Callable
+
+from cachebox import FIFOCache, LFUCache, LRUCache, RRCache, TTLCache, VTTLCache, cached
+
+__all__ = [
+    "cache",
+    "lru_cache",
+    "ttl_cache",
+    "vttl_cache",
+    "lfu_cache",
+    "fifo_cache",
+    "rr_cache",
+]
+
+
+def cache(func: Callable, /) -> Callable:
+    """Simple LRU cache decorator with a default maxsize of 1000."""
+    return cached(LRUCache(maxsize=1000))(func)
+
+
+def vttl_cache(maxsize: int = 1000, ttl: int = 60) -> Callable:
+    """VTTLCache: removes expired elements lazily when accessed.
+
+    VTTLCache: 在访问时才惰性移除已过期的缓存元素。
+    """
+    return lambda func: cached(VTTLCache(maxsize=maxsize, ttl=ttl))(func)
+
+
+def ttl_cache(maxsize: int = 1000, ttl: int = 60) -> Callable:
+    """TTLCache: automatically removes expired elements.
+
+    TTLCache：自动移除已过期的缓存元素。
+    """
+    return lambda func: cached(TTLCache(maxsize=maxsize, ttl=ttl))(func)
+
+
+def lru_cache(maxsize: int = 1000) -> Callable:
+    """LRUCache: removes the least recently used element.
+
+    LRUCache：移除缓存中自上次访问以来时间最长的元素。
+    """
+    return lambda func: cached(LRUCache(maxsize=maxsize))(func)
+
+
+def lfu_cache(maxsize: int = 1000) -> Callable:
+    """LFUCache: removes the least frequently used element.
+
+    LFUCache：移除缓存中访问次数最少的元素，不论其访问时间。
+    """
+    return lambda func: cached(LFUCache(maxsize=maxsize))(func)
+
+
+def fifo_cache(maxsize: int = 1000) -> Callable:
+    """FIFOCache: removes the oldest element.
+
+    FIFOCache：移除在缓存中停留时间最长的元素。
+    """
+    return lambda func: cached(FIFOCache(maxsize=maxsize))(func)
+
+
+def rr_cache(maxsize: int = 1000) -> Callable:
+    """RRCache: randomly removes an element when space is needed.
+
+    RRCache: 在必要时随机选择一个元素进行移除，以腾出空间。
+    """
+    return lambda func: cached(RRCache(maxsize=maxsize))(func)

nltcache-1.0.6/src/nltcache/core.py

@@ -0,0 +1,97 @@
+import hashlib
+import os
+import pickle
+from functools import cached_property, wraps
+from typing import Any, Callable, Optional
+
+from funlog import getLogger
+
+from ._utils import ensure_gitignore, normalize_args
+
+logger = getLogger("funcache")
+
+__all__ = ["PickleCache", "pkl_cache", "cached_property"]
+
+
+class PickleCache:
+    """Decorator that caches function results to pickle files on disk.
+
+    Args:
+        cache_key: The name of the function parameter whose value is used as the cache key.
+        cache_dir: Directory to store pickle cache files.
+        is_cache: The name of a boolean parameter that controls whether caching is enabled.
+        printf: If True, also print cache log messages to stdout.
+    """
+
+    def __init__(
+        self,
+        cache_key: str,
+        cache_dir: str = ".cache",
+        is_cache: str = "cache",
+        printf: bool = False,
+    ) -> None:
+        self.cache_key = cache_key
+        self.cache_dir = cache_dir
+        self.is_cache = is_cache
+        self.printf = printf
+
+    def _log(self, msg: str) -> None:
+        if self.printf:
+            print(msg)
+        logger.debug(msg)
+
+    def _get_cache_file(self, key: str) -> str:
+        hashed = hashlib.md5(str(key).encode()).hexdigest()
+        return os.path.join(self.cache_dir, f"{hashed}.pkl")
+
+    @staticmethod
+    def _load_cache(cache_file: str) -> Optional[Any]:
+        try:
+            with open(cache_file, "rb") as f:
+                return pickle.load(f)
+        except (FileNotFoundError, pickle.PickleError):
+            return None
+
+    def _save_cache(self, cache_file: str, data: Any) -> None:
+        ensure_gitignore(self.cache_dir)
+        with open(cache_file, "wb") as f:
+            pickle.dump(data, f)
+
+    def __call__(self, func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            merged = normalize_args(func, args, kwargs)
+
+            is_cache = merged.get(self.is_cache, True)
+            cache_key = merged.get(self.cache_key, "")
+            is_cache = is_cache and cache_key is not None
+
+            if is_cache:
+                cache_file = self._get_cache_file(cache_key)
+                cached_result = self._load_cache(cache_file)
+                if cached_result is not None:
+                    self._log(
+                        f"Cache hit for function '{func.__name__}' with key: {cache_key}"
+                    )
+                    return cached_result
+
+            result = func(**merged)
+
+            if is_cache:
+                self._save_cache(cache_file, result)
+                self._log(
+                    f"Cache data for function '{func.__name__}' with key: {cache_key}"
+                )
+            return result
+
+        return wrapper
+
+
+def pkl_cache(
+    cache_key: str,
+    cache_dir: str = ".cache",
+    is_cache: str = "cache",
+    printf: bool = False,
+) -> PickleCache:
+    """Convenience factory for :class:`PickleCache`."""
+    return PickleCache(cache_key, cache_dir, is_cache, printf=printf)

nltcache-1.0.6/src/nltcache/disk.py

@@ -0,0 +1,97 @@
+import os
+from functools import wraps
+from hashlib import md5
+from typing import Any, Callable, Optional
+
+from diskcache import Cache
+from funlog import getLogger
+
+from ._utils import ensure_gitignore, normalize_args
+
+logger = getLogger("funcache")
+
+__all__ = ["DiskCache", "disk_cache"]
+
+
+class DiskCache:
+    """Decorator that caches function results using :class:`diskcache.Cache`.
+
+    Args:
+        cache_key: The name of the function parameter whose value is used as the cache key.
+        cache_dir: Directory for the disk cache. Auto-generated from the function if *None*.
+        is_cache: The name of a boolean parameter that controls whether caching is enabled.
+        expire: Cache entry expiration time in seconds (default: 1 day).
+    """
+
+    def __init__(
+        self,
+        cache_key: str,
+        cache_dir: Optional[str] = None,
+        is_cache: str = "cache",
+        expire: int = 60 * 60 * 24,
+    ) -> None:
+        self.cache_key = cache_key
+        self.cache_dir = cache_dir
+        self.is_cache = is_cache
+        self.expire = expire
+        self._cache: Optional[Cache] = None
+
+    def _init_cache(self, func: Callable) -> Cache:
+        if self._cache is not None:
+            return self._cache
+
+        if self.cache_dir is None:
+            uid = md5(func.__code__.co_filename.encode("utf-8")).hexdigest()
+            self.cache_dir = os.path.join(".disk_cache", f"{uid}-{func.__name__}")
+
+        self._cache = Cache(self.cache_dir)
+        ensure_gitignore(self.cache_dir)
+
+        logger.success(
+            f"init func {func.__name__} success. with cache_dir: {self.cache_dir}"
+        )
+        return self._cache
+
+    def __call__(self, func: Callable) -> Callable:
+        cache = self._init_cache(func)
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            merged = normalize_args(func, args, kwargs)
+
+            cache_key = merged.get(self.cache_key, "")
+            is_cache = merged.get(self.is_cache, True) and cache_key is not None
+
+            if not is_cache:
+                return func(**merged)
+
+            cached_result = cache.get(cache_key)
+            if cached_result is not None:
+                logger.debug(
+                    f"Cache hit for function '{func.__name__}' with key: {cache_key}"
+                )
+                return cached_result
+
+            result = func(**merged)
+            cache.set(cache_key, result, expire=self.expire)
+            logger.debug(
+                f"Cache data for function '{func.__name__}' with key: {cache_key}"
+            )
+            return result
+
+        return wrapper
+
+
+def disk_cache(
+    cache_key: str,
+    cache_dir: Optional[str] = None,
+    is_cache: str = "cache",
+    expire: int = 60 * 60 * 24,
+) -> DiskCache:
+    """Convenience factory for :class:`DiskCache`."""
+    return DiskCache(
+        cache_key=cache_key,
+        cache_dir=cache_dir,
+        is_cache=is_cache,
+        expire=expire,
+    )

nltcache-1.0.6/src/nltcache.egg-info/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: nltcache
+Version: 1.0.6
+Summary: nltcache
+Author-email: niuliangtao <farfarfun@qq.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cachebox==5.0.1
+Requires-Dist: diskcache>=5.6.3
+Requires-Dist: nltlog>=1.0.9
+
+# funcache
+
+一个简洁的 Python 函数缓存装饰器库，提供多种缓存策略，涵盖内存缓存、磁盘缓存和 Pickle 文件缓存。
+
+## 安装
+
+```bash
+pip install funcache-tau
+```
+
+要求 Python >= 3.8。
+
+## 快速开始
+
+```python
+from funcache import lru_cache
+
+@lru_cache()
+def fibonacci(n):
+    if n < 2:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+print(fibonacci(50))
+```
+
+## 内存缓存
+
+基于 [cachebox](https://github.com/awolverp/cachebox) 实现，提供多种淘汰策略。
+
+### cache
+
+最简单的 LRU 缓存装饰器，默认 maxsize=1000，无需传参直接使用。
+
+```python
+from funcache import cache
+
+@cache
+def add(a, b):
+    return a + b
+```
+
+### lru_cache
+
+**LRU (Least Recently Used)** — 淘汰最久未被访问的缓存条目。
+
+```python
+from funcache import lru_cache
+
+@lru_cache(maxsize=500)
+def query(sql):
+    ...
+```
+
+### ttl_cache
+
+**TTL (Time To Live)** — 缓存条目在超过指定时间后自动过期。
+
+```python
+from funcache import ttl_cache
+
+@ttl_cache(maxsize=1000, ttl=300)  # 300 秒后过期
+def get_config(key):
+    ...
+```
+
+### vttl_cache
+
+**VTTL (Virtual TTL)** — 与 TTL 类似，但采用惰性淘汰策略，仅在访问时检查并移除过期条目。
+
+```python
+from funcache import vttl_cache
+
+@vttl_cache(maxsize=1000, ttl=60)
+def get_status(service):
+    ...
+```
+
+### lfu_cache
+
+**LFU (Least Frequently Used)** — 淘汰访问次数最少的缓存条目。
+
+```python
+from funcache import lfu_cache
+
+@lfu_cache(maxsize=1000)
+def translate(word):
+    ...
+```
+
+### fifo_cache
+
+**FIFO (First In First Out)** — 淘汰最早进入缓存的条目。
+
+```python
+from funcache import fifo_cache
+
+@fifo_cache(maxsize=1000)
+def process(data):
+    ...
+```
+
+### rr_cache
+
+**RR (Random Replacement)** — 随机淘汰一个缓存条目。
+
+```python
+from funcache import rr_cache
+
+@rr_cache(maxsize=1000)
+def compute(x):
+    ...
+```
+
+## 磁盘缓存
+
+### disk_cache
+
+基于 [diskcache](https://github.com/grantjenks/python-diskcache) 实现，将缓存持久化到本地磁盘，支持过期时间，适用于需要跨进程或重启后保留缓存的场景。
+
+```python
+from funcache import disk_cache
+
+@disk_cache(cache_key="query", expire=3600)  # 缓存 1 小时
+def search(query):
+    # 耗时的搜索操作
+    ...
+
+search("python cache")  # 首次执行，结果写入磁盘
+search("python cache")  # 命中缓存，直接返回
+```
+
+**参数说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cache_key` | `str` | *必填* | 用作缓存键的函数参数名 |
+| `cache_dir` | `str \| None` | `None` | 缓存目录，为 None 时自动生成 |
+| `is_cache` | `str` | `"cache"` | 控制是否启用缓存的布尔参数名 |
+| `expire` | `int` | `86400` | 缓存过期时间（秒），默认 1 天 |
+
+通过 `is_cache` 参数可以在运行时动态控制是否使用缓存：
+
+```python
+@disk_cache(cache_key="sql", is_cache="use_cache")
+def run_query(sql, use_cache=True):
+    ...
+
+run_query("SELECT ...", use_cache=False)  # 跳过缓存，直接执行
+```
+
+## Pickle 文件缓存
+
+### pkl_cache
+
+将函数结果序列化为 `.pkl` 文件存储到本地，适用于需要简单持久缓存但不想引入额外数据库的场景。
+
+```python
+from funcache import pkl_cache
+
+@pkl_cache(cache_key="filepath", cache_dir=".my_cache")
+def parse_file(filepath):
+    # 耗时的文件解析操作
+    ...
+
+parse_file("/data/large.csv")  # 首次执行，结果写入 .pkl 文件
+parse_file("/data/large.csv")  # 命中缓存
+```
+
+**参数说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cache_key` | `str` | *必填* | 用作缓存键的函数参数名 |
+| `cache_dir` | `str` | `".cache"` | 存储 pkl 文件的目录 |
+| `is_cache` | `str` | `"cache"` | 控制是否启用缓存的布尔参数名 |
+| `printf` | `bool` | `False` | 是否将缓存日志输出到 stdout |
+
+## 其他
+
+### cached_property
+
+重新导出自标准库 `functools.cached_property`，将方法结果缓存为实例属性。
+
+```python
+from funcache import cached_property
+
+class Config:
+    @cached_property
+    def settings(self):
+        # 仅在首次访问时执行
+        return load_settings()
+```
+
+## API 一览
+
+| 装饰器 | 存储位置 | 淘汰策略 | 支持过期 |
+|--------|---------|---------|---------|
+| `cache` | 内存 | LRU | - |
+| `lru_cache` | 内存 | LRU | - |
+| `lfu_cache` | 内存 | LFU | - |
+| `fifo_cache` | 内存 | FIFO | - |
+| `rr_cache` | 内存 | 随机 | - |
+| `ttl_cache` | 内存 | TTL | 是 |
+| `vttl_cache` | 内存 | VTTL (惰性) | 是 |
+| `disk_cache` | 磁盘 | - | 是 |
+| `pkl_cache` | 磁盘 (pkl) | - | - |
+| `cached_property` | 实例属性 | - | - |

nltcache-1.0.6/src/nltcache.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/nltcache/__init__.py
+src/nltcache/_utils.py
+src/nltcache/box.py
+src/nltcache/core.py
+src/nltcache/disk.py
+src/nltcache.egg-info/PKG-INFO
+src/nltcache.egg-info/SOURCES.txt
+src/nltcache.egg-info/dependency_links.txt
+src/nltcache.egg-info/requires.txt
+src/nltcache.egg-info/top_level.txt

nltcache-1.0.6/src/nltcache.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nltcache-1.0.6/src/nltcache.egg-info/requires.txt

@@ -0,0 +1,3 @@
+cachebox==5.0.1
+diskcache>=5.6.3
+nltlog>=1.0.9

nltcache-1.0.6/src/nltcache.egg-info/top_level.txt

@@ -0,0 +1 @@
+nltcache