Metadata-Version: 2.4
Name: total-time-formatter
Version: 1.0.5
Summary: A flexible library to convert various time inputs into a total duration format (HH:MM:SS).
Author-email: Cibelle Maciel da Costa <cibellemaciel02@gmail.com>
License: # LICENSE
        Copyright (c) 2025 Cibelle Maciel da Costa
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/cibellemc/total-time-formatter/
Project-URL: Bug Tracker, https://github.com/cibellemc/total-time-formatter/issues
Keywords: datetime,timedelta,formatter,time,duration,hours,precision
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: openpyxl
Dynamic: license-file

# Total Time Formatter

[![PyPI Version](https://img.shields.io/pypi/v/total-time-formatter)](https://pypi.org/project/total-time-formatter/)
[![Python Versions](https://img.shields.io/pypi/pyversions/total-time-formatter)](https://pypi.org/project/total-time-formatter/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:

```bash
pip install total-time-formatter
```

### How to Use

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

```python
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.

```python
# 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.

```python
# 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.

```python
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.

```python
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.

```python
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.
