record: Docstrings and examples

Author: mhash1m

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Docstrings and doctestable examples to `record.py`.
 ### Fixed
 - New model tutorial mentions file paths that should be edited.
 

dffml/record.py

@@ -217,7 +217,7 @@ def features(self, subset: List[str] = []) -> Dict[str, Any]:
 
         Parameters
         ----------
-        subset : list
+        subset : list[str]
             The subset of features that will be returned.
 
         Returns
@@ -245,14 +245,44 @@ def features(self, subset: List[str] = []) -> Dict[str, Any]:
     def feature(self, name: str) -> Any:
         """
         Returns a feature of the record.
+
+        Parameters
+        ----------
+        name : str
+            The name of the feature that will be returned.
+
+        Returns
+        -------
+        any
+            feature.
+
+        Examples
+        --------
+        >>> example = Record("example", data=dict(features=dict(dead="beef")))
+        >>> print(example.feature("dead"))
+        beef
         """
         if name not in self.data.features:
             raise NoSuchFeature(name)
         return self.data.features[name]
 
     def predicted(self, target: str, value: Any, confidence: float):
         """
-        Set the prediction for this record
+        Set the prediction for this record.
+
+        Parameters
+        ----------
+        target : str
+            The target you want to store the prediction at.
+        value : Any
+            The prediction.
+
+        Examples
+        --------
+        >>> example = Record("example", data=dict(features=dict(dead="beef")))
+        >>> example.predicted("target_name", "feed", 1.00)
+        >>> print(example.prediction("target_name"))
+        {'confidence': 1.0, 'value': 'feed'}
         """
         self.data.prediction[target] = RecordPrediction(
             value=value, confidence=float(confidence)
@@ -261,11 +291,49 @@ def predicted(self, target: str, value: Any, confidence: float):
 
     def prediction(self, target: str) -> RecordPrediction:
         """
-        Get the prediction for this record
+        Get the prediction for this record.
+
+        Parameters
+        ----------
+        target : str
+            The name of the feature that will be returned.
+
+        Returns
+        -------
+        RecordPrediction
+            The prediction of the target specified.
+
+        Examples
+        --------
+        >>> example = Record("example", data=dict(features=dict(dead="beef")))
+        >>> example.predicted("target_name", "feed", 1.00)
+        >>> print(example.prediction("target_name"))
+        {'confidence': 1.0, 'value': 'feed'}
         """
         return self.data.prediction[target]
 
     def predictions(self, subset: List[str] = []) -> Dict[str, Any]:
+        """
+        Get the predictions for the subset of record.
+
+        Parameters
+        ----------
+        subset : list[str]
+            The list of subset of the record that predictions are returned for.
+
+        Returns
+        -------
+        dict
+            The prediction of the specified subset.
+
+        Examples
+        --------
+        >>> example = Record("example", data=dict(features=dict(dead="beef")))
+        >>> example.predicted("target_name1", "feed", 1.00)
+        >>> example.predicted("target_name2", "deed", 0.97)
+        >>> print(example.predictions(["target_name1", "target_name2"]))
+        {'target_name1': {'confidence': 1.0, 'value': 'feed'}, 'target_name2': {'confidence': 0.97, 'value': 'deed'}}
+        """
         if not subset:
             return self.data.prediction
         for name in subset: