Skip to main content

tooltime makes it easy to create and convert representations of time

Project description


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

tooltime operates on 4 abstract time datatypes:

meaning example
Timestamp a moment in time today at 3:03 PM
Timelength a length of time four minutes
Timeperiod a period with a start and an end from 3:03 PM to 3:07 PM today
Timefrequency a rate every four minutes

Each datatype has multiple interconvertible representations using native python types


pip install tooltime


Example Usage

Convert Timelength Representations

import tooltime

> 600
> '10m'
> '0:10:00'
> '10 minutes'

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

Introspect Time Data

# load data
timestamps = load_data(...)

# summarize sequence
n_t: 216
n_unique: 216
    start: 20210117_201840Z (1610914720.757)
    end:   20210118_235708Z (1611014228.542)
    duration: 1 days, 3:38:27.785000 (99507.785000086 s)
    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 Standardized Timeperiods

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('standardized timeperiods containing timestamp:')
for block_unit in ['day', 'hour', 'minute']:
    timeperiod = tooltime.get_standard_timeperiod(
    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]

Datatype Representations

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

Timestamp Representations
python type example
TimestampSeconds int seconds since UTC epoch 1600000000
TimestampSecondsPrecise float seconds since UTC epoch 1600000000.0
TimestampLabel str in format '%Y%m%d_%H%M%SZ' '20200913_122640Z'
TimestampISO str in ISO 8601 format '2020-09-13T12:26:40Z'
TimestampISOPretty str in ISO 8601 format, prettier '2020-09-13 12:26:40Z'
TimestampDatetime datetime.datetime object
TimestampYear str of year 2020
TimestampMonth str of dashed year and month 2020-09
TimestampMonthCompact str of plain year and month 202009
TimestampDate str of dashed date 2020-09-13
TimestampDateCompact str of plain date 20200913
Timelength Representations
python type example
TimelengthSeconds int seconds 310
TimelengthSecondsPrecise float seconds 310.0
TimelengthLabel str of '{number}{time_unit}' '310s'
TimelengthClock str of '{hours}:{minutes}:{seconds}' '0:05:10'
TimelengthPhrase str of comma-separated list of English amounts '5 minutes, 10 seconds'
TimelengthClockPhrase str of TimelengthPhrase modulo 1 day, remainder in TimelengthClock '3 days, 0:05:10'
TimelengthTimedelta datetime.timedelta object datetime.timedelta(3, 310)

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

Timeperiod Representations
python type example
TimeperiodMap dict in form {'start': 'Timestamp', 'end': 'Timestamp'} {'start': 1600000000, 'end': 1600000001}
TimeperiodPair list in form [start, end] [1600000000, 1600000001]
Timefrequency Representations
python type example
TimefrequencyFrequency int or float of cycles per second 5.0
TimefrequencyCountPer dict in form {'count': ['int', 'float'], 'per': 'Timelength'} {'count': 5, 'per': '1s'}
TimefrequencyInterval dict in form {'interval': 'Timelength'} {'interval': 0.2}

Function Reference

  • all functions can be accessed using syntax tooltime.<function_name>(...)
  • tooltime contains many functions, but most derive from one of the following patterns:
operation type template (functions that are more specific will have better performance) description
identification is_<datatype>() return bool of whether input is instance of datatype
identification is_<datatype>_<representation>() return bool of whether input is instance of specific datatype representation
identification detect_<datatype>_representation() return str of datatype representation name
creation create_<datatype>() create datatype
creation create_<datatype>_<representation>() create datatype with specific representation
conversion convert_<datatype>() convert datattype representation
conversion convert_<datatype>_to_<representation>() convert datatype to specific representation
conversion convert_<datatype>_<representation>_to _<representation>() convert datatype with known representation to specific representation

All functions for each datatype are listed below

Identification Functions

