1# Copyright (C) 2016-2020 by the Free Software Foundation, Inc.
2#
3# This file is part of GNU Mailman.
4#
5# GNU Mailman is free software: you can redistribute it and/or modify it under
6# the terms of the GNU General Public License as published by the Free
7# Software Foundation, either version 3 of the License, or (at your option)
8# any later version.
9#
10# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
11# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
13# more details.
14#
15# You should have received a copy of the GNU General Public License along with
16# GNU Mailman.  If not, see <https://www.gnu.org/licenses/>.
17
18"""File caches."""
19
20from public import public
21from zope.interface import Interface
22
23
24@public
25class ICacheManager(Interface):
26    """Manager for managing cached files."""
27
28    def add(key, contents, lifetime=None):
29        """Add the contents to the cache, indexed by the key.
30
31        If there is already some contents cached under the given key, the old
32        contents are overwritten with the new contents.
33
34        :param key: The key to use when storing the contents.
35        :type name: str
36        :param contents: The contents to store in the cache.  If this is a
37            bytes object, it will be stored on disk in binary.  If it's a str,
38            it will be stored in UTF-8.  Either way, the manager will remember
39            the type and return it when you access the file.
40        :type contents: bytes or str
41        :param lifetime: How long should the file be cached for, before it
42            expires (leading to its eventual eviction)?  If not given, the
43            system default lifetime is used.
44        :type lifetime: datetime.timedelta
45        :return: The SHA256 hash under which the file contents are stored.
46        :rtype: str
47        """
48
49    def get(key, *, expunge=False):
50        """Return the contents cached under the given key.
51
52        :param key: The key identifying the contents you want to retrieve.
53        :type key: str
54        :param expunge: A flag indicating whether the file contents should
55            also be removed from the cache.
56        :type expunge: bool
57        :return: The contents of the cached file or None if the given id isn't
58            in the cache (or it's already expired).
59        :rtype: bytes or str, depending on the original contents.
60        """
61
62    def evict(key):
63        """Evict the file pointed to by key.
64
65        :param key: The key identifying the contents you want to evict.
66        :type key: str
67        """
68
69    def evict_expired():
70        """Evict all files which have expired."""
71
72    def clear():
73        """Clear the entire cache of files."""
74