update docstrings

Author: LiamConnors

packages/python/plotly/plotly/figure_factory/utils.py

@@ -27,10 +27,13 @@ def is_sequence(obj):
 
 def validate_index(index_vals):
     """
-    Validates if a list contains all numbers or all strings
+    Validates if a list contains all numbers or all strings.
+
+    Raises
+    ------
+    PlotlyError
+        If there are any two items in the list whose types differ.
 
-    :raises: (PlotlyError) If there are any two items in the list whose
-        types differ
     """
     from numbers import Number
 
@@ -55,10 +58,13 @@ def validate_index(index_vals):
 
 def validate_dataframe(array):
     """
-    Validates all strings or numbers in each dataframe column
+    Validates all strings or numbers in each dataframe column.
+
+    Raises
+    ------
+    PlotlyError
+        If there are any two items in any list whose types differ.
 
-    :raises: (PlotlyError) If there are any two items in any list whose
-        types differ
     """
     from numbers import Number
 
@@ -85,7 +91,10 @@ def validate_equal_length(*args):
     """
     Validates that data lists or ndarrays are the same length.
 
-    :raises: (PlotlyError) If any data lists are not the same length.
+    Raises
+    ------
+    PlotlyError
+        If any data lists or ndarrays are not the same length.
     """
     length = len(args[0])
     if any(len(lst) != length for lst in args):
@@ -98,9 +107,15 @@ def validate_positive_scalars(**kwargs):
     """
     Validates that all values given in key/val pairs are positive.
 
-    Accepts kwargs to improve Exception messages.
+    Parameters
+    ----------
+    **kwargs : dict
+        Key/value pairs to validate.
 
-    :raises: (PlotlyError) If any value is < 0 or raises.
+    Raises
+    ------
+    PlotlyError
+        If any value is less than 0.
     """
     for key, val in kwargs.items():
         try:
@@ -112,11 +127,23 @@ def validate_positive_scalars(**kwargs):
 
 def flatten(array):
     """
-    Uses list comprehension to flatten array
+    Uses list comprehension to flatten an array.
+
+    Parameters
+    ----------
+    array : iterable
+        An iterable to flatten.
+
+    Returns
+    -------
+    list
+        The flattened list.
+
+    Raises
+    ------
+    PlotlyError
+        If the iterable is not nested.
 
-    :param (array): An iterable to flatten
-    :raises (PlotlyError): If iterable is not nested.
-    :rtype (list): The flattened list.
     """
     try:
         return [item for sublist in array for item in sublist]
@@ -130,16 +157,36 @@ def flatten(array):
 
 def endpts_to_intervals(endpts):
     """
-    Returns a list of intervals for categorical colormaps
+    Returns a list of intervals for categorical colormaps.
 
     Accepts a list or tuple of sequentially increasing numbers and returns
     a list representation of the mathematical intervals with these numbers
-    as endpoints. For example, [1, 6] returns [[-inf, 1], [1, 6], [6, inf]]
-
-    :raises: (PlotlyError) If input is not a list or tuple
-    :raises: (PlotlyError) If the input contains a string
-    :raises: (PlotlyError) If any number does not increase after the
-        previous one in the sequence
+    as endpoints. For example, [1, 6] returns [[-inf, 1], [1, 6], [6, inf]].
+
+    Parameters
+    ----------
+    values : list or tuple
+        A list or tuple of sequentially increasing numbers.
+
+    Returns
+    -------
+    list
+        A list of intervals for categorical colormaps.
+
+    Raises
+    ------
+    PlotlyError
+        If input is not a list or tuple.
+    PlotlyError
+        If the input contains a string.
+    PlotlyError
+        If any number does not increase after the previous one in the sequence.
+
+    Examples
+    --------
+    >>> intervals = create_intervals([1, 6])
+    >>> print(intervals)
+    [[-inf, 1], [1, 6], [6, inf]]
     """
     length = len(endpts)
     # Check if endpts is a list or tuple
@@ -194,18 +241,29 @@ def annotation_dict_for_label(
     """
     Returns annotation dict for label of n labels of a 1xn or nx1 subplot.
 
-    :param (str) text: the text for a label.
-    :param (int) lane: the label number for text. From 1 to n inclusive.
-    :param (int) num_of_lanes: the number 'n' of rows or columns in subplot.
-    :param (float) subplot_spacing: the value for the horizontal_spacing and
-        vertical_spacing params in your plotly.tools.make_subplots() call.
-    :param (str) row_col: choose whether labels are placed along rows or
-        columns.
-    :param (bool) flipped: flips text by 90 degrees. Text is printed
-        horizontally if set to True and row_col='row', or if False and
-        row_col='col'.
-    :param (bool) right_side: only applicable if row_col is set to 'row'.
-    :param (str) text_color: color of the text.
+    Parameters
+    ----------
+    text : str
+        The text for a label.
+    lane : int
+        The label number for text. From 1 to n inclusive.
+    num_of_lanes : int
+        The number 'n' of rows or columns in subplot.
+    subplot_spacing : float
+        The value for the horizontal_spacing and vertical_spacing params in your plotly.tools.make_subplots() call.
+    row_col : str
+        Choose whether labels are placed along rows or columns.
+    flipped : bool
+        Flips text by 90 degrees. Text is printed horizontally if set to True and row_col='row', or if False and row_col='col'.
+    right_side : bool
+        Only applicable if row_col is set to 'row'.
+    text_color : str
+        Color of the text.
+
+    Returns
+    -------
+    dict
+        Annotation dictionary for the label.
     """
     l = (1 - (num_of_lanes - 1) * subplot_spacing) / (num_of_lanes)
     if not flipped:
@@ -254,7 +312,7 @@ def annotation_dict_for_label(
 
 def list_of_options(iterable, conj="and", period=True):
     """
-    Returns an English listing of objects seperated by commas ','
+    Returns an English listing of objects separated by commas ','.
 
     For example, ['foo', 'bar', 'baz'] becomes 'foo, bar and baz'
     if the conjunction 'and' is selected.