Hightime Python API

1.0.0 · active · verified Fri Apr 17

Hightime is a Python library from National Instruments designed for representing and manipulating durations and time intervals with high precision. It provides classes like `Interval` and `Unit` to define time quantities, enabling arithmetic operations and conversions between different units. The current stable version is 1.0.0, which includes significant improvements in Python version compatibility and type hinting. Releases appear to be driven by feature additions and Python version updates rather than a fixed schedule.

Common errors

```
ModuleNotFoundError: No module named 'hightime'
```
cause The `hightime` library is not installed in your current Python environment.

fix Run `pip install hightime` to install the library.
```
TypeError: unsupported operand type(s) for +: 'hightime.Interval' and 'datetime.timedelta'
```
cause You are attempting to directly add a `hightime.Interval` object with a standard library `datetime.timedelta` object, which `hightime` does not implicitly support.

fix Convert `datetime.timedelta` to a `hightime.Interval` first. For example: `hightime_interval + Interval(timedelta_obj.total_seconds(), Unit.SECONDS)`.
```
ERROR: Package 'hightime' requires a different Python version: 3.x.y (current is 3.a.b)
```
cause You are trying to install or run `hightime` (especially v1.0.0 or later) on an unsupported Python version (e.g., Python 3.7 or 3.8).

fix Upgrade your Python environment to version 3.9 or higher (e.g., 3.9, 3.10, 3.11, 3.12, 3.13) to meet the library's requirements.

Warnings

breaking Version 1.0.0 dropped support for Python 3.7 and 3.8. Users on these older Python versions must upgrade their Python environment or use an older version of the `hightime` library.
Fix: Upgrade your Python environment to 3.9 or newer (e.g., Python 3.9-3.13 are supported by v1.0.0).
gotcha When running on PyPy, versions of `hightime` prior to 1.0.0 could experience infinite recursion if `copy` or `pickle` operations were performed on `hightime` objects.
Fix: Upgrade to `hightime` version 1.0.0 or newer to resolve the infinite recursion issue on PyPy.
gotcha Older versions of `hightime` (pre-1.0.0) had issues with comparisons against 'unknown types', potentially leading to unexpected `TypeError` or incorrect comparison results.
Fix: Ensure you are using `hightime` version 1.0.0 or newer. When comparing `Interval` objects, ensure the other operand is also a `hightime.Interval` or a type explicitly supported for comparison.
gotcha For maximum precision when getting the total duration in seconds, use `interval.precision_total_seconds`. The `total_seconds` property might truncate precision in some cases.
Fix: Use `interval.precision_total_seconds` (available from v0.2.2) for the most accurate representation of an interval's total duration in seconds.

Install

pip install hightime Install stable version

Imports

Interval
```
from hightime import Interval
```
Unit
```
from hightime import Unit
```
State
```
from hightime import State
```
Used for representing discrete states in time (e.g., ON/OFF), less common for basic duration tasks.

Quickstart

This quickstart demonstrates how to create `Interval` objects, perform basic arithmetic, and convert intervals between different `Unit` types. It also shows how to retrieve precise total seconds.

from hightime import Interval, Unit

# Create an interval of 5.5 seconds
interval_a = Interval(5.5, Unit.SECONDS)
print(f"Interval A: {interval_a}")

# Create another interval of 1000 milliseconds
interval_b = Interval(1000, Unit.MILLISECONDS)
print(f"Interval B: {interval_b}")

# Perform arithmetic operations
interval_sum = interval_a + interval_b
print(f"Sum: {interval_sum}")  # Should be 6.5 seconds

# Convert an interval to different units
milliseconds = interval_sum.in_units(Unit.MILLISECONDS)
print(f"Sum in milliseconds: {milliseconds} ms")

# Access total seconds with higher precision
total_seconds_precise = interval_sum.precision_total_seconds
print(f"Sum in precise total seconds: {total_seconds_precise} s")

view raw JSON →