pickle-debug 1.0__py3-none-any.whl

pickle_debug/__init__.py

@@ -0,0 +1,84 @@
+import functools
+import hashlib
+import importlib.metadata
+import logging
+import os
+import pickle
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any, Callable
+
+pickle_debug_logger = logging.getLogger(__name__)
+
+__version__ = importlib.metadata.version('pickle-debug')
+
+_CACHE_DIRECTORY: Path | None = None
+_SUFFIX = '.pickle'
+
+
+def enable(directory: Path | str) -> None:
+    """Enable caching in specified directory. Raises OSError if directory can't be created or written"""
+    global _CACHE_DIRECTORY
+    directory = Path(directory)
+    directory.mkdir(parents=True, exist_ok=True)
+    # verify we can create and write files
+    with tempfile.TemporaryFile(dir=directory) as f:
+        f.write(b'test')
+    _CACHE_DIRECTORY = directory
+    pickle_debug_logger.debug(f"caching to {directory}")
+
+
+def reset() -> None:
+    """Remove entire cache directory. Raises exception if it exists and can't be removed"""
+    if _CACHE_DIRECTORY is None or not _CACHE_DIRECTORY.exists():
+        return
+    unexpected = [p for p in _CACHE_DIRECTORY.iterdir()
+                  if not (p.is_file() and not p.is_symlink() and p.suffix in (_SUFFIX, '.tmp'))]
+    if unexpected:
+        raise RuntimeError(f"Not removing {_CACHE_DIRECTORY}, unexpected contents: "
+                           + ', '.join(p.name for p in unexpected))
+    try:
+        shutil.rmtree(_CACHE_DIRECTORY)
+    except OSError as e:
+        raise RuntimeError(f"Unable to remove cache {_CACHE_DIRECTORY}") from e
+    if _CACHE_DIRECTORY.exists():
+        raise RuntimeError(f"Unable to remove cache {_CACHE_DIRECTORY}")
+
+
+def _save(path: Path, result: Any) -> None:
+    """Write via temporary file so an interrupted write doesn't leave partial result"""
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix='.tmp')
+    try:
+        with os.fdopen(fd, 'wb') as f:
+            pickle.dump(result, f)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def cached(func: Callable) -> Callable:
+    """Decorator: cache result of func in directory set by enable(), keyed by arguments"""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        directory = _CACHE_DIRECTORY
+        if directory is None:
+            return func(*args, **kwargs)
+        key = pickle.dumps((func.__module__, func.__qualname__, args, sorted(kwargs.items())))
+        path = directory / (hashlib.sha256(key).hexdigest() + _SUFFIX)
+        try:
+            with open(path, 'rb') as f:
+                result = pickle.load(f)
+            pickle_debug_logger.debug(f"{func.__qualname__} read from {path}")
+            return result
+        except FileNotFoundError:
+            pass
+        result = func(*args, **kwargs)
+        directory.mkdir(parents=True, exist_ok=True)
+        _save(path, result)
+        pickle_debug_logger.debug(f"{func.__qualname__} stored in {path}")
+        return result
+
+    return wrapper

pickle_debug-1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pickle_debug
+Version: 1.0
+Summary: Store expensive objects from debugging
+Author: Gerard
+Author-email: gweatherby@uchc.edu
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pickle-debug
+Pickle expensive operations for debugging operation
+
+When debugging code that runs after a slow step (loading a large file, a long computation, a network call),
+re-running the slow step on every iteration wastes time. `pickle_debug` caches the return value of
+selected functions on disk, so the first call computes and stores the result and later calls with the
+same arguments load it from the cache.
+
+Requires Python 3.12 or later. No dependencies.
+
+## Usage
+
+```python
+import pickle_debug
+
+@pickle_debug.cached
+def load_data(path, limit=None):
+    ...  # slow
+
+pickle_debug.enable("/tmp/mycache")
+
+load_data("big.csv")   # computed, then stored
+load_data("big.csv")   # read from cache
+```
+
+Caching is off until `enable()` is called. Until then, decorated functions simply call through.
+This makes it safe to leave the `@cached` decorators in place and turn caching on only while debugging.
+
+### Decorating a function from another module
+
+A decorator is an ordinary function, so you can apply it after importing:
+
+```python
+import other_module
+other_module.slow = pickle_debug.cached(other_module.slow)
+```
+
+This affects callers that look up `other_module.slow` at call time. Modules that already did
+`from other_module import slow` keep the undecorated function, so patch before they import it.
+
+### Methods
+
+```python
+slow = Slow()
+slow.invoke = pickle_debug.cached(slow.invoke)   # one instance
+
+Slow.invoke = pickle_debug.cached(Slow.invoke)   # all instances
+```
+
+## API
+
+### `enable(directory)`
+Turn caching on, storing results in `directory` (a `str` or `Path`). The directory is created if
+needed and checked for writability. Raises `OSError` if it cannot be created or written.
+
+### `cached(func)`
+Decorator. Returns a wrapper (using `functools.wraps`) that:
+
+1. calls `func` directly if caching is not enabled;
+2. otherwise builds a key from `func.__module__`, `func.__qualname__`, the positional arguments and
+   the sorted keyword arguments, and hashes it with SHA-256;
+3. returns the pickled result from `<directory>/<hash>.pickle` if present;
+4. otherwise calls `func`, writes the result to the cache, and returns it.
+
+Results are written to a temporary file and then renamed, so an interrupted run does not leave a partial
+cache entry.
+
+### `reset()`
+Delete the whole cache directory. It refuses (raises `RuntimeError`) if the directory contains anything
+other than `.pickle` and `.tmp` files, to avoid deleting unrelated data if `enable()` was pointed at the
+wrong place. It does nothing if caching is not enabled or the directory does not exist.
+
+## Caveats
+
+- **Arguments and results must be picklable.** The arguments are pickled to build the key, and the result
+  is pickled to store it.
+- **The key is the pickled arguments.** Equal arguments that pickle differently (for example sets with a
+  different iteration order) may miss the cache. Objects whose pickle changes between calls never hit it.
+- **The key does not include the function's code or any files it reads.** If you change the function or
+  its input data, call `reset()` or use a new cache directory, or you will get stale results.
+- **Bound methods and `self`.** A wrapped bound method (`slow.invoke`) does not include `self` in the key,
+  so all instances share entries. A wrapped class function (`Slow.invoke`) includes `self`, so the
+  instance must be picklable and its state is part of the key.
+- This is a debugging aid. Do not use it as a production cache. Cached files are loaded with `pickle`,
+  so only use a directory you trust.
+
+## Logging
+
+The module logs to the `pickle_debug` logger at `DEBUG` level when it enables caching, reads from the
+cache, or stores a result.

