feat: Replace the latest parameter by version in Project.get (#1173)

Following #1052 , change the API to be compliant with `set_note` and
@MarieS-WiMLDS comments.

examples/getting_started/plot_tracking_items.py

@@ -75,7 +75,7 @@
 # We retrieve the history of the ``my_int`` item:
 
 # %%
-history = my_project.get("my_int", latest=False, metadata=True)
+history = my_project.get("my_int", version="all", metadata=True)
 
 # %%
 # We can print the details of the first version of this item:

skore/src/skore/project/project.py

@@ -87,17 +87,24 @@ def put(
             ),
         )
 
-    def get(self, key, *, latest=True, metadata=False):
+    def get(
+        self,
+        key: str,
+        *,
+        version: Optional[Union[Literal[-1, "all"], int]] = -1,
+        metadata: bool = False,
+    ):
         """Get the value associated to ``key`` from the Project.
 
         Parameters
         ----------
         key : str
             The key corresponding to the item to get.
-        latest : boolean, default=True
-            If True, get the latest value, otherwise get all the values associated to
-            ``key``.
-        metadata : boolean, default=False
+        version : Union[Literal[-1, "all"], int], default=-1
+            If -1, get the latest value associated to ``key``.
+            If "all", get all the values associated to ``key``.
+            If instance of int, get the nth value associated to ``key``.
+        metadata : bool, default=False
             If True, get the metadata in addition to the value.
 
         Returns
@@ -132,9 +139,14 @@ def dto(item):
                     "note": item.note,
                 }
 
-        if latest:
+        if version == -1:
             return dto(self.item_repository.get_item(key))
-        return list(map(dto, self.item_repository.get_item_versions(key)))
+        if version == "all":
+            return list(map(dto, self.item_repository.get_item_versions(key)))
+        if isinstance(version, int):
+            return dto(self.item_repository.get_item_versions(key)[version])
+
+        raise ValueError('`version` should be -1, "all", or an integer')
 
     def keys(self) -> list[str]:
         """

skore/tests/unit/project/test_project.py

@@ -188,10 +188,14 @@ def test_get(in_memory_project, mock_nowstr):
     in_memory_project.put("key", 1, note="1")
     in_memory_project.put("key", 2, note="2")
 
-    assert in_memory_project.get("key") == 2
-    assert in_memory_project.get("key", latest=True, metadata=False) == 2
-    assert in_memory_project.get("key", latest=False, metadata=False) == [1, 2]
-    assert in_memory_project.get("key", latest=False, metadata=True) == [
+    assert in_memory_project.get("key", metadata=False) == 2
+    assert in_memory_project.get("key", metadata=True) == {
+        "value": 2,
+        "date": mock_nowstr,
+        "note": "2",
+    }
+    assert in_memory_project.get("key", version="all", metadata=False) == [1, 2]
+    assert in_memory_project.get("key", version="all", metadata=True) == [
         {
             "value": 1,
             "date": mock_nowstr,
@@ -203,15 +207,19 @@ def test_get(in_memory_project, mock_nowstr):
             "note": "2",
         },
     ]
-    assert in_memory_project.get("key", latest=True, metadata=True) == {
-        "value": 2,
+    assert in_memory_project.get("key", version=0, metadata=False) == 1
+    assert in_memory_project.get("key", version=0, metadata=True) == {
+        "value": 1,
         "date": mock_nowstr,
-        "note": "2",
+        "note": "1",
     }
 
     with pytest.raises(KeyError):
         in_memory_project.get("<unknown>")
 
+    with pytest.raises(ValueError):
+        in_memory_project.get("key", version=None)
+
 
 def test_delete(in_memory_project):
     in_memory_project.put("key1", 1)