[python][docs] Refer to string type as str and add commas in `list …

…of ...` types (#4557)

* Reffer to string type as `str` and and commas in `list of ...` types

* update `libpath.py` too

.ci/get_workflow_status.py

@@ -22,7 +22,7 @@ def get_runs(trigger_phrase):
 
     Parameters
     ----------
-    trigger_phrase : string
+    trigger_phrase : str
         Code phrase that triggers workflow.
 
     Returns
@@ -55,7 +55,7 @@ def get_status(runs):
 
     Returns
     -------
-    status : string
+    status : str
         The most recent status of workflow.
         Can be 'success', 'failure' or 'in-progress'.
     """

examples/python-guide/advanced_example.py

@@ -147,7 +147,7 @@ def loglikelihood(preds, train_data):
 
 
 # self-defined eval metric
-# f(preds: array, train_data: Dataset) -> name: string, eval_result: float, is_higher_better: bool
+# f(preds: array, train_data: Dataset) -> name: str, eval_result: float, is_higher_better: bool
 # binary error
 # NOTE: when you do customized loss function, the default prediction value is margin
 # This may make built-in evaluation metric calculate wrong results
@@ -171,7 +171,7 @@ def binary_error(preds, train_data):
 
 
 # another self-defined eval metric
-# f(preds: array, train_data: Dataset) -> name: string, eval_result: float, is_higher_better: bool
+# f(preds: array, train_data: Dataset) -> name: str, eval_result: float, is_higher_better: bool
 # accuracy
 # NOTE: when you do customized loss function, the default prediction value is margin
 # This may make built-in evaluation metric calculate wrong results

examples/python-guide/logistic_regression.py

@@ -57,9 +57,9 @@ def experiment(objective, label_type, data):
 
     Parameters
     ----------
-    objective : string 'binary' or 'xentropy'
+    objective : {'binary', 'xentropy'}
         Objective function.
-    label_type : string 'binary' or 'probability'
+    label_type : {'binary', 'probability'}
         Type of the label.
     data : dict
         Data for training.

examples/python-guide/sklearn_example.py

@@ -41,7 +41,7 @@
 
 
 # self-defined eval metric
-# f(y_true: array, y_pred: array) -> name: string, eval_result: float, is_higher_better: bool
+# f(y_true: array, y_pred: array) -> name: str, eval_result: float, is_higher_better: bool
 # Root Mean Squared Logarithmic Error (RMSLE)
 def rmsle(y_true, y_pred):
     return 'RMSLE', np.sqrt(np.mean(np.power(np.log1p(y_pred) - np.log1p(y_true), 2))), False
@@ -56,7 +56,7 @@ def rmsle(y_true, y_pred):
 
 
 # another self-defined eval metric
-# f(y_true: array, y_pred: array) -> name: string, eval_result: float, is_higher_better: bool
+# f(y_true: array, y_pred: array) -> name: str, eval_result: float, is_higher_better: bool
 # Relative Absolute Error (RAE)
 def rae(y_true, y_pred):
     return 'RAE', np.sum(np.abs(y_pred - y_true)) / np.sum(np.abs(np.mean(y_true) - y_true)), False

helpers/check_dynamic_dependencies.py

@@ -13,7 +13,7 @@ def check_dependicies(objdump_string: str) -> None:
 
     Parameters
     ----------
-    objdump_string : string
+    objdump_string : str
         The dynamic symbol table entries of the file (result of `objdump -T` command).
     """
     GLIBC_version = re.compile(r'0{16}[ \t]+GLIBC_(\d{1,2})[.](\d{1,3})[.]?\d{,3}[ \t]+')

helpers/parameter_generator.py

@@ -139,7 +139,7 @@ def parse_check(
 
     Parameters
     ----------
-    check : string
+    check : str
         String representation of the constraint.
     reverse : bool, optional (default=False)
         Whether to reverse the sign of the constraint.
@@ -171,16 +171,16 @@ def set_one_var_from_string(
 
     Parameters
     ----------
-    name : string
+    name : str
         Name of the parameter.
-    param_type : string
+    param_type : str
         Type of the parameter.
     checks : list
         Constraints of the parameter.
 
     Returns
     -------
-    ret : string
+    ret : str
         Lines of auto config file with getting and checks of one parameter value.
     """
     ret = ""

python-package/lightgbm/dask.py

@@ -428,12 +428,12 @@ def _train(
         sum(group) = n_samples.
         For example, if you have a 100-document dataset with ``group = [10, 20, 40, 10, 10, 10]``, that means that you have 6 groups,
         where the first 10 records are in the first group, records 11-30 are in the second group, records 31-70 are in the third group, etc.
-    eval_set : list of (X, y) tuples of Dask data collections or None, optional (default=None)
+    eval_set : list of (X, y) tuples of Dask data collections, or None, optional (default=None)
         List of (X, y) tuple pairs to use as validation sets.
         Note, that not all workers may receive chunks of every eval set within ``eval_set``. When the returned
         lightgbm estimator is not trained using any chunks of a particular eval set, its corresponding component
         of evals_result_ and best_score_ will be 'not_evaluated'.
-    eval_names : list of strings or None, optional (default=None)
+    eval_names : list of str, or None, optional (default=None)
         Names of eval_set.
     eval_sample_weight : list of Dask Arrays, Dask Series or None, optional (default=None)
         Weights for each validation set in eval_set.

python-package/lightgbm/engine.py

@@ -50,9 +50,9 @@ def train(
         Data to be trained on.
     num_boost_round : int, optional (default=100)
         Number of boosting iterations.
-    valid_sets : list of Datasets or None, optional (default=None)
+    valid_sets : list of Datasets, or None, optional (default=None)
         List of data to be evaluated on during training.
-    valid_names : list of strings or None, optional (default=None)
+    valid_names : list of str, or None, optional (default=None)
         Names of ``valid_sets``.
     fobj : callable or None, optional (default=None)
         Customized objective function.
@@ -76,7 +76,7 @@ def train(
         If you want to get i-th row preds in j-th class, the access way is score[j * num_data + i]
         and you should group grad and hess in this way as well.
 
-    feval : callable, list of callable functions or None, optional (default=None)
+    feval : callable, list of callable functions, or None, optional (default=None)
         Customized evaluation function.
         Each evaluation function should accept two parameters: preds, train_data,
         and return (eval_name, eval_result, is_higher_better) or list of such tuples.
@@ -87,7 +87,7 @@ def train(
                 e.g. they are raw margin instead of probability of positive class for binary task in this case.
             train_data : Dataset
                 The training dataset.
-            eval_name : string
+            eval_name : str
                 The name of evaluation function (without whitespaces).
             eval_result : float
                 The eval result.
@@ -98,15 +98,15 @@ def train(
         If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
         To ignore the default metric corresponding to the used objective,
         set the ``metric`` parameter to the string ``"None"`` in ``params``.
-    init_model : string, pathlib.Path, Booster or None, optional (default=None)
+    init_model : str, pathlib.Path, Booster or None, optional (default=None)
         Filename of LightGBM model or Booster instance used for continue training.
-    feature_name : list of strings or 'auto', optional (default="auto")
+    feature_name : list of str, or 'auto', optional (default="auto")
         Feature names.
         If 'auto' and data is pandas DataFrame, data columns names are used.
-    categorical_feature : list of strings or int, or 'auto', optional (default="auto")
+    categorical_feature : list of str or int, or 'auto', optional (default="auto")
         Categorical features.
         If list of int, interpreted as indices.
-        If list of strings, interpreted as feature names (need to specify ``feature_name`` as well).
+        If list of str, interpreted as feature names (need to specify ``feature_name`` as well).
         If 'auto' and data is pandas DataFrame, pandas unordered categorical columns are used.
         All values in categorical features should be less than int32 max value (2147483647).
         Large values could be memory consuming. Consider using consecutive integers starting from zero.
@@ -156,7 +156,7 @@ def train(
         When your model is very large and cause the memory error,
         you can try to set this param to ``True`` to avoid the model conversion performed during the internal call of ``model_to_string``.
         You can still use _InnerPredictor as ``init_model`` for future continue training.
-    callbacks : list of callables or None, optional (default=None)
+    callbacks : list of callables, or None, optional (default=None)
         List of callback functions that are applied at each iteration.
         See Callbacks in Python API for more information.
 
@@ -447,7 +447,7 @@ def cv(params, train_set, num_boost_round=100,
         Whether to perform stratified sampling.
     shuffle : bool, optional (default=True)
         Whether to shuffle before splitting data.
-    metrics : string, list of strings or None, optional (default=None)
+    metrics : str, list of str, or None, optional (default=None)
         Evaluation metrics to be monitored while CV.
         If not None, the metric in ``params`` will be overridden.
     fobj : callable or None, optional (default=None)
@@ -472,7 +472,7 @@ def cv(params, train_set, num_boost_round=100,
         If you want to get i-th row preds in j-th class, the access way is score[j * num_data + i]
         and you should group grad and hess in this way as well.
 
-    feval : callable, list of callable functions or None, optional (default=None)
+    feval : callable, list of callable functions, or None, optional (default=None)
         Customized evaluation function.
         Each evaluation function should accept two parameters: preds, train_data,
         and return (eval_name, eval_result, is_higher_better) or list of such tuples.
@@ -483,7 +483,7 @@ def cv(params, train_set, num_boost_round=100,
                 e.g. they are raw margin instead of probability of positive class for binary task in this case.
             train_data : Dataset
                 The training dataset.
-            eval_name : string
+            eval_name : str
                 The name of evaluation function (without whitespace).
             eval_result : float
                 The eval result.
@@ -494,15 +494,15 @@ def cv(params, train_set, num_boost_round=100,
         If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
         To ignore the default metric corresponding to the used objective,
         set ``metrics`` to the string ``"None"``.
-    init_model : string, pathlib.Path, Booster or None, optional (default=None)
+    init_model : str, pathlib.Path, Booster or None, optional (default=None)
         Filename of LightGBM model or Booster instance used for continue training.
-    feature_name : list of strings or 'auto', optional (default="auto")
+    feature_name : list of str, or 'auto', optional (default="auto")
         Feature names.
         If 'auto' and data is pandas DataFrame, data columns names are used.
-    categorical_feature : list of strings or int, or 'auto', optional (default="auto")
+    categorical_feature : list of str or int, or 'auto', optional (default="auto")
         Categorical features.
         If list of int, interpreted as indices.
-        If list of strings, interpreted as feature names (need to specify ``feature_name`` as well).
+        If list of str, interpreted as feature names (need to specify ``feature_name`` as well).
         If 'auto' and data is pandas DataFrame, pandas unordered categorical columns are used.
         All values in categorical features should be less than int32 max value (2147483647).
         Large values could be memory consuming. Consider using consecutive integers starting from zero.
@@ -528,7 +528,7 @@ def cv(params, train_set, num_boost_round=100,
         Results are not affected by this parameter, and always contain std.
     seed : int, optional (default=0)
         Seed used to generate the folds (passed to numpy.random.seed).
-    callbacks : list of callables or None, optional (default=None)
+    callbacks : list of callables, or None, optional (default=None)
         List of callback functions that are applied at each iteration.
         See Callbacks in Python API for more information.
     eval_train_metric : bool, optional (default=False)

python-package/lightgbm/libpath.py

@@ -11,7 +11,7 @@ def find_lib_path() -> List[str]:
 
     Returns
     -------
-    lib_path: list of strings
+    lib_path: list of str
        List of all found library paths to LightGBM.
     """
     if environ.get('LIGHTGBM_BUILD_DOC', False):

python-package/lightgbm/plotting.py

@@ -56,16 +56,16 @@ def plot_importance(
         Tuple passed to ``ax.xlim()``.
     ylim : tuple of 2 elements or None, optional (default=None)
         Tuple passed to ``ax.ylim()``.
-    title : string or None, optional (default="Feature importance")
+    title : str or None, optional (default="Feature importance")
         Axes title.
         If None, title is disabled.
-    xlabel : string or None, optional (default="Feature importance")
+    xlabel : str or None, optional (default="Feature importance")
         X-axis title label.
         If None, title is disabled.
-    ylabel : string or None, optional (default="Features")
+    ylabel : str or None, optional (default="Features")
         Y-axis title label.
         If None, title is disabled.
-    importance_type : string, optional (default="split")
+    importance_type : str, optional (default="split")
         How the importance is calculated.
         If "split", result contains numbers of times the feature is used in a model.
         If "gain", result contains total gains of splits which use the feature.
@@ -173,14 +173,14 @@ def plot_split_value_histogram(
     ----------
     booster : Booster or LGBMModel
         Booster or LGBMModel instance of which feature split value histogram should be plotted.
-    feature : int or string
+    feature : int or str
         The feature name or index the histogram is plotted for.
         If int, interpreted as index.
-        If string, interpreted as name.
-    bins : int, string or None, optional (default=None)
+        If str, interpreted as name.
+    bins : int, str or None, optional (default=None)
         The maximum number of bins.
         If None, the number of bins equals number of unique split values.
-        If string, it should be one from the list of the supported values by ``numpy.histogram()`` function.
+        If str, it should be one from the list of the supported values by ``numpy.histogram()`` function.
     ax : matplotlib.axes.Axes or None, optional (default=None)
         Target axes instance.
         If None, new figure and axes will be created.
@@ -190,17 +190,17 @@ def plot_split_value_histogram(
         Tuple passed to ``ax.xlim()``.
     ylim : tuple of 2 elements or None, optional (default=None)
         Tuple passed to ``ax.ylim()``.
-    title : string or None, optional (default="Split value histogram for feature with @index/name@ @feature@")
+    title : str or None, optional (default="Split value histogram for feature with @index/name@ @feature@")
         Axes title.
         If None, title is disabled.
         @feature@ placeholder can be used, and it will be replaced with the value of ``feature`` parameter.
         @index/name@ placeholder can be used,
         and it will be replaced with ``index`` word in case of ``int`` type ``feature`` parameter
-        or ``name`` word in case of ``string`` type ``feature`` parameter.
-    xlabel : string or None, optional (default="Feature split value")
+        or ``name`` word in case of ``str`` type ``feature`` parameter.
+    xlabel : str or None, optional (default="Feature split value")
         X-axis title label.
         If None, title is disabled.
-    ylabel : string or None, optional (default="Count")
+    ylabel : str or None, optional (default="Count")
         Y-axis title label.
         If None, title is disabled.
     figsize : tuple of 2 elements or None, optional (default=None)
@@ -288,11 +288,11 @@ def plot_metric(
     ----------
     booster : dict or LGBMModel
         Dictionary returned from ``lightgbm.train()`` or LGBMModel instance.
-    metric : string or None, optional (default=None)
+    metric : str or None, optional (default=None)
         The metric name to plot.
         Only one metric supported because different metrics have various scales.
         If None, first metric picked from dictionary (according to hashcode).
-    dataset_names : list of strings or None, optional (default=None)
+    dataset_names : list of str, or None, optional (default=None)
         List of the dataset names which are used to calculate metric to plot.
         If None, all datasets are used.
     ax : matplotlib.axes.Axes or None, optional (default=None)
@@ -302,13 +302,13 @@ def plot_metric(
         Tuple passed to ``ax.xlim()``.
     ylim : tuple of 2 elements or None, optional (default=None)
         Tuple passed to ``ax.ylim()``.
-    title : string or None, optional (default="Metric during training")
+    title : str or None, optional (default="Metric during training")
         Axes title.
         If None, title is disabled.
-    xlabel : string or None, optional (default="Iterations")
+    xlabel : str or None, optional (default="Iterations")
         X-axis title label.
         If None, title is disabled.
-    ylabel : string or None, optional (default="auto")
+    ylabel : str or None, optional (default="auto")
         Y-axis title label.
         If 'auto', metric name is used.
         If None, title is disabled.
@@ -536,7 +536,7 @@ def create_tree_digraph(
         Booster or LGBMModel instance to be converted.
     tree_index : int, optional (default=0)
         The index of a target tree to convert.
-    show_info : list of strings or None, optional (default=None)
+    show_info : list of str, or None, optional (default=None)
         What information should be shown in nodes.
 
             - ``'split_gain'`` : gain from adding this split to the model
@@ -548,7 +548,7 @@ def create_tree_digraph(
             - ``'data_percentage'`` : percentage of training data that fall into this node
     precision : int or None, optional (default=3)
         Used to restrict the display of floating point values to a certain precision.
-    orientation : string, optional (default='horizontal')
+    orientation : str, optional (default='horizontal')
         Orientation of the tree.
         Can be 'horizontal' or 'vertical'.
     **kwargs
@@ -629,7 +629,7 @@ def plot_tree(
         Figure size.
     dpi : int or None, optional (default=None)
         Resolution of the figure.
-    show_info : list of strings or None, optional (default=None)
+    show_info : list of str, or None, optional (default=None)
         What information should be shown in nodes.
 
             - ``'split_gain'`` : gain from adding this split to the model
@@ -641,7 +641,7 @@ def plot_tree(
             - ``'data_percentage'`` : percentage of training data that fall into this node
     precision : int or None, optional (default=3)
         Used to restrict the display of floating point values to a certain precision.
-    orientation : string, optional (default='horizontal')
+    orientation : str, optional (default='horizontal')
         Orientation of the tree.
         Can be 'horizontal' or 'vertical'.
     **kwargs