[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/numpy_array_item.py

@@ -1,3 +1,10 @@
+"""
+NumpyArrayItem.
+
+This module defines the ``NumpyArrayItem`` class used to serialize instances of
+``numpy.Array``, using binary protocols.
+"""
+
 from __future__ import annotations
 
 from functools import cached_property
@@ -9,18 +16,31 @@
     ItemTypeError,
     b64_str_to_bytes,
     bytes_to_b64_str,
+    lazy_is_instance,
 )
 
 if TYPE_CHECKING:
     import numpy
 
 
 class NumpyArrayItem(Item):
+    """Serialize instances of ``numpy.Array``, using binary protocols."""
+
     def __init__(self, array_b64_str: str):
+        """
+        Initialize a ``NumpyArrayItem``.
+
+        Parameters
+        ----------
+        array_b64_str : str
+            The raw bytes of the array in the ``numpy`` serialization format, encoded in
+            base64 string.
+        """
         self.array_b64_str = array_b64_str
 
     @cached_property
     def __raw__(self) -> numpy.ndarray:
+        """Get the value from the ``NumpyArrayItem``."""
         import numpy
 
         array_bytes = b64_str_to_bytes(self.array_b64_str)
@@ -30,6 +50,7 @@ def __raw__(self) -> numpy.ndarray:
 
     @property
     def __representation__(self) -> dict:
+        """Get the representation of the ``NumpyArrayItem`` instance."""
         return {
             "representation": {
                 "media_type": "application/json",
@@ -38,19 +59,37 @@ def __representation__(self) -> dict:
         }
 
     @classmethod
-    def factory(cls, array: numpy.ndarray, /, **kwargs) -> NumpyArrayItem:
-        import numpy
+    def factory(cls, value: numpy.ndarray, /) -> NumpyArrayItem:
+        """
+        Create a new ``NumpyArrayItem`` from ``value`` using binary protocols.
 
-        if not isinstance(array, numpy.ndarray):
-            raise ItemTypeError(f"Type '{array.__class__}' is not supported.")
+        Parameters
+        ----------
+        value: Any
+            The value to serialize.
+
+        Returns
+        -------
+        NumpyArrayItem
+            A new ``NumpyArrayItem`` instance.
+
+        Raises
+        ------
+        ItemTypeError
+            If ``value`` is not an instance of ``numpy.Array``.
+        """
+        if not lazy_is_instance(value, "numpy.ndarray"):
+            raise ItemTypeError(f"Type '{value.__class__}' is not supported.")
+
+        import numpy
 
         with BytesIO() as stream:
-            numpy.save(stream, array, allow_pickle=False)
+            numpy.save(stream, value, allow_pickle=False)
 
             array_bytes = stream.getvalue()
             array_b64_str = bytes_to_b64_str(array_bytes)
 
-        instance = cls(array_b64_str, **kwargs)
-        instance.__raw__ = array
+        instance = cls(array_b64_str)
+        instance.__raw__ = value
 
         return instance