Redisign the cahce API

cachecontrol/adapter.py

@@ -9,7 +9,7 @@
 from requests.adapters import HTTPAdapter
 
 from .controller import CacheController, PERMANENT_REDIRECT_STATUSES
-from .cache import DictCache
+# from .cache import DictCache
 from .filewrapper import CallbackFileWrapper
 
 

cachecontrol/controller.py

@@ -13,7 +13,7 @@
 
 from requests.structures import CaseInsensitiveDict
 
-from .cache import DictCache
+#from .cache import DictCache
 from .serialize import Serializer
 
 

cachecontrol/streaming_cache.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: Apache-2.0
+
+import io
+
+
+class NotFound(Exception):
+    '''Raised by Cache.open_read() and Cache.delete() when the key is missing'''
+
+
+class ReadHandle:
+    def read(self, size: int = -1) -> bytes:
+        pass
+
+    def close(self) -> None:
+        pass
+
+
+class WriteHandle:
+    def write(self, b: bytes) -> int:
+        pass
+
+    def commit(self) -> None:
+        '''Assign the value to the key and close the WriteHandle'''
+        pass
+
+    def close(self) -> None:
+        '''Discard the value without assigning it to the key'''
+        pass
+
+
+class Cache:
+    '''Cache API docs
+
+    No need to inherit form this. This is just a documenation
+    of the interface between CacheControl and a cache
+    '''
+
+    # TODO: are keys really str?
+    def open_read(self, key: str) -> ReadHandle:
+        '''Get data from the cache
+
+        Throw NotFound if the key is missing
+        '''
+        pass
+
+    def open_write(self, key: str, expires=None) -> WriteHandle:
+        pass
+
+    def delete(self, key):
+        '''Delete key from the cache
+
+        Throw NotFound if the key is missing
+        '''
+        pass
+
+    def close(self):
+        '''Cleanup any temporary files, database connections etc.'''
+        pass
+    # Cache does not have __enter__ and __exit__ on purpose. Same for ReadHandle
+    # and WriteHandle. The idea is to keep the interface small, simple and easy
+    # to implement - it is the interface between CacheControl and storage
+    # backends. Helpers can be written on top of this interface
+    # to make it easier to use.
+
+
+# An example to use while prototyping
+class ExampleCache:
+    class WriteHandle:
+        def __init__(self, put):
+            self.put = put
+            self.buf = io.BytesIO()
+
+        def write(self, b):
+            self.buf.write(b)
+
+        def commit(self):
+            self.put(self.buf.getvalue())
+
+        def close(self):
+            pass
+
+    def __init__(self):
+        self.data = {}
+
+    def open_read(self, key):
+        try:
+            return io.BytesIO(self.data[key])
+        except KeyError:
+            raise NotFound(f'{key} not found in the cache')
+
+    def open_write(self, key, expires=None):
+        def put(b):
+            self.data[key] = b
+        return self.WriteHandle(put)
+
+    def delete(self, key):
+        try:
+            del self.data[key]
+        except KeyError:
+            raise NotFound(f'{key} not found in the cache')
+
+    def close(self):
+        pass

cachecontrol/wrapper.py

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from .adapter import CacheControlAdapter
-from .cache import DictCache
+# from .cache import DictCache
 
 
 def CacheControl(