[ci skip] WIP - Add docstr

Author: thomass-dev

skore-remote-project/pyproject.toml

@@ -69,9 +69,9 @@ parallel = true
 omit = ["src/*", "tests/*"]
 show_missing = true
 exclude_also = [
-    'raise NotImplementedError',
-    'if __name__ == .__main__.:',
-    'if TYPE_CHECKING:',
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
 ]
 
 [tool.ruff]

skore-remote-project/src/skore_remote_project/__init__.py

@@ -1,3 +1,5 @@
+"""Package that provides APIs to communicate between ``skore`` and ``skore hub``."""
+
 from rich.console import Console
 from rich.theme import Theme
 

skore-remote-project/src/skore_remote_project/item/__init__.py

@@ -1,3 +1,10 @@
+"""
+Module definition of the ``Item`` classes.
+
+``Item`` is an internal concept that is used as a DTO (Data Transfer Object) to exchange
+python objects between ``skore`` and ``skore hub``.
+"""
+
 from __future__ import annotations
 
 from contextlib import suppress
@@ -22,6 +29,7 @@
 
 
 def object_to_item(object: Any, /) -> Item:
+    """Serialize any python object into an ``Item``."""
     for cls in (
         # Lexicographically sorted, the order of execution doesn't matter
         AltairChartItem,

skore-remote-project/src/skore_remote_project/item/altair_chart_item.py

@@ -1,3 +1,10 @@
+"""
+AltairChartItem.
+
+This module defines the ``AltairChartItem`` class used to serialize instances of
+``altair`` charts, using the ``JSON`` format.
+"""
+
 from __future__ import annotations
 
 from json import loads
@@ -10,17 +17,29 @@
 
 
 class AltairChartItem(Item):
+    """Serialize instances of ``altair`` charts, using the ``JSON`` format."""
+
     def __init__(self, chart_json_str: str):
+        """
+        Initialize a ``AltairChartItem``.
+
+        Parameters
+        ----------
+        chart_json_str : str
+            The ``altair`` chart serialized in a str in the ``JSON`` format.
+        """
         self.chart_json_str = chart_json_str
 
     @property
     def __raw__(self) -> AltairChart:
+        """Get the value from the ``AltairChartItem`` instance."""
         import altair
 
         return altair.Chart.from_json(self.chart_json_str)
 
     @property
     def __representation__(self) -> dict:
+        """Get the representation of the ``AltairChartItem`` instance."""
         return {
             "representation": {
                 "media_type": "application/vnd.vega.v5+json",
@@ -29,8 +48,28 @@ def __representation__(self) -> dict:
         }
 
     @classmethod
-    def factory(cls, chart: AltairChart, /, **kwargs) -> AltairChartItem:
-        if not lazy_is_instance(chart, "altair.vegalite.v5.schema.core.TopLevelSpec"):
-            raise ItemTypeError(f"Type '{chart.__class__}' is not supported.")
+    def factory(cls, value: AltairChart, /) -> AltairChartItem:
+        """
+        Create a new ``AltairChartItem`` from an instance of ``altair`` chart.
+
+        It uses the ``JSON`` format.
+
+        Parameters
+        ----------
+        value: ``altair`` chart.
+            The value to serialize.
+
+        Returns
+        -------
+        AltairChartItem
+            A new ``AltairChartItem`` instance.
+
+        Raises
+        ------
+        ItemTypeError
+            If ``value`` is not an instance of ``altair`` chart.
+        """
+        if not lazy_is_instance(value, "altair.vegalite.v5.schema.core.TopLevelSpec"):
+            raise ItemTypeError(f"Type '{value.__class__}' is not supported.")
 
-        return cls(chart.to_json(), **kwargs)
+        return cls(value.to_json())

skore-remote-project/src/skore_remote_project/item/item.py

@@ -1,3 +1,5 @@
+"""Abstract base class for all items in the ``skore`` remote project."""
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -7,30 +9,50 @@
 
 
 def lazy_is_instance(value: Any, cls_fullname: str) -> bool:
-    """Return True if value is an instance of `cls_fullname`."""
+    """Return True if value is an instance of ``cls_fullname``."""
     return cls_fullname in {
         f"{cls.__module__}.{cls.__name__}" for cls in value.__class__.__mro__
     }
 
 
 def bytes_to_b64_str(literal: bytes) -> str:
-    """Encode the bytes-like object `literal` in a Base64 str."""
+    """Encode the bytes-like object ``literal`` in a Base64 str."""
     return b64encode(literal).decode("utf-8")
 
 
 def b64_str_to_bytes(literal: str) -> bytes:
-    """Decode the Base64 str object `literal` in a bytes."""
+    """Decode the Base64 str object ``literal`` in a bytes."""
     return b64decode(literal.encode("utf-8"))
 
 
 class ItemTypeError(Exception):
-    """"""
+    """
+    Item type exception.
+
+    Exception raised when an attempt is made to convert an object to an ``Item`` with an
+    unsupported type.
+    """
 
 
 class Item(ABC):
+    """
+    Abstract base class for all items in the ``skore`` remote project.
+
+    This class provides a common interface for all items, including the serialization of
+    the parameters needed to recreate the instance from the remote project.
+
+    ``Item`` is an internal concept that is used as a DTO (Data Transfer Object) to
+    exchange python objects between ``skore`` and ``skore hub``.
+    """
+
     @property
     def __parameters__(self) -> dict[str, dict[str, Any]]:
-        """"""
+        """
+        Get the parameters of the ``Item`` instance.
+
+        These parameters must be sufficient to recreate the instance.
+        They are persisted in the ``skore`` remote project and retrieved as needed.
+        """
         cls = self.__class__
         cls_name = cls.__name__
         cls_parameters = inspect_signature(cls).parameters
@@ -44,19 +66,20 @@ def __parameters__(self) -> dict[str, dict[str, Any]]:
 
     @property
     def __metadata__(self) -> dict[str, Any]:
+        """Get the metadata of the ``Item`` instance."""
         return dict()
 
     @property
     @abstractmethod
     def __raw__(self) -> Any:
-        """"""
+        """Get the raw python object from the ``Item`` instance."""
 
     @property
     @abstractmethod
     def __representation__(self) -> dict[str, Any]:
-        """"""
+        """Get the representation of the ``Item`` instance."""
 
     @classmethod
     @abstractmethod
     def factory(cls, *args, **kwargs) -> Item:
-        """"""
+        """Create and return a new instance of ``Item``."""

skore-remote-project/src/skore_remote_project/item/jsonable_item.py

@@ -1,3 +1,10 @@
+"""
+JSONableItem.
+
+This module defines the ``JSONableItem`` class used to serialize objects using the
+``JSON`` format.
+"""
+
 from __future__ import annotations
 
 from json import dumps, loads
@@ -7,15 +14,27 @@
 
 
 class JSONableItem(Item):
+    """Serialize objects using the ``JSON`` format."""
+
     def __init__(self, value: Any):
+        """
+        Initialize a ``JSONableItem``.
+
+        Parameters
+        ----------
+        value : Any
+            The value.
+        """
         self.value = value
 
     @property
     def __raw__(self):
+        """Get the value from the ``JSONableItem`` instance."""
         return self.value
 
     @property
     def __representation__(self) -> dict:
+        """Get the representation of the ``JSONableItem`` instance."""
         return {
             "representation": {
                 "media_type": "application/json",
@@ -24,10 +43,28 @@ def __representation__(self) -> dict:
         }
 
     @classmethod
-    def factory(cls, value: Any, /, **kwargs) -> JSONableItem:
+    def factory(cls, value: Any, /) -> JSONableItem:
+        """
+        Create a new ``JSONableItem`` from ``value`` using the ``JSON`` format.
+
+        Parameters
+        ----------
+        value: Any
+            The value to serialize.
+
+        Returns
+        -------
+        JSONableItem
+            A new ``JSONableItem`` instance.
+
+        Raises
+        ------
+        ItemTypeError
+            If ``value`` cannot be serialized using the ``JSON`` format.
+        """
         try:
             value = loads(dumps(value))
         except TypeError:
             raise ItemTypeError(f"Type '{value.__class__}' is not supported.") from None
 
-        return cls(value, **kwargs)
+        return cls(value)

skore-remote-project/src/skore_remote_project/item/pickle_item.py

@@ -1,7 +1,8 @@
-"""PickleItem.
+"""
+PickleItem.
 
-This module defines the PickleItem class, which is used to persist objects that cannot
-be otherwise.
+This module defines the ``PickleItem`` class used to serialize objects that cannot be
+otherwise, using binary protocols.
 """
 
 from __future__ import annotations
@@ -19,25 +20,30 @@
 
 
 class PickleItem(Item):
-    """
-    An item used to persist objects that cannot be otherwise, using binary protocols.
-
-    It encapsulates the object with its pickle representaton, its creation and update
-    timestamps.
-    """
+    """Serialize objects that cannot be otherwise, using binary protocols."""
 
     def __init__(self, pickle_b64_str: str):
+        """
+        Initialize a ``PickleItem``.
+
+        Parameters
+        ----------
+        pickle_b64_str : str
+            The raw bytes of the pickled object encoded in a base64 str.
+        """
         self.pickle_b64_str = pickle_b64_str
 
     @cached_property
     def __raw__(self) -> Any:
+        """Get the deserialized python object from the ``PickleItem`` instance."""
         pickle_bytes = b64_str_to_bytes(self.pickle_b64_str)
 
         with BytesIO(pickle_bytes) as stream:
             return load(stream)
 
     @property
     def __representation__(self) -> dict:
+        """Get the representation of the ``PickleItem`` instance."""
         return {
             "representation": {
                 "media_type": "text/markdown",
@@ -46,19 +52,19 @@ def __representation__(self) -> dict:
         }
 
     @classmethod
-    def factory(cls: type[T], value: Any) -> T:
+    def factory(cls: type[T], value: Any, /) -> T:
         """
-        Create a new PickleItem from ``object``.
+        Create a new ``PickleItem`` from ``value`` using binary protocols.
 
         Parameters
         ----------
         value: Any
-            The value to store.
+            The value to serialize.
 
         Returns
         -------
         PickleItem
-            A new PickleItem instance.
+            A new ``PickleItem`` instance.
         """
         with BytesIO() as stream:
             dump(value, stream)