refactor(docs, ruff): Add pydocstyle rules (#3493)

altair/_magics.py

@@ -1,6 +1,4 @@
-"""
-Magic functions for rendering vega-lite specifications
-"""
+"""Magic functions for rendering vega-lite specifications."""
 
 __all__ = ["vegalite"]
 
@@ -36,7 +34,7 @@
 
 
 def _prepare_data(data, data_transformers):
-    """Convert input data to data for use within schema"""
+    """Convert input data to data for use within schema."""
     if data is None or isinstance(data, dict):
         return data
     elif _is_pandas_dataframe(data):
@@ -74,7 +72,8 @@ def _get_variable(name):
 @magic_arguments.argument("-v", "--version", dest="version", default="v5")
 @magic_arguments.argument("-j", "--json", dest="json", action="store_true")
 def vegalite(line, cell):
-    """Cell magic for displaying vega-lite visualizations in CoLab.
+    """
+    Cell magic for displaying vega-lite visualizations in CoLab.
 
     %%vegalite [dataframe] [--json] [--version='v5']
 

altair/expr/__init__.py

@@ -914,6 +914,7 @@ def upper(cls, *args) -> FunctionExpression:
     def merge(cls, *args) -> FunctionExpression:
         """
         Merges the input objects *object1*, *object2*, etc into a new output object.
+
         Inputs are visited in sequential order, such that key values from later arguments can overwrite those from earlier arguments.
 
         Example: `merge({a:1, b:2}, {a:3}) -> {a:3, b:2}`.

altair/expr/core.py

@@ -4,7 +4,7 @@
 
 
 class DatumType:
-    """An object to assist in building Vega-Lite Expressions"""
+    """An object to assist in building Vega-Lite Expressions."""
 
     def __repr__(self) -> str:
         return "datum"
@@ -18,15 +18,15 @@ def __getitem__(self, attr) -> GetItemExpression:
         return GetItemExpression("datum", attr)
 
     def __call__(self, datum, **kwargs) -> dict[str, Any]:
-        """Specify a datum for use in an encoding"""
+        """Specify a datum for use in an encoding."""
         return dict(datum=datum, **kwargs)
 
 
 datum = DatumType()
 
 
 def _js_repr(val) -> str:
-    """Return a javascript-safe string representation of val"""
+    """Return a javascript-safe string representation of val."""
     if val is True:
         return "true"
     elif val is False:
@@ -163,7 +163,8 @@ def __invert__(self):
 
 
 class Expression(OperatorMixin, SchemaBase):
-    """Expression
+    """
+    Expression.
 
     Base object for enabling build-up of Javascript expressions using
     a Python syntax. Calling ``repr(obj)`` will return a Javascript

altair/jupyter/jupyter_chart.py

@@ -17,9 +17,7 @@
 
 
 class Params(traitlets.HasTraits):
-    """
-    Traitlet class storing a JupyterChart's params
-    """
+    """Traitlet class storing a JupyterChart's params."""
 
     def __init__(self, trait_values):
         super().__init__()
@@ -47,9 +45,7 @@ def __repr__(self):
 
 
 class Selections(traitlets.HasTraits):
-    """
-    Traitlet class storing a JupyterChart's selections
-    """
+    """Traitlet class storing a JupyterChart's selections."""
 
     def __init__(self, trait_values):
         super().__init__()
@@ -78,10 +74,7 @@ def __repr__(self):
         return f"Selections({self.trait_values()})"
 
     def _make_read_only(self, change):
-        """
-        Work around to make traits read-only, but still allow us to change
-        them internally
-        """
+        """Work around to make traits read-only, but still allow us to change them internally."""
         if change["name"] in self.traits() and change["old"] != change["new"]:
             self._set_value(change["name"], change["old"])
         msg = (
@@ -137,7 +130,7 @@ class JupyterChart(anywidget.AnyWidget):
     @classmethod
     def enable_offline(cls, offline: bool = True):
         """
-        Configure JupyterChart's offline behavior
+        Configure JupyterChart's offline behavior.
 
         Parameters
         ----------
@@ -192,8 +185,7 @@ def __init__(
         **kwargs: Any,
     ):
         """
-        Jupyter Widget for displaying and updating Altair Charts, and
-        retrieving selection and parameter values
+        Jupyter Widget for displaying and updating Altair Charts, and retrieving selection and parameter values.
 
         Parameters
         ----------
@@ -225,10 +217,7 @@ def __init__(
 
     @traitlets.observe("chart")
     def _on_change_chart(self, change):
-        """
-        Internal callback function that updates the JupyterChart's internal
-        state when the wrapped Chart instance changes
-        """
+        """Updates the JupyterChart's internal state when the wrapped Chart instance changes."""
         new_chart = change.new
         selection_watches = []
         selection_types = {}
@@ -360,11 +349,7 @@ def _on_change_params(self, change):
 
     @traitlets.observe("_vl_selections")
     def _on_change_selections(self, change):
-        """
-        Internal callback function that updates the JupyterChart's public
-        selections traitlet in response to changes that the JavaScript logic
-        makes to the internal _selections traitlet.
-        """
+        """Updates the JupyterChart's public selections traitlet in response to changes that the JavaScript logic makes to the internal _selections traitlet."""
         for selection_name, selection_dict in change.new.items():
             value = selection_dict["value"]
             store = selection_dict["store"]
@@ -390,7 +375,7 @@ def _on_change_selections(self, change):
 
 def collect_transform_params(chart: TopLevelSpec) -> set[str]:
     """
-    Collect the names of params that are defined by transforms
+    Collect the names of params that are defined by transforms.
 
     Parameters
     ----------

altair/utils/_dfi_types.py

@@ -55,7 +55,8 @@ def dtype(self) -> tuple[Any, int, str, str]:
                         Data Interface format.
         Endianness : current only native endianness (``=``) is supported
 
-        Notes:
+        Notes
+        -----
             - Kind specifiers are aligned with DLPack where possible (hence the
               jump to 20, leave enough room for future extension)
             - Masks must be specified as boolean with either bit width 1 (for bit
@@ -83,7 +84,8 @@ def dtype(self) -> tuple[Any, int, str, str]:
     @property
     def describe_categorical(self) -> Any:
         """
-        If the dtype is categorical, there are two options:
+        If the dtype is categorical, there are two options.
+
         - There are only values in the data buffer.
         - There is a separate non-categorical Column encoding categorical values.
 
@@ -104,8 +106,7 @@ def describe_categorical(self) -> Any:
 
 class DataFrame(Protocol):
     """
-    A data frame class, with only the methods required by the interchange
-    protocol defined.
+    A data frame class, with only the methods required by the interchange protocol defined.
 
     A "data frame" represents an ordered collection of named columns.
     A column's "name" must be a unique string.
@@ -134,14 +135,10 @@ def __dataframe__(
         """
 
     def column_names(self) -> Iterable[str]:
-        """
-        Return an iterator yielding the column names.
-        """
+        """Return an iterator yielding the column names."""
 
     def get_column_by_name(self, name: str) -> Column:
-        """
-        Return the column whose name is the indicated name.
-        """
+        """Return the column whose name is the indicated name."""
 
     def get_chunks(self, n_chunks: int | None = None) -> Iterable[DataFrame]:
         """