diff --git a/README.md b/README.md index 5224a07..2d15c3a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![PyPI version](https://badge.fury.io/py/jort.svg)](https://badge.fury.io/py/jort) [![Documentation Status](https://readthedocs.org/projects/jort/badge/?version=latest)](https://jort.readthedocs.io/en/latest/?badge=latest) -* Track, profile, and notify at custom checkpoints in your coding scripts. +* Track, profile, and notify at custom blocks in your coding scripts. * Time new and existing shell commands with a convenient command line tool. * Save and view details of finished jobs with a local database. ![jort help message](jort_help.png) @@ -13,9 +13,9 @@ pip install jort ``` ## Script Timing -Use the `Tracker` to create named checkpoints throughout your code. Checkpoints need `start` and `stop` calls, and +Use the `Tracker` to create named blocks throughout your code. Blocks need `start` and `stop` calls, and multiple iterations are combined to summarize how long it takes to complete each leg. The `report` function -prints the results from all checkpoints. If `stop` is not supplied a checkpoint name, the tracker will close and calculate elapsed time from the last open checkpoint (i.e. last in, first out). +prints the results from all blocks. If `stop` is not supplied a block name, the tracker will close and calculate elapsed time from the last open block (i.e. last in, first out). ``` import jort from time import sleep @@ -39,6 +39,8 @@ my_script | 11.0 s ± 0.0 s per iteration, n = 1 sleep_1s | 1.0 s ± 0.0 s per iteration, n = 10 ``` +Alternatively, you can use single line checkpoints with `tr.checkpoint()`, which create timing blocks that close at the start of the next checkpoint. Note that you must use another `tr.stop()` call to end the final checkpoint block. + ### Function Decorators `jort` supports timing functions with decorators, via `Tracker.track`. As in the first example: ``` @@ -74,11 +76,11 @@ SMS handling is done through Twilio, which offers a [free trial tier](https://su ## Saving to Database -`jort` allows you to save details of finished jobs to a local database. To save all checkpoints to database, use the `to_db` keyword. You can also optionally group jobs under a common "session" by specifying the `session_name` keyword: +`jort` allows you to save details of finished jobs to a local database. To save all blocks to database, use the `to_db` keyword. You can also optionally group jobs under a common "session" by specifying the `session_name` keyword: ``` tr = jort.Tracker(to_db=True, session_name="my_session") ``` -If you do not want every checkpoint to be saved, you can specify manually: +If you do not want every block to be saved, you can specify manually: ``` tr.stop('my_script', to_db=True) diff --git a/docs/source/scripts.rst b/docs/source/scripts.rst index e72f0fa..5a34b64 100644 --- a/docs/source/scripts.rst +++ b/docs/source/scripts.rst @@ -5,11 +5,11 @@ Basic usage ----------- The main tracking functionality uses the :code:`Tracker` object, which is used to -create named checkpoints throughout your code. Checkpoints need :code:`start` and +create named blocks throughout your code. Blocks need :code:`start` and :code:`stop` calls, and multiple iterations are combined to summarize how long it takes -to complete each leg. The :code:`report` function prints the results from all checkpoints. -If :code:`stop` is not supplied a checkpoint name, the tracker will close and calculate -elapsed time from the last open checkpoint (i.e. last in, first out). +to complete each leg. The :code:`report` function prints the results from all blocks. +If :code:`stop` is not supplied a block name, the tracker will close and calculate +elapsed time from the last open block (i.e. last in, first out). As an example of the basic usage: @@ -37,6 +37,10 @@ The printed report appears as: my_script | 11.0 s ± 0.0 s per iteration, n = 1 sleep_1s | 1.0 s ± 0.0 s per iteration, n = 10 +Alternatively, you can use single line checkpoints with :code:`tr.checkpoint()`, which create +timing blocks that close at the start of the next checkpoint. Note that you must use another +:code:`tr.stop()` call to end the final checkpoint block. + Notifications ------------- @@ -50,7 +54,7 @@ main callbacks: jort.EmailNotification() jort.TextNotification() -Notifications are executed at the end of checkpoints using the function +Notifications are executed at the end of blocks using the function :code:`Tracker.stop` with argument :code:`callbacks`, which accepts a list of callbacks. Note: notification callbacks are not intended to be called frequently. @@ -164,14 +168,14 @@ Saving to database ------------------ `jort` allows you to save details of finished jobs to a local database. To save all -checkpoints to database, use the :code:`to_db` keyword. You can also optionally group jobs +blocks to database, use the :code:`to_db` keyword. You can also optionally group jobs under a common "session" by specifying the :code:`session_name` keyword: .. code-block:: Python tr = jort.Tracker(to_db=True, session_name="my_session") -If you do not want every checkpoint to be saved, you can specify manually: +If you do not want every block to be saved, you can specify manually: .. code-block:: Python