example call example output
is_timestamp() is_timestamp('hello') False
is_timestamp_seconds() is_timestamp_seconds(610) True
is_timestamp_label() is_timestamp_label(610) False
is_timestamp_iso() is_timestamp_iso( '2020-09-13T12:26:40Z') True
is_timestamp_datetime() is_timestamp_datetime(610) False
detect_timestamp _representation() detect_timestamp_representation( 610) 'TimestampSeconds'
is_timelength() is_timelength('10m') True
is_timelength_seconds() is_timelength_seconds('10m') False
is_timelength_label() is_timelength_label('10m') True
is_timelength_clock() is_timelength_clock('10m) False
is_timelength_phrase() is_timelength_phrase('10 minutes') True
is_timelength_clock_phrase() is_timelength_clock_phrase('10m') False
is_timelength_timedelta() is_timelength_timedelta('10 minutes') False
detect_timelength _representation() detect_timelength_representation( '10m') 'TimelengthLabel'
is_timeperiod() is_timeperiod({'start': 1600000000, 'end': 1600000001'}) True
is_timeperiod_map() is_timeperiod_map({'start': 1600000000, 'end': 1600000001'}) True
is_timeperiod_pair() is_timeperiod_length({'start': 1600000000, 'end': 1600000001'}) False
detect_timeperiod _representation() detect_timeperiod_representation( {'start': 1600000000, 'end': 1600000001'}) 'TimeperiodMap'
is_timefrequency() is_timefrequency({'interval': 0.2}) True
is_timefrequency_frequency() is_timefrequency_frequency( {'interval': 0.2}) False
is_timefrequency_count_per() is_timefrequency_count_per( {'interval': 0.2}) False
is_timefrequency_interval() is_timefrequency_interval( {'interval': 0.2}) True
detect_timefrequency _representation() detect_timefrequency _representation({'interval': 0.2}) 'TimefrequencyInterval'

Creation Functions

example call example output
create_timestamp_seconds() create_timestamp_seconds() 1600000000
create_timestamp_label() create_timestamp_label() '20200913_122640Z'
create_timestamp_iso() create_timestamp_iso() '2020-09-13T12:26:40Z'
create_timestamp_datetime() create_timestamp_datetime() '2020-09-13T12:26:40Z'
create_timelength() create_timelength(seconds=310, to_representation= 'TimelengthLabel') '310s'
create_timelength_seconds() create_timelength_seconds( seconds=310) 310
create_timelength_seconds_precise() create_timelength_seconds _precise(seconds=310) 310.0
create_timelength_label() create_timelength_label( seconds=310) '310s'
create_timelength_clock() create_timelength_clock( seconds=310) '0:05:10'
create_timelength_phrase() create_timelength_phrase( seconds=310) '5 minutes, 10 seconds'
create_timelength_clock_phrase() create_timelength_clock_phrase( seconds=310) '0:05:10'
create_timelength_timedelta() create_timelength_timedelta( seconds=310) datetime.timedelta(0, 310)
create_timeperiod() create_timeperiod( start=1600000000, length=1) {'start': 1600000000, 'end': 1600000001}
create_timeperiod_map() create_timeperiod_map( start=1600000000, length=1) {'start': 1600000000, 'end': 1600000001}
create_timeperiod_pair() create_timeperiod_pair( start=1600000000, length=1) [1600000000, 1600000001]
create_timefrequency() create_timefrequency(count=5, per=1) 5.0
create_timefrequency_frequency() create_timefrequency_frequency( count=5, per=1) 5.0
create_timefrequency_count_per() create_timefrequency_count_per( count=5, per=1) {'count': 5, 'per': 1}
create_timefrequency_interval() create_timefrequency_interval( interval=0.2) {'interval': 0.2}

Conversion Functions

Timestamp Conversion Functions
example call example output
convert_timestamp() convert_timestamp(1600000000, 'TimestampLabel') '20200913_122640Z'
timestamp_to_seconds() timestamp_to_seconds( '20200913_122640Z') 1600000000
timestamp_to_label() timestamp_to_label(1600000000) '20200913_122640Z'
timestamp_to_iso() timestamp_to_iso(1600000000) '2020-09-13T12:26:40Z'
timestamp_to_datetime() timestamp_to_datetime(1600000000) datetime.datetime(2020, 9, 13, 12, 26, 40)
timestamp_seconds_to_label() timestamp_seconds_to_label( 1600000000) '20200913_122640Z'
timestamp_label_to_seconds() timestamp_label_to_seconds( '20200913_122640Z') 1600000000
timestamp_seconds_to_iso() timestamp_seconds_to_iso(1600000000) '2020-09-13T12:26:40Z'
timestamp_iso_to_seconds() timestamp_iso_to_seconds( '2020-09-13T12:26:40Z') 1600000000
Timelength Conversion Functions
example call example output
convert_timelength() convert_timelength(1600000000, 'TimestampLabel') '20200913_122640Z'
timelength_to_seconds() timelength_to_seconds(610) 610
timelength_to_phrase() timelength_to_phrase(610) '10 minutes, 10 seconds'
timelength_to_clock() timelength_to_clock(610) '0:10:10'
timelength_to_clock_phrase() timelength_to_clock_phrase( 259810) '3 days, 0:10:10'
timelength_seconds_to_label() timelength_seconds_to_label(600) '10m'
timelength_seconds_to_clock() timelength_seconds_to_clock(610) '0:10:10'
timelength_seconds_to_phrase() timelength_seconds_to_phrase(610) '10 minutes, 10 seconds'
timelength_seconds_to_clock_phrase() timelength_seconds_to_clock _phrase(600) '3 days, 0:05:10'
timelength_seconds_to_timedelta() timelength_seconds_to_timedelta( 259810) datetime.timedelta( 3, 610)
timelength_label_to_seconds() timelength_label_to_seconds( '10m') 600
timelength_clock_to_seconds() timelength_clock_to_seconds( '0:10:10') 610
timelength_phrase_to_seconds() timelength_phrase_to_seconds('10 minutes') 610
timelength_clock_phrase_to_seconds() timelength_clock_phrase_to _seconds( '3 days, 0:05:10') 259510
timelength_timedelta_to_seconds() timelength_timedelta_to_seconds( timedelta) 259510
Timeperiod Conversion Functions
example call example output
convert_timeperiod() convert_timeperiod({'start': 1600000000, 'end': 1600000001}, 'TimePeriodStartLength') {'start': 1600000000, 'length': 1}
convert_timeperiod_to_start_end() convert_timeperiod_to_start_end( {'start': 1600000000, 'end': 1600000001}, 'TimePeriodStartLength') {'start': 1600000000, 'end': 1600000001}
convert_timeperiod_to_start_length() convert_timeperiod_to_start_length( {'start': 1600000000, 'end': 1600000001}, 'TimePeriodStartLength') {'start': 1600000000, 'length': 1}
convert_timeperiod_to_end_length() convert_timeperiod_to_end_length( {'start': 1600000000, 'end': 1600000001}, 'TimePeriodStartLength') {'end': 1600000001, 'length': 1}
Timefrequency Conversion Functions
example call example output
convert_timefrequency() convert_timefrequency({'count': 5, 'per': '1s'}, 'TimeInterval') {'interval': 0.5}
convert_timefrequency_to_frequency() convert_timefrequency_to_frequency( {'interval': 0.2}) 5.0
convert_timefrequency_to_count_per() convert_timefrequency_to_count_per( {'interval': 0.2}) {'count': 5, 'per': '1s'}
convert_timefrequency_to_interval() convert_timefrequency_to_interval( {'count': 5, 'per': '1s'}) {'interval': 0.2}

Specialized Functions

these are functions that are specific to each datatype

datatype function description
Timestamp floor_datetime() return floor of datetime to specified unit of precision
Timestamp get_unit_lowest_value() return int of lowest possible for value for a given time unit
Timestamp iterable print_timestamp_summary() print a variety of summary statistics about Timestamps
Timeperiod timeperiods_overlap() return bool of whether Timeperiods have any overlap
Timeperiod timeperiod_contains() return bool of whether Timeperiod contains other Timeperiod
Timeperiod create_superset_timeperiod() create Timeperiod that contains all input Timeperiods
Timeperiod create_overlapping_timeperiod() create copy of Timeperiod with start or end trimmed or extended by relative or absolute amounts
Timeperiod get_standard_timeperiod() get standardized Timeperiod whose boundaries are integer multiples of some block_unit
Timefrequency detect_resolution() detect resolution of iterable of Timestamp

Frequently Asked Questions

How are timezones handled?

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.

Why not just use datetime?

  • 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.

What do the T and Z mean in an ISO 8601 timestamp, such as "2020-09-13T12:26:40Z"?

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tooltime-0.2.11.tar.gz (35.3 kB view hashes)

Uploaded source

Built Distribution

tooltime-0.2.11-py3-none-any.whl (38.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page