Add docs for JSONDisk.

grantjenks · grantjenks · commit 19f908bd5d6d · 2019-10-13T16:07:48.000-07:00
diff --git a/diskcache/__init__.py b/diskcache/__init__.py
@@ -25,7 +25,7 @@
     'EmptyDirWarning',
     'FanoutCache',
     'Index',
-    "JSONDisk",
+    'JSONDisk',
     'Lock',
     'RLock',
     'Timeout',
diff --git a/diskcache/core.py b/diskcache/core.py
@@ -363,26 +363,42 @@ def remove(self, filename):
 
 
 class JSONDisk(Disk):
-    """Cache key and value (de)serialized as JSON."""
+    "Cache key and value using JSON serialization with zlib compression."
     def __init__(self, directory, compress_level=1, **kwargs):
+        """Initialize JSON disk instance.
+
+        Keys and values are compressed using the zlib library. The
+        `compress_level` is an integer from 0 to 9 controlling the level of
+        compression; 1 is fastest and produces the least compression, 9 is
+        slowest and produces the most compression, and 0 is no compression.
+
+        :param str directory: directory path
+        :param int compress_level: zlib compression level (default 1)
+        :param kwargs: super class arguments
+
+        """
         self.compress_level = compress_level
         super(JSONDisk, self).__init__(directory, **kwargs)
 
+
     def put(self, key):
         json_bytes = json.dumps(key).encode('utf-8')
         data = zlib.compress(json_bytes, self.compress_level)
         return super(JSONDisk, self).put(data)
 
+
     def get(self, key, raw):
         data = super(JSONDisk, self).get(key, raw)
         return json.loads(zlib.decompress(data).decode('utf-8'))
 
+
     def store(self, value, read, key=UNKNOWN):
         if not read:
             json_bytes = json.dumps(value).encode('utf-8')
             value = zlib.compress(json_bytes, self.compress_level)
         return super(JSONDisk, self).store(value, read, key=key)
 
+
     def fetch(self, mode, filename, value, read):
         data = super(JSONDisk, self).fetch(mode, filename, value, read)
         if not read:
diff --git a/docs/api.rst b/docs/api.rst
@@ -116,6 +116,16 @@ Read the :ref:`Disk tutorial <tutorial-disk>` for details.
    :special-members:
    :exclude-members: __weakref__
 
+JSONDisk
+--------
+
+Read the :ref:`Disk tutorial <tutorial-disk>` for details.
+
+.. autoclass:: diskcache.JSONDisk
+   :members:
+   :special-members:
+   :exclude-members: __weakref__
+
 Timeout
 -------
 
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -813,8 +813,8 @@ database while values are sometimes stored separately in files.
 To customize serialization, you may pass in a :class:`Disk <diskcache.Disk>`
 subclass to initialize the cache. All clients accessing the cache are expected
 to use the same serialization. The default implementation uses Pickle and the
-example below uses compressed JSON,
-available for convenience as :class:`Disk <diskcache.JSONDisk>`.
+example below uses compressed JSON, available for convenience as
+:class:`JSONDisk <diskcache.JSONDisk>`.
 
 .. code-block:: python
 
