flux-cache 0.1.0__tar.gz

flux_cache-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alvin Shaita
+
+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.

flux_cache-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: flux-cache
+Version: 0.1.0
+Summary: Caching library for Python with sync and async support
+Author-email: Alvin Shaita <alvinshaita@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/alvinshaita/flux-cache
+Project-URL: Source, https://github.com/alvinshaita/flux-cache
+Keywords: cache,caching,async,performance
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == "redis"
+Dynamic: license-file
+
+# Flux Cache
+
+A lightweight, extensible caching library for Python with support for synchronous and asynchronous functions.
+
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from flux_cache import cache
+
+@cache(ttl=60)
+def expensive_function(x, y):
+    print("Computing...")
+    return x + y
+
+expensive_function(1, 2)  # computes
+expensive_function(1, 2)  # cached
+```
+
+---
+
+### Async Usage
+
+```python
+from flux_cache import async_cache
+
+@async_cache(ttl=60)
+async def fetch_data(x):
+    return x * 2
+```
+
+---
+
+## How It Works
+
+* A cache key is generated using:
+
+  * Function module
+  * Function name
+  * Arguments (args + kwargs)
+* The key is hashed using SHA-256
+* Values are stored in the backend along with optional expiration timestamps
+
+---
+
+## Cache Control
+
+### Clear entire cache
+
+```python
+expensive_function.clear()
+```
+
+### Invalidate specific call
+
+```python
+expensive_function.invalidate(1, 2)
+```
+
+---
+
+## Backends
+
+### Default: In-Memory
+
+Thread-safe, simple dictionary-based backend.
+
+```python
+from flux_cache.backends import MemoryBackend
+
+@cache(backend=MemoryBackend())
+def foo():
+    return "bar"
+```
+
+### Custom Backend
+
+Implement the `BaseBackend` interface:
+
+```python
+class BaseBackend:
+    def get(self, key): ...
+    def set(self, key, value, ttl=None): ...
+    def delete(self, key): ...
+    def clear(self): ...
+```
+
+---
+
+## 🧪 Testing
+
+Run tests using:
+
+```bash
+pytest
+```
+
+---
+
+## 📄 License
+
+MIT License

flux_cache-0.1.0/README.md

@@ -0,0 +1,104 @@
+# Flux Cache
+
+A lightweight, extensible caching library for Python with support for synchronous and asynchronous functions.
+
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from flux_cache import cache
+
+@cache(ttl=60)
+def expensive_function(x, y):
+    print("Computing...")
+    return x + y
+
+expensive_function(1, 2)  # computes
+expensive_function(1, 2)  # cached
+```
+
+---
+
+### Async Usage
+
+```python
+from flux_cache import async_cache
+
+@async_cache(ttl=60)
+async def fetch_data(x):
+    return x * 2
+```
+
+---
+
+## How It Works
+
+* A cache key is generated using:
+
+  * Function module
+  * Function name
+  * Arguments (args + kwargs)
+* The key is hashed using SHA-256
+* Values are stored in the backend along with optional expiration timestamps
+
+---
+
+## Cache Control
+
+### Clear entire cache
+
+```python
+expensive_function.clear()
+```
+
+### Invalidate specific call
+
+```python
+expensive_function.invalidate(1, 2)
+```
+
+---
+
+## Backends
+
+### Default: In-Memory
+
+Thread-safe, simple dictionary-based backend.
+
+```python
+from flux_cache.backends import MemoryBackend
+
+@cache(backend=MemoryBackend())
+def foo():
+    return "bar"
+```
+
+### Custom Backend
+
+Implement the `BaseBackend` interface:
+
+```python
+class BaseBackend:
+    def get(self, key): ...
+    def set(self, key, value, ttl=None): ...
+    def delete(self, key): ...
+    def clear(self): ...
+```
+
+---
+
+## 🧪 Testing
+
+Run tests using:
+
+```bash
+pytest
+```
+
+---
+
+## 📄 License
+
+MIT License

flux_cache-0.1.0/flux_cache/__init__.py

@@ -0,0 +1 @@
+from .core import async_cache, cache

flux_cache-0.1.0/flux_cache/backends/__init__.py

@@ -0,0 +1,2 @@
+from .memory import MemoryBackend
+from .redis import RedisBackend

flux_cache-0.1.0/flux_cache/backends/base.py

