Merge pull request #3 from Sun-Lab-NBB/2.0.0

2.0.0

README.md

@@ -5,8 +5,8 @@ time data.
 
 ![PyPI - Version](https://img.shields.io/pypi/v/ataraxis-time)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ataraxis-time)
-[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://tinyurl.com/uvbadge)](https://github.com/astral-sh/uv)
+[![Ruff](https://tinyurl.com/ruffbadge)](https://github.com/astral-sh/ruff)
 ![type-checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue?style=flat-square&logo=python)
 ![PyPI - License](https://img.shields.io/pypi/l/ataraxis-time)
 ![PyPI - Status](https://img.shields.io/pypi/status/ataraxis-time)
@@ -60,8 +60,8 @@ ___
 
 ### Source
 
-**_Note. Building from source may require additional build-components to be available to compile the C++ portion of the
-library. It is highly advised to use the option to install from PIP or CONDA instead._**
+**_Note. Building from source may require additional build components to be available to compile the C++ portion of the
+library. It is highly recommended to install from PIP or CONDA instead._**
 
 1. Download this repository to your local machine using your preferred method, such as git-cloning. Optionally, use one
    of the stable releases that include precompiled binary wheels in addition to source code.
@@ -87,48 +87,97 @@ ___
 ## Usage
 
 ### Precision Timer
+The timer API is intentionally minimalistic to simplify class adoption and usage. It is heavily inspired by the
+[elapsedMillis](https://github.com/pfeerick/elapsedMillis/blob/master/elapsedMillis.h) library for 
+Teensy and Arduino microcontrollers.
+
+All timer class functionality is realized through a fast c-extension wrapped into the PrecisionTimer class. Primarily,
+the functionality comes through 3 class methods: reset(), elapsed (property) and delay():
+
+#### Initialization and Configuration
+The timer takes the 'precision' to use as the only initialization argument. All instances of the timer class are 
+thread- and process-safe and do not interfere with each other. The precision of the timer can be adjusted after 
+initialization if needed, which is more efficient than re-initializing the timer.
 
-This is a minimal example of how to use the precision timer class from this library:
 ```
-# First, import the timer class.
+from ataraxis_time import PrecisionTimer
+
+# Currently, the timer supports 4 'precisions: 'ns' (nanoseconds), 'us' (microseconds), 'ms' (milliseconds), and 
+# 's' seconds.'
+timer = PrecisionTimer('us')
+
+# However, the precision can be adjusted after initialization if needed:
+timer.set_precision('ms')  # Switches timer precision to milliseconds
+```
+
+#### Interval Timing
+Interval timing functionality is realized through two methods: reset() and elapsed. This functionality of the class
+is identical to using perf_counter_ns() from 'time' library. The main difference from the 'time' library is that the 
+class uses a slightly different interface (reset / elapsed) and automatically converts the output to the desired 
+precision.
+```
 from ataraxis_time import PrecisionTimer
 import time as tm
 
-# Then, instantiate the timer class using the desired precision. Supported precisions are: 'ns' (nanoseconds),
-# 'us' (microseconds), 'ms' (milliseconds), and 's' seconds.
 timer = PrecisionTimer('us')
 
 # Interval timing example
 timer.reset()  # Resets (re-bases) the timer
 tm.sleep(1)  # Simulates work (for 1 second)
 print(f'Work time: {timer.elapsed} us')  # This returns the 'work' duration using the precision units of the timer.
+```
 
-print()  # Separates interval example from delay examples
+#### Delay
+Delay timing functionality is the primary advantage of this class over the standard 'time' library. At the time of 
+writing, the 'time' library can provide nanosecond-precise delays via a 'busywait' perf_counter_ns() loop that does not
+release the GIL. Alternatively, it can release the GIL via sleep() method, that is, however, only accurate up to 
+millisecond precision (up to 16ms on some Windows platforms). PrecisionTimer class can delay for time-periods up to 
+nanosecond precision (on some systems) while releasing or holding the GIL (depends on the method used):
+```
+from ataraxis_time import PrecisionTimer
+import time as tm
 
-# Delay example:
+timer = PrecisionTimer('us')
+
+# GIL-releasing microsecond delays.
 for i in range(10):
     print(f'us delay iteration: {i}')
     timer.delay_block(500)  # Delays for 500 microseconds, does not release the GIL
 
-print()  # Separates the us loop from ms loop
-
+# Non-GIL-releasing milliseconds delay (uses sleep for millisecond delays to optimize resource usage).
 timer.set_precision('ms')  # Switches timer precision to milliseconds
 for i in range(10):
     print(f'ms delay iteration: {i}')
     timer.delay_noblock(500)  # Delays for 500 milliseconds, releases the GIL
 ```
 
-### Date & Time Helper Methods
+### Date & Time Helper Functions
+These are minor helper methods that are not directly part of the timer class showcased above. Since these methods are
+not intended for realtime applications, they are implemented using pure python (slow), rather than fast 
+c-extension method.
 
-This is a minimal example of how to use helper-functions from this library:
+#### Convert Time
+This helper method performs time-conversions, rounding to 3 Significant Figures for the chosen precision, and works 
+with time-scales from nanoseconds to days.
 ```
-# Import the desired function(s) from the time_helpers sub-package.
-from ataraxis_time.time_helpers import convert_time, get_timestamp
+from ataraxis_time.time_helpers import convert_time
 
-# Time converter example. The function can convert single inputs and lists / numpy arrays.
+# The method can convert single inputs...
 initial_time = 12
 time_in_seconds = convert_time(time=initial_time, from_units='d', to_units='s')  # Returns 1036800.0
 
+# And Python iterables and numpy arrays
+initial_time = np.array([12, 12, 12])
+# Returns a numpy aray with all values set to 1036800.0 (uses float_64 format)
+time_in_seconds = convert_time(time=initial_time, from_units='d', to_units='s')
+```
+
+#### Get Timestamp
+This method is used to get timestamps accurate up to seconds. This is typically helpful when time-stamping file 
+names and slow events.
+```
+from ataraxis_time.time_helpers import get_timestamp
+
 # Obtains the current date and time and uses it to generate a timestamp that can be used in file-names (for example).
 dt = get_timestamp(time_separator='-')  # Returns 2024-06-18-00-06-25 (yyyy-mm-dd-hh-mm-ss)
 ```
@@ -194,6 +243,9 @@ to see the list of available tasks.
 **Note!** All commits to this project have to successfully complete the ```tox``` task before being pushed to GitHub. 
 To minimize the runtime task for this task, use ```tox --parallel```.
 
+For more information, you can also see the 'Usage' section of the 
+[ataraxis-automation project](https://github.com/Sun-Lab-NBB/ataraxis-automation) documentation.
+
 ### Environments
 
 All environments used during development are exported as .yml files and as spec.txt files to the [envs](envs) folder.
@@ -253,3 +305,13 @@ ___
   development of this library.
 - My [NBB](https://nbb.cornell.edu/) Cohort for answering 'random questions' pertaining to the desired library
   functionality.
+- [click](https://github.com/pallets/click/) project for providing the low-level command-line-interface functionality 
+  for this project.
+- [tqdm](https://github.com/tqdm/tqdm) project for providing an easy-to-use progress bar functionality used in our
+  benchmark script.
+- [numpy](https://github.com/numpy/numpy) project for providing low-level functionality for our benchmark script.
+- [elapsedMillis](https://github.com/pfeerick/elapsedMillis/blob/master/elapsedMillis.h) project for providing the 
+  inspiration for the API and the functionality of the timer class.
+- [nanobind](https://github.com/wjakob/nanobind) project for providing a fast and convenient way of binding c++ code to
+  python projects.
+- The creators of all other projects used in our development automation pipelines [see pyproject.toml](pyproject.toml).

envs/axt_dev_lin.yml

@@ -12,9 +12,9 @@ dependencies:
   - black=24.4.2=py312h7900ff3_0
   - breathe=4.15.0=pyh9f0ad1d_0
   - brotli-python=1.1.0=py312h30efb56_1
-  - bzip2=1.0.8=hd590300_5
+  - bzip2=1.0.8=h4bc722e_7
   - ca-certificates=2024.7.4=hbcca054_0
-  - cachetools=5.3.3=pyhd8ed1ab_0
+  - cachetools=5.4.0=pyhd8ed1ab_0
   - certifi=2024.7.4=pyhd8ed1ab_0
   - cffi=1.16.0=py312hf06ca03_0
   - chardet=5.2.0=py312h7900ff3_1
@@ -23,12 +23,12 @@ dependencies:
   - cmarkgfm=0.8.0=py312h98912ed_3
   - colorama=0.4.6=pyhd8ed1ab_0
   - conda-souschef=2.2.3=pyhd8ed1ab_0
-  - coverage=7.5.4=py312h9a8786e_0
-  - cryptography=42.0.8=py312hbcc2302_0
+  - coverage=7.6.0=py312h41a817b_0
+  - cryptography=43.0.0=py312h8aaac84_0
   - dbus=1.13.6=h5008d03_3
   - distlib=0.3.8=pyhd8ed1ab_0
   - docutils=0.20.1=py312h7900ff3_3
-  - exceptiongroup=1.2.0=pyhd8ed1ab_2
+  - exceptiongroup=1.2.2=pyhd8ed1ab_0
   - execnet=2.1.1=pyhd8ed1ab_0
   - expat=2.6.2=h59595ed_0
   - filelock=3.15.4=pyhd8ed1ab_0
@@ -80,7 +80,7 @@ dependencies:
   - ncurses=6.5=h59595ed_0
   - nh3=0.2.18=py312hf008fa9_0
   - numpy=2.0.0=py312h22e1c76_0
-  - openssl=3.3.1=h4ab18f5_1
+  - openssl=3.3.1=h4bc722e_2
   - packaging=24.1=pyhd8ed1ab_0
   - pathspec=0.12.1=pyhd8ed1ab_0
   - pcre2=10.44=h0f59acf_0
@@ -94,7 +94,7 @@ dependencies:
   - pygments=2.18.0=pyhd8ed1ab_0
   - pyproject-api=1.7.1=pyhd8ed1ab_0
   - pysocks=1.7.1=pyha2e5f31_6
-  - pytest=8.2.2=pyhd8ed1ab_0
+  - pytest=8.3.1=pyhd8ed1ab_0
   - pytest-cov=5.0.0=pyhd8ed1ab_0
   - pytest-xdist=3.6.1=pyhd8ed1ab_0
   - python=3.12.4=h194c7f8_0_cpython
@@ -111,32 +111,33 @@ dependencies:
   - ruamel.yaml=0.18.6=py312h98912ed_0
   - ruamel.yaml.clib=0.2.8=py312h98912ed_0
   - ruamel.yaml.jinja2=0.2.4=py_1
-  - ruff=0.5.1=py312hbe4c86d_0
+  - ruff=0.5.2=py312hbe4c86d_0
   - scikit-build-core=0.9.8=pyh4af843d_0
   - secretstorage=3.3.3=py312h7900ff3_2
   - semver=3.0.2=pyhd8ed1ab_0
-  - setuptools=70.1.1=pyhd8ed1ab_0
+  - setuptools=71.0.4=pyhd8ed1ab_0
   - six=1.16.0=pyh6c4a22f_0
   - snowballstemmer=2.2.0=pyhd8ed1ab_0
   - soupsieve=2.5=pyhd8ed1ab_1
-  - sphinx=7.3.7=pyhd8ed1ab_0
-  - sphinx-autodoc-typehints=2.2.2=pyhd8ed1ab_0
+  - sphinx=7.4.7=pyhd8ed1ab_0
+  - sphinx-autodoc-typehints=2.2.3=pyhd8ed1ab_0
   - sphinx-click=6.0.0=pyhd8ed1ab_0
   - sphinx-rtd-theme=2.0.0=hd8ed1ab_0
   - sphinx_rtd_theme=2.0.0=pyha770c72_0
   - sphinxcontrib-applehelp=1.0.8=pyhd8ed1ab_0
   - sphinxcontrib-devhelp=1.0.6=pyhd8ed1ab_0
-  - sphinxcontrib-htmlhelp=2.0.5=pyhd8ed1ab_0
+  - sphinxcontrib-htmlhelp=2.0.6=pyhd8ed1ab_0
   - sphinxcontrib-jquery=4.1=pyhd8ed1ab_0
   - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_0
-  - sphinxcontrib-qthelp=1.0.7=pyhd8ed1ab_0
+  - sphinxcontrib-qthelp=1.0.8=pyhd8ed1ab_0
   - sphinxcontrib-serializinghtml=1.1.10=pyhd8ed1ab_0
   - stdlib-list=0.10.0=pyhd8ed1ab_0
   - tk=8.6.13=noxft_h4845f30_101
   - toml=0.10.2=pyhd8ed1ab_0
   - tomli=2.0.1=pyhd8ed1ab_0
   - tomli-w=1.0.0=pyhd8ed1ab_0
   - tox=4.16.0=pyhd8ed1ab_0
+  - tqdm=4.66.4=pyhd8ed1ab_0
   - twine=5.1.1=pyhd8ed1ab_0
   - types-tqdm=4.66.0.20240417=pyhd8ed1ab_0
   - typing-extensions=4.12.2=hd8ed1ab_0
@@ -147,23 +148,19 @@ dependencies:
   - wheel=0.43.0=pyhd8ed1ab_1
   - xz=5.2.6=h166bdaf_0
   - zipp=3.19.2=pyhd8ed1ab_0
-  - zstandard=0.22.0=py312h5b18bf6_1
+  - zstandard=0.23.0=py312h3483029_0
   - zstd=1.5.6=ha6fb4c9_0
   - pip:
-      - annotated-types==0.7.0
       - appdirs==1.4.4
-      - ataraxis-automation==2.0.2
-      - ataraxis-base-utilities==1.2.0
-      - ataraxis-time==1.1.0
+      - ataraxis-automation==3.0.3
+      - ataraxis-base-utilities==2.1.1
+      - ataraxis-time==2.0.0
       - bashlex==0.18
       - bracex==2.4
       - build==1.2.1
       - cibuildwheel==2.19.2
       - loguru==0.7.2
-      - pydantic==2.8.2
-      - pydantic-core==2.20.1
       - pyproject-hooks==1.1.0
       - pyyaml==6.0.1
       - tox-uv==1.9.1
-      - tqdm==4.66.4
-      - uv==0.2.23
+      - uv==0.2.27

envs/axt_dev_lin_spec.txt

@@ -1,9 +1,9 @@
-2024-07-09 23:45:10  (rev 0)
+2024-07-21 18:23:46  (rev 0)
     +_libgcc_mutex-0.1 (conda-forge/linux-64)
     +_openmp_mutex-4.5 (conda-forge/linux-64)
     +bzip2-1.0.8 (conda-forge/linux-64)
     +ca-certificates-2024.7.4 (conda-forge/linux-64)
-    +cachetools-5.3.3 (conda-forge/noarch)
+    +cachetools-5.4.0 (conda-forge/noarch)
     +chardet-5.2.0 (conda-forge/linux-64)
     +colorama-0.4.6 (conda-forge/noarch)
     +distlib-0.3.8 (conda-forge/noarch)
@@ -29,17 +29,17 @@
     +python-3.12.4 (conda-forge/linux-64)
     +python_abi-3.12 (conda-forge/linux-64)
     +readline-8.2 (conda-forge/linux-64)
-    +setuptools-70.1.1 (conda-forge/noarch)
+    +setuptools-71.0.4 (conda-forge/noarch)
     +tk-8.6.13 (conda-forge/linux-64)
     +tomli-2.0.1 (conda-forge/noarch)
     +tox-4.16.0 (conda-forge/noarch)
     +tzdata-2024a (conda-forge/noarch)
-    +uv-0.2.23 (conda-forge/linux-64)
+    +uv-0.2.27 (conda-forge/linux-64)
     +virtualenv-20.26.3 (conda-forge/noarch)
     +wheel-0.43.0 (conda-forge/noarch)
     +xz-5.2.6 (conda-forge/linux-64)
 
-2024-07-09 23:45:16  (rev 1)
+2024-07-21 18:23:52  (rev 1)
     +alabaster-0.7.16 (conda-forge/noarch)
     +babel-2.14.0 (conda-forge/noarch)
     +backports-1.0 (conda-forge/noarch)
@@ -54,11 +54,11 @@
     +click-8.1.7 (conda-forge/noarch)
     +cmarkgfm-0.8.0 (conda-forge/linux-64)
     +conda-souschef-2.2.3 (conda-forge/noarch)
-    +coverage-7.5.4 (conda-forge/linux-64)
-    +cryptography-42.0.8 (conda-forge/linux-64)
+    +coverage-7.6.0 (conda-forge/linux-64)
+    +cryptography-43.0.0 (conda-forge/linux-64)
     +dbus-1.13.6 (conda-forge/linux-64)
     +docutils-0.20.1 (conda-forge/linux-64)
-    +exceptiongroup-1.2.0 (conda-forge/noarch)
+    +exceptiongroup-1.2.2 (conda-forge/noarch)
     +execnet-2.1.1 (conda-forge/noarch)
     +expat-2.6.2 (conda-forge/linux-64)
     +future-1.0.0 (conda-forge/noarch)
@@ -105,7 +105,7 @@
     +pycparser-2.22 (conda-forge/noarch)
     +pygments-2.18.0 (conda-forge/noarch)
     +pysocks-1.7.1 (conda-forge/noarch)
-    +pytest-8.2.2 (conda-forge/noarch)
+    +pytest-8.3.1 (conda-forge/noarch)
     +pytest-cov-5.0.0 (conda-forge/noarch)
     +pytest-xdist-3.6.1 (conda-forge/noarch)
     +python-utils-3.8.2 (conda-forge/noarch)
@@ -119,34 +119,35 @@
     +ruamel.yaml-0.18.6 (conda-forge/linux-64)
     +ruamel.yaml.clib-0.2.8 (conda-forge/linux-64)
     +ruamel.yaml.jinja2-0.2.4 (conda-forge/noarch)
-    +ruff-0.5.1 (conda-forge/linux-64)
+    +ruff-0.5.2 (conda-forge/linux-64)
     +scikit-build-core-0.9.8 (conda-forge/noarch)
     +secretstorage-3.3.3 (conda-forge/linux-64)
     +semver-3.0.2 (conda-forge/noarch)
     +six-1.16.0 (conda-forge/noarch)
     +snowballstemmer-2.2.0 (conda-forge/noarch)
     +soupsieve-2.5 (conda-forge/noarch)
-    +sphinx-7.3.7 (conda-forge/noarch)
-    +sphinx-autodoc-typehints-2.2.2 (conda-forge/noarch)
+    +sphinx-7.4.7 (conda-forge/noarch)
+    +sphinx-autodoc-typehints-2.2.3 (conda-forge/noarch)
     +sphinx-click-6.0.0 (conda-forge/noarch)
     +sphinx-rtd-theme-2.0.0 (conda-forge/noarch)
     +sphinx_rtd_theme-2.0.0 (conda-forge/noarch)
     +sphinxcontrib-applehelp-1.0.8 (conda-forge/noarch)
     +sphinxcontrib-devhelp-1.0.6 (conda-forge/noarch)
-    +sphinxcontrib-htmlhelp-2.0.5 (conda-forge/noarch)
+    +sphinxcontrib-htmlhelp-2.0.6 (conda-forge/noarch)
     +sphinxcontrib-jquery-4.1 (conda-forge/noarch)
     +sphinxcontrib-jsmath-1.0.1 (conda-forge/noarch)
-    +sphinxcontrib-qthelp-1.0.7 (conda-forge/noarch)
+    +sphinxcontrib-qthelp-1.0.8 (conda-forge/noarch)
     +sphinxcontrib-serializinghtml-1.1.10 (conda-forge/noarch)
     +stdlib-list-0.10.0 (conda-forge/noarch)
     +toml-0.10.2 (conda-forge/noarch)
     +tomli-w-1.0.0 (conda-forge/noarch)
+    +tqdm-4.66.4 (conda-forge/noarch)
     +twine-5.1.1 (conda-forge/noarch)
     +types-tqdm-4.66.0.20240417 (conda-forge/noarch)
     +typing-extensions-4.12.2 (conda-forge/noarch)
     +typing_extensions-4.12.2 (conda-forge/noarch)
     +urllib3-2.2.2 (conda-forge/noarch)
     +zipp-3.19.2 (conda-forge/noarch)
-    +zstandard-0.22.0 (conda-forge/linux-64)
+    +zstandard-0.23.0 (conda-forge/linux-64)
     +zstd-1.5.6 (conda-forge/linux-64)