tooltime makes it simple to represent and manipulate many different representations of time

tooltime operates on 4 abstract time datatypes:

Each datatype has multiple interconvertible representations using native python types

pip install tooltime

• Example Usage
• Datatype Representations
• Function Reference
• Frequently Asked Questions

import tooltime

tooltime.timelength_to_seconds('10m')
> 600
tooltime.timelength_to_label(600)
> '10m'
tooltime.timelength_to_clock('10m')
> '0:10:00'
tooltime.timelength_to_phrase('10m')
> '10 minutes'

(
    tooltime.timelength_to_seconds(600)
    == tooltime.timelength_to_seconds('10m')
    == tooltime.timelength_to_seconds('0:10:00')
    == tooltime.timelength_to_seconds('10 minutes')
)
> True

# load data
timestamps = load_data(...)

# summarize sequence
tooltime.print_timestamp_summary(timestamps)

n_t: 216
n_unique: 216
extent:
    start: 20210117_201840Z (1610914720.757)
    end:   20210118_235708Z (1611014228.542)
    duration: 1 days, 3:38:27.785000 (99507.785000086 s)
resolution:
    median_dt: 4m
    mean_dt: 462s
    missing timestamps: 200 (if median_dt maintained)
    outlier_dts: 20
        small: 8        dt < median_dt / (1 + outlier_rtol)
        large: 12        dt > median_dt * (1 + outlier_rtol)
        (outlier_rtol = 0.5)

Create timeperiods whose boundaries are integer multiples of some block_unit. These useful for placing erratically distributed timestamps into regular bins

timestamp = 1600000000
block_size = 3
print('timestamp:', tooltime.timestamp_to_label(timestamp))
print()
print('standardized timeperiods containing timestamp:')
for block_unit in ['day', 'hour', 'minute']:
    timeperiod = tooltime.get_standard_timeperiod(
        timestamp=timestamp,
        block_size=block_size,
        block_unit=block_unit,
    )    
    block_str = str(block_size) + ' ' + block_unit
    timeperiod_str = tooltime.timeperiod_to_str(timeperiod)
    print('   %8s' % block_str + ':', timeperiod_str)

timestamp: 20200913_122640Z

standardized timeperiods containing timestamp:
      3 day: [20200913_000000Z, 20200915_235959Z]
     3 hour: [20200913_120000Z, 20200913_145959Z]
   3 minute: [20200913_122400Z, 20200913_122659Z]

each of the 4 time datatypes has multiple interconvertible representations, and each representation is assembled from native python types:

valid time units are 's', 'm', 'h', 'd', 'w', 'M', and 'y', indicating seconds, minutes, hours, days, weeks, months, and years

• all functions can be accessed using syntax tooltime.<function_name>(...)
• tooltime contains many functions, but most derive from one of the following patterns:

All functions for each datatype are listed below

• Identfication Functions
• Creation Functions
• Conversion Functions
• Specialized Functions

these are functions that are specific to each datatype

All Timestamp representations except TimestampDatetime are linked to specific timezone, which in most cases is GMT (UTC). Counts of seconds since epoch (as in TimestampSeconds and TimestampSecondsPrecise) are conventionally always GMT (UTC). TimestampLabel and TimestampISO use a military time zone abbreviation as their last characters. The datetime object of TimestampDatetime internally represents a count of seconds since epoch, but datetime objects can have implicit or explicit timezones depending on how they are instantiated.

• datetime does not handle timezones in a simple or explicit way.
• datetime does not make it easy to ingest, output, or convert representations of time using primitive python types.
• tooltime contains different convenience functions than datetime that are better suited for different workloads.

The T character separates the date portion of the timestamp from the time portion. The Z character indicates the GMT (UTC) timezone. Each timezone has its own letter. Read more here.