cachier 3.0.0__tar.gz → 3.1.0__tar.gz

{cachier-3.0.0 → cachier-3.1.0}/MANIFEST.in

@@ -1,9 +1,9 @@
 # Manifest syntax https://docs.python.org/2/distutils/sourcedist.html
 graft wheelhouse
 
-recursive-exclude __pycache__  *.py[cod] *.orig
-include cachier/version.info
+recursive-include src *.info
 include README.rst
-include requirements.txt
+include LICENSE
 
+prune __pycache__
 prune tests

{cachier-3.0.0/cachier.egg-info → cachier-3.1.0}/PKG-INFO

@@ -1,33 +1,50 @@
 Metadata-Version: 2.1
 Name: cachier
-Version: 3.0.0
+Version: 3.1.0
 Summary: Persistent, stale-free, local and cross-machine caching for Python functions.
-Home-page: https://github.com/python-cachier/cachier
-Author: Shay Palachy & al.
-Author-email: shay.palachy@gmail.com
-License: MIT
-Keywords: cache,persistence,mongo,memoization,decorator
-Platform: linux
-Platform: osx
-Platform: windows
+Author-email: Shay Palachy Affek <shay.palachy@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2016 Shay Palachy
+        
+        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.
+        
+Project-URL: Source, https://github.com/python-cachier/cachier
+Keywords: cache,caching,cross-machine,decorator,local,memoization,mongo,persistent
 Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Other/Nonlisted Topic
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
-Classifier: Topic :: Other/Nonlisted Topic
-Classifier: Intended Audience :: Developers
+Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: watchdog>=2.3.1
 Requires-Dist: portalocker>=2.3.2
-Requires-Dist: setuptools>=67.6.0
+Requires-Dist: watchdog>=2.3.1
 
 Cachier
 #######
@@ -492,8 +509,8 @@ Notable bugfixers:
 .. |PyPI-Versions| image:: https://img.shields.io/pypi/pyversions/cachier.svg
    :target: https://pypi.python.org/pypi/cachier
 
-.. |Build-Status| image:: https://github.com/python-cachier/cachier/actions/workflows/test.yml/badge.svg
-  :target: https://github.com/python-cachier/cachier/actions/workflows/test.yml
+.. |Build-Status| image:: https://github.com/python-cachier/cachier/actions/workflows/ci-test.yml/badge.svg
+  :target: https://github.com/python-cachier/cachier/actions/workflows/ci-test.yml
 
 .. |LICENCE| image:: https://img.shields.io/pypi/l/cachier.svg
   :target: https://pypi.python.org/pypi/cachier

{cachier-3.0.0 → cachier-3.1.0}/README.rst

@@ -461,8 +461,8 @@ Notable bugfixers:
 .. |PyPI-Versions| image:: https://img.shields.io/pypi/pyversions/cachier.svg
    :target: https://pypi.python.org/pypi/cachier
 
-.. |Build-Status| image:: https://github.com/python-cachier/cachier/actions/workflows/test.yml/badge.svg
-  :target: https://github.com/python-cachier/cachier/actions/workflows/test.yml
+.. |Build-Status| image:: https://github.com/python-cachier/cachier/actions/workflows/ci-test.yml/badge.svg
+  :target: https://github.com/python-cachier/cachier/actions/workflows/ci-test.yml
 
 .. |LICENCE| image:: https://img.shields.io/pypi/l/cachier.svg
   :target: https://pypi.python.org/pypi/cachier

cachier-3.1.0/pyproject.toml

