total-time-formatter 1.0.3

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 up, 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.
• Dependency-Free: Pure Python with no external dependencies required for its core logic.

Installation (from TestPyPI)

Note: This package is currently available on TestPyPI for testing purposes. To install it, you must specify the index URL:

pip install --index-url [https://test.pypi.org/simple/](https://test.pypi.org/simple/) 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_UP, 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" 
# Expected: 1 full day (24h) + 1 day (24h) + 10h = 58 hours
print(f"Full Datetime String: {format_total_hours(date_str)}")

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

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)}")

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

# 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)}")

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}")

# Round Up
rounded = format_total_hours(time_with_ms, precision_mode=ROUND_UP)
print(f"Rounded Up: {rounded}")

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

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}")

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.