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