@@ -0,0 +1,174 @@
+[build-system]
+requires = [
+  "setuptools",
+  "wheel",
+]
+
+[project]
+name = "cachier"
+description = "Persistent, stale-free, local and cross-machine caching for Python functions."
+readme = "README.rst"
+keywords = [
+  "cache",
+  "caching",
+  "cross-machine",
+  "decorator",
+  "local",
+  "memoization",
+  "mongo",
+  "persistent",
+]
+license = { file = "LICENSE" }
+authors = [
+  { name = "Shay Palachy Affek", email = 'shay.palachy@gmail.com' },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Other/Nonlisted Topic",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Utilities",
+]
+dynamic = [
+  "version",
+]
+dependencies = [
+  "portalocker>=2.3.2",
+  "watchdog>=2.3.1",
+]
+urls.Source = "https://github.com/python-cachier/cachier"
+scripts.cachier = "cachier.__main__:cli"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.dynamic]
+version = { attr = "cachier._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = [
+  "src",
+] # list of folders that contain the packages (["."] by default)
+include = [
+  "cachier*",
+] # package names should match these glob patterns (["*"] by default)
+namespaces = false # to disable scanning PEP 420 namespaces (true by default)
+
+[tool.ruff]
+target-version = "py38"
+line-length = 79
+# Exclude a variety of commonly ignored directories.
+exclude = [
+  ".eggs",
+  ".git",
+  ".ruff_cache",
+  "__pypackages__",
+  "_build",
+  "build",
+  "dist",
+]
+# Enable Pyflakes `E` and `F` codes by default.
+lint.select = [
+  "D",      # see: https://pypi.org/project/pydocstyle
+  "E",
+  "F",      # see: https://pypi.org/project/pyflakes
+  "I",      #see: https://pypi.org/project/isort/
+  "RUF100", # alternative to yesqa
+  #"N", # see: https://pypi.org/project/pep8-naming
+  "S",   # see: https://pypi.org/project/flake8-bandit
+  "SIM",
+  "W",   # see: https://pypi.org/project/pycodestyle
+]
+lint.extend-select = [
+  "A",  # see: https://pypi.org/project/flake8-builtins
+  "B",  # see: https://pypi.org/project/flake8-bugbear
+  "C4", # see: https://pypi.org/project/flake8-comprehensions
+  "PT", # see: https://pypi.org/project/flake8-pytest-style
+]
+lint.ignore = [
+  "C901",
+  "E203",
+]
+lint.per-file-ignores."src/**/__init__.py" = [
+  "D104",
+]
+lint.per-file-ignores."src/cachier/config.py" = [
+  "D100",
+]
+lint.per-file-ignores."tests/**" = [
+  "D100",
+  "D101",
+  "D103",
+  "D104",
+  "D401",
+  "S101",
+  "S105",
+  "S311",
+  "S603",
+]
+lint.unfixable = [
+  "F401",
+]
+
+#[tool.ruff.pydocstyle]
+## Use Google-style docstrings.
+#convention = "google"
+#[tool.ruff.pycodestyle]
+#ignore-overlong-task-comments = true
+# Unlike Flake8, default to a complexity level of 10.
+lint.mccabe.max-complexity = 10
+
+[tool.docformatter]
+recursive = true
+# some docstring start with r"""
+wrap-summaries = 79
+wrap-descriptions = 79
+blank = true
+
+[tool.pytest.ini_options]
+testpaths = [
+  "cachier",
+  "tests",
+]
+norecursedirs = [
+  "dist",
+  "build",
+]
+addopts = [
+  "--color=yes",
+  "-r a",
+  "-v",
+  "-s",
+]
+markers = [
+  "mongo: test the MongoDB core",
+  "memory: test the memory core",
+  "pickle: test the pickle core",
+]
+
+[tool.coverage.run]
+branch = true
+dynamic_context = "test_function"
+omit = [
+  "tests/*",
+  "cachier/_version.py",
+  "cachier/__init__.py",
+  "**/scripts/**",
+]
+[tool.coverage.report]
+show_missing = true
+# Regexes for lines to exclude from consideration
+exclude_lines = [
+  "pragma: no cover",          # Have to re-enable the standard pragma
+  "raise NotImplementedError", # Don't complain if tests don't hit defensive assertion code:
+  "if TYPE_CHECKING:",         # Is only true when running mypy, not tests
+]

{cachier-3.0.0 → cachier-3.1.0/src}/cachier/__init__.py

@@ -2,15 +2,15 @@ from ._version import *  # noqa: F403
 from .config import (
     disable_caching,
     enable_caching,
-    get_default_params,
-    set_default_params,
+    get_global_params,
+    set_global_params,
 )
 from .core import cachier
 
 __all__ = [
     "cachier",
-    "set_default_params",
-    "get_default_params",
+    "set_global_params",
+    "get_global_params",
     "enable_caching",
     "disable_caching",
 ]

{cachier-3.0.0 → cachier-3.1.0/src}/cachier/__main__.py

@@ -7,7 +7,7 @@ from cachier.core import _set_max_workers
 
 @click.group()
 def cli():
-    """A command-line interface for cachier."""
+    """A command-line interface for cachier."""  # noqa: D401
 
 
 @cli.command("Limits the number of worker threads used by cachier.")

cachier-3.1.0/src/cachier/config.py

