improved and fixed docstrings for properties in About, Extensions, Result, Score, TypedList

Author: Chaim-Leib Halbert

tincan/about.py

@@ -18,6 +18,15 @@
 
 
 class About(SerializableBase):
+
+    """Stores info about this installation of `tincan`.
+
+    :param version: The versions supported. This attribute is required.
+    :type version: list of unicode
+    :param extensions: Custom user data. This attribute is optional.
+    :type extensions: :class:`tincan.extensions.Extensions`
+    """
+
     _props_req = [
         'version',
     ]
@@ -31,9 +40,11 @@ class About(SerializableBase):
     def version(self):
         """Version for About
 
-        :setter: Sets the version
-        :setter type: list | tuple | str | unicode
-        :rtype: unicode | list
+        :setter: Sets the version. If None is provided, defaults to
+        `[tincan.version.Version.latest]`. If a string is provided,
+        makes a 1-element list containing the string.
+        :setter type: list | tuple | str | unicode | None
+        :rtype: list
 
         """
         return self._version
@@ -45,6 +56,7 @@ def check_version(v):
             if invalid.
 
             :param v: the version string to check
+            :type v: list of str or unicode | tuple of str or unicode
             :raises ValueError
             """
             if v in Version.supported:
@@ -92,9 +104,10 @@ def check_version(v):
     def extensions(self):
         """Extensions for About
 
-        :setter: Tries to convert to Extensions
-        :setter type: :mod:`tincan.extensions`
-        :rtype: :mod:`tincan.extensions`
+        :setter: Tries to convert to Extensions. If None is provided,
+        sets to an empty `tincan.extensions.Extensions` dict.
+        :setter type: :class:`tincan.extensions.Extensions` | dict | None
+        :rtype: :class:`tincan.extensions.Extensions`
 
         """
         return self._extensions

tincan/extensions.py

@@ -13,13 +13,14 @@
 #    limitations under the License.
 
 from tincan.serializable_base import SerializableBase
-from tincan.version import Version
 
 
 class Extensions(dict, SerializableBase):
     """
     Contains domain-specific custom data.
 
