plain.cache 0.0.0__tar.gz

plain_cache-0.0.0/LICENSE

@@ -0,0 +1,61 @@
+## Plain is released under the BSD 3-Clause License
+
+BSD 3-Clause License
+
+Copyright (c) 2023, Dropseed, LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+## This package contains code forked from github.com/django/django
+
+Copyright (c) Django Software Foundation and individual contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Django nor the names of its contributors may be used
+       to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plain_cache-0.0.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.1
+Name: plain.cache
+Version: 0.0.0
+Summary: 
+Author: Dave Gaeddert
+Author-email: dave.gaeddert@dropseed.dev
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12

plain_cache-0.0.0/plain/cache/README.md

@@ -0,0 +1,46 @@
+# Cache
+
+A simple cache using the database.
+
+The Plain Cache stores JSON-serializable values in a `CachedItem` model.
+Cached data can be set to expire after a certain amount of time.
+
+Access to the cache is provided through the `Cached` class.
+
+```python
+from plain.cache import Cached
+
+
+cached = Cached("my-cache-key")
+
+if cached.exists():
+    print("Cache hit and not expired!")
+    print(cached.value)
+else:
+    print("Cache miss!")
+    cached.set("a JSON-serializable value", expiration=60)
+
+# Delete the item if you need to
+cached.delete()
+```
+
+Expired cache items can be cleared with `plain cache clear-expired`.
+You can run this on a schedule through various cron-like tools or [plain-worker](../../../plain-worker/plain/worker/).
+
+## Installation
+
+Add `plain.cache` to your `INSTALLED_PACKAGES`:
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    # ...
+    "plain.cache",
+]
+```
+
+## CLI
+
+- `plain cache clear-expired` - Clear all expired cache items
+- `plain cache clear-all` - Clear all cache items
+- `plain cache stats` - Show cache statistics

plain_cache-0.0.0/plain/cache/__init__.py

@@ -0,0 +1,5 @@
+from .core import Cached
+
+__all__ = [
+    "Cached",
+]

plain_cache-0.0.0/plain/cache/admin.py

@@ -0,0 +1,32 @@
+from plain.cache.models import CachedItem
+from plain.staff.admin.views import (
+    AdminModelDetailView,
+    AdminModelListView,
+    AdminModelViewset,
+    register_viewset,
+)
+
+
+@register_viewset
+class CachedItemViewset(AdminModelViewset):
+    class ListView(AdminModelListView):
+        nav_section = "Cache"
+        model = CachedItem
+        title = "Cached items"
+        fields = [
+            "key",
+            "created_at",
+            "expires_at",
+            "updated_at",
+        ]
+        queryset_order = ["-pk"]
+        allow_global_search = False
+
+        def get_list_queryset(self):
+            return CachedItem.objects.all().only(
+                "key", "created_at", "expires_at", "updated_at"
+            )
+
+    class DetailView(AdminModelDetailView):
+        model = CachedItem
+        title = "Cached item"

plain_cache-0.0.0/plain/cache/cli.py

@@ -0,0 +1,40 @@
+import click
+
+from .models import CachedItem
+
+
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+def clear_expired():
+    click.echo("Clearing expired cache items...")
+    result = CachedItem.objects.expired().delete()
+    click.echo(f"Deleted {result[0]} expired cache items.")
+
+
+@cli.command()
+@click.option("--force", is_flag=True)
+def clear_all(force):
+    if not force and not click.confirm(
+        "Are you sure you want to delete all cache items?"
+    ):
+        return
+    click.echo("Clearing all cache items...")
+    result = CachedItem.objects.all().delete()
+    click.echo(f"Deleted {result[0]} cache items.")
+
+
+@cli.command()
+def stats():
+    total = CachedItem.objects.count()
+    expired = CachedItem.objects.expired().count()
+    unexpired = CachedItem.objects.unexpired().count()
+    forever = CachedItem.objects.forever().count()
+
+    click.echo(f"Total: {click.style(total, bold=True)}")
+    click.echo(f"Expired: {click.style(expired, bold=True)}")
+    click.echo(f"Unexpired: {click.style(unexpired, bold=True)}")
+    click.echo(f"Forever: {click.style(forever, bold=True)}")

plain_cache-0.0.0/plain/cache/config.py

@@ -0,0 +1,6 @@
+from plain.packages import PackageConfig
+
+
+class PlainCacheConfig(PackageConfig):
+    name = "plain.cache"
+    label = "plaincache"

plain_cache-0.0.0/plain/cache/core.py

@@ -0,0 +1,93 @@
+from datetime import datetime, timedelta
+from functools import cached_property
+
+from plain.models import IntegrityError
+from plain.utils import timezone
+
+
+class Cached:
+    """Store and retrieve cached items."""
+
+    def __init__(self, key: str) -> None:
+        self.key = key
+
+        # So we can import Cached in __init__.py
+        # without getting the packages not ready error...
+        from .models import CachedItem
+
+        self._model_class = CachedItem
+
+    @cached_property
+    def _model_instance(self):
+        try:
+            return self._model_class.objects.get(key=self.key)
+        except self._model_class.DoesNotExist:
+            return None
+
+    def reload(self) -> None:
+        if hasattr(self, "_model_instance"):
+            del self._model_instance
+
+    def _is_expired(self):
+        if not self._model_instance:
+            return True
+
+        if not self._model_instance.expires_at:
+            return False
+
+        return self._model_instance.expires_at < timezone.now()
+
+    def exists(self) -> bool:
+        if self._model_instance is None:
+            return False
+
+        return not self._is_expired()
+
+    @property
+    def value(self):
+        if not self.exists():
+            return None
+
+        return self._model_instance.value
+
+    def set(self, value, expiration: datetime | timedelta | int | float | None = None):
+        defaults = {
+            "value": value,
+        }
+
+        if isinstance(expiration, int | float):
+            defaults["expires_at"] = timezone.now() + timedelta(seconds=expiration)
+        elif isinstance(expiration, timedelta):
+            defaults["expires_at"] = timezone.now() + expiration
+        elif isinstance(expiration, datetime):
+            defaults["expires_at"] = expiration
+        else:
+            # Keep existing expires_at value or None
+            pass
+
+        # Make sure expires_at is timezone aware
+        if defaults["expires_at"] and not timezone.is_aware(defaults["expires_at"]):
+            defaults["expires_at"] = timezone.make_aware(defaults["expires_at"])
+
+        try:
+            item, _ = self._model_class.objects.update_or_create(
+                key=self.key, defaults=defaults
+            )
+        except IntegrityError:
+            # Most likely a race condition in creating the item,
+            # so trying again should do an update
+            item, _ = self._model_class.objects.update_or_create(
+                key=self.key, defaults=defaults
+            )
+
+        self.reload()
+        return item.value
+
+    def delete(self) -> bool:
+        if not self._model_instance:
+            # A no-op, but a return value you can use to know whether it did anything
+            return False
+
+        self._model_instance.delete()
+        self.reload()
+        return True

plain_cache-0.0.0/plain/cache/migrations/0001_initial.py

@@ -0,0 +1,34 @@
+# Generated by Plain 5.0.dev20231127233940 on 2023-12-22 03:47
+
+from plain import models
+from plain.models import migrations
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="CacheItem",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("key", models.CharField(max_length=255, unique=True)),
+                ("value", models.JSONField(blank=True, null=True)),
+                (
+                    "expires_at",
+                    models.DateTimeField(blank=True, db_index=True, null=True),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+        ),
+    ]

plain_cache-0.0.0/plain/cache/migrations/0002_rename_cacheitem_cacheditem.py

@@ -0,0 +1,16 @@
+# Generated by Plain 5.0.dev20231127233940 on 2023-12-22 17:40
+
+from plain.models import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("plaincache", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.RenameModel(
+            old_name="CacheItem",
+            new_name="CachedItem",
+        ),
+    ]

plain_cache-0.0.0/plain/cache/models.py

@@ -0,0 +1,26 @@
+from plain import models
+from plain.utils import timezone
+
+
+class CachedItemQuerySet(models.QuerySet):
+    def expired(self):
+        return self.filter(expires_at__lt=timezone.now())
+
+    def unexpired(self):
+        return self.filter(expires_at__gte=timezone.now())
+
+    def forever(self):
+        return self.filter(expires_at=None)
+
+
+class CachedItem(models.Model):
+    key = models.CharField(max_length=255, unique=True)
+    value = models.JSONField(blank=True, null=True)
+    expires_at = models.DateTimeField(blank=True, null=True, db_index=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    objects = CachedItemQuerySet.as_manager()
+
+    def __str__(self) -> str:
+        return self.key

plain_cache-0.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[tool.poetry]
+name = "plain.cache"
+packages = [
+    { include = "plain" },
+]
+version = "0.0.0"
+description = ""
+authors = ["Dave Gaeddert <dave.gaeddert@dropseed.dev>"]
+# readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"