Skip to content

Latest commit

 

History

History
129 lines (81 loc) · 3.67 KB

timevalue.md

File metadata and controls

129 lines (81 loc) · 3.67 KB

timevalue() and retime() - Cleanly translate time values with units to seconds and other units

Skip to API documentation

timevalue() is a class for dealing with time values (eg, 5 minutes, 2 weeks, 30 seconds) in a simple form. timevalues are cleanly used in time/datetime calculations and print statements. There's no magic here, just convenience and cleaner code.

retime() translates an int or float resolution-seconds value into a new target resolution.

Creating a timevalue instance gives ready access to the value in seconds, and useful unit_chr and unit_str strings for use in printing and logging.

Using timevalues in configuration files is quite convenient.

  • A service loop time param may be expressed as 5m (5 minutes), rather than 300 (hard coded for seconds), or 5 (hard coded for minutes)
  • A failed command retry interval param my be expressed a 3s (3 seconds), rather than 3 (what are the time units again?)

Example usage

Given

#!/usr/bin/env python3
# ***** timevalue_ex1.py *****

import time
from cjnfuncs.timevalue import timevalue, retime

xx = timevalue('0.5m')
print (xx)
print (f"Sleep <{xx.seconds}> seconds")
time.sleep(xx.seconds)

print()
yy = timevalue("1w")
print (f"{yy.orig_val} = {yy.seconds} seconds = {retime(yy.seconds, 'h')} hours")

Output:

$ ./timevalue_ex1.py 
.orig_val   :  0.5m     <class 'str'>
.seconds    :  30.0     <class 'float'>
.unit_char  :  m        <class 'str'>
.unit_str   :  mins     <class 'str'>
Sleep <30.0> seconds

1w = 604800.0 seconds = 168.0 hours

timevalue() accepts int and float values, with assumed seconds resolution, and accepts int and float values with a case insensitive time unit suffix character:

unit_char suffix unit_str
s secs
m mins
h hours
d days
w weeks


Links to classes, methods, and functions


Class timevalue (orig_val) - Convert time value strings of various resolutions to seconds

timevalue() provides a convenience mechanism for working with time values and time/datetime calculations. timevalues are generally an integer value with an attached single character time resolution, such as "5m". Supported timevalue units are 's'econds, 'm'inutes, 'h'ours, 'd'ays, and 'w'eeks, and are case insensitive. timevalue() also accepts integer and float values, which are interpreted as seconds resolution. Also see retime().

Parameters

orig_val (str, int, or float)

  • The original, passed-in value

Returns

  • Handle to instance
  • Raises ValueError if given an unsupported time unit suffix.

Instance attributes

  • .orig_val - orig_val value passed in, type str (converted to str if int or float passed in)
  • .seconds - time value in seconds resolution, type float, useful for time calculations
  • .unit_char - the single character suffix unit of the orig_val value. 's' for int and float orig_val values.
  • .unit_str - the long-form units of the orig_val value useful for printing/logging ("secs", "mins", "hours", "days", or "weeks")

retime (time_sec, unitC) - Convert time value in seconds to unitC resolution

retime() translates a value is resolution seconds into a new target resolution

Parameters

time_sec (int or float)

  • The time value in resolution seconds to be converted

unitC (str)

  • Target time resolution: "s", "m", "h", "d", or "w" (case insensitive)

Returns

  • time_sec value scaled for the specified unitC, type float
  • Raises ValueError if not given an int or float value for time_sec, or given an unsupported unitC time unit suffix.