@@ -0,0 +1,25 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class BaseBackend(ABC):
+
+	@abstractmethod
+	def has(self, key: str) -> bool:
+		pass
+
+	@abstractmethod
+	def get(self, key: str) -> Optional[Any]:
+		pass
+
+	@abstractmethod
+	def set(self, key: str, value: Any) -> None:
+		pass
+
+	@abstractmethod
+	def delete(self, key: str) -> None:
+		pass
+
+	@abstractmethod
+	def clear(self) -> None:
+		pass

flux_cache-0.1.0/flux_cache/backends/memory.py

@@ -0,0 +1,41 @@
+import threading
+import time
+from typing import Any, Optional
+
+from .base import BaseBackend
+
+
+class MemoryBackend(BaseBackend):
+	def __init__(self):
+		self.store = {}
+		self._lock = threading.RLock()
+
+	def has(self, key: str) -> bool:
+		with self._lock:
+			return key in self.store
+
+	def get(self, key: str) -> Optional[Any]:
+		with self._lock:
+			item = self.store.get(key)
+			if not item:
+				return None
+			
+			value, expires_at = item
+			if expires_at and expires_at < time.time():
+				self.store.pop(key, None)
+				return None
+
+			return value, expires_at
+
+	def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+		with self._lock:
+			expires_at = time.time() + ttl if ttl else None
+			self.store[key] = (value, expires_at)
+
+	def delete(self, key: str) -> None:
+		with self._lock:
+			self.store.pop(key, None)
+
+	def clear(self) -> None:
+		with self._lock:
+			self.store.clear()

flux_cache-0.1.0/flux_cache/backends/redis.py

@@ -0,0 +1,62 @@
+import json
+import threading
+import time
+from typing import Any, Optional
+
+from .base import BaseBackend
+
+
+class RedisBackend(BaseBackend):
+	def __init__(self, url="redis://localhost:6379/0", prefix="flux-cache"):
+		try:
+			import redis
+		except ImportError:
+			raise ImportError(
+				"RedisBackend requires 'redis' package.\n"
+				"Install with: pip install flux-cache[redis]"
+			)
+		self.prefix = prefix
+		self.red = redis.Redis.from_url(url)
+
+	def _serialize(self, value: Any) -> bytes:
+		return json.dumps(value)
+
+	def _deserialize(self, value: Optional[bytes]) -> Any:
+		if value is None:
+			return None
+
+		try:
+			return json.loads(value)
+		except:
+			return value
+
+	def _key(self, key: str) -> str:
+		return f"{self.prefix}:{key}"
+
+	def has(self, key: str) -> bool:
+		namespaced_key = self._key(key)
+		present = self.red.exists(namespaced_key)
+		return True if present == 1 else False
+
+	def get(self, key: str) -> Optional[Any]:
+		namespaced_key = self._key(key)
+		value = self.red.get(namespaced_key)
+		if value is None:
+			return None
+
+		deserialized_value = self._deserialize(value)
+		return deserialized_value, None
+
+	def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+		serialized_value = self._serialize(value)
+		namespaced_key = self._key(key)
+		self.red.set(namespaced_key, serialized_value, ex=ttl)
+
+	def delete(self, key: str) -> None:
+		namespaced_key = self._key(key)
+		self.red.delete(namespaced_key)
+
+	def clear(self) -> None:
+		keys = self.red.keys(f"{self.prefix}*")
+		if keys:
+			self.red.delete(*keys)

flux_cache-0.1.0/flux_cache/core.py

@@ -0,0 +1,82 @@
+import functools
+from typing import Callable, Optional
+
+from .backends import MemoryBackend
+from .utils import generate_cache_key
+
+def cache(
+	func: Optional[Callable] = None,
+	*,
+	ttl: Optional[int] = None,
+	backend = None
+):
+	if backend is None:
+		backend = MemoryBackend()
+
+	if func is None:
+		return lambda f: cache(f, ttl=ttl, backend=backend)
+
+	@functools.wraps(func)
+	def wrapper(*args, **kwargs):
+		key = generate_cache_key(func, args, kwargs)
+
+		item = backend.get(key)
+		if item:
+			value, _ = item
+			return value
+
+		result = func(*args, **kwargs)
+		backend.set(key, result, ttl=ttl)
+
+		return result
+
+	def clear():
+		backend.clear()
+
+	def invalidate(*args, **kwargs):
+		key = generate_cache_key(func, args, kwargs)
+		backend.delete(key)
+
+	wrapper.clear = clear
+	wrapper.invalidate = invalidate
+
+	return wrapper
+
+
+def async_cache(
+	func: Optional[Callable] = None,
+	*,
+	ttl: Optional[int] = None,
+	backend = None
+):
+	if backend is None:
+		backend = MemoryBackend()
+
+	if func is None:
+		return lambda f: async_cache(f, ttl=ttl, backend=backend)
+
+	@functools.wraps(func)
+	async def wrapper(*args, **kwargs):
+		key = generate_cache_key(func, args, kwargs)
+
+		item = backend.get(key)
+		if item:
+			value, _ = item
+			return value
+
+		result = await func(*args, **kwargs)
+		backend.set(key, result, ttl=ttl)
+
+		return result
+
+	def clear():
+		backend.clear()
+
+	def invalidate(*args, **kwargs):
+		key = generate_cache_key(func, args, kwargs)
+		backend.delete(key)
+
+	wrapper.clear = clear
+	wrapper.invalidate = invalidate
+
+	return wrapper