pickle_debug-1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pickle_debug/__init__.py,sha256=p4KhG1gXI5l_E4oBN1Bb_I0uj69CL2cz0tu_GqfMRek,2951
+pickle_debug-1.0.dist-info/licenses/LICENSE,sha256=kZWT22beIUMcucFOsCTbUT97IwKS7dzjUlVFm8tRzuY,1063
+test/patch_test.py,sha256=HGZF9ZRufenD5tlEUjHfSOemZpLFt4HG5l6Ff9n1Rrw,397
+test/pd_test.py,sha256=dYNULIBaCm8M-DjcgswRewTxEAJ3_zEChNmrfyZaGOw,990
+test/ttest.py,sha256=3VJ9VE6lYAfteulpsf5KL-st-0yQg24hFSu9Qb13uGk,273
+pickle_debug-1.0.dist-info/METADATA,sha256=wQoKyOVfBmYoYl0LRtJSUy2eiNTDK57vahE04zPR2IM,3958
+pickle_debug-1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pickle_debug-1.0.dist-info/top_level.txt,sha256=8PVaLGUiMvXr3X6lNQ7vkV7i2y1I4Toa2rosLI2wIqA,18
+pickle_debug-1.0.dist-info/RECORD,,

pickle_debug-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pickle_debug-1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NMRhub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pickle_debug-1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+pickle_debug
+test

test/patch_test.py

@@ -0,0 +1,27 @@
+import time
+
+import pickle_debug
+
+
+def f(x, y=1):
+    print(f"call {x} {y}")
+    time.sleep(1.5)
+    return x + y
+
+class Slow:
+
+    def invoke(self,x):
+        time.sleep(1.5)
+        return x * x
+
+
+pickle_debug.enable("/tmp/mycache")
+
+f = pickle_debug.cached(f)
+print(f(5,6))
+print(f(5,6))
+
+slow = Slow()
+slow.invoke = pickle_debug.cached(slow.invoke)
+print(slow.invoke(7))
+print(slow.invoke(7))

test/pd_test.py

@@ -0,0 +1,43 @@
+import pathlib
+import tempfile
+
+from pickle_debug import cached, enable, reset
+
+calls = []
+
+
+@cached
+def f(x, y=1):
+    calls.append((x, y))
+    return [x, y]
+
+
+assert f(1) == [1, 1] and f(1) == [1, 1] and len(calls) == 2  # disabled: passthrough
+d = pathlib.Path(tempfile.mkdtemp()) / 'cache'
+enable(d)
+assert d.is_dir()
+calls.clear()
+assert f(2, y=3) == [2, 3]
+assert f(2, y=3) == [2, 3]
+assert f(2) == [2, 1]
+assert len(calls) == 2, calls
+assert len(list(d.glob('*.pickle'))) == 2
+(d / 'keep.txt').write_text('x')
+try:
+    reset()
+    raise SystemExit('reset should refuse')
+except RuntimeError as e:
+    print('reset refusal ok:', e)
+assert (d / 'keep.txt').exists() and len(list(d.glob('*.pickle'))) == 2
+(d / 'keep.txt').unlink()
+reset()
+assert not d.exists()
+f(2, y=3)
+assert len(calls) == 3
+assert len(list(d.glob('*.pickle'))) == 1
+try:
+    enable('/proc/nope')
+    raise SystemExit('should fail')
+except OSError as e:
+    print('enable failure ok:', type(e).__name__)
+print('ok')

test/ttest.py

@@ -0,0 +1,20 @@
+import time
+
+import pickle_debug
+
+
+@pickle_debug.cached
+def f(x, y=1):
+    print(f"call {x} {y}")
+    time.sleep(1.5)
+    return x + y  
+
+print(f(1,2))
+print(f(1,2))
+pickle_debug.enable("/tmp/mycache")
+print(f(1,2))
+print(f(1,2))
+print(f(3,4))
+print(f(1,2))
+print(f(3,4))
+