From 1927e6578c794383c51fa89439a9ff38ab6dee27 Mon Sep 17 00:00:00 2001 From: pollfly <75068813+pollfly@users.noreply.github.com> Date: Sun, 7 May 2023 15:50:49 +0300 Subject: [PATCH] Edit docstrings (#1011) --- clearml/backend_interface/task/task.py | 10 +++--- clearml/logger.py | 40 ++++++++++------------- clearml/model.py | 44 ++++++++++---------------- clearml/task.py | 26 ++++++--------- 4 files changed, 48 insertions(+), 72 deletions(-) diff --git a/clearml/backend_interface/task/task.py b/clearml/backend_interface/task/task.py index cf1ba8fc..07a6a385 100644 --- a/clearml/backend_interface/task/task.py +++ b/clearml/backend_interface/task/task.py @@ -684,7 +684,7 @@ class Task(IdObjectBase, AccessMixin, SetupUploadMixin): This is in contrast to :meth:`Task.close`, which does the first two steps, but does not terminate any Python process. Let's say that process A created the task and process B has a handle on the task, e.g., with :meth:`Task.get_task`. - Then, if we call :meth:`Task.mark_completed`, the process A is terminated, but process B is not. + Then, if we call :meth:`Task.mark_completed`, process A is terminated, but process B is not. However, if :meth:`Task.mark_completed` was called from the same process in which the task was created, then - effectively - the process terminates itself. @@ -1135,7 +1135,7 @@ class Task(IdObjectBase, AccessMixin, SetupUploadMixin): Notice the parameter dict is flat: i.e. {'Args/param': 'value'} will set the argument "param" in section "Args" to "value" - :param args: Positional arguments, which are one or more dictionary or (key, value) iterable. They are + :param args: Positional arguments, which are one or more dictionaries or (key, value) iterable. They are merged into a single key-value pair dictionary. :param kwargs: Key-value pairs, merged into the parameters dictionary created from ``args``. """ @@ -1147,7 +1147,7 @@ class Task(IdObjectBase, AccessMixin, SetupUploadMixin): Set the parameters for a Task. This method sets a complete group of key-value parameter pairs, but does not support parameter descriptions (the input is a dictionary of key-value pairs). - :param args: Positional arguments, which are one or more dictionary or (key, value) iterable. They are + :param args: Positional arguments, which are one or more dictionaries or (key, value) iterable. They are merged into a single key-value pair dictionary. :param kwargs: Key-value pairs, merged into the parameters dictionary created from ``args``. """ @@ -1362,7 +1362,7 @@ class Task(IdObjectBase, AccessMixin, SetupUploadMixin): Notice the parameter dict is flat: i.e. {'Args/param': 'value'} will set the argument "param" in section "Args" to "value" - :param args: Positional arguments, which are one or more dictionary or (key, value) iterable. They are + :param args: Positional arguments, which are one or more dictionaries or (key, value) iterable. They are merged into a single key-value pair dictionary. :param kwargs: Key-value pairs, merged into the parameters dictionary created from ``args``. """ @@ -1551,7 +1551,7 @@ class Task(IdObjectBase, AccessMixin, SetupUploadMixin): :param list artifact_names: list of artifact names :param bool raise_on_errors: if True, do not suppress connectivity related exceptions :param bool delete_from_storage: If True, try to delete the actual - file from the external storage (e.g. S3, GS, Azure, File Server etc.) + file from the external storage (e.g. S3, GS, Azure, File Server etc.) :return: True if successful """ diff --git a/clearml/logger.py b/clearml/logger.py index dbbaf277..2d6a2d6a 100644 --- a/clearml/logger.py +++ b/clearml/logger.py @@ -132,12 +132,11 @@ class Logger(object): :param str msg: The text to log. :param int level: The log level from the Python ``logging`` package. The default value is ``logging.INFO``. - :param bool print_console: In addition to the log, print to the console - + :param bool print_console: In addition to the log, print to the console. The values are: - - ``True`` - Print to the console. (default) - - ``False`` - Do not print to the console. + - ``True`` - Print to the console. (default) + - ``False`` - Do not print to the console. """ force_send = not print_console and self._parse_level(level) >= logging.WARNING return self._console(msg, level, not print_console, force_send=force_send, *args, **_) @@ -420,19 +419,17 @@ class Logger(object): :param str xaxis: The x-axis title. (Optional) :param str yaxis: The y-axis title. (Optional) :param str mode: The type of line plot. - The values are: - - ``lines`` (default) - - ``markers`` - - ``lines+markers`` - - :param bool reverse_xaxis: Reverse the x-axis + - ``lines`` (default) + - ``markers`` + - ``lines+markers`` + :param bool reverse_xaxis: Reverse the x-axis. The values are: - - ``True`` - The x-axis is high to low (reversed). - - ``False`` - The x-axis is low to high (not reversed). (default) + - ``True`` - The x-axis is high to low (reversed). + - ``False`` - The x-axis is low to high (not reversed). (default) :param str comment: A comment displayed with the plot, underneath the title. :param dict extra_layout: optional dictionary for layout configuration, passed directly to plotly @@ -566,19 +563,14 @@ class Logger(object): :param str zaxis: The z-axis title. (Optional) :param list(str) labels: Labels per point in the data assigned to the ``scatter`` parameter. The labels must be in the same order as the data. - :param str mode: The type of scatter plot. The values are: + :param str mode: The type of scatter plot. The values are: ``lines``, ``markers``, ``lines+markers``. + For example: - - ``lines`` - - ``markers`` - - ``lines+markers`` + .. code-block:: py - For example: - - .. code-block:: py - - scatter3d = np.random.randint(10, size=(10, 3)) - logger.report_scatter3d(title="example_scatter_3d", series="series_xyz", iteration=1, scatter=scatter3d, - xaxis="title x", yaxis="title y", zaxis="title z") + scatter3d = np.random.randint(10, size=(10, 3)) + logger.report_scatter3d(title="example_scatter_3d", series="series_xyz", iteration=1, scatter=scatter3d, + xaxis="title x", yaxis="title y", zaxis="title z") :param bool fill: Fill the area under the curve. The values are: @@ -1258,7 +1250,7 @@ class Logger(object): def matplotlib_force_report_non_interactive(cls, force): # type: (bool) -> None """ - If True, all matplotlib are always converted to non interactive static plots (images), appearing in under + If True, all matplotlib are always converted to non-interactive static plots (images), appearing in under the Plots section. If False (default), matplotlib figures are converted into interactive web UI plotly figures, in case figure conversion fails, it defaults to non-interactive plots. diff --git a/clearml/model.py b/clearml/model.py index a62b08b6..fa51b80a 100644 --- a/clearml/model.py +++ b/clearml/model.py @@ -678,20 +678,16 @@ class BaseModel(object): :param int iteration: The reported iteration / step. :param str xaxis: The x-axis title. (Optional) :param str yaxis: The y-axis title. (Optional) - :param str mode: The type of line plot. + :param str mode: The type of line plot. The values are: - The values are: + - ``lines`` (default) + - ``markers`` + - ``lines+markers`` - - ``lines`` (default) - - ``markers`` - - ``lines+markers`` + :param bool reverse_xaxis: Reverse the x-axis. The values are: - :param bool reverse_xaxis: Reverse the x-axis - - The values are: - - - ``True`` - The x-axis is high to low (reversed). - - ``False`` - The x-axis is low to high (not reversed). (default) + - ``True`` - The x-axis is high to low (reversed). + - ``False`` - The x-axis is low to high (not reversed). (default) :param str comment: A comment displayed with the plot, underneath the title. :param dict extra_layout: optional dictionary for layout configuration, passed directly to plotly @@ -819,19 +815,15 @@ class BaseModel(object): :param str zaxis: The z-axis title. (Optional) :param list(str) labels: Labels per point in the data assigned to the ``scatter`` parameter. The labels must be in the same order as the data. - :param str mode: The type of scatter plot. The values are: + :param str mode: The type of scatter plot. The values are: ``lines``, ``markers``, ``lines+markers``. - - ``lines`` - - ``markers`` - - ``lines+markers`` + For example: - For example: + .. code-block:: py - .. code-block:: py - - scatter3d = np.random.randint(10, size=(10, 3)) - model.report_scatter3d(title="example_scatter_3d", series="series_xyz", iteration=1, scatter=scatter3d, - xaxis="title x", yaxis="title y", zaxis="title z") + scatter3d = np.random.randint(10, size=(10, 3)) + model.report_scatter3d(title="example_scatter_3d", series="series_xyz", iteration=1, scatter=scatter3d, + xaxis="title x", yaxis="title y", zaxis="title z") :param bool fill: Fill the area under the curve. The values are: @@ -1550,13 +1542,11 @@ class InputModel(Model): :param str weights_url: A valid URL for the initial weights file. If the **ClearML Web-App** (backend) already stores the metadata of a model with the same URL, that existing model is returned - and ClearML ignores all other parameters. + and ClearML ignores all other parameters. For example: - For example: - - - ``https://domain.com/file.bin`` - - ``s3://bucket/file.bin`` - - ``file:///home/user/file.bin`` + - ``https://domain.com/file.bin`` + - ``s3://bucket/file.bin`` + - ``file:///home/user/file.bin`` :param str config_text: The configuration as a string. This is usually the content of a configuration dictionary file. Specify ``config_text`` or ``config_dict``, but not both. diff --git a/clearml/task.py b/clearml/task.py index 4a73b657..aead25ef 100644 --- a/clearml/task.py +++ b/clearml/task.py @@ -1173,9 +1173,8 @@ class Task(_Task): :param str comment: A comment / description for the new cloned Task. (Optional) :param str parent: The ID of the parent Task of the new Task. - - If ``parent`` is not specified, then ``parent`` is set to ``source_task.parent``. - - If ``parent`` is not specified and ``source_task.parent`` is not available, then - ``parent`` set to ``source_task``. + - If ``parent`` is not specified, then ``parent`` is set to ``source_task.parent``. + - If ``parent`` is not specified and ``source_task.parent`` is not available, then ``parent`` set to ``source_task``. :param str project: The ID of the project in which to create the new Task. If ``None``, the new task inherits the original Task's project. (Optional) @@ -1456,9 +1455,9 @@ class Task(_Task): :param configuration: The configuration. This is usually the configuration used in the model training process. Specify one of the following: - - A dictionary/list - A dictionary containing the configuration. ClearML stores the configuration in + - A dictionary/list - A dictionary containing the configuration. ClearML stores the configuration in the **ClearML Server** (backend), in a HOCON format (JSON-like format) which is editable. - - A ``pathlib2.Path`` string - A path to the configuration file. ClearML stores the content of the file. + - A ``pathlib2.Path`` string - A path to the configuration file. ClearML stores the content of the file. A local path must be relative path. When executing a Task remotely in a worker, the contents brought from the **ClearML Server** (backend) overwrites the contents of the file. @@ -2506,20 +2505,15 @@ class Task(_Task): :param queue_name: The queue name used for enqueueing the task. If ``None``, this call exits the process without enqueuing the task. :param clone: Clone the Task and execute the newly cloned Task - The values are: - - ``True`` - A cloned copy of the Task will be created, and enqueued, instead of this Task. - - ``False`` - The Task will be enqueued. + - ``True`` - A cloned copy of the Task will be created, and enqueued, instead of this Task. + - ``False`` - The Task will be enqueued. - :param exit_process: The function call will leave the calling process at the end + :param exit_process: The function call will leave the calling process at the end. - - ``True`` - Exit the process (exit(0)). - - ``False`` - Do not exit the process. - - .. warning:: - - If ``clone==False``, then ``exit_process`` must be ``True``. + - ``True`` - Exit the process (exit(0)). Note: if ``clone==False``, then ``exit_process`` must be ``True``. + - ``False`` - Do not exit the process. :return Task: return the task object of the newly generated remotely executing task """ @@ -2589,7 +2583,7 @@ class Task(_Task): """ Create a new task, and call ``func`` with the specified kwargs. One can think of this call as remote forking, where the newly created instance is the new Task - calling the specified func with the appropriate kwargs and leave once the func terminates. + calling the specified func with the appropriate kwargs and leaving once the func terminates. Notice that a remote executed function cannot create another child remote executed function. .. note::