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

@@ -1,28 +1,51 @@
+"""
+PandasDataFrameItem.
+
+This module defines the ``PandasDataFrameItem`` class used to serialize instances of
+``pandas.DataFrame``, using the ``JSON`` format.
+"""
+
 from __future__ import annotations
 
 from functools import cached_property
 from typing import TYPE_CHECKING, Literal
 
-from .item import Item, ItemTypeError
+from .item import Item, ItemTypeError, lazy_is_instance
 
 if TYPE_CHECKING:
     import pandas
 
 
 class PandasDataFrameItem(Item):
+    """Serialize instances of ``pandas.DataFrame``, using the ``JSON`` format."""
+
     ORIENT: Literal["split"] = "split"
 
     def __init__(self, index_json_str: str, dataframe_json_str: str):
+        """
+        Initialize a ``PandasDataFrameItem``.
+
+        Parameters
+        ----------
+        index_json_str : str
+            The index of the ``pandas.DataFrame`` serialized in a str in the ``JSON``
+            format.
+        dataframe_json_str : str
+            The ``pandas.DataFrame`` serialized in a str in the ``JSON`` format, without
+            its index.
+        """
         self.index_json_str = index_json_str
         self.dataframe_json_str = dataframe_json_str
 
     @cached_property
     def __raw__(self) -> pandas.DataFrame:
         """
-        The pandas DataFrame from the persistence.
+        Get the value from the ``PandasDataFrameItem``.
 
-        Its content can differ from the original dataframe because it has been
-        serialized using pandas' `to_json` function and not pickled, in order to be
+        Notes
+        -----
+        Its content can slightly differ from the original because it has been serialized
+        using ``pandas.to_json`` function and not pickled, in order to be
         environment-independent.
         """
         import io
@@ -42,6 +65,7 @@ def __raw__(self) -> pandas.DataFrame:
 
     @property
     def __representation__(self) -> dict:
+        """Get the representation of the ``PandasDataFrameItem`` instance."""
         return {
             "representation": {
                 "media_type": "application/vnd.dataframe",
@@ -50,28 +74,33 @@ def __representation__(self) -> dict:
         }
 
     @classmethod
-    def factory(cls, dataframe: pandas.DataFrame, /) -> PandasDataFrameItem:
+    def factory(cls, value: pandas.DataFrame, /) -> PandasDataFrameItem:
         """
-        Create a new PandasDataFrameItem instance from a pandas DataFrame.
+        Create a new ``PandasDataFrameItem`` from an instance of ``pandas.DataFrame``.
+
+        It uses the ``JSON`` format.
 
         Parameters
         ----------
-        dataframe : pd.DataFrame
-            The pandas DataFrame to store.
+        value : ``pandas.DataFrame``
+            The value to serialize.
 
         Returns
         -------
         PandasDataFrameItem
-            A new PandasDataFrameItem instance.
+            A new ``PandasDataFrameItem`` instance.
+
+        Raises
+        ------
+        ItemTypeError
+            If ``value`` is not an instance of ``pandas.DataFrame``.
 
         Notes
         -----
         The dataframe must be JSON serializable.
         """
-        import pandas
-
-        if not isinstance(dataframe, pandas.DataFrame):
-            raise ItemTypeError(f"Type '{dataframe.__class__}' is not supported.")
+        if not lazy_is_instance(value, "pandas.core.frame.DataFrame"):
+            raise ItemTypeError(f"Type '{value.__class__}' is not supported.")
 
         # Two native methods are available to serialize dataframe with multi-index,
         # while keeping the index names:
@@ -95,13 +124,13 @@ def factory(cls, dataframe: pandas.DataFrame, /) -> PandasDataFrameItem:
         #
         # None of those methods being compatible, we decide to store indexes separately.
 
-        index = dataframe.index.to_frame(index=False)
-        dataframe_without_index = dataframe.reset_index(drop=True)
+        index = value.index.to_frame(index=False)
+        dataframe_without_index = value.reset_index(drop=True)
 
         instance = cls(
             index.to_json(orient=PandasDataFrameItem.ORIENT),
             dataframe_without_index.to_json(orient=PandasDataFrameItem.ORIENT),
         )
-        instance.__raw__ = dataframe
+        instance.__raw__ = value
 
         return instance