pickle-debug 1.2__tar.gz → 2.1__tar.gz

{pickle_debug-1.2/src/pickle_debug.egg-info → pickle_debug-2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pickle_debug
-Version: 1.2
+Version: 2.1
 Summary: Store expensive objects from debugging
 Author: Gerard
 Author-email: gweatherby@uchc.edu
@@ -59,18 +59,49 @@ slow.invoke = pickle_debug.cached(slow.invoke)   # one instance
 Slow.invoke = pickle_debug.cached(Slow.invoke)   # all instances
 ```
 
+The decorator also works inside a class body. For a classmethod, put `@cached` below `@classmethod`:
+
+```python
+class Slow:
+    @pickle_debug.cached
+    def invoke(self, x):
+        ...
+
+    @classmethod
+    @pickle_debug.cached
+    def build(cls, x):
+        ...
+```
+
+A wrapper may be needed to cache some functions, e.g. a method returning a generator:
+
+```python
+def something(x,y,z)->Generator:
+
+@pickle_debug.cached
+def cache_something(x,y,z)->list:
+	return list(something(x,y,z))
+```
+
+When a cached function is called as a method, `self` (or `cls`) is keyed by its class's name
+(`module.QualifiedName`), not its current value. All instances of a class share cache entries, and the
+instance does not need to be picklable. Subclasses get their own entries. Static methods are keyed like
+plain functions.
+
 ## API
 
-### `enable(directory)`
+### `enable(directory: str | Path | None)`
 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.
+enable(None) disables caching.
 
 ### `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;
+   the sorted keyword arguments, and hashes it with SHA-256. If `func` is called as a method, the
+   first argument (`self` or `cls`) is replaced by its class's name (see [Methods](#methods));
 3. returns the pickled result from `<directory>/<hash>.pickle` if present;
 4. otherwise calls `func`, writes the result to the cache, and returns it.
 
@@ -101,13 +132,15 @@ wrong place. It does nothing if caching is not enabled or the directory does not
   [Unpicklable attributes](#unpicklable-attributes)). The arguments are pickled to build the key, and the
   result is pickled to store it. Because dropped attributes are not part of the key, two arguments that
   differ only in unpicklable attributes share a cache entry.
+- **Wrappers may be required** for methods that return generators.
 - **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.
+- **Instance state is not part of the key.** Methods are keyed by the class of `self` or `cls`, not by its
+  value, so all instances of a class share entries. If a method's result depends on instance attributes,
+  instances with different state will get each other's cached results. Pass that state as an argument
+  instead, or call `reset()` between runs.
 - 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.
 

{pickle_debug-1.2 → pickle_debug-2.1}/README.md

@@ -47,18 +47,49 @@ slow.invoke = pickle_debug.cached(slow.invoke)   # one instance
 Slow.invoke = pickle_debug.cached(Slow.invoke)   # all instances
 ```
 
+The decorator also works inside a class body. For a classmethod, put `@cached` below `@classmethod`:
+
+```python
+class Slow:
+    @pickle_debug.cached
+    def invoke(self, x):
+        ...
+
+    @classmethod
+    @pickle_debug.cached
+    def build(cls, x):
+        ...
+```
+
+A wrapper may be needed to cache some functions, e.g. a method returning a generator:
+
+```python
+def something(x,y,z)->Generator:
+
+@pickle_debug.cached
+def cache_something(x,y,z)->list:
+	return list(something(x,y,z))
+```
+
+When a cached function is called as a method, `self` (or `cls`) is keyed by its class's name
+(`module.QualifiedName`), not its current value. All instances of a class share cache entries, and the
+instance does not need to be picklable. Subclasses get their own entries. Static methods are keyed like
+plain functions.
+
 ## API
 
-### `enable(directory)`
+### `enable(directory: str | Path | None)`
 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.
+enable(None) disables caching.
 
 ### `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;
+   the sorted keyword arguments, and hashes it with SHA-256. If `func` is called as a method, the
+   first argument (`self` or `cls`) is replaced by its class's name (see [Methods](#methods));
 3. returns the pickled result from `<directory>/<hash>.pickle` if present;
 4. otherwise calls `func`, writes the result to the cache, and returns it.
 
@@ -89,13 +120,15 @@ wrong place. It does nothing if caching is not enabled or the directory does not
   [Unpicklable attributes](#unpicklable-attributes)). The arguments are pickled to build the key, and the
   result is pickled to store it. Because dropped attributes are not part of the key, two arguments that
   differ only in unpicklable attributes share a cache entry.
+- **Wrappers may be required** for methods that return generators.
 - **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.
+- **Instance state is not part of the key.** Methods are keyed by the class of `self` or `cls`, not by its
+  value, so all instances of a class share entries. If a method's result depends on instance attributes,
+  instances with different state will get each other's cached results. Pass that state as an argument
+  instead, or call `reset()` between runs.
 - 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.
 

{pickle_debug-1.2 → pickle_debug-2.1}/pyproject.toml

@@ -2,7 +2,7 @@
 name = "pickle_debug"
 description = "Store expensive objects from debugging"
 license = {text = "MIT" }
-version = "1.2"
+version = "2.1"
 dependencies = []
 requires-python= ">= 3.12"
 readme = "README.md"

{pickle_debug-1.2 → pickle_debug-2.1}/src/pickle_debug/__init__.py

@@ -18,16 +18,19 @@ _CACHE_DIRECTORY: Path | None = None
 _SUFFIX = '.pickle'
 
 
-def enable(directory: Path | str) -> None:
+def enable(directory: Path | str|None) -> 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}")
+    if directory is not None:
+        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}")
+    else: 
+        _CACHE_DIRECTORY = None 
 
 
 def reset() -> None:

{pickle_debug-1.2 → pickle_debug-2.1/src/pickle_debug.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pickle_debug
-Version: 1.2
+Version: 2.1
 Summary: Store expensive objects from debugging
 Author: Gerard
 Author-email: gweatherby@uchc.edu
@@ -59,18 +59,49 @@ slow.invoke = pickle_debug.cached(slow.invoke)   # one instance
 Slow.invoke = pickle_debug.cached(Slow.invoke)   # all instances
 ```
 
+The decorator also works inside a class body. For a classmethod, put `@cached` below `@classmethod`:
+
+```python
+class Slow:
+    @pickle_debug.cached
+    def invoke(self, x):
+        ...
+
+    @classmethod
+    @pickle_debug.cached
+    def build(cls, x):
+        ...
+```
+
+A wrapper may be needed to cache some functions, e.g. a method returning a generator:
+
+```python
+def something(x,y,z)->Generator:
+
+@pickle_debug.cached
+def cache_something(x,y,z)->list:
+	return list(something(x,y,z))
+```
+
+When a cached function is called as a method, `self` (or `cls`) is keyed by its class's name
+(`module.QualifiedName`), not its current value. All instances of a class share cache entries, and the
+instance does not need to be picklable. Subclasses get their own entries. Static methods are keyed like
+plain functions.
+
 ## API
 
-### `enable(directory)`
+### `enable(directory: str | Path | None)`
 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.
+enable(None) disables caching.
 
 ### `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;
+   the sorted keyword arguments, and hashes it with SHA-256. If `func` is called as a method, the
+   first argument (`self` or `cls`) is replaced by its class's name (see [Methods](#methods));
 3. returns the pickled result from `<directory>/<hash>.pickle` if present;
 4. otherwise calls `func`, writes the result to the cache, and returns it.
 
@@ -101,13 +132,15 @@ wrong place. It does nothing if caching is not enabled or the directory does not
   [Unpicklable attributes](#unpicklable-attributes)). The arguments are pickled to build the key, and the
   result is pickled to store it. Because dropped attributes are not part of the key, two arguments that
   differ only in unpicklable attributes share a cache entry.
+- **Wrappers may be required** for methods that return generators.
 - **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.
+- **Instance state is not part of the key.** Methods are keyed by the class of `self` or `cls`, not by its
+  value, so all instances of a class share entries. If a method's result depends on instance attributes,
+  instances with different state will get each other's cached results. Pass that state as an argument
+  instead, or call `reset()` between runs.
 - 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.
 

{pickle_debug-1.2 → pickle_debug-2.1}/src/pickle_debug.egg-info/SOURCES.txt

@@ -6,8 +6,7 @@ src/pickle_debug.egg-info/PKG-INFO
 src/pickle_debug.egg-info/SOURCES.txt
 src/pickle_debug.egg-info/dependency_links.txt
 src/pickle_debug.egg-info/top_level.txt
+src/test/ntest.py
 src/test/patch_test.py
 src/test/pd_test.py
-src/test/record.py
-src/test/ttest.py
-src/test/unpicklable_test.py
+src/test/ttest.py

pickle_debug-2.1/src/test/ntest.py

@@ -0,0 +1,15 @@
+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
+
+
+pickle_debug.enable(None)
+print(f(1, 2))
+print(f(1, 2))

pickle_debug-1.2/src/test/record.py

@@ -1,11 +0,0 @@
-import pickle_debug
-
-def sum(x,y):
-    print(f"{x} + {y}")
-    return x + y
-
-pickle_debug.enable("/tmp/sum")
-ans = pickle_debug.record("sum",sum,3,4)
-print(ans)
-ans = pickle_debug.record("sum",sum,3,4)
-print(ans)

pickle_debug-1.2/src/test/unpicklable_test.py

@@ -1,46 +0,0 @@
-import pathlib
-import tempfile
-import threading
-
-from pickle_debug import cached, enable
-
-
-class Holder:
-    def __init__(self, value):
-        self.value = value
-        self.lock = threading.Lock()
-        self.inner = Inner()
-        self.me = self
-
-
-class Inner:
-    def __init__(self):
-        self.ok = 'inner'
-        self.callback = lambda: None
-
-
-class Slotted:
-    __slots__ = ('a', 'lock')
-
-    def __init__(self):
-        self.a = 1
-        self.lock = threading.Lock()
-
-
-calls = []
-
-
-@cached
-def make(x):
-    calls.append(x)
-    return Holder(x), Slotted()
-
-
-enable(pathlib.Path(tempfile.mkdtemp()) / 'cache')
-make(5)
-h, s = make(5)
-assert calls == [5], calls
-assert h.value == 5 and not hasattr(h, 'lock') and h.me is h
-assert h.inner.ok == 'inner' and not hasattr(h.inner, 'callback')
-assert s.a == 1 and not hasattr(s, 'lock')
-print('ok')