@@ -0,0 +1,139 @@
+import datetime
+import hashlib
+import os
+import pickle
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any, Optional, Union
+
+from ._types import Backend, HashFunc, Mongetter
+
+
+def _default_hash_func(args, kwds):
+    # Sort the kwargs to ensure consistent ordering
+    sorted_kwargs = sorted(kwds.items())
+    # Serialize args and sorted_kwargs using pickle or similar
+    serialized = pickle.dumps((args, sorted_kwargs))
+    # Create a hash of the serialized data
+    return hashlib.sha256(serialized).hexdigest()
+
+
+@dataclass
+class Params:
+    """Default definition for cachier parameters."""
+
+    caching_enabled: bool = True
+    hash_func: HashFunc = _default_hash_func
+    backend: Backend = "pickle"
+    mongetter: Optional[Mongetter] = None
+    stale_after: datetime.timedelta = datetime.timedelta.max
+    next_time: bool = False
+    cache_dir: Union[str, os.PathLike] = "~/.cachier/"
+    pickle_reload: bool = True
+    separate_files: bool = False
+    wait_for_calc_timeout: int = 0
+    allow_none: bool = False
+
+
+_global_params = Params()
+
+
+@dataclass
+class CacheEntry:
+    """Data class for cache entries."""
+
+    value: Any
+    time: datetime
+    stale: bool
+    _processing: bool
+    _condition: Optional[threading.Condition] = None
+    _completed: bool = False
+
+
+def _update_with_defaults(
+    param, name: str, func_kwargs: Optional[dict] = None
+):
+    import cachier
+
+    if func_kwargs:
+        kw_name = f"cachier__{name}"
+        if kw_name in func_kwargs:
+            return func_kwargs.pop(kw_name)
+    if param is None:
+        return getattr(cachier.config._global_params, name)
+    return param
+
+
+def set_default_params(**params: Mapping) -> None:
+    """Configure default parameters applicable to all memoized functions."""
+    # It is kept for backwards compatibility with desperation warning
+    import warnings
+
+    warnings.warn(
+        "Called `set_default_params` is deprecated and will be removed."
+        " Please use `set_global_params` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    set_global_params(**params)
+
+
+def set_global_params(**params: Mapping) -> None:
+    """Configure global parameters applicable to all memoized functions.
+
+    This function takes the same keyword parameters as the ones defined in the
+    decorator, which can be passed all at once or with multiple calls.
+    Parameters given directly to a decorator take precedence over any values
+    set by this function.
+
+    Only 'stale_after', 'next_time', and 'wait_for_calc_timeout' can be changed
+    after the memoization decorator has been applied. Other parameters will
+    only have an effect on decorators applied after this function is run.
+
+    """
+    import cachier
+
+    valid_params = {
+        k: v
+        for k, v in params.items()
+        if hasattr(cachier.config._global_params, k)
+    }
+    cachier.config._global_params = replace(
+        cachier.config._global_params, **valid_params
+    )
+
+
+def get_default_params() -> Params:
+    """Get current set of default parameters."""
+    # It is kept for backwards compatibility with desperation warning
+    import warnings
+
+    warnings.warn(
+        "Called `get_default_params` is deprecated and will be removed."
+        " Please use `get_global_params` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return get_global_params()
+
+
+def get_global_params() -> Params:
+    """Get current set of default parameters."""
+    import cachier
+
+    return cachier.config._global_params
+
+
+def enable_caching():
+    """Enable caching globally."""
+    import cachier
+
+    cachier.config._global_params.caching_enabled = True
+
+
+def disable_caching():
+    """Disable caching globally."""
+    import cachier
+
+    cachier.config._global_params.caching_enabled = False

{cachier-3.0.0 → cachier-3.1.0/src}/cachier/core.py

@@ -14,14 +14,13 @@ import warnings
 from collections import OrderedDict
 from concurrent.futures import ThreadPoolExecutor
 from functools import wraps
-from typing import Optional, Union
+from typing import Any, Optional, Union
 from warnings import warn
 
 from .config import (
     Backend,
     HashFunc,
     Mongetter,
-    _default_params,
     _update_with_defaults,
 )
 from .cores.base import RecalculationNeeded, _BaseCore
@@ -56,13 +55,11 @@ def _function_thread(core, key, func, args, kwds):
         print(f"Function call failed with the following exception:\n{exc}")
 
 
-def _calc_entry(core, key, func, args, kwds):
+def _calc_entry(core, key, func, args, kwds) -> Optional[Any]:
+    core.mark_entry_being_calculated(key)
     try:
-        core.mark_entry_being_calculated(key)
-        # _get_executor().submit(core.mark_entry_being_calculated, key)
         func_res = func(*args, **kwds)
         core.set_entry(key, func_res)
-        # _get_executor().submit(core.set_entry, key, func_res)
         return func_res
     finally:
         core.mark_entry_not_calculated(key)
@@ -118,7 +115,7 @@ def cachier(
     wait_for_calc_timeout: Optional[int] = None,
     allow_none: Optional[bool] = None,
 ):
-    """A persistent, stale-free memoization decorator.
+    """Wrap as a persistent, stale-free memoization decorator.
 
     The positional and keyword arguments to the wrapped function must be
     hashable (i.e. Python's immutable built-in objects, not mutable
@@ -127,13 +124,14 @@ def cachier(
     value is their id), equal objects across different sessions will not yield
     identical keys.
 
-    Arguments
+    Arguments:
     ---------
     hash_func : callable, optional
         A callable that gets the args and kwargs from the decorated function
         and returns a hash key for them. This parameter can be used to enable
         the use of cachier with functions that get arguments that are not
         automatically hashable by Python.
+    hash_params : callable, optional
     backend : str, optional
         The name of the backend to use. Valid options currently include
         'pickle', 'mongo' and 'memory'. If not provided, defaults to
@@ -175,6 +173,8 @@ def cachier(
         None will not be cached and are recalculated every call.
 
     """
+    from .config import _global_params
+
     # Check for deprecated parameters
     if hash_params is not None:
         message = (
@@ -240,29 +240,34 @@ def cachier(
                 func, _is_method=core.func_is_method, args=args, kwds=kwds
             )
 
-            _print = lambda x: None  # noqa: E731
-            if verbose:
-                _print = print
-            if ignore_cache or not _default_params["caching_enabled"]:
-                return func(**kwargs)
-            key, entry = core.get_entry(tuple(), kwargs)
+            _print = print if verbose else lambda x: None
+
+            if ignore_cache or not _global_params.caching_enabled:
+                return (
+                    func(args[0], **kwargs)
+                    if core.func_is_method
+                    else func(**kwargs)
+                )
+            key, entry = core.get_entry((), kwargs)
             if overwrite_cache:
                 return _calc_entry(core, key, func, args, kwds)
-            if entry is None:
+            if entry is None or (
+                not entry._completed and not entry._processing
+            ):
                 _print("No entry found. No current calc. Calling like a boss.")
                 return _calc_entry(core, key, func, args, kwds)
             _print("Entry found.")
-            if _allow_none or entry.get("value", None) is not None:
+            if _allow_none or entry.value is not None:
                 _print("Cached result found.")
                 now = datetime.datetime.now()
-                if now - entry["time"] <= _stale_after:
+                if now - entry.time <= _stale_after:
                     _print("And it is fresh!")
-                    return entry["value"]
+                    return entry.value
                 _print("But it is stale... :(")
-                if entry["being_calculated"]:
+                if entry._processing:
                     if _next_time:
                         _print("Returning stale.")
-                        return entry["value"]  # return stale val
+                        return entry.value  # return stale val
                     _print("Already calc. Waiting on change.")
                     try:
                         return core.wait_on_entry_calc(key)
@@ -270,17 +275,17 @@ def cachier(
                         return _calc_entry(core, key, func, args, kwds)
                 if _next_time:
                     _print("Async calc and return stale")
+                    core.mark_entry_being_calculated(key)
                     try:
-                        core.mark_entry_being_calculated(key)
                         _get_executor().submit(
                             _function_thread, core, key, func, args, kwds
                         )
                     finally:
                         core.mark_entry_not_calculated(key)
-                    return entry["value"]
+                    return entry.value
                 _print("Calling decorated function and waiting")
                 return _calc_entry(core, key, func, args, kwds)
-            if entry["being_calculated"]:
+            if entry._processing:
                 _print("No value but being calculated. Waiting.")
                 try:
                     return core.wait_on_entry_calc(key)
@@ -294,17 +299,17 @@ def cachier(
             core.clear_cache()
 
         def _clear_being_calculated():
-            """Marks all entries in this cache as not being calculated."""
+            """Mark all entries in this cache as not being calculated."""
             core.clear_being_calculated()
 
         def _cache_dpath():
-            """Returns the path to the cache dir, if exists; None if not."""
+            """Return the path to the cache dir, if exists; None if not."""
             return getattr(core, "cache_dir", None)
 
-        def _precache_value(*args, value_to_cache, **kwds):
+        def _precache_value(*args, value_to_cache, **kwds):  # noqa: D417
             """Add an initial value to the cache.
 
-            Arguments
+            Arguments:
             ---------
             value_to_cache : any
                 entry to be written into the cache
@@ -314,7 +319,7 @@ def cachier(
             kwargs = _convert_args_kwargs(
                 func, _is_method=core.func_is_method, args=args, kwds=kwds
             )
-            return core.precache_value(tuple(), kwargs, value_to_cache)
+            return core.precache_value((), kwargs, value_to_cache)
 
         func_wrapper.clear_cache = _clear_cache
         func_wrapper.clear_being_calculated = _clear_being_calculated