cherry-pick fcollonval#1

Co-authored-by: Frédéric Collonval <fcollonval@gmail.com>
Wh1isper · Nov 23, 2023 · f5956f5 · f5956f5
1 parent 6353c6a
commit f5956f5
Show file tree

Hide file tree

Showing 11 changed files with 421 additions and 244 deletions.
diff --git a/docs/source/developers/contents.rst b/docs/source/developers/contents.rst
@@ -33,44 +33,46 @@ which we refer to as **models**.
 
 Models may contain the following entries:
 
-+--------------------+-----------+------------------------------+
-| Key                | Type      |Info                          |
-+====================+===========+==============================+
-|**name**            |unicode    |Basename of the entity.       |
-+--------------------+-----------+------------------------------+
-|**path**            |unicode    |Full                          |
-|                    |           |(:ref:`API-style<apipaths>`)  |
-|                    |           |path to the entity.           |
-+--------------------+-----------+------------------------------+
-|**type**            |unicode    |The entity type. One of       |
-|                    |           |``"notebook"``, ``"file"`` or |
-|                    |           |``"directory"``.              |
-+--------------------+-----------+------------------------------+
-|**created**         |datetime   |Creation date of the entity.  |
-+--------------------+-----------+------------------------------+
-|**last_modified**   |datetime   |Last modified date of the     |
-|                    |           |entity.                       |
-+--------------------+-----------+------------------------------+
-|**content**         |variable   |The "content" of the entity.  |
-|                    |           |(:ref:`See                    |
-|                    |           |Below<modelcontent>`)         |
-+--------------------+-----------+------------------------------+
-|**mimetype**        |unicode or |The mimetype of ``content``,  |
-|                    |``None``   |if any.  (:ref:`See           |
-|                    |           |Below<modelcontent>`)         |
-+--------------------+-----------+------------------------------+
-|**format**          |unicode or |The format of ``content``,    |
-|                    |``None``   |if any. (:ref:`See            |
-|                    |           |Below<modelcontent>`)         |
-+--------------------+-----------+------------------------------+
-|**hash**            |unicode or |The hash of the contents.     |
-|                    |``None``   |                              |
-|                    |           |                              |
-+--------------------+-----------+------------------------------+
-|**hash_algorithm**  |unicode    |The algorithm used to compute |
-|                    |           |hash value.                   |
-|                    |           |                              |
-+--------------------+-----------+------------------------------+
++--------------------+------------+-----------------------------------------+
+|        Key         |    Type    |                  Info                   |
++====================+============+=========================================+
+| **name**           | unicode    | Basename of the entity.                 |
++--------------------+------------+-----------------------------------------+
+| **path**           | unicode    | Full                                    |
+|                    |            | (:ref:`API-style<apipaths>`)            |
+|                    |            | path to the entity.                     |
++--------------------+------------+-----------------------------------------+
+| **type**           | unicode    | The entity type. One of                 |
+|                    |            | ``"notebook"``, ``"file"`` or           |
+|                    |            | ``"directory"``.                        |
++--------------------+------------+-----------------------------------------+
+| **created**        | datetime   | Creation date of the entity.            |
++--------------------+------------+-----------------------------------------+
+| **last_modified**  | datetime   | Last modified date of the               |
+|                    |            | entity.                                 |
++--------------------+------------+-----------------------------------------+
+| **content**        | variable   | The "content" of the entity.            |
+|                    |            | (:ref:`See                              |
+|                    |            | Below<modelcontent>`)                   |
++--------------------+------------+-----------------------------------------+
+| **mimetype**       | unicode or | The mimetype of ``content``,            |
+|                    | ``None``   | if any.  (:ref:`See                     |
+|                    |            | Below<modelcontent>`)                   |
++--------------------+------------+-----------------------------------------+
+| **format**         | unicode or | The format of ``content``,              |
+|                    | ``None``   | if any. (:ref:`See                      |
+|                    |            | Below<modelcontent>`)                   |
++--------------------+------------+-----------------------------------------+
+| [optional]         |            |                                         |
+| **hash**           | unicode or | The hash of the contents.               |
+|                    | ``None``   | It cannot be null if ``hash_algorithm`` |
+|                    |            | is defined.                             |
++--------------------+------------+-----------------------------------------+
+| [optional]         |            |                                         |
+| **hash_algorithm** | unicode or | The algorithm used to compute           |
+|                    | ``None``   | hash value.                             |
+|                    |            | It cannot be null if hash is defined.   |
++--------------------+------------+-----------------------------------------+
 
 .. _modelcontent:
 
@@ -122,7 +124,7 @@ model. There are three model types: **notebook**, **file**, and **directory**.
 
 .. code-block:: python
 
-    # Notebook Model with Content
+    # Notebook Model with Content and Hash
     {
         "content": {
             "metadata": {},

diff --git a/jupyter_server/services/api/api.yaml b/jupyter_server/services/api/api.yaml
@@ -108,7 +108,7 @@ paths:
           type: integer
         - name: hash
           in: query
-          description: "Return hash hexdigest string of content (0 for no hash, 1 for return hash), when ContentsManager not support hash, it will be ignored."
+          description: "May return hash hexdigest string of content and the hash algorithm (0 for no hash - default, 1 for return hash). It may be ignored by the content manager."
           type: integer
       responses:
         404:
@@ -901,8 +901,6 @@ definitions:
       - mimetype
       - format
       - content
-      - hash
-      - hash_algorithm
     properties:
       name:
         type: string
@@ -942,10 +940,10 @@ definitions:
         description: Format of content (one of null, 'text', 'base64', 'json')
       hash:
         type: string
-        description: "The hexdigest hash string of content, if requested (otherwise null)."
+        description: "[optional] The hexdigest hash string of content, if requested (otherwise null). It cannot be null if hash_algorithm is defined."
       hash_algorithm:
         type: string
-        ddescription: "The algorithm used to produce the hash."
+        description: "[optional] The algorithm used to produce the hash, if requested (otherwise null). It cannot be null if hash is defined."
   Checkpoints:
     description: A checkpoint object.
     type: object

diff --git a/jupyter_server/services/contents/filecheckpoints.py b/jupyter_server/services/contents/filecheckpoints.py
@@ -252,7 +252,7 @@ def get_file_checkpoint(self, checkpoint_id, path):
         if not os.path.isfile(os_checkpoint_path):
             self.no_such_checkpoint(path, checkpoint_id)
 
-        content, format, _ = self._read_file(os_checkpoint_path, format=None)
+        content, format = self._read_file(os_checkpoint_path, format=None)
         return {
             "type": "file",
             "content": content,
@@ -318,7 +318,7 @@ async def get_file_checkpoint(self, checkpoint_id, path):
         if not os.path.isfile(os_checkpoint_path):
             self.no_such_checkpoint(path, checkpoint_id)
 
-        content, format, _ = await self._read_file(os_checkpoint_path, format=None)
+        content, format = await self._read_file(os_checkpoint_path, format=None)
         return {
             "type": "file",
             "content": content,