From 8888e47e8de917f08af717c9de7ae4c049d6107b Mon Sep 17 00:00:00 2001 From: Brandon Butler Date: Fri, 27 Oct 2023 10:57:19 -0400 Subject: [PATCH] doc: Correct TrackOperations docstring. --- flow/hooks/track_operations.py | 43 ++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/flow/hooks/track_operations.py b/flow/hooks/track_operations.py index 9822b20bf..875b164ad 100644 --- a/flow/hooks/track_operations.py +++ b/flow/hooks/track_operations.py @@ -17,21 +17,27 @@ class TrackOperations: """:class:`~.TrackOperations` tracks information about the execution of operations to a logfile. - This hooks can provides information on the start, successful completion, and/or - erroring of one or more operations in a `flow.FlowProject` instance. The logs are stored in a - file given by the parameter ``fn_logfile``. This file will be appended to if it already exists. - The default formating for the log provides the [time, job id, log level, and log message]. - - Note - ---- - All tracking is performed at the INFO level. To ensure outputs are captured in log files, - use the `--debug` flag when running or submitting jobs, or specify - `submit_options=--debug` in your directives (example shown below). + This hooks can provides information on the start, successful completion, and/or erroring of + one or more operations in a `flow.FlowProject` instance. The logs are stored either in the + job document or the file given by ``log_filename``. If stored in the job document, it uses + the key ``execution_history``. The file or document list will be appended to if it already + exists. + + The hooks stores metadata regarding the execution of the operation and the state of the + project at the time of execution, error, and/or completion. The data will also include + information about the git status if the project is detected as a git repo and + ``GitPython`` is installed in the environment. + + Warning + ------- + This class will error on construction if GitPython is not available and ``strict_git`` is set + to ``True``. If ``strict_git`` is ``True`` trying to execute an operation with uncommitted + changes. Examples -------- The following example will install :class:`~.TrackOperations` at the operation level. - Where the log will be stored in a file name `foo.log` in the job workspace. + Where the log will be stored in the job document. .. code-block:: python from flow import FlowProject @@ -42,15 +48,11 @@ class Project(FlowProject): pass - def install_operation_track_hook(operation_name, project_cls): - track = TrackOperation(f"{operation_name}.log") - return lambda op: track.install_operation_hooks(op, project_cls) + track = TrackOperation() - @install_operation_log_hook("foo", Project) - @Project.operation(directives={ - "submit_options": "--debug" # Always submit operation foo with the --debug flag - }) + @track.install_operation_hooks(Project) + @Project.operation def foo(job): pass @@ -60,7 +62,7 @@ def foo(job): .. code-block:: python from flow import FlowProject - from flow.hooks import TrackOperations # Import build + from flow.hooks import TrackOperations class Project(FlowProject): @@ -80,7 +82,8 @@ class Project(FlowProject): document in a key labeled ``f"{operation_name}"`` under the ``"execution_history"`` key. Defaults to ``None``. strict_git: bool, optional - Whether to fail if ``GitPython`` cannot be imported. Defaults to ``True``. + Whether to fail if ``GitPython`` cannot be imported or if there are uncommitted changes + to the project's git repo. Defaults to ``True``. """ def __init__(self, log_filename=None, strict_git=True):