Time Helper
A lightweight Python library for effortless datetime handling with timezone support. Built for simplicity and flexibility, it provides a comprehensive set of utilities for parsing, converting, and manipulating dates and times.
Key Features:
🌍 Timezone-aware operations with abbreviation support (e.g., IST, PST, CET)
with abbreviation support (e.g., IST, PST, CET) 🔄 Universal datetime parsing from strings, timestamps, and various formats
from strings, timestamps, and various formats 📊 Optional pandas/numpy integration for DataFrame operations
for DataFrame operations 🎯 Simple, intuitive API with one-line conversions
with one-line conversions 🐍 Modern Python 3.10+ with full type hints
Installation
Basic Installation
For core datetime functionality without heavy dependencies:
# Using pip pip install time-helper # Using uv (recommended) uv add time-helper
With Optional Dependencies
Add pandas and/or numpy support for DataFrame operations and advanced array handling:
# With pandas support (includes DataFrame/Series datetime operations) pip install time-helper[pandas] uv add time-helper[pandas] # With numpy support (for numpy datetime64 conversions) pip install time-helper[numpy] uv add time-helper[numpy] # With both pandas and numpy pip install time-helper[pandas,numpy] uv add time-helper[pandas,numpy]
Quick Start
from time_helper import any_to_datetime , make_aware , round_time # Parse any datetime format automatically dt = any_to_datetime ( "2024-03-15 10:30:45" ) dt = any_to_datetime ( 1710501045 ) # Unix timestamp dt = any_to_datetime ( "15/03/2024" , date_format = "%d/%m/%Y" ) # Make timezone-aware (auto-detects system timezone) aware_dt = make_aware ( "2024-03-15" ) # > datetime.datetime(2024, 3, 15, 0, 0, tzinfo=ZoneInfo('America/New_York')) # Convert between timezones using abbreviations from time_helper import localize_datetime tokyo_time = localize_datetime ( aware_dt , "JST" ) # Japan Standard Time delhi_time = localize_datetime ( aware_dt , "IST" ) # Indian Standard Time # Round to nearest hour, day, week, etc. rounded = round_time ( dt , "H" ) # Hour rounded = round_time ( dt , "D" , max_out = True ) # End of day (23:59:59.999999)
Features
🔄 Universal DateTime Parsing
The any_to_datetime function intelligently parses various datetime formats:
from time_helper import any_to_datetime from datetime import date # Parse different formats automatically dt = any_to_datetime ( "2024-03-19" ) # ISO date dt = any_to_datetime ( "2024-03-19 20:15:30" ) # ISO datetime dt = any_to_datetime ( "19/03/2024" , date_format = "%d/%m/%Y" ) # Custom format dt = any_to_datetime ( 1710501045 ) # Unix timestamp dt = any_to_datetime ( date ( 2024 , 3 , 19 )) # Python date object dt = any_to_datetime ( "2024-03-19T15:30:00.123Z" ) # ISO with milliseconds
🌍 Timezone Operations
Seamlessly work with timezones using names or abbreviations:
from time_helper import make_aware , make_unaware , localize_datetime , current_timezone # Auto-detect system timezone current_tz = current_timezone () # Make timezone-aware using system timezone aware_dt = make_aware ( "2024-03-15" ) # Explicit timezone utc_dt = make_aware ( "2024-03-15" , "UTC" ) tokyo_dt = make_aware ( "2024-03-15" , "Asia/Tokyo" ) # Use timezone abbreviations (automatically mapped) ist_dt = make_aware ( "2024-03-15" , "IST" ) # Maps to Asia/Kolkata pst_dt = make_aware ( "2024-03-15" , "PST" ) # Maps to America/Los_Angeles # Convert between timezones ny_time = localize_datetime ( utc_dt , "America/New_York" ) berlin_time = localize_datetime ( utc_dt , "Europe/Berlin" ) # Remove timezone information unaware_dt = make_unaware ( aware_dt ) # Keeps the time as-is unaware_utc = make_unaware ( berlin_time , "UTC" ) # Converts to UTC first
⏰ DateTime Operations
Powerful operations for datetime manipulation:
from time_helper import round_time , time_diff # Round to various frequencies dt = any_to_datetime ( "2024-03-15 14:35:27.123456" ) # Round down (floor) hour_start = round_time ( dt , "H" ) # 2024-03-15 14:00:00 day_start = round_time ( dt , "D" ) # 2024-03-15 00:00:00 week_start = round_time ( dt , "W" ) # 2024-03-11 00:00:00 (Monday) month_start = round_time ( dt , "m" ) # 2024-03-01 00:00:00 year_start = round_time ( dt , "Y" ) # 2024-01-01 00:00:00 # Round up (ceiling) with max_out=True hour_end = round_time ( dt , "H" , max_out = True ) # 2024-03-15 14:59:59.999999 day_end = round_time ( dt , "D" , max_out = True ) # 2024-03-15 23:59:59.999999 week_end = round_time ( dt , "W" , max_out = True ) # 2024-03-17 23:59:59.999999 # Calculate timezone-aware differences tokyo = make_aware ( "2024-03-15 10:00" , "Asia/Tokyo" ) london = make_aware ( "2024-03-15 10:00" , "Europe/London" ) diff = time_diff ( tokyo , london ) # -9 hours difference
📊 Pandas Integration (Optional)
When pandas is installed, additional DataFrame operations become available:
import pandas as pd from time_helper import make_aware , has_timezone # Create sample DataFrame df = pd . DataFrame ({ 'timestamp' : [ '2024-03-15 10:00' , '2024-03-16 15:30' ], 'event' : [ 'start' , 'end' ] }) # Make timezone-aware df = make_aware ( df , col = 'timestamp' , tz = 'UTC' ) # Check timezone presence has_tz = has_timezone ( df , 'timestamp' ) # True # Convert timezone df = make_aware ( df , col = 'timestamp' , tz = 'America/New_York' )
📈 Time Range Operations
Create and manipulate time intervals:
from time_helper import create_intervals , time_to_interval from datetime import datetime , timedelta start = datetime ( 2024 , 3 , 15 , 9 , 0 ) end = datetime ( 2024 , 3 , 15 , 17 , 0 ) # Create hourly intervals hourly = create_intervals ( start , end , interval = timedelta ( hours = 1 )) # [(datetime(2024, 3, 15, 9, 0), datetime(2024, 3, 15, 10, 0)), # (datetime(2024, 3, 15, 10, 0), datetime(2024, 3, 15, 11, 0)), ...] # Convert time to position in day (0.0 = midnight, 0.5 = noon) noon = datetime ( 2024 , 3 , 15 , 12 , 0 ) pos = time_to_interval ( noon , offset = 0 ) # 0.0 (noon centered) pos = time_to_interval ( noon , offset = 0 , zero_center = False ) # 0.5
Development
Install for development with all optional dependencies:
# Clone the repository git clone https://github.com/felixnext/python-time-helper.git cd python-time-helper # Install with all extras using uv uv sync --all-extras # Run tests uv run pytest # Run linting and type checking uv run ruff check . uv run mypy time_helper
DateTimeWrapper
The library includes a DateTimeWrapper class that provides a fluent, object-oriented interface for datetime operations:
from time_helper import DateTimeWrapper # Create wrapper from various inputs dtw = DateTimeWrapper ( "2024-03-15 10:30:00" ) dtw = DateTimeWrapper ( datetime . now ()) dtw = DateTimeWrapper ( date ( 2024 , 3 , 15 )) dtw = DateTimeWrapper ( 1710501045 ) # Unix timestamp # Chainable operations result = ( DateTimeWrapper ( "2024-03-15 10:35:45" ) . make_aware ( "UTC" ) . round ( "H" ) . localize ( "Asia/Tokyo" ) . to_string ( "%Y-%m-%d %H:%M %Z" )) # Arithmetic operations tomorrow = dtw + timedelta ( days = 1 ) yesterday = dtw - timedelta ( days = 1 ) diff = tomorrow - yesterday # Returns timedelta # Comparison operations if dtw > DateTimeWrapper ( "2024-01-01" ): print ( "After new year" ) # Direct property access print ( f"Year: { dtw . year } , Month: { dtw . month } , Day: { dtw . day } " ) print ( f"Weekday: { dtw . weekday } " ) # 0=Monday, 6=Sunday # Timezone operations aware = dtw . make_aware ( "EST" ) unaware = aware . make_unaware () tokyo = aware . localize ( "Asia/Tokyo" ) # String conversion iso_str = dtw . to_string () # ISO format custom_str = dtw . to_string ( "%B %d, %Y" ) # "March 15, 2024" unix_ts = dtw . to_timestamp () # Unix timestamp
DST Support
The library includes comprehensive Daylight Saving Time (DST) support for handling timezone transitions:
from time_helper import is_dst_active , get_dst_transitions , next_dst_transition , make_aware # Check if DST is currently active summer_time = make_aware ( "2024-07-15 12:00:00" , "Europe/Berlin" ) is_dst_active ( summer_time ) # True (CEST is active) winter_time = make_aware ( "2024-01-15 12:00:00" , "Europe/Berlin" ) is_dst_active ( winter_time ) # False (CET is active) # Get all DST transitions for a timezone in a given year transitions = get_dst_transitions ( "Europe/Berlin" , 2024 ) # [ # {"type": "spring_forward", "date": datetime(2024, 3, 31, 2, 0, ...)}, # {"type": "fall_back", "date": datetime(2024, 10, 27, 3, 0, ...)} # ] # Find the next DST transition from a given datetime winter_dt = make_aware ( "2024-02-15 12:00:00" , "Europe/Berlin" ) next_trans = next_dst_transition ( winter_dt ) # {"type": "spring_forward", "date": datetime(2024, 3, 31, 2, 0, ...)} summer_dt = make_aware ( "2024-07-15 12:00:00" , "Europe/Berlin" ) next_trans = next_dst_transition ( summer_dt ) # {"type": "fall_back", "date": datetime(2024, 10, 27, 3, 0, ...)}
DST Features:
Automatic handling of "spring forward" and "fall back" transitions
Support for ambiguous times (when clocks fall back)
Robust handling of non-existent times (when clocks spring forward)
Works with all timezone databases that support DST
Natural Language Parsing
The library supports parsing natural language datetime expressions for intuitive date and time manipulation:
from time_helper import parse_natural , DateTimeWrapper from datetime import datetime # Basic relative expressions ref_date = datetime ( 2024 , 7 , 15 , 12 , 0 , 0 ) # Monday, July 15, 2024 # Time references now = parse_natural ( "now" ) today = parse_natural ( "today" , reference = ref_date ) tomorrow = parse_natural ( "tomorrow" , reference = ref_date ) yesterday = parse_natural ( "yesterday" , reference = ref_date ) # Weekday references monday = parse_natural ( "monday" , reference = ref_date ) # Current Monday next_monday = parse_natural ( "next monday" , reference = ref_date ) # Next Monday last_friday = parse_natural ( "last friday" , reference = ref_date ) # Previous Friday # Time expressions morning = parse_natural ( "morning" , reference = ref_date ) # 9:00 AM afternoon = parse_natural ( "afternoon" , reference = ref_date ) # 2:00 PM evening = parse_natural ( "evening" , reference = ref_date ) # 7:00 PM night = parse_natural ( "night" , reference = ref_date ) # 10:00 PM # Specific times nine_am = parse_natural ( "9am" , reference = ref_date ) two_thirty_pm = parse_natural ( "2:30pm" , reference = ref_date ) noon = parse_natural ( "noon" , reference = ref_date ) midnight = parse_natural ( "midnight" , reference = ref_date ) # Complex expressions tomorrow_9am = parse_natural ( "tomorrow at 9am" , reference = ref_date ) next_week = parse_natural ( "next week" , reference = ref_date ) last_month = parse_natural ( "last month" , reference = ref_date ) # Relative time offsets in_2_hours = parse_natural ( "in 2 hours" , reference = ref_date ) in_30_minutes = parse_natural ( "in 30 minutes" , reference = ref_date ) 2_ days_ago = parse_natural ( "2 days ago" , reference = ref_date ) 1_ week_ago = parse_natural ( "1 week ago" , reference = ref_date ) # Business day references next_business_day = parse_natural ( "next business day" , reference = ref_date ) last_business_day = parse_natural ( "last business day" , reference = ref_date ) # Weekend references this_weekend = parse_natural ( "this weekend" , reference = ref_date ) next_weekend = parse_natural ( "next weekend" , reference = ref_date ) # Date boundaries beginning_of_month = parse_natural ( "beginning of month" , reference = ref_date ) end_of_month = parse_natural ( "end of month" , reference = ref_date ) beginning_of_year = parse_natural ( "beginning of year" , reference = ref_date ) end_of_year = parse_natural ( "end of year" , reference = ref_date ) # Ordinal expressions first_of_month = parse_natural ( "first of the month" , reference = ref_date ) 15 th_next_month = parse_natural ( "15th of next month" , reference = ref_date )
Natural Language with DateTimeWrapper
The DateTimeWrapper class supports natural language parsing and provides additional methods for natural language operations:
from time_helper import DateTimeWrapper from datetime import timedelta # Create wrapper with natural language dtw = DateTimeWrapper ( "tomorrow at 9am" ) dtw = DateTimeWrapper ( "next monday" ) dtw = DateTimeWrapper ( "in 2 hours" ) # Chain operations with natural language result = ( DateTimeWrapper ( "tomorrow at 9am" ) . make_aware ( "UTC" ) . round ( "H" ) . localize ( "Asia/Tokyo" )) # Use natural language parsing with timedelta for offsets dtw = DateTimeWrapper ( "2024-07-15 12:00:00" ) tomorrow = dtw + timedelta ( days = 1 ) next_week = dtw + timedelta ( weeks = 1 ) in_2_hours = dtw + timedelta ( hours = 2 )
Supported Natural Language Patterns:
Time references: "now", "today", "tomorrow", "yesterday"
Weekdays: "monday", "tuesday", etc. with "next" and "last" modifiers
Time of day: "morning", "afternoon", "evening", "night", "noon", "midnight"
Specific times: "9am", "2:30pm", "14:30"
Time ranges: "this weekend", "next weekend", "next week", "last month"
Relative offsets: "in 2 hours", "3 days ago", "1 week ago"
Business days: "next business day", "last business day"
Date boundaries: "beginning of month", "end of year"
Ordinals: "first of the month", "15th of next month"
Complex expressions: "tomorrow at 9am", "next monday at 2:30pm"
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
License
This project is licensed under the MIT License - see the LICENSE file for details.