| Name | total-time-formatter JSON |
| Version |
1.0.4
JSON |
| download |
| home_page | None |
| Summary | A flexible library to convert various time inputs into a total duration format (HH:MM:SS). |
| upload_time | 2025-08-10 11:27:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| 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. |
| keywords |
datetime
timedelta
formatter
time
duration
hours
precision
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
build
twine
pandas
openpyxl
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Total Time Formatter
[](https://pypi.org/project/total-time-formatter/)
[](https://pypi.org/project/total-time-formatter/)
[](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 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
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_UP, 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"
# Expected: 2 full days (48h) + 10h = 58 hours from reference
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.
```python
# 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 = 84 hours from reference
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.
```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}")
# 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.
```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}")
```
### 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "total-time-formatter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "datetime, timedelta, formatter, time, duration, hours, precision",
"author": null,
"author_email": "Cibelle Maciel da Costa <cibellemaciel02@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/07/2b/abb1bca3547d6caec4d837d9c3da6d060e412879c817ace35d0c548a2331/total_time_formatter-1.0.4.tar.gz",
"platform": null,
"description": "# Total Time Formatter\n\n[](https://pypi.org/project/total-time-formatter/)\n[](https://pypi.org/project/total-time-formatter/)\n[](https://opensource.org/licenses/MIT)\n\nA robust and versatile Python library to convert various time inputs into a total cumulative hours format (`HH:MM:SS`), where hours can exceed 24.\n\nThis 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.\n\n### Key Features\n\n* **Versatile Inputs**: Seamlessly handles a wide variety of types: `str`, `datetime.timedelta`, `datetime.datetime`, `pandas.Timestamp`, and `datetime.time`.\n* **Total Hour Calculation**: Correctly calculates total hours from inputs that include date information, allowing hour counts well beyond 24.\n* **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.\n* **Customizable Reference Date**: Allows setting a custom start date for duration calculations.\n* **Pandas-Friendly**: Designed to integrate perfectly with pandas DataFrames via the `.apply()` method.\n* **Dependency-Free**: Pure Python with no external dependencies required for its core logic.\n\n### Installation\n\nInstall the latest official version from PyPI:\n\n```bash\npip install total-time-formatter\n```\n\n### How to Use\n\nImport the main function and the precision mode constants to get started.\n\n```python\nfrom total_time_formatter import format_total_hours, TRUNCATE, ROUND_UP, KEEP_PRECISION\nfrom datetime import datetime, timedelta, time\n```\n\n#### 1. Basic Usage with Strings\n\nThe function can intelligently parse different string formats.\n\n```python\n# A full datetime string (calculates duration from default reference '1899-12-31')\ndate_str = \"1900-01-02 10:30:15\" \n# Expected: 2 full days (48h) + 10h = 58 hours from reference\nprint(f\"Full Datetime String: {format_total_hours(date_str)}\")\n\n# A time-only string (treated as a direct duration)\nduration_str = \"58:30:15\"\nprint(f\"Duration String: {format_total_hours(duration_str)}\")\n```\n\n#### 2. Handling Different Object Types\n\nThe library automatically recognizes common Python time objects.\n\n```python\n# A timedelta object\ntd_obj = timedelta(hours=75, minutes=5, seconds=22)\nprint(f\"Timedelta Object: {format_total_hours(td_obj)}\")\n\n# A datetime object\ndt_obj = datetime(1900, 1, 3, 12, 0, 0) # 3 full days + 12h = 84 hours from reference\nprint(f\"Datetime Object: {format_total_hours(dt_obj)}\")\n\n# A time object (treated as a duration from midnight)\ntime_obj = time(hour=5, minute=10, second=3)\nprint(f\"Time Object: {format_total_hours(time_obj)}\")\n```\n\n#### 3. Controlling Precision (`precision_mode`)\n\nThis is a key feature for controlling how fractional seconds are handled.\n\n```python\ntime_with_ms = \"10:20:30.789123\"\n\n# Truncate (default behavior)\ntruncated = format_total_hours(time_with_ms, precision_mode=TRUNCATE)\nprint(f\"Truncated: {truncated}\")\n\n# Round Up\nrounded = format_total_hours(time_with_ms, precision_mode=ROUND_UP)\nprint(f\"Rounded Up: {rounded}\")\n\n# Keep Exact Precision\nprecise = format_total_hours(time_with_ms, precision_mode=KEEP_PRECISION)\nprint(f\"Precise: {precise}\")\n```\n\n#### 4. Advanced Usage: Custom Reference Date\n\nYou can override the default reference date for duration calculations.\n\n```python\ntarget_date = \"2024-01-10 12:00:00\"\ncustom_ref_date = \"2024-01-01 00:00:00\"\n\n# Calculates duration from the start of 2024\n# Expected: 9 days (216h) + 12h = 228 hours\nduration = format_total_hours(target_date, reference_date=custom_ref_date)\nprint(f\"Duration from custom reference: {duration}\")\n```\n\n### Integration with Pandas\n\nThe library is designed to work perfectly with pandas via `.apply()`, automatically handling the various data types that pandas can produce when reading data.\n\n```python\nimport pandas as pd\n\n# Sample DataFrame simulating data read from a file\ndata = {\n 'raw_time_data': [\n datetime(1900, 1, 2, 10, 0, 0), # A datetime object\n \"75:30:15\", # A duration string\n time(4, 15, 20), # A time object\n None # A null value\n ]\n}\ndf = pd.DataFrame(data)\n\n# Apply the function to create a new, clean column\ndf['formatted_duration'] = df['raw_time_data'].apply(format_total_hours)\n\nprint(df)\n```\n\n### License\n\nThis project is licensed under the MIT License - see the `LICENSE` file for details.\n",
"bugtrack_url": null,
"license": "# LICENSE\n Copyright (c) 2025 Cibelle Maciel da Costa\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A flexible library to convert various time inputs into a total duration format (HH:MM:SS).",
"version": "1.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/cibellemc/total-time-formatter/issues",
"Homepage": "https://github.com/cibellemc/total-time-formatter/"
},
"split_keywords": [
"datetime",
" timedelta",
" formatter",
" time",
" duration",
" hours",
" precision"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "44e415ae62f1662a15f0a0c99a42bfbd0071f123e978e86c0db5413fe4a34f4a",
"md5": "463d9a7b654bb499d9e6da71e828ef05",
"sha256": "ac32d8696d87ead9acb02cd54b18eb01aadd2cc1cd790c0f83038119e6d26313"
},
"downloads": -1,
"filename": "total_time_formatter-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "463d9a7b654bb499d9e6da71e828ef05",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6829,
"upload_time": "2025-08-10T11:27:05",
"upload_time_iso_8601": "2025-08-10T11:27:05.742106Z",
"url": "https://files.pythonhosted.org/packages/44/e4/15ae62f1662a15f0a0c99a42bfbd0071f123e978e86c0db5413fe4a34f4a/total_time_formatter-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "072babb1bca3547d6caec4d837d9c3da6d060e412879c817ace35d0c548a2331",
"md5": "e5b34488cbc866668312fea214bcb0ae",
"sha256": "17f617851b90d8e06802d4922d22f65a0728c8568ec62e7d2e5dfc5e7ffa30f7"
},
"downloads": -1,
"filename": "total_time_formatter-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "e5b34488cbc866668312fea214bcb0ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6661,
"upload_time": "2025-08-10T11:27:07",
"upload_time_iso_8601": "2025-08-10T11:27:07.179171Z",
"url": "https://files.pythonhosted.org/packages/07/2b/abb1bca3547d6caec4d837d9c3da6d060e412879c817ace35d0c548a2331/total_time_formatter-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 11:27:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cibellemc",
"github_project": "total-time-formatter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "build",
"specs": []
},
{
"name": "twine",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "openpyxl",
"specs": []
}
],
"lcname": "total-time-formatter"
}