+    Can be created from a dict, another Extensions, or from args and kwargs.
+
     Use this like a regular Python dict.
     """
     def __init__(self, *args, **kwargs):

tincan/result.py

@@ -26,6 +26,8 @@ class Result(SerializableBase):
 
     Can be created from a dict, another Result, or from kwargs.
 
+    All these attributes are optional and settable to None:
+
     :param score: Contains the score and its scaling information
     :type score: Score
     :param success: Whether successful
@@ -37,7 +39,7 @@ class Result(SerializableBase):
     :param response: HTTPResponse data
     :type response: unicode
     :param extensions: Custom user data
-    :type extensions: Extensions
+    :type extensions: :class:`tincan.extensions.Extensions`
     """
 
     _props = [
@@ -53,9 +55,10 @@ class Result(SerializableBase):
     def score(self):
         """Score for Result
 
-        :setter: Tries to convert to Score
-        :setter type: :mod:`tincan.score`
-        :rtype: :mod:`tincan.score`
+        :setter: Tries to convert to :class:`tincan.score.Score`. If
+        None is provided, this signifies the absence of this data.
+        :setter type: :class:`tincan.score.Score` | dict | None
+        :rtype: :class:`tincan.score.Score` | None
 
         """
         return self._score
@@ -85,9 +88,10 @@ def score(self):
     def success(self):
         """Success for Result
 
-        :setter: Tries to convert to bool
-        :setter type: bool
-        :rtype: bool
+        :setter: Tries to convert to bool. If None is provided,
+        this signifies the absence of this data.
+        :setter type: bool | None
+        :rtype: bool | None
 
         """
         return self._success
@@ -105,9 +109,10 @@ def success(self):
     def completion(self):
         """Completion for Result
 
-        :setter: Tries to convert to bool
-        :setter type: bool
-		:rtype: bool
+        :setter: Tries to convert to bool. If None is provided,
+        this signifies the absence of this data.
+        :setter type: bool | None
+        :rtype: bool | None
 
         """
         return self._completion
@@ -125,7 +130,8 @@ def completion(self):
     def duration(self):
         """Duration for Result
 
-        :setter: Tries to convert to :class:`datetime.timedelta`.
+        :setter: Tries to convert to :class:`datetime.timedelta`. If
+        None is provided, this signifies the absence of this data.
 
         Strings will be parsed as ISO 8601 durations.
 
@@ -135,7 +141,7 @@ def duration(self):
         If a `dict` is provided, does `datetime.timedelta(**value)`.
 
         :setter type: :class:`datetime.timedelta` | unicode | str | int | float | dict | None
-        :rtype: :class:`datetime.timedelta`
+        :rtype: :class:`datetime.timedelta` | None
         """
         return self._duration
 
@@ -167,9 +173,10 @@ def duration(self):
     def response(self):
         """Response for Result
 
-        :setter: Tries to convert to unicode
-        :setter type: unicode
-        :rtype: unicode
+        :setter: Tries to convert to unicode. If None is provided,
+        this signifies the absence of this data.
+        :setter type: unicode | str | None
+        :rtype: unicode | None
 
         """
         return self._response
@@ -197,9 +204,10 @@ def response(self):
     def extensions(self):
         """Extensions for Result
 
-        :setter: Tries to convert to Extensions
-        :setter type: :mod:`tincan.extensions`
-        :rtype: :mod:`tincan.extensions`
+        :setter: Tries to convert to Extensions. If None is provided,
+        this signifies the absence of this data.
+        :setter type: :class:`tincan.extensions.Extensions` | dict | None
+        :rtype: :class:`tincan.extensions.Extensions` | None
 
         """
         return self._extensions

tincan/score.py

@@ -17,6 +17,22 @@
 
 class Score(SerializableBase):
 
+    """Stores the scoring data for an activity.
+
+    Can be created from a dict, another Score, or from kwargs.
+
+    All these attributes are optional and settable to None:
+
+    :param scaled: Scaled score
+    :type scaled: float
+    :param raw: Raw score
+    :type raw: float
+    :param min: Minimum score possible
+    :type min: float
+    :param max: Maximum score possible
+    :type max: float
+    """
+
     _props = [
         'scaled',
         'raw',
@@ -28,9 +44,10 @@ class Score(SerializableBase):
     def scaled(self):
         """Scaled for Score
 
-        :setter: Tries to convert to float
-        :setter type: float
-        :rtype: float
+        :setter: Tries to convert to float. If None is provided,
+        this signifies the absence of this data.
+        :setter type: float | int | None
+        :rtype: float | None
 
         """
         return self._scaled
@@ -60,9 +77,10 @@ def scaled(self):
     def raw(self):
         """Raw for Score
 
-        :setter: Tries to convert to float
-        :setter type: float
-        :rtype: float
+        :setter: Tries to convert to float. If None is provided,
+        this signifies the absence of this data.
+        :setter type: float | int | None
+        :rtype: float | None
 
         """
         return self._raw
@@ -92,9 +110,10 @@ def raw(self):
     def min(self):
         """Min for Score
 
-        :setter: Tries to convert to float
-        :setter type: float
-        :rtype: float
+        :setter: Tries to convert to float. If None is provided,
+        this signifies the absence of this data.
+        :setter type: float | int | None
+        :rtype: float | None
 
         """
         return self._min
@@ -123,9 +142,10 @@ def min(self):
     def max(self):
         """Max for Score
 
-        :setter: Tries to convert to float
-        :setter type: float
-        :rtype: float
+        :setter: Tries to convert to float. If None is provided,
+        this signifies the absence of this data.
+        :setter type: float | int | None
+        :rtype: float | None
 
         """
         return self._max

tincan/typed_list.py

@@ -44,9 +44,10 @@ def _check_cls(self):
             raise ValueError("_cls has not been set")
 
     def _make_cls(self, value):
-        """If value is instance of self._cls, converts and returns
+        """If value is not instance of self._cls, converts and returns
         it. Otherwise, returns value.
 
+        :param value: the thing to make a self._cls from
         :rtype self._cls
         """
         if isinstance(value, self._cls):