dt-helper 0.1.0

Helper funcs for doing things with datetime objects and UTC floats

A Python library for datetime operations optimized for human comprehension and operational clarity. Built around a universal timestamp format that prioritizes instant readability over technical standards, dt-helper reduces cognitive load in production workflows where time matters most. Complex datetime operations become naturally composable through pure functions designed for reliability, debugging ease, and cross-system compatibility.

The '%Y%m%d%H%M%S.%f' format for “UTC float strings” enables instant visual parsing, lexicographic sorting, and cross-system compatibility while remaining debugger-friendly. It is also a great “score” for values in Redis sorted sets.

Who benefits from dt-helper: - DevOps engineers managing time-series data across multiple systems - Data pipeline developers who need predictable, fault-tolerant timestamp handling - Teams building CLI tools and automation scripts that require human-readable time formats - Developers working with Redis, APIs, and databases who want consistent timestamp representation

Core workflows it optimizes: - Interactive timestamp validation and conversion in REPLs - Time range queries for Redis sorted sets and database operations - Log analysis and debugging with instantly readable timestamps - Cross-system data integration where timestamp format consistency matters

Tested for Python 3.5 - 3.13.

Install

Install with pip

pip install dt-helper

Configuration

dt-helper uses a settings.ini file for configuration:

[default]
admin_timezone = America/Chicago
admin_date_fmt = %a %m/%d/%Y %I:%M:%S %p

On first use, the default settings.ini file is copied to ~/.config/dt-helper/settings.ini

QuickStart

import dt_helper as dh

# Generate human-readable timestamps
now = dh.utc_now_float_string()
print(now)  # '20231215142530.123456' - instantly readable

# Convert to pretty formats
pretty = dh.utc_float_to_pretty(now)
print(pretty)  # 'Fri 12/15/2023 02:25:30 PM'  - admin_date_fmt from settings

# Time arithmetic made simple
five_minutes_ago = dh.utc_ago_float_string('5:minutes', now=now)
print(five_minutes_ago)  # '20231215142030.123456'

# Complex time range generation for database queries
ranges = dh.get_time_ranges_and_args(
    start_ts='2023-12-01',
    end_ts='2023-12-15',
    tz='America/Chicago'
)
print(ranges)
# {'start_ts=2023-12-01,end_ts=2023-12-15': (20231201060000.0, 20231215060000.0), 'start_ts=2023-12-01': (20231201060000.0, inf), 'end_ts=2023-12-15': (0, 20231215060000.0)}

What you gain: Timestamps that sort correctly lexicographically, work seamlessly across Redis/databases/APIs, and remain human-readable during production debugging.

API Overview

Core Timestamp Generation

• ``utc_now_float_string(fmt=FLOAT_STRING_FMT)`` - Current UTC timestamp as human-readable string

  • Returns: String timestamp like ‘20231215142530.123456’

  • Internal calls: dt_to_float_string()

• ``get_utcnow()`` - Current UTC time as non-localized datetime object

  • Returns: datetime object in UTC

  • Internal calls: None

• ``utc_now_localized()`` - Current UTC time as timezone-aware datetime object

  • Returns: pytz-localized datetime object in UTC

  • Internal calls: None

• ``local_now_string(fmt=FLOAT_STRING_FMT)`` - Current local time as string

  • fmt - strftime format (defaults to FLOAT_STRING_FMT)

  • Returns: String timestamp in local timezone

  • Internal calls: dt_to_float_string()

Time Arithmetic and History

• ``utc_ago_float_string(num_unit, now=None, fmt=FLOAT_STRING_FMT)`` - Timestamp from the past

  • num_unit - String like ‘15:seconds’, ‘1.5:weeks’, ‘3:hours’ ((se)conds, (mi)nutes, (ho)urs, (da)ys, (we)eks, hr, wk)

  • now - Reference time (utc_float string or None for current time)

  • fmt - Output format

  • Returns: String timestamp or None if invalid input

  • Internal calls: float_string_to_dt(), dt_to_float_string(), get_utcnow()