flux_cache-0.1.0/flux_cache/utils.py

@@ -0,0 +1,7 @@
+import hashlib
+import pickle
+
+def generate_cache_key(func, args, kwargs) -> str:
+	key_data = (func.__module__, func.__name__, args, kwargs)
+	raw_data = pickle.dumps(key_data)
+	return hashlib.sha256(raw_data).hexdigest()

flux_cache-0.1.0/flux_cache.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: flux-cache
+Version: 0.1.0
+Summary: Caching library for Python with sync and async support
+Author-email: Alvin Shaita <alvinshaita@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/alvinshaita/flux-cache
+Project-URL: Source, https://github.com/alvinshaita/flux-cache
+Keywords: cache,caching,async,performance
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == "redis"
+Dynamic: license-file
+
+# Flux Cache
+
+A lightweight, extensible caching library for Python with support for synchronous and asynchronous functions.
+
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from flux_cache import cache
+
+@cache(ttl=60)
+def expensive_function(x, y):
+    print("Computing...")
+    return x + y
+
+expensive_function(1, 2)  # computes
+expensive_function(1, 2)  # cached
+```
+
+---
+
+### Async Usage
+
+```python
+from flux_cache import async_cache
+
+@async_cache(ttl=60)
+async def fetch_data(x):
+    return x * 2
+```
+
+---
+
+## How It Works
+
+* A cache key is generated using:
+
+  * Function module
+  * Function name
+  * Arguments (args + kwargs)
+* The key is hashed using SHA-256
+* Values are stored in the backend along with optional expiration timestamps
+
+---
+
+## Cache Control
+
+### Clear entire cache
+
+```python
+expensive_function.clear()
+```
+
+### Invalidate specific call
+
+```python
+expensive_function.invalidate(1, 2)
+```
+
+---
+
+## Backends
+
+### Default: In-Memory
+
+Thread-safe, simple dictionary-based backend.
+
+```python
+from flux_cache.backends import MemoryBackend
+
+@cache(backend=MemoryBackend())
+def foo():
+    return "bar"
+```
+
+### Custom Backend
+
+Implement the `BaseBackend` interface:
+
+```python
+class BaseBackend:
+    def get(self, key): ...
+    def set(self, key, value, ttl=None): ...
+    def delete(self, key): ...
+    def clear(self): ...
+```
+
+---
+
+## 🧪 Testing
+
+Run tests using:
+
+```bash
+pytest
+```
+
+---
+
+## 📄 License
+
+MIT License

flux_cache-0.1.0/flux_cache.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+flux_cache/__init__.py
+flux_cache/core.py
+flux_cache/utils.py
+flux_cache.egg-info/PKG-INFO
+flux_cache.egg-info/SOURCES.txt
+flux_cache.egg-info/dependency_links.txt
+flux_cache.egg-info/requires.txt
+flux_cache.egg-info/top_level.txt
+flux_cache/backends/__init__.py
+flux_cache/backends/base.py
+flux_cache/backends/memory.py
+flux_cache/backends/redis.py

flux_cache-0.1.0/flux_cache.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flux_cache-0.1.0/flux_cache.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[redis]
+redis>=5.0.0

flux_cache-0.1.0/flux_cache.egg-info/top_level.txt

@@ -0,0 +1 @@
+flux_cache

flux_cache-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flux-cache"
+version = "0.1.0"
+description = "Caching library for Python with sync and async support"
+readme = "README.md"
+authors = [
+    { name="Alvin Shaita", email="alvinshaita@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.8"
+
+dependencies = []
+
+keywords = ["cache", "caching", "async", "performance"]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+redis = ["redis>=5.0.0"]
+
+[project.urls]
+"Homepage" = "https://github.com/alvinshaita/flux-cache"
+"Source" = "https://github.com/alvinshaita/flux-cache"

flux_cache-0.1.0/setup.cfg

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