total-time-formatter 1.0.6.1

A flexible library to convert various time inputs into a total duration format (HH:MM:SS).

Total Time Formatter

A robust and versatile Python library to convert various time inputs into a total cumulative hours format (HH:MM:SS), where hours can exceed 24.

This tool is perfect for applications that need to calculate and display total durations, such as project time tracking, data analysis pipelines, equipment runtime logs, or simply formatting time data consistently.

Key Features

• Versatile Inputs: Seamlessly handles a wide variety of types: str, datetime.timedelta, datetime.datetime, pandas.Timestamp, and datetime.time.
• Total Hour Calculation: Correctly calculates total hours from inputs that include date information, allowing hour counts well beyond 24.
• High Precision Control: Offers precise control over how fractional seconds are handled: truncate, round, or keep the exact original precision down to the microsecond.
• Customizable Reference Date: Allows setting a custom start date for duration calculations.
• Pandas-Friendly: Designed to integrate perfectly with pandas DataFrames via the .apply() method.

Installation

Install the latest official version from PyPI:

pip install total-time-formatter

How to Use

Import the main function and the precision mode constants to get started.

from total_time_formatter import format_total_hours, TRUNCATE, ROUND, KEEP_PRECISION
from datetime import datetime, timedelta, time

1. Basic Usage with Strings

The function can intelligently parse different string formats.

# A full datetime string (calculates duration from default reference '1899-12-31')
date_str = "1900-01-02 10:30:15" 
print(f"Full Datetime String: {format_total_hours(date_str)}") # 58:30:15

# A time-only string (treated as a direct duration)
duration_str = "58:30:15"
print(f"Duration String: {format_total_hours(duration_str)}") # 58:30:15

2. Handling Different Object Types

The library automatically recognizes common Python time objects.

# A timedelta object
td_obj = timedelta(hours=75, minutes=5, seconds=22)
print(f"Timedelta Object: {format_total_hours(td_obj)}") # 75:05:22

# A datetime object
dt_obj = datetime(1900, 1, 3, 12, 0, 0) # 3 full days + 12h = 84 hours from reference
print(f"Datetime Object: {format_total_hours(dt_obj)}") # 84:00:00

# A time object (treated as a duration from midnight)
time_obj = time(hour=5, minute=10, second=3)
print(f"Time Object: {format_total_hours(time_obj)}") # 05:10:03

3. Controlling Precision (precision_mode)

This is a key feature for controlling how fractional seconds are handled.

time_with_ms = "10:20:30.789123"

# Truncate (default behavior)
truncated = format_total_hours(time_with_ms, precision_mode=TRUNCATE)
print(f"Truncated: {truncated}") # 10:20:30

# Round
rounded = format_total_hours(time_with_ms, precision_mode=ROUND)
print(f"Rounded: {rounded}") # 10:20:31

# Keep Exact Precision
precise = format_total_hours(time_with_ms, precision_mode=KEEP_PRECISION)
print(f"Precise: {precise}") # 10:20:31.789123

4. Advanced Usage: Custom Reference Date

You can override the default reference date for duration calculations.

target_date = "2024-01-10 12:00:00"
custom_ref_date = "2024-01-01 00:00:00"

# Calculates duration from the start of 2024
# Expected: 9 days (216h) + 12h = 228 hours
duration = format_total_hours(target_date, reference_date=custom_ref_date)
print(f"Duration from custom reference: {duration}") # 228:00:00

Integration with Pandas

The library is designed to work perfectly with pandas via .apply(), automatically handling the various data types that pandas can produce when reading data.

import pandas as pd

# Sample DataFrame simulating data read from a file
data = {
    'raw_time_data': [
        datetime(1900, 1, 2, 10, 0, 0), # A datetime object
        "75:30:15",                      # A duration string
        time(4, 15, 20),                 # A time object
        None                             # A null value
    ]
}
df = pd.DataFrame(data)

# Apply the function to create a new, clean column
df['formatted_duration'] = df['raw_time_data'].apply(format_total_hours)

print(df)

License

This project is licensed under the MIT License - see the LICENSE file for details.