• ``days_ago(days=0, timezone=”America/Chicago”)`` - Start of day N days ago in timezone

  • days - Number of days back (non-negative)

  • timezone - Target timezone string

  • Returns: UTC datetime object for start of specified day

  • Internal calls: utc_now_localized()

Format Conversion and Parsing

• ``dt_to_float_string(dt, fmt=FLOAT_STRING_FMT)`` - Convert datetime to string

  • dt - datetime object

  • fmt - strftime format string

  • Returns: Formatted timestamp string

  • Internal calls: ih.from_string()

• ``float_string_to_dt(float_string, fmt=FLOAT_STRING_FMT)`` - Parse string to datetime

  • float_string - Timestamp string (auto-adds .0 if no decimal)

  • fmt - Expected format

  • Returns: datetime object

  • Internal calls: None

• ``date_string_to_utc_float_string(date_string, timezone=None)`` - Flexible date parsing

  • date_string - Date in format from ‘YYYY’ to ‘YYYY-MM-DD HH:MM:SS.f’

  • timezone - Source timezone for localization

  • Returns: UTC float string or None if unparseable

  • Internal calls: dt_to_float_string()

Human-Friendly Formatting

• ``utc_float_to_pretty(utc_float=None, fmt=None, timezone=None)`` - Format for human display

  • utc_float - Timestamp string/float (uses current time if None)

  • fmt - strftime format (uses admin settings if None)

  • timezone - Target timezone (uses admin settings if None)

  • Returns: Formatted string or original value if no format specified

  • Internal calls: utc_now_float_string()

• ``get_timestamp_formatter_from_args(ts_fmt=None, ts_tz=None, admin_fmt=False)`` - Create formatter function

  • ts_fmt - strftime format for output

  • ts_tz - timezone for conversion

  • admin_fmt - boolean to use admin settings from config

  • Returns: Function that formats utc_float values

  • Internal calls: utc_float_to_pretty()

ISO and Standard Format Support

• ``utc_now_iso()`` - Current time in ISO format

  • Returns: ISO format string like ‘2023-12-15T14:25:30.123456’

  • Internal calls: get_utcnow()

• ``utc_localized_from_iso_timestamp(date_string)`` - Parse ISO timestamp to UTC

  • date_string - ISO format timestamp (timezone-aware or UTC assumed)

  • Returns: UTC localized datetime object or None if invalid

  • Internal calls: get_utcnow()

Advanced Date Operations

• ``date_string_to_datetime(date_string, fmt=’%Y-%m-%d’, timezone=None)`` - Flexible date parsing

  • date_string - Date string or datetime object (passthrough)

  • fmt - Expected format (auto-handles fractional seconds)

  • timezone - Target timezone for localization

  • Returns: datetime object (localized if timezone specified)

  • Internal calls: None

• ``date_start_utc(date_string, fmt=’%Y-%m-%d’, timezone=”America/Chicago”)`` - Day start in UTC

  • date_string - Date in specified format

  • fmt - Date format string

  • timezone - Source timezone

  • Returns: UTC datetime for start of day

  • Internal calls: date_string_to_datetime()

Complex Time Range Operations

• ``get_time_ranges_and_args(**kwargs)`` - Generate time ranges for Redis ZRANGEBYSCORE, ZCOUNT and database queries; multiple values separated by , ; |

  • tz - timezone for timestamp interpretation

  • now - reference time as float_string

  • start - direct utc_float start value

  • end - direct utc_float end value

  • start_ts - timestamp strings (format YYYY to YYYY-MM-DD HH:MM:SS.f)

  • end_ts - timestamp strings (format YYYY to YYYY-MM-DD HH:MM:SS.f)

  • since - relative time strings (‘15:minutes’, ‘2:days’, etc.)

  • until - relative time strings (‘15:minutes’, ‘2:days’, etc.)

  • Returns: Dictionary with descriptive keys and (start_float, end_float) tuples

  • Internal calls: utc_now_float_string(), date_string_to_utc_float_string(), utc_ago_float_string(), ih.string_to_set()