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 %pOn 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()
1 maintainer
Metadata
1 maintainer
Release files for dt-helper 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| dt_helper-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Release files / dt_helper-0.1.0-py3-none-any.whl
| Download URL | dt_helper-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ece9485ead6fca6c4bdd40bcd0727e316ef8a371a6bb35270f84534fe88e7bde
|
|
BLAKE2b-256 checksum How to use checksums |
b17635915edce4ea2c72ea070d33ca92d8b8e959c6f3469cfb8fbdb29209ed88
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.8.10
|
