Improve docstrings and type hints (Part 2).

.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
     rev: 'v0.0.264'
     hooks:
       - id: ruff
-        args: [--line-length=100, --select, "D,E,F,I", --ignore, "D212", --per-file-ignores, "tests/test*.py:D103"]
+        args: [--line-length=100, --select, "D,E,F,I", --ignore, "D212", --per-file-ignores, "tests/test*.py:D103,skll/data/featureset.py:E501"]
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: 'v1.2.0'
     hooks:

CONTRIBUTING.md

@@ -155,6 +155,6 @@ README file in the doc/ directory for more information.
 
 For building the documentation, you will need [sphinx](http://sphinx.pocoo.org/) as well as the readthedocs sphinx theme. To install both, just run:
 
-      $ conda install 'sphinx>=6,<7' sphinx_rtd_theme==1.2.0
+      $ conda install 'sphinx<6' sphinx_rtd_theme==1.2.0
 
 in your existing conda environment.

doc/api/data.rst

@@ -12,13 +12,58 @@
 :mod:`data.readers` Module
 --------------------------
 
-.. automodule:: skll.data.readers
+.. autoclass:: skll.data.readers.Reader
     :members:
     :show-inheritance:
 
+.. autoclass:: skll.data.readers.CSVReader
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.readers.TSVReader
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.readers.NDJReader
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.readers.DictListReader
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.readers.ARFFReader
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.readers.LibSVMReader
+    :members:
+    :show-inheritance:
+
+
 :mod:`data.writers` Module
 --------------------------
 
-.. automodule:: skll.data.writers
+.. autoclass:: skll.data.writers.Writer
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.writers.CSVWriter
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.writers.TSVWriter
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.writers.NDJWriter
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.writers.ARFFWriter
+    :members:
+    :show-inheritance:
+
+.. autoclass:: skll.data.writers.LibSVMWriter
     :members:
     :show-inheritance:

doc/api/types.rst

@@ -40,7 +40,8 @@ data.
 
 .. autoclass:: skll.types.LabelType
 
-A float, integer, or a string; this is useful for SKLL labels that can be both.
+A float, integer, or a string; this is useful for SKLL labels that can be any
+of them.
 
 .. autoclass:: skll.types.LearningCurveSizes
 

doc/requirements.txt

@@ -2,7 +2,7 @@ beautifulsoup4
 ruamel.yaml
 scikit-learn>=1.2.0,<1.3.0
 seaborn
-sphinx>=6,<7
+sphinx>=5.0,<6.0
 sphinx_rtd_theme==1.2.0
 tabulate
 typing_extensions

skll/data/dict_vectorizer.py

@@ -1,4 +1,6 @@
 """
+Enhance scikit-learn's ``DictVectorizer`` to add equality checking.
+
 This module is here because the scikit-learn version of `DictVectorizer`
 does not contain an `__eq__` method for vectorizer equality which we need
 for SKLL.
@@ -13,7 +15,7 @@
 
 class DictVectorizer(OldDictVectorizer):
     """
-    Transforms lists of feature-value mappings to vectors.
+    Transform lists of feature-value mappings to vectors.
 
     This transformer turns lists of mappings (dict-like objects) of feature
     names to feature values into Numpy arrays or scipy.sparse matrices for use
@@ -37,26 +39,26 @@ class DictVectorizer(OldDictVectorizer):
 
     Parameters
     ----------
-    dtype : callable, optional
+    dtype : Optional[Callable]
         The type of feature values. Passed to Numpy array/scipy.sparse matrix
         constructors as the dtype argument.
 
-    separator : string, optional
+    separator : Optional[str]
         Separator string used when constructing new features for one-hot
         coding.
 
-    sparse : boolean, default=True
+    sparse : bool, default=True
         Whether transform should produce scipy.sparse matrices.
 
-    sort : boolean, default=True
+    sort : bool, default=True
         Whether `feature_names_` and `vocabulary_` should be sorted when fitting.
 
     Attributes
     ----------
-    vocabulary_ : dict
+    vocabulary_ : Dict[str, Any]
         A dictionary mapping feature names to feature indices.
 
-    feature_names_ : list
+    feature_names_ : List[str]
         A list of length n_features containing the feature names (e.g., "f=ham"
         and "f=spam").
 
@@ -75,18 +77,15 @@ class DictVectorizer(OldDictVectorizer):
     >>> v.transform({'foo': 4, 'unseen_feature': 3})
     array([[ 0.,  0.,  4.]])
 
-    See also
-    --------
+    Notes
+    -----
     FeatureHasher : performs vectorization using only a hash function.
     sklearn.preprocessing.OneHotEncoder : handles nominal/categorical features
       encoded as columns of integers.
     """
 
     def __eq__(self, other):
-        """
-        Check whether two vectorizers are the same, assuming
-        we are actually comparing to a vectorizer
-        """
+        """Check whether two vectorizers are the same."""
         return (
             isinstance(other, OldDictVectorizer)
             and self.dtype == other.dtype

skll/data/featureset.py

@@ -35,12 +35,12 @@ class FeatureSet(object):
     labels : Optional[Union[List[str], numpy.ndarray], default=None
         Labels for this set.
 
-    features : Optional[Union[FeatureDictList, np.ndarray]], default=None
+    features : Optional[Union[:class:`skll.types.FeatureDictList`, :class:`numpy.ndarray`]], default=None
         The features for each instance represented as either a
-        list of dictionaries or an array-like (if ``vectorizer`` is
+        list of dictionaries or a numpy array (if ``vectorizer`` is
         also specified).
 
-    vectorizer : Union[DictVectorizer, FeatureHasher], default=None
+    vectorizer : Optional[Union[:class:`sklearn.feature_extraction.DictVectorizer`, :class:`sklearn.feature_extraction.FeatureHasher`], default=None
         Vectorizer which will be used to generate the feature matrix.
 
     Warnings
@@ -134,16 +134,16 @@ def __eq__(self, other):
 
         Parameters
         ----------
-        other : skll.data.FeatureSet
+        other : :class:`skll.data.featureset.FeatureSet`
             The other ``FeatureSet`` to check equivalence with.
 
         Returns
         -------
         bool
             ``True`` if they are the same, ``False`` otherwise.
 
-        Note
-        ----
+        Notes
+        -----
         We consider feature values to be equal if any differences are in the
         sixth decimal place or higher.
         """
@@ -193,12 +193,12 @@ def __add__(self, other: "FeatureSet") -> "FeatureSet":
 
         Parameters
         ----------
-        other : skll.data.FeatureSet
+        other : :class:`skll.data.featureset.FeatureSet`
             The other ``FeatureSet`` to add to this one.
 
         Returns
         -------
-        skll.data.FeatureSet
+        :class:`skll.data.featureset.FeatureSet
             The combined feature set.
 
         Raises
@@ -301,17 +301,17 @@ def filter(
         inverse: bool = False,
     ) -> None:
         """
-        Remove or keep features and/or examples from the ``Featureset``.
+        Remove or keep features and/or examples from the given feature set.
 
         Filtering is done in-place.
 
         Parameters
         ----------
-        ids : Optional[List[FloatOrStr]], default=None
+        ids : Optional[List[:class:`skll.types.IdType`]], default=None
             Examples to keep in the FeatureSet. If ``None``, no ID
             filtering takes place.
 
-        labels : Optional[List[LabelType]], default=None
+        labels : Optional[List[:class:`skll.types.LabelType`]], default=None
             Labels that we want to retain examples for. If ``None``,
             no label filtering takes place.
 
@@ -386,11 +386,11 @@ def filtered_iter(
 
         Parameters
         ----------
-        ids : Optional[List[IdType]], default=None
+        ids : Optional[List[:class:`skll.types.IdType`]], default=None
             Examples to keep in the ``FeatureSet``. If ``None``, no ID
             filtering takes place.
 
-        labels : Optional[List[LabelType]], default=None
+        labels : Optional[List[:class:`skll.types.LabelType`]], default=None
             Labels that we want to retain examples for. If ``None``,
             no label filtering takes place.
 
@@ -409,17 +409,18 @@ def filtered_iter(
             Instead of keeping features and/or examples in lists,
             remove them.
 
-        Yields
-        ------
-        id_ : IdType
-            The ID of the example.
+        Returns
+        -------
+        :class:`skll.types.FeatGenerator`
 
-        label_ : LabelType
-            The label of the example.
+            A generator that yields 3-tuples containing:
 
-        feat_dict : FeatureDict
-            The feature dictionary, with feature name as the key
-            and example value as the value.
+              - :class:`skll.types.IdType`  - The ID of the example.
+
+              - :class:`skll.types.LabelType` - The label of the example.
+
+              - :class:`skll.types.FeatureDict` - The feature dictionary, with
+                feature name as the key and example value as the value.
 
         Raises
         ------
@@ -468,13 +469,13 @@ def __sub__(self, other: "FeatureSet") -> "FeatureSet":
 
         Parameters
         ----------
-        other : skll.data.FeatureSet
+        other : :class:`skll.data.featureset.FeatureSet`
             The other ``FeatureSet`` containing the features that should
             be removed from this ``FeatureSet``.
 
         Returns
         -------
-        FeatureSet:
+        :class:`skll.data.featureset.FeatureSet`
             A copy of ``self`` with all features in ``other`` removed.
         """
         new_set = deepcopy(self)
@@ -537,7 +538,7 @@ def __getitem__(
 
         Returns
         -------
-        Union["FeatureSet", Tuple[IdType, LabelType, FeatureDictList]]
+        Union[:class:`skll.data.featureset.FeatureSet`, Tuple[:class:`skll.types.IdType`, :class:`skll.types.LabelType`, :class:`skll.types.FeatureDictList`]]  # noqa: E501
             If `value` is a slice, then return a new ``FeatureSet`` instance
             containing a subset of the data. If it's an index, return the
             specific example by row number.
@@ -574,7 +575,7 @@ def split(
 
         Parameters
         ----------
-        fs : skll.data.FeatureSet
+        fs : skll.data.featureset.FeatureSet
             The ``FeatureSet`` instance to split.
 
         ids_for_split1 : List[int]
@@ -594,11 +595,8 @@ def split(
 
         Returns
         -------
-        fs1 : skll.data.FeatureSet
-            The first ``FeatureSet``.
-
-        fs2 : skll.data.FeatureSet
-            The second ``FeatureSet``.
+        Tuple[:class:`skll.data.featureset.FeatureSet`, :class:`skll.data.featureset.FeatureSet`]
+            A tuple containing the two featureset instances.
         """
         # Note: an alternative way to implement this is to make copies
         # of the given FeatureSet instance and then use the `filter()`
@@ -634,7 +632,7 @@ def from_data_frame(
         vectorizer: Optional[Union[DictVectorizer, FeatureHasher]] = None,
     ) -> "FeatureSet":
         """
-        Create a ``FeatureSet`` instance from a `pandas.DataFrame`.
+        Create a ``FeatureSet`` instance from a pandas data frame.
 
         Will raise an Exception if pandas is not installed in your environment.
         The ``ids`` in the ``FeatureSet`` will be the index from the given frame.
@@ -650,12 +648,12 @@ def from_data_frame(
         labels_column : Optional[str], default=None
             The name of the column containing the labels (data to predict).
 
-        vectorizer : Optional[Union[DictVectorizer, FeatureHasher]], default=None
+        vectorizer : Optional[Union[:class:`sklearn.feature_extraction.DictVectorizer`, :class:`sklearn.feature_extraction.FeatureHasher`]], default=None
             Vectorizer which will be used to generate the feature matrix.
 
         Returns
         -------
-        feature_set : skll.data.FeatureSet
+        :class:`skll.data.featureset.FeatureSet`
             A ``FeatureSet`` instance generated from from the given data frame.
         """
         if labels_column: