Feature/clean up and add cache (#194)

* clean up hook methods slightly

* move private attributes to top

* add basic cache using diskcache

* ensure cache is closed

* add docstring

* finally get rid of false errors in tests by not initializing test apps if in pytest

* lazy load cache, handle exception when closing

* remove some old crap from test files

* no longer need this

* move cancel and cache closing to cleanup method, improve base resource cleanup method with timeout, add new timeout config

* add back .env file, put something more inocuous in there

* update changelog

* add a fake token to test config class

* use cached_property instead

* bring back private attribute, use for testing existence when closing

* update docstring and changelog entry

Author: NodeJSmith

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+- Add `diskcache` dependency and `cache` attribute to all resources
+  - Each resource class has its own cache directory under the Hassette data directory
+
 ## [0.16.0] - 2025-11-16
 
 ### Added

pyproject.toml

@@ -38,6 +38,7 @@ dependencies = [
     "coloredlogs>=15.0.1",
     "croniter>=6.0.0",
     "deepdiff>=8.6.1",
+    "diskcache>=5.6.3",
     "fair-async-rlock>=1.0.7",
     "glom>=24.11.0",
     "humanize>=4.13.0",

src/hassette/app/app.py

@@ -1,7 +1,6 @@
 import asyncio
 import logging
 import typing
-from contextlib import suppress
 from logging import getLogger
 from typing import Any, ClassVar, Generic, final
 
@@ -67,6 +66,9 @@ class App(Generic[AppConfigT], Resource, metaclass=AppMeta):
     _only_app: ClassVar[bool] = False
     """If True, only this app will be run. Only one app can be marked as only."""
 
+    _import_exception: ClassVar[Exception | None] = None
+    """Exception raised during import, if any. This prevents having all apps in a module fail due to one exception."""
+
     role: ClassVar[ResourceRole] = ResourceRole.APP
     """Role of the resource, e.g. 'App', 'Service', etc."""
 
@@ -77,9 +79,6 @@ class App(Generic[AppConfigT], Resource, metaclass=AppMeta):
     """Config class to use for instances of the created app. Configuration from hassette.toml or
     other sources will be validated by this class."""
 
-    _import_exception: ClassVar[Exception | None] = None
-    """Exception raised during import, if any. This prevents having all apps in a module fail due to one exception."""
-
     logger: logging.Logger
     """Logger for the instance."""
 
@@ -147,10 +146,9 @@ async def cleanup(self, timeout: int | None = None) -> None:
 
         This method is called during shutdown to ensure that all resources are properly released.
         """
-        self.cancel()
-        with suppress(asyncio.CancelledError):
-            if self._init_task:
-                await asyncio.wait_for(self._init_task, timeout=timeout)
+        timeout = timeout or self.hassette.config.app_shutdown_timeout_seconds
+
+        await super().cleanup(timeout=timeout)
 
         tasks = []
 
@@ -167,69 +165,65 @@ async def cleanup(self, timeout: int | None = None) -> None:
 
 
 class AppSync(App[AppConfigT]):
-    """Synchronous adapter for App.
-
-    This class allows synchronous apps to work properly in the async environment
-    by using anyio's thread management capabilities.
-    """
+    """Synchronous adapter for App."""
 
     def send_event_sync(self, event_name: str, event: Event[Any]) -> None:
         """Synchronous version of send_event."""
         self.task_bucket.run_sync(self.send_event(event_name, event))
 
-    # --- developer-facing hooks (override as needed) -------------------
+    @final
     async def before_shutdown(self) -> None:
         """Optional: stop accepting new work, signal loops to wind down, etc."""
         await self.task_bucket.run_in_thread(self.before_shutdown_sync)
 
+    @final
     async def on_shutdown(self) -> None:
         """Primary hook: release your own stuff (sockets, queues, temp files…)."""
         await self.task_bucket.run_in_thread(self.on_shutdown_sync)
-        await super().on_shutdown()
 
+    @final
     async def after_shutdown(self) -> None:
         """Optional: last-chance actions after on_shutdown, before cleanup/STOPPED."""
         await self.task_bucket.run_in_thread(self.after_shutdown_sync)
 
-    # --- developer-facing hooks (override as needed) -------------------
+    @final
     async def before_initialize(self) -> None:
         """Optional: prepare to accept new work, allocate sockets, queues, temp files, etc."""
         await self.task_bucket.run_in_thread(self.before_initialize_sync)
 
+    @final
     async def on_initialize(self) -> None:
         """Primary hook: perform your own initialization (sockets, queues, temp files…)."""
         await self.task_bucket.run_in_thread(self.on_initialize_sync)
 
+    @final
     async def after_initialize(self) -> None:
         """Optional: finalize initialization, signal readiness, etc."""
         await self.task_bucket.run_in_thread(self.after_initialize_sync)
 
-    # --- developer-facing hooks (override as needed) -------------------
     def before_shutdown_sync(self) -> None:
         """Optional: stop accepting new work, signal loops to wind down, etc."""
-        # Default: cancel an in-flight initialize() task if you used Resource.start()
-        self.cancel()
+        pass
 
     def on_shutdown_sync(self) -> None:
         """Primary hook: release your own stuff (sockets, queues, temp files…)."""
-        # Default: nothing. Subclasses override when they own resources.
+        pass
 
     def after_shutdown_sync(self) -> None:
         """Optional: last-chance actions after on_shutdown, before cleanup/STOPPED."""
-        # Default: nothing.
+        pass
 
-    # --- developer-facing hooks (override as needed) -------------------
     def before_initialize_sync(self) -> None:
         """Optional: prepare to accept new work, allocate sockets, queues, temp files, etc."""
-        # Default: nothing. Subclasses override when they own resources.
+        pass
 
     def on_initialize_sync(self) -> None:
         """Primary hook: perform your own initialization (sockets, queues, temp files…)."""
-        # Default: nothing. Subclasses override when they own resources.
+        pass
 
     def after_initialize_sync(self) -> None:
         """Optional: finalize initialization, signal readiness, etc."""
-        # Default: nothing. Subclasses override when they own resources.
+        pass
 
     @final
     def initialize_sync(self) -> None:

src/hassette/config/core.py

@@ -153,6 +153,11 @@ def settings_customise_sources(
     app_shutdown_timeout_seconds: int = Field(default=10)
     """Length of time to wait for an app to shut down before giving up."""
 
+    resource_shutdown_timeout_seconds: int = Field(
+        default_factory=lambda data: data.get("app_shutdown_timeout_seconds", 10)
+    )
+    """Length of time to wait for a resource to shut down before giving up. Defaults to app_shutdown_timeout_seconds."""
+
     websocket_authentication_timeout_seconds: int = Field(default=10)
     """Length of time to wait for WebSocket authentication to complete."""
 
@@ -198,6 +203,9 @@ def settings_customise_sources(
     task_cancellation_timeout_seconds: int = Field(default=5)
     """Length of time to wait for tasks to cancel before forcing."""
 
+    default_cache_size: int = Field(default=100 * 1024 * 1024)
+    """Default size limit for caches in bytes. Defaults to 100 MiB."""
+
     # Service log levels
 
     bus_service_log_level: LOG_ANNOTATION = Field(default_factory=log_level_default_factory)

src/hassette/config/hassette.dev.toml

@@ -11,6 +11,7 @@ allow_startup_if_app_precheck_fails = true
 startup_timeout_seconds = 20
 app_startup_timeout_seconds = 40
 app_shutdown_timeout_seconds = 20
+resource_shutdown_timeout_seconds = 20
 websocket_authentication_timeout_seconds = 20
 websocket_response_timeout_seconds = 10
 websocket_connection_timeout_seconds = 10
@@ -40,3 +41,4 @@ log_all_hass_events = false
 log_all_hassette_events = false
 allow_reload_in_prod = false
 allow_only_app_in_prod = false
+default_cache_size = 104857600                # 100 MiB

src/hassette/config/hassette.prod.toml

@@ -11,6 +11,7 @@ allow_startup_if_app_precheck_fails = false
 startup_timeout_seconds = 10
 app_startup_timeout_seconds = 20
 app_shutdown_timeout_seconds = 10
+resource_shutdown_timeout_seconds = 10
 websocket_authentication_timeout_seconds = 10
 websocket_response_timeout_seconds = 5
 websocket_connection_timeout_seconds = 5
@@ -40,3 +41,4 @@ log_all_hass_events = false
 log_all_hassette_events = false
 allow_reload_in_prod = false
 allow_only_app_in_prod = false
+default_cache_size = 104857600                # 100 MiB

src/hassette/resources/base.py

@@ -5,9 +5,12 @@
 from abc import abstractmethod
 from collections.abc import Coroutine
 from contextlib import suppress
+from functools import cached_property
 from logging import Logger, getLogger
 from typing import Any, ClassVar, TypeVar, final
 
+from diskcache import Cache
+
 from hassette.exceptions import CannotOverrideFinalError, FatalError
 from hassette.types.enums import ResourceRole
 
@@ -66,6 +69,18 @@ def __init__(cls, name, bases, ns, **kw):
 class Resource(LifecycleMixin, metaclass=FinalMeta):
     """Base class for resources in the Hassette framework."""
 
+    _shutting_down: bool = False
+    """Flag indicating whether the instance is in the process of shutting down."""
+
+    _initializing: bool = False
+    """Flag indicating whether the instance is in the process of starting up."""
+
+    _unique_name: str
+    """Unique name for the instance."""
+
+    _cache: Cache | None
+    """Private attribute to hold the cache, to allow lazy initialization."""
+
     role: ClassVar[ResourceRole] = ResourceRole.RESOURCE
     """Role of the resource, e.g. 'App', 'Service', etc."""
 
@@ -78,18 +93,9 @@ class Resource(LifecycleMixin, metaclass=FinalMeta):
     children: list["Resource"]
     """List of child resources."""
 
-    _shutting_down: bool = False
-    """Flag indicating whether the instance is in the process of shutting down."""
-
-    _initializing: bool = False
-    """Flag indicating whether the instance is in the process of starting up."""
-
     logger: Logger
     """Logger for the instance."""
 
-    _unique_name: str
-    """Unique name for the instance."""
-
     unique_id: str
     """Unique identifier for the instance."""
 
@@ -124,6 +130,7 @@ def __init__(
 
         super().__init__()
 
+        self._cache = None  # lazy init
         self.unique_id = uuid.uuid4().hex[:8]
 
         self.hassette = hassette
@@ -152,6 +159,18 @@ def _setup_logger(self) -> None:
     def __repr__(self) -> str:
         return f"<{type(self).__name__} unique_name={self.unique_name}>"
 
+    @cached_property
+    def cache(self) -> Cache:
+        """Disk cache for storing arbitrary data. All instances of the same resource class share a cache directory."""
+        if self._cache is not None:
+            return self._cache
+
+        # set up cache
+        cache_dir = self.hassette.config.data_dir.joinpath(self.class_name).joinpath("cache")
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        self._cache = Cache(cache_dir, size_limit=self.hassette.config.default_cache_size)
+        return self._cache
+
     @property
     def unique_name(self) -> str:
         """Get the unique name of the instance."""
@@ -199,19 +218,6 @@ def add_child(self, child_class: type[_ResourceT], **kwargs) -> _ResourceT:
         self.children.append(inst)
         return inst
 
-    # --- developer-facing hooks (override as needed) -------------------
-    async def before_initialize(self) -> None:
-        """Optional: prepare to accept new work, allocate sockets, queues, temp files, etc."""
-        # Default: nothing. Subclasses override when they own resources.
-
-    async def on_initialize(self) -> None:
-        """Primary hook: perform your own initialization (sockets, queues, temp files…)."""
-        # Default: nothing. Subclasses override when they own resources.
-
-    async def after_initialize(self) -> None:
-        """Optional: finalize initialization, signal readiness, etc."""
-        # Default: nothing. Subclasses override when they own resources.
-
     @final
     async def initialize(self) -> None:
         """Initialize the instance by calling the lifecycle hooks in order."""
@@ -244,19 +250,17 @@ async def initialize(self) -> None:
         finally:
             self._initializing = False
 
-    # --- developer-facing hooks (override as needed) -------------------
-    async def before_shutdown(self) -> None:
-        """Optional: stop accepting new work, signal loops to wind down, etc."""
-        # Default: cancel an in-flight initialize() task if you used Resource.start()
-        self.cancel()
+    async def before_initialize(self) -> None:
+        """Optional: prepare to accept new work, allocate sockets, queues, temp files, etc."""
+        pass
 
-    async def on_shutdown(self) -> None:
-        """Primary hook: release your own stuff (sockets, queues, temp files…)."""
-        # Default: nothing. Subclasses override when they own resources.
+    async def on_initialize(self) -> None:
+        """Primary hook: perform your own initialization (sockets, queues, temp files…)."""
+        pass
 
-    async def after_shutdown(self) -> None:
-        """Optional: last-chance actions after on_shutdown, before cleanup/STOPPED."""
-        # Default: nothing.
+    async def after_initialize(self) -> None:
+        """Optional: finalize initialization, signal readiness, etc."""
+        pass
 
     @final
     async def shutdown(self) -> None:
@@ -302,21 +306,45 @@ async def shutdown(self) -> None:
 
             self._shutting_down = False
 
+    async def before_shutdown(self) -> None:
+        """Optional: stop accepting new work, signal loops to wind down, etc."""
+        pass
+
+    async def on_shutdown(self) -> None:
+        """Primary hook: release your own stuff (sockets, queues, temp files…)."""
+        pass
+
+    async def after_shutdown(self) -> None:
+        """Optional: last-chance actions after on_shutdown, before cleanup/STOPPED."""
+        pass
+
     async def restart(self) -> None:
         """Restart the instance by shutting it down and re-initializing it."""
         self.logger.debug("Restarting '%s' %s", self.class_name, self.role)
         await self.shutdown()
         await self.initialize()
 
-    async def cleanup(self) -> None:
+    async def cleanup(self, timeout: int | None = None) -> None:
         """Cleanup resources owned by the instance.
 
         This method is called during shutdown to ensure that all resources are properly released.
         """
+        timeout = timeout or self.hassette.config.resource_shutdown_timeout_seconds
+
         self.cancel()
+        with suppress(asyncio.CancelledError):
+            if self._init_task:
+                await asyncio.wait_for(self._init_task, timeout=timeout)
+
         await self.task_bucket.cancel_all()
         self.logger.debug("Cleaned up resources")
 
+        if self._cache is not None:
+            try:
+                self.cache.close()
+            except Exception as e:
+                self.logger.exception("Error closing cache: %s %s", type(e).__name__, e)
+
 
 class Service(Resource):
     """Base class for services in the Hassette framework."""

tests/conftest.py

@@ -35,6 +35,8 @@ class TestConfig(HassetteConfig):
         "env_file": ENV_FILE,
     }
 
+    token: str = "test-token"
+
     websocket_connection_timeout_seconds: int | float = 1
     websocket_authentication_timeout_seconds: int | float = 1
     websocket_total_timeout_seconds: int | float = 2

tests/data/.env

@@ -1,3 +1 @@
-hassette__token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJmNjlhYTIxMDlhNjU0MGU3YWZiYzdjZDJlN2U0ODIwOSIsImlhdCI6MTc1MzIzNzc2MiwiZXhwIjoyMDY4NTk3NzYyfQ.Q-V4TOPp9dVb_S9kTi1OAWQoe0DG0AIWQIsNwEAJ3Fg
-hassette__base_url=http://127.0.0.1:8123
-hassette__apps__myfakeapp__config__value=42
+hassette__apps_log_level=CRITICAL

tests/data/hassette.toml

@@ -1,5 +1,3 @@
 [hassette]
 base_url = "http://127.0.0.1:8123"
 app_dir = "tests/data"
-
-secrets = ["my_secret"]