update docstrings

Author: LiamConnors

packages/python/plotly/_plotly_utils/colors/__init__.py

@@ -426,12 +426,17 @@ def convert_colors_to_same_type(
     be coverted to the selected colortype. If colors is None, then there is an
     option to return portion of the DEFAULT_PLOTLY_COLORS
 
-    :param (str|tuple|list) colors: either a plotly scale name, an rgb or hex
-        color, a color tuple or a list/tuple of colors
-    :param (list) scale: see docs for validate_scale_values()
-
-    :rtype (tuple) (colors_list, scale) if scale is None in the function call,
-        then scale will remain None in the returned tuple
+    Parameters
+    ----------
+    colors : str or tuple or list
+        Either a plotly scale name, an rgb or hex color, a color tuple, or a list/tuple of colors.
+    scale : list
+        See docs for validate_scale_values().
+
+    Returns
+    -------
+    tuple
+        (colors_list, scale) if scale is None in the function call, then scale will remain None in the returned tuple.
     """
     colors_list = []
 
@@ -496,7 +501,10 @@ def convert_dict_colors_to_same_type(colors_dict, colortype="rgb"):
     """
     Converts a colors in a dictionary of colors to the specified color type
 
-    :param (dict) colors_dict: a dictionary whose values are single colors
+    Parameters
+    ----------
+    colors_dict : dict
+        A dictionary whose values are single colors.
     """
     for key in colors_dict:
         if "#" in colors_dict[key]:
@@ -522,14 +530,17 @@ def convert_dict_colors_to_same_type(colors_dict, colortype="rgb"):
 
 def validate_scale_values(scale):
     """
-    Validates scale values from a colorscale
+    Validates scale values from a colorscale.
 
-    :param (list) scale: a strictly increasing list of floats that begins
-        with 0 and ends with 1. Its usage derives from a colorscale which is
-        a list of two-lists (a list with two elements) of the form
-        [value, color] which are used to determine how interpolation weighting
-        works between the colors in the colorscale. Therefore scale is just
-        the extraction of these values from the two-lists in order
+    Parameters
+    ----------
+    scale : list of float
+        A strictly increasing list of floats that begins with 0 and ends with 1.
+        Its usage derives from a colorscale which is a list of two-element lists
+        of the form [value, color]. These values are used to determine how
+        interpolation weighting works between the colors in the colorscale.
+        Therefore, `scale` is just the extraction of these values from the
+        two-element lists in order.
     """
     if len(scale) < 2:
         raise exceptions.PlotlyError(
@@ -565,16 +576,23 @@ def validate_colorscale(colorscale):
 
 def make_colorscale(colors, scale=None):
     """
-    Makes a colorscale from a list of colors and a scale
+    Makes a colorscale from a list of colors and a scale.
 
     Takes a list of colors and scales and constructs a colorscale based
-    on the colors in sequential order. If 'scale' is left empty, a linear-
-    interpolated colorscale will be generated. If 'scale' is a specificed
-    list, it must be the same legnth as colors and must contain all floats
-    For documentation regarding to the form of the output, see
-    https://plot.ly/python/reference/#mesh3d-colorscale
-
-    :param (list) colors: a list of single colors
+    on the colors in sequential order. If `scale` is left empty, a linear-
+    interpolated colorscale will be generated. If `scale` is a specified
+    list, it must be the same length as `colors` and must contain all floats.
+    For documentation regarding the form of the output, see
+    https://plot.ly/python/reference/#mesh3d-colorscale.
+
+    Parameters
+    ----------
+    colors : list
+        A list of single colors.
+    scale : list of float, optional
+        A list of scale values. If provided, it must be the same length as
+        `colors` and must contain all floats. If not provided, a linear-
+        interpolated colorscale will be generated.
     """
     colorscale = []
 
@@ -646,16 +664,28 @@ def unconvert_from_RGB_255(colors):
 
 def convert_to_RGB_255(colors):
     """
-    Multiplies each element of a triplet by 255
+    Multiplies each element of a triplet by 255.
 
     Each coordinate of the color tuple is rounded to the nearest float and
     then is turned into an integer. If a number is of the form x.5, then
     if x is odd, the number rounds up to (x+1). Otherwise, it rounds down
     to just x. This is the way rounding works in Python 3 and in current
-    statistical analysis to avoid rounding bias
+    statistical analysis to avoid rounding bias.
+
+    Parameters
+    ----------
+    colors : list of float
+        A list of three float values representing the RGB components of a color.
 
-    :param (list) rgb_components: grabs the three R, G and B values to be
-        returned as computed in the function
+    Returns
+    -------
+    tuple of int
+        A tuple of three integers representing the RGB components.
+
+    Examples
+    --------
+    >>> convert_to_RGB_255([0.1, 0.2, 0.3])
+    (26, 51, 76)
     """
     rgb_components = []
 
@@ -752,11 +782,22 @@ def unlabel_rgb(colors):
 
 def hex_to_rgb(value):
     """
-    Calculates rgb values from a hex color code.
+    Calculates RGB values from a hex color code.
+
+    Parameters
+    ----------
+    value : str
+        Hex color string.
 
-    :param (string) value: Hex color string
+    Returns
+    -------
+    tuple of int
+        A tuple of three integers representing the RGB components.
 
-    :rtype (tuple) (r_value, g_value, b_value): tuple of rgb values
+    Examples
+    --------
+    >>> hex_to_rgb("#ff5733")
+    (255, 87, 51)
     """
     value = value.lstrip("#")
     hex_total_length = len(value)

packages/python/plotly/plotly/data/__init__.py

@@ -24,19 +24,19 @@ def gapminder(
 
     Parameters
     ----------
-    datetimes: bool
+    datetimes : bool
         Whether or not 'year' column will converted to datetime type
 
-    centroids: bool
+    centroids : bool
         If True, ['centroid_lat', 'centroid_lon'] columns are added
 
-    year: int | None
+    year : int | None
         If provided, the dataset will be filtered for that year
 
-    pretty_names: bool
+    pretty_names : bool
         If True, prettifies the column names
 
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
@@ -91,10 +91,10 @@ def tips(pretty_names=False, return_type="pandas"):
 
     Parameters
     ----------
-    pretty_names: bool
+    pretty_names : bool
         If True, prettifies the column names
 
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
@@ -128,7 +128,7 @@ def iris(return_type="pandas"):
 
     Parameters
     ----------
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
@@ -146,7 +146,7 @@ def wind(return_type="pandas"):
 
     Parameters
     ----------
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
@@ -165,7 +165,7 @@ def election(return_type="pandas"):
 
     Parameters
     ----------
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
@@ -183,9 +183,9 @@ def election_geojson():
 
     Returns
     -------
-        A GeoJSON-formatted `dict` with 58 polygon or multi-polygon features whose `id`
-        is an electoral district numerical ID and whose `district` property is the ID and
-        district name.
+    A GeoJSON-formatted `dict` with 58 polygon or multi-polygon features whose `id`
+    is an electoral district numerical ID and whose `district` property is the ID and
+    district name.
     """
     import gzip
     import json
@@ -209,13 +209,13 @@ def carshare(return_type="pandas"):
 
     Parameters
     ----------
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
     -------
     Dataframe of `return_type` type
-        Dataframe` with 249 rows and the following columns:
+        Dataframe with 249 rows and the following columns:
         `['centroid_lat', 'centroid_lon', 'car_hours', 'peak_hour']`.
     """
     return _get_dataset("carshare", return_type=return_type)
@@ -227,14 +227,14 @@ def stocks(indexed=False, datetimes=False, return_type="pandas"):
 
     Parameters
     ----------
-    indexed: bool
+    indexed : bool
         Whether or not the 'date' column is used as the index and the column index
         is named 'company'. Applicable only if `return_type='pandas'`
 
-    datetimes: bool
+    datetimes : bool
         Whether or not the 'date' column will be of datetime type
 
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
@@ -272,11 +272,11 @@ def experiment(indexed=False, return_type="pandas"):
 
     Parameters
     ----------
-    indexed: bool
+    indexed : bool
         If True, then the index is named "participant".
         Applicable only if `return_type='pandas'`
 
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
@@ -308,11 +308,11 @@ def medals_wide(indexed=False, return_type="pandas"):
 
     Parameters
     ----------
-    indexed: bool
+    indexed : bool
         Whether or not the 'nation' column is used as the index and the column index
         is named 'medal'. Applicable only if `return_type='pandas'`
 
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns
@@ -345,11 +345,11 @@ def medals_long(indexed=False, return_type="pandas"):
 
     Parameters
     ----------
-    indexed: bool
+    indexed : bool
         Whether or not the 'nation' column is used as the index.
         Applicable only if `return_type='pandas'`
 
-    return_type: {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
+    return_type : {'pandas', 'polars', 'pyarrow', 'modin', 'cudf'}
         Type of the resulting dataframe
 
     Returns