nanotime (jbenet's library)

Common errors

• AttributeError: 'datetime.datetime' object has no attribute 'nanotime'

  cause Attempting to call `nanotime` methods directly on a standard `datetime.datetime` object.
  fix To convert a `datetime` object to a `Nanotime` object, use `Nanotime.from_datetime(your_datetime_obj)`.

• TypeError: 'float' object cannot be interpreted as an integer

  cause Passing a floating-point number (e.g., from `time.time()`) directly to a `Nanotime` constructor or method expecting an integer nanosecond value, or when converting `Nanotime` to an imprecise float.
  fix Ensure you are using integer nanosecond values when working with `Nanotime` or explicitly convert from seconds to nanoseconds (e.g., `int(time.time() * 1_000_000_000)`).

• Precision loss when converting Nanotime to datetime object.

  cause `datetime` objects internally store time with microsecond precision (6 decimal places for seconds), while `Nanotime` stores nanosecond precision (9 decimal places for seconds).
  fix This is expected behavior. If nanosecond precision is critical, retain the `Nanotime` object or the raw nanosecond integer. Only convert to `datetime` when the loss of nanosecond detail is acceptable.

Warnings

• breaking The `nanotime` library provides its own `Nanotime` object. Direct integration with standard Python `datetime` objects will result in loss of nanosecond precision as `datetime` objects only support microseconds. This is a fundamental limitation of `datetime`.
  Fix: Store time as a `Nanotime` object or as a raw nanosecond integer if full precision is required. Convert to `datetime` only when microsecond precision is acceptable for display or interoperability with other libraries.
• deprecated The `nanotime` library has not been updated since 2011. Python 3.7+ introduced `time.time_ns()`, `monotonic_ns()`, `perf_counter_ns()`, and `process_time_ns()` into the standard library, providing native nanosecond precision integers. These standard library functions are generally preferred for new development requiring nanosecond resolution.
  Fix: For new projects on Python 3.7 or later, consider using `time.time_ns()` and related functions from the standard `time` module for nanosecond-level timestamps, rather than relying on this unmaintained third-party library.
• gotcha The internal representation of `Nanotime` is a 64-bit unsigned integer representing nanoseconds since the Unix epoch. While this provides a theoretical range of approximately 584 years, the library's design assumes an epoch of 1970 and may behave unexpectedly or have practical limits for dates far outside the 1970-2554 range.
  Fix: Understand the intended range and representation. For extremely broad date ranges, other time representations might be more suitable or robustly supported.

Install

• pip install nanotime Install stable version

Imports

• Nanotime

  from nanotime import Nanotime

Quickstart

Demonstrates how to create a `Nanotime` object, convert it to an integer nanosecond timestamp, convert it to and from a standard `datetime` object, and measure elapsed time.

from nanotime import Nanotime
import datetime

# Get current time with nanosecond precision
now = Nanotime.now()
print(f"Current nanotime: {now}")

# Convert to nanoseconds (integer)
ns_since_epoch = int(now)
print(f"Nanoseconds since epoch: {ns_since_epoch}")

# Convert to datetime object (loses nanosecond precision beyond microseconds)
dt_obj = now.datetime()
print(f"Converted to datetime: {dt_obj}")

# Create from a datetime object
some_dt = datetime.datetime(2023, 1, 1, 12, 30, 0, 123456)
nt_from_dt = Nanotime.from_datetime(some_dt)
print(f"Nanotime from datetime: {nt_from_dt}")

# Calculate duration
import time
start_nt = Nanotime.now()
time.sleep(0.001) # Simulate some work
end_nt = Nanotime.now()
delta_ns = int(end_nt) - int(start_nt)
print(f"Time elapsed (nanoseconds): {delta_ns}")