cachier 3.1.2__py3-none-any.whl → 3.2.1__py3-none-any.whl

cachier/__init__.py

@@ -1,4 +1,4 @@
-from ._version import *  # noqa: F403
+from ._version import __version__
 from .config import (
     disable_caching,
     enable_caching,
@@ -17,4 +17,5 @@ __all__ = [
     "get_global_params",
     "enable_caching",
     "disable_caching",
+    "__version__",
 ]

cachier/_version.py

@@ -18,7 +18,8 @@ with open(_PATH_VERSION) as fopen:
 def _get_git_sha() -> str:
     from subprocess import DEVNULL, check_output
 
-    out = check_output(["git", "rev-parse", "--short", "HEAD"], stderr=DEVNULL)  # noqa: S603, S607
+    args = ["git", "rev-parse", "--short", "HEAD"]
+    out = check_output(args, stderr=DEVNULL)  # noqa: S603
     return out.decode("utf-8").strip()
 
 

cachier/config.py

@@ -2,7 +2,6 @@ import hashlib
 import os
 import pickle
 import threading
-from collections.abc import Mapping
 from dataclasses import dataclass, replace
 from datetime import datetime, timedelta
 from typing import Any, Optional, Union
@@ -65,7 +64,7 @@ def _update_with_defaults(
     return param
 
 
-def set_default_params(**params: Mapping) -> None:
+def set_default_params(**params: Any) -> None:
     """Configure default parameters applicable to all memoized functions."""
     # It is kept for backwards compatibility with desperation warning
     import warnings
@@ -79,7 +78,7 @@ def set_default_params(**params: Mapping) -> None:
     set_global_params(**params)
 
 
-def set_global_params(**params: Mapping) -> None:
+def set_global_params(**params: Any) -> None:
     """Configure global parameters applicable to all memoized functions.
 
     This function takes the same keyword parameters as the ones defined in the

cachier/core.py

@@ -14,7 +14,7 @@ from collections import OrderedDict
 from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timedelta
 from functools import wraps
-from typing import Any, Optional, Union
+from typing import Any, Callable, Optional, Union
 from warnings import warn
 
 from .config import (
@@ -27,6 +27,7 @@ from .cores.base import RecalculationNeeded, _BaseCore
 from .cores.memory import _MemoryCore
 from .cores.mongo import _MongoCore
 from .cores.pickle import _PickleCore
+from .cores.sql import _SQLCore
 
 MAX_WORKERS_ENVAR_NAME = "CACHIER_MAX_WORKERS"
 DEFAULT_MAX_WORKERS = 8
@@ -107,6 +108,7 @@ def cachier(
     hash_params: Optional[HashFunc] = None,
     backend: Optional[Backend] = None,
     mongetter: Optional[Mongetter] = None,
+    sql_engine: Optional[Union[str, Any, Callable[[], Any]]] = None,
     stale_after: Optional[timedelta] = None,
     next_time: Optional[bool] = None,
     cache_dir: Optional[Union[str, os.PathLike]] = None,
@@ -134,13 +136,16 @@ def cachier(
     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
+        'pickle', 'mongo', 'memory', and 'sql'. If not provided, defaults to
         'pickle' unless the 'mongetter' argument is passed, in which
         case the mongo backend is automatically selected.
     mongetter : callable, optional
         A callable that takes no arguments and returns a pymongo.Collection
         object with writing permissions. If unset a local pickle cache is used
         instead.
+    sql_engine : str, Engine, or callable, optional
+        SQLAlchemy connection string, Engine, or callable returning an Engine.
+        Used for the SQL backend.
     stale_after : datetime.timedelta, optional
         The time delta after which a cached result is considered stale. Calls
         made after the result goes stale will trigger a recalculation of the
@@ -208,6 +213,12 @@ def cachier(
         core = _MemoryCore(
             hash_func=hash_func, wait_for_calc_timeout=wait_for_calc_timeout
         )
+    elif backend == "sql":
+        core = _SQLCore(
+            hash_func=hash_func,
+            sql_engine=sql_engine,
+            wait_for_calc_timeout=wait_for_calc_timeout,
+        )
     else:
         raise ValueError("specified an invalid core: %s" % backend)
 

cachier/cores/base.py

@@ -1,4 +1,5 @@
 """Defines the interface of a cachier caching core."""
+
 # This file is part of Cachier.
 # https://github.com/python-cachier/cachier
 

cachier/cores/mongo.py

@@ -75,7 +75,9 @@ class _MongoCore(_BaseCore):
         )
         if not res:
             return key, None
-        val = pickle.loads(res["value"]) if "value" in res else None  # noqa: S301
+        val = None
+        if "value" in res:
+            val = pickle.loads(res["value"])  # noqa: S301
         entry = CacheEntry(
             value=val,
             time=res.get("time", None),

cachier/cores/sql.py

@@ -0,0 +1,288 @@
+"""A SQLAlchemy-based caching core for cachier."""
+
+import pickle
+import threading
+from datetime import datetime
+from typing import Any, Callable, Optional, Tuple, Union
+
+try:
+    from sqlalchemy import (
+        Boolean,
+        Column,
+        DateTime,
+        Index,
+        LargeBinary,
+        String,
+        and_,
+        create_engine,
+        delete,
+        insert,
+        select,
+        update,
+    )
+    from sqlalchemy.engine import Engine
+    from sqlalchemy.orm import declarative_base, sessionmaker
+
+    SQLALCHEMY_AVAILABLE = True
+except ImportError:
+    SQLALCHEMY_AVAILABLE = False
+
+from .._types import HashFunc
+from ..config import CacheEntry
+from .base import RecalculationNeeded, _BaseCore, _get_func_str
+
+if SQLALCHEMY_AVAILABLE:
+    Base = declarative_base()
+
+    class CacheTable(Base):  # type: ignore[misc, valid-type]
+        """SQLAlchemy model for cachier cache entries."""
+
+        __tablename__ = "cachier_cache"
+        id = Column(String, primary_key=True)
+        function_id = Column(String, index=True, nullable=False)
+        key = Column(String, index=True, nullable=False)
+        value = Column(LargeBinary, nullable=True)
+        timestamp = Column(DateTime, nullable=False)
+        stale = Column(Boolean, default=False)
+        processing = Column(Boolean, default=False)
+        completed = Column(Boolean, default=False)
+        __table_args__ = (
+            Index("ix_func_key", "function_id", "key", unique=True),
+        )
+
+
+class _SQLCore(_BaseCore):
+    """SQLAlchemy-based core for Cachier, supporting SQL-based backends.
+
+    This should work with SQLite, PostgreSQL and so on.
+
+    """
+
+    def __init__(
+        self,
+        hash_func: Optional[HashFunc],
+        sql_engine: Optional[Union[str, "Engine", Callable[[], "Engine"]]],
+        wait_for_calc_timeout: Optional[int] = None,
+    ):
+        if not SQLALCHEMY_AVAILABLE:
+            raise ImportError(
+                "SQLAlchemy is required for the SQL core. "
+                "Install with `pip install SQLAlchemy`."
+            )
+        super().__init__(
+            hash_func=hash_func, wait_for_calc_timeout=wait_for_calc_timeout
+        )
+        self._engine = self._resolve_engine(sql_engine)
+        self._Session = sessionmaker(bind=self._engine)
+        Base.metadata.create_all(self._engine)
+        self._lock = threading.RLock()
+        self._func_str = None
+
+    def _resolve_engine(self, sql_engine):
+        if isinstance(sql_engine, Engine):
+            return sql_engine
+        if isinstance(sql_engine, str):
+            return create_engine(sql_engine, future=True)
+        if callable(sql_engine):
+            return sql_engine()
+        raise ValueError(
+            "sql_engine must be a SQLAlchemy Engine, connection string, "
+            "or callable returning an Engine."
+        )
+
+    def set_func(self, func):
+        super().set_func(func)
+        self._func_str = _get_func_str(func)
+
+    def get_entry_by_key(self, key: str) -> Tuple[str, Optional[CacheEntry]]:
+        with self._lock, self._Session() as session:
+            row = session.execute(
+                select(CacheTable).where(
+                    and_(
+                        CacheTable.function_id == self._func_str,
+                        CacheTable.key == key,
+                    )
+                )
+            ).scalar_one_or_none()
+            if not row:
+                return key, None
+            value = pickle.loads(row.value) if row.value is not None else None
+            entry = CacheEntry(
+                value=value,
+                time=row.timestamp,
+                stale=row.stale,
+                _processing=row.processing,
+                _completed=row.completed,
+            )
+            return key, entry
+
+    def set_entry(self, key: str, func_res: Any) -> None:
+        with self._lock, self._Session() as session:
+            thebytes = pickle.dumps(func_res)
+            now = datetime.now()
+            base_insert = insert(CacheTable)
+            stmt = (
+                base_insert.values(
+                    id=f"{self._func_str}:{key}",
+                    function_id=self._func_str,
+                    key=key,
+                    value=thebytes,
+                    timestamp=now,
+                    stale=False,
+                    processing=False,
+                    completed=True,
+                ).on_conflict_do_update(
+                    index_elements=[CacheTable.function_id, CacheTable.key],
+                    set_={
+                        "value": thebytes,
+                        "timestamp": now,
+                        "stale": False,
+                        "processing": False,
+                        "completed": True,
+                    },
+                )
+                if hasattr(base_insert, "on_conflict_do_update")
+                else None
+            )
+            # Fallback for non-SQLite/Postgres: try update, else insert
+            if stmt:
+                session.execute(stmt)
+            else:
+                row = session.execute(
+                    select(CacheTable).where(
+                        and_(
+                            CacheTable.function_id == self._func_str,
+                            CacheTable.key == key,
+                        )
+                    )
+                ).scalar_one_or_none()
+                if row:
+                    session.execute(
+                        update(CacheTable)
+                        .where(
+                            and_(
+                                CacheTable.function_id == self._func_str,
+                                CacheTable.key == key,
+                            )
+                        )
+                        .values(
+                            value=thebytes,
+                            timestamp=now,
+                            stale=False,
+                            processing=False,
+                            completed=True,
+                        )
+                    )
+                else:
+                    session.add(
+                        CacheTable(
+                            id=f"{self._func_str}:{key}",
+                            function_id=self._func_str,
+                            key=key,
+                            value=thebytes,
+                            timestamp=now,
+                            stale=False,
+                            processing=False,
+                            completed=True,
+                        )
+                    )
+            session.commit()
+
+    def mark_entry_being_calculated(self, key: str) -> None:
+        with self._lock, self._Session() as session:
+            row = session.execute(
+                select(CacheTable).where(
+                    and_(
+                        CacheTable.function_id == self._func_str,
+                        CacheTable.key == key,
+                    )
+                )
+            ).scalar_one_or_none()
+            if row:
+                session.execute(
+                    update(CacheTable)
+                    .where(
+                        and_(
+                            CacheTable.function_id == self._func_str,
+                            CacheTable.key == key,
+                        )
+                    )
+                    .values(processing=True)
+                )
+            else:
+                session.add(
+                    CacheTable(
+                        id=f"{self._func_str}:{key}",
+                        function_id=self._func_str,
+                        key=key,
+                        value=None,
+                        timestamp=datetime.now(),
+                        stale=False,
+                        processing=True,
+                        completed=False,
+                    )
+                )
+            session.commit()
+
+    def mark_entry_not_calculated(self, key: str) -> None:
+        with self._lock, self._Session() as session:
+            session.execute(
+                update(CacheTable)
+                .where(
+                    and_(
+                        CacheTable.function_id == self._func_str,
+                        CacheTable.key == key,
+                    )
+                )
+                .values(processing=False)
+            )
+            session.commit()
+
+    def wait_on_entry_calc(self, key: str) -> Any:
+        import time
+
+        time_spent = 0
+        while True:
+            with self._lock, self._Session() as session:
+                row = session.execute(
+                    select(CacheTable).where(
+                        and_(
+                            CacheTable.function_id == self._func_str,
+                            CacheTable.key == key,
+                        )
+                    )
+                ).scalar_one_or_none()
+                if not row:
+                    raise RecalculationNeeded()
+                if not row.processing:
+                    return (
+                        pickle.loads(row.value)
+                        if row.value is not None
+                        else None
+                    )
+            time.sleep(1)
+            time_spent += 1
+            self.check_calc_timeout(time_spent)
+
+    def clear_cache(self) -> None:
+        with self._lock, self._Session() as session:
+            session.execute(
+                delete(CacheTable).where(
+                    CacheTable.function_id == self._func_str
+                )
+            )
+            session.commit()
+
+    def clear_being_calculated(self) -> None:
+        with self._lock, self._Session() as session:
+            session.execute(
+                update(CacheTable)
+                .where(
+                    and_(
+                        CacheTable.function_id == self._func_str,
+                        CacheTable.processing,
+                    )
+                )
+                .values(processing=False)
+            )
+            session.commit()

cachier/version.info

@@ -1 +1 @@
-3.1.2
+3.2.1

{cachier-3.1.2.dist-info → cachier-3.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: cachier
-Version: 3.1.2
+Version: 3.2.1
 Summary: Persistent, stale-free, local and cross-machine caching for Python functions.
 Author-email: Shay Palachy Affek <shay.palachy@gmail.com>
 License: MIT License
@@ -32,11 +32,11 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 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: Programming Language :: Python :: 3.13
 Classifier: Topic :: Other/Nonlisted Topic
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -45,6 +45,7 @@ Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: portalocker>=2.3.2
 Requires-Dist: watchdog>=2.3.1
+Dynamic: license-file
 
 Cachier
 #######
@@ -92,7 +93,7 @@ Features
 ========
 
 * Pure Python.
-* Compatible with Python 3.8+ (Python 2.7 was discontinued in version 1.2.8).
+* Compatible with Python 3.9+ (Python 2.7 was discontinued in version 1.2.8).
 * Supported and `tested on Linux, OS X and Windows <https://travis-ci.org/shaypal5/cachier>`_.
 * A simple interface.
 * Defining "shelf life" for cached values.
@@ -390,6 +391,64 @@ You can set an in-memory cache by assigning the ``backend`` parameter with ``'me
 
 Note, however, that ``cachier``'s in-memory core is simple, and has no monitoring or cap on cache size, and can thus lead to memory errors on large return values - it is mainly intended to be used with future multi-core functionality. As a rule, Python's built-in ``lru_cache`` is a much better stand-alone solution.
 
+SQLAlchemy (SQL) Core
+---------------------
+
+**Note:** The SQL core requires SQLAlchemy to be installed. It is not installed by default with cachier. To use the SQL backend, run::
+
+    pip install SQLAlchemy
+
+Cachier supports a generic SQL backend via SQLAlchemy, allowing you to use SQLite, PostgreSQL, MySQL, and other databases.
+
+**Usage Example (SQLite in-memory):**
+
+.. code-block:: python
+
+    from cachier import cachier
+
+    @cachier(backend="sql", sql_engine="sqlite:///:memory:")
+    def my_func(x):
+        return x * 2
+
+**Usage Example (PostgreSQL):**
+
+.. code-block:: python
+
+    @cachier(backend="sql", sql_engine="postgresql://user:pass@localhost/dbname")
+    def my_func(x):
+        return x * 2
+
+**Usage Example (MySQL):**
+
+.. code-block:: python
+
+    @cachier(backend="sql", sql_engine="mysql+pymysql://user:pass@localhost/dbname")
+    def my_func(x):
+        return x * 2
+
+**Configuration Options:**
+
+- ``sql_engine``: SQLAlchemy connection string, Engine, or callable returning an Engine.
+- All other standard cachier options are supported.
+
+**Table Schema:**
+
+- ``function_id``: Unique identifier for the cached function
+- ``key``: Cache key
+- ``value``: Pickled result
+- ``timestamp``: Datetime of cache entry
+- ``stale``: Boolean, is value stale
+- ``processing``: Boolean, is value being calculated
+- ``completed``: Boolean, is value calculation completed
+
+**Limitations & Notes:**
+
+- Requires SQLAlchemy (install with ``pip install SQLAlchemy``)
+- For production, use a persistent database (not ``:memory:``)
+- Thread/process safety is handled via transactions and row-level locks
+- Value serialization uses ``pickle``. **Warning:** `pickle` can execute arbitrary code during deserialization if the cache database is compromised. Ensure the cache is stored securely and consider using safer serialization methods like `json` if security is a concern.
+- For best performance, ensure your DB supports row-level locking
+
 
 Contributing
 ============

cachier-3.2.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+cachier/__init__.py,sha256=1isxXaP2l6Vq7gC1Gob6hduRLC07dHfWze1-oCjwSP0,415
+cachier/__main__.py,sha256=upg-TlHs1vngKYvkjoPpl3Pvl6xOx4ut-M1mElMiAo0,443
+cachier/_types.py,sha256=EGJMiw-oCIC_cDLyzw7YC40lfo8jnD3zMmoJpA9Y8Iw,238
+cachier/_version.py,sha256=jnPPRn_qmjNi-qmQjlHnzNGf3LSBTYkMmJdGjxMTOBM,1089
+cachier/config.py,sha256=6hyQtn9T6UXu2UQhKJltWT0Nu4OBS4ION1x7Lt1i8Og,3838
+cachier/core.py,sha256=7pqf_EGvGXu5WWtC5MeY0tVW4M59XljZI9_2R4RVfRU,13627
+cachier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachier/version.info,sha256=OCJyh4MEn8LyKlbR7nTWI1LEn7-BxrVLUIMNb2HDryI,6
+cachier/cores/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachier/cores/base.py,sha256=s7qgmDJA4LGub6ydGfMk9vVJW4fgeU0EXl-9gmpuh28,3683
+cachier/cores/memory.py,sha256=fsvqq9rwwmAaMBvYo-oUNAxB6UOyfBpuf8ACW_XTaU0,3572
+cachier/cores/mongo.py,sha256=pCBrxLsmGr68Q50JVD_CUPAYwhaLDrJUQs_6A-_GYLA,4993
+cachier/cores/pickle.py,sha256=FgfvZWAFdWQPOo3G-L57iEV2ujEkIDH8TyGzbarsZeE,10678
+cachier/cores/sql.py,sha256=nuf2-Szo7VTPRa7IC3JGWEtGsBtdkIrx0bhOm3U0mfE,9895
+cachier-3.2.1.dist-info/licenses/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
+cachier-3.2.1.dist-info/METADATA,sha256=xowxZuYhc4r5f4pKxrhROtHGT7FYObRJ4ULWFDXwA-Q,22101
+cachier-3.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cachier-3.2.1.dist-info/entry_points.txt,sha256=x4Y7t6Y0Qev_3fgG-Jv7TrsvVdJty3FnGAdkT8-_5mY,49
+cachier-3.2.1.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
+cachier-3.2.1.dist-info/RECORD,,

{cachier-3.1.2.dist-info → cachier-3.2.1.dist-info}/WHEEL

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

cachier-3.1.2.dist-info/RECORD

@@ -1,19 +0,0 @@
-cachier/__init__.py,sha256=GZeDebG0EgWIYBmRgPhO19dMiiaam8f9Pu7cWLv3ywY,400
-cachier/__main__.py,sha256=upg-TlHs1vngKYvkjoPpl3Pvl6xOx4ut-M1mElMiAo0,443
-cachier/_types.py,sha256=EGJMiw-oCIC_cDLyzw7YC40lfo8jnD3zMmoJpA9Y8Iw,238
-cachier/_version.py,sha256=yE6UYwvdoIRpw3HmNifiGwV3fqVea5PwZj_EvyosiZ8,1079
-cachier/config.py,sha256=zp5AfhDIYsYmfQCrlQP-Jg-m6r_xIsk5tK3vPmQEhTA,3882
-cachier/core.py,sha256=x2uHH7twqNPpO09bUf5-Vfzx-G95qggmGTHPw1xkYo8,13156
-cachier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cachier/version.info,sha256=kFNgkh5j9BnWoRHdMha_KEAvNnq5qmlETYDpdBlgDYA,6
-cachier/cores/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cachier/cores/base.py,sha256=q2QXw35UduQEFseNdwbBv1ZKPl1U25NKIX1NbC2i1U4,3682
-cachier/cores/memory.py,sha256=fsvqq9rwwmAaMBvYo-oUNAxB6UOyfBpuf8ACW_XTaU0,3572
-cachier/cores/mongo.py,sha256=tM1TJUA4UjknwOfcXF4l0DLDZb1ucUpL-dD75h7VgTA,4971
-cachier/cores/pickle.py,sha256=FgfvZWAFdWQPOo3G-L57iEV2ujEkIDH8TyGzbarsZeE,10678
-cachier-3.1.2.dist-info/LICENSE,sha256=-2WrMJkIa0gVP6YQHXXDT7ws-S3M2NEVEF4XF3K8qrY,1069
-cachier-3.1.2.dist-info/METADATA,sha256=blJgO_8gOHhLkjmMxcHyX84D_IXXCfUXPTzsZ2IScZU,20136
-cachier-3.1.2.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
-cachier-3.1.2.dist-info/entry_points.txt,sha256=x4Y7t6Y0Qev_3fgG-Jv7TrsvVdJty3FnGAdkT8-_5mY,49
-cachier-3.1.2.dist-info/top_level.txt,sha256=_rW_HiJumDCch67YT-WAgzcyvKg5RiYDMZq9d-0ZpaE,8
-cachier-3.1.2.dist-info/RECORD,,