# ALT-time-utils
A collection of time-related utility functions for Python applications.
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/psf/black)
## Features
- 🌍 **UTC-first design**: All timestamps are UTC by default with timezone awareness
- 🔄 **Timezone conversions**: Easy conversion between UTC and local time
- 📅 **Multiple formats**: ISO 8601, file-friendly timestamps, and human-readable durations
- 🏷️ **Type hints**: Full type annotations for better IDE support
- ✅ **Well tested**: 100% test coverage
- 🚀 **Zero dependencies**: Uses only Python standard library
## Installation
```bash
pip install ALT-time-utils
```
## Quick Start
```python
from alt_time_utils import (
get_utc_timestamp,
get_utc_timestamp_string,
format_duration,
local_to_utc,
utc_to_local
)
# Get current UTC time
utc_now = get_utc_timestamp()
print(utc_now) # 2025-01-15 12:30:45.123456+00:00
# Get UTC timestamp as string with 'Z' suffix
utc_string = get_utc_timestamp_string()
print(utc_string) # 2025-01-15T12:30:45.123456Z
# Convert local time to UTC
from datetime import datetime
local_time = datetime.now()
utc_time = local_to_utc(local_time)
# Format duration in human-readable format
duration = format_duration(3665.5)
print(duration) # 1h 1m 5.5s
```
## API Reference
### Timestamp Functions
#### `get_utc_timestamp() -> datetime`
Get the current UTC timestamp with timezone info.
```python
>>> utc_time = get_utc_timestamp()
>>> print(utc_time.tzinfo)
datetime.timezone.utc
```
#### `get_utc_timestamp_string() -> str`
Get the current UTC timestamp as an ISO format string with 'Z' suffix.
```python
>>> timestamp = get_utc_timestamp_string()
>>> print(timestamp)
'2025-01-15T12:30:45.123456Z'
```
#### `get_local_timestamp() -> datetime`
Get the current timestamp in the local timezone.
```python
>>> local_time = get_local_timestamp()
>>> print(local_time.tzinfo)
<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>
```
### Timezone Conversion
#### `local_to_utc(local_dt: datetime) -> datetime`
Convert a local datetime to UTC. Handles both naive and timezone-aware datetimes.
```python
>>> from datetime import datetime
>>> local = datetime.now() # Naive datetime
>>> utc = local_to_utc(local)
>>> print(utc.tzinfo)
datetime.timezone.utc
```
#### `utc_to_local(utc_dt: datetime) -> datetime`
Convert a UTC datetime to local timezone.
```python
>>> from datetime import datetime, timezone
>>> utc = datetime.now(timezone.utc)
>>> local = utc_to_local(utc)
>>> print(local.tzinfo)
<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>
```
### Formatting Functions
#### `get_file_timestamp() -> str`
Get timestamp formatted for filenames (YYYYMMDD_HHMMSS).
```python
>>> timestamp = get_file_timestamp()
>>> print(timestamp)
'20250115_123045'
```
#### `get_date_string() -> str`
Get the current date as a string (YYYYMMDD).
```python
>>> date_str = get_date_string()
>>> print(date_str)
'20250115'
```
#### `get_time_string() -> str`
Get the current time as a string (HHMMSS).
```python
>>> time_str = get_time_string()
>>> print(time_str)
'123045'
```
#### `format_duration(seconds: float) -> str`
Format a duration in seconds to a human-readable string.
```python
>>> format_duration(0.123)
'123ms'
>>> format_duration(45.6)
'45.6s'
>>> format_duration(3665.5)
'1h 1m 5.5s'
>>> format_duration(-5)
'0s'
```
### Utility Functions
#### `get_local_timezone_name() -> str`
Get the name of the local timezone.
```python
>>> tz_name = get_local_timezone_name()
>>> print(tz_name)
'EST'
```
#### `get_local_utc_offset() -> str`
Get the local timezone's UTC offset as a string.
```python
>>> offset = get_local_utc_offset()
>>> print(offset)
'-05:00'
```
#### `format_utc_timestamp(dt: datetime) -> str`
Format any datetime as UTC ISO string with 'Z' suffix.
```python
>>> from datetime import datetime
>>> dt = datetime.now()
>>> formatted = format_utc_timestamp(dt)
>>> print(formatted)
'2025-01-15T12:30:45.123456Z'
```
## Examples
### Working with Log Files
```python
from alt_time_utils import get_file_timestamp, get_date_string
import os
# Create timestamped log file
timestamp = get_file_timestamp()
log_file = f"app_{timestamp}.log"
# Organize logs by date
date_dir = get_date_string()
os.makedirs(f"logs/{date_dir}", exist_ok=True)
```
### Duration Tracking
```python
from alt_time_utils import get_utc_timestamp, format_duration
start_time = get_utc_timestamp()
# ... do some work ...
end_time = get_utc_timestamp()
duration = (end_time - start_time).total_seconds()
print(f"Operation took: {format_duration(duration)}")
```
### Timezone-Aware Operations
```python
from alt_time_utils import local_to_utc, utc_to_local, get_local_utc_offset
from datetime import datetime
# Schedule something in local time, store in UTC
local_scheduled = datetime(2025, 1, 20, 9, 0, 0) # 9 AM local
utc_scheduled = local_to_utc(local_scheduled)
# Display in user's timezone
user_local = utc_to_local(utc_scheduled)
offset = get_local_utc_offset()
print(f"Meeting at {user_local.strftime('%I:%M %p')} ({offset})")
```
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/Avilir/time_utils.git
cd time_utils
# Set up development environment
./scripts/setup_dev.sh
# Or using make
make setup
```
### Running Tests
```bash
# Using make
make test
# Using script
./scripts/run_tests.sh
# Or directly with pytest
python -m pytest
```
### Code Quality
```bash
# Run all checks
make all
# Individual checks
make lint # Run linting
make type-check # Run type checking
make format # Format code
```
### Building
```bash
# Build distributions
make build
# Or using script
./scripts/build.sh
```
## Contributing
Contributions are welcome! Please follow these guidelines:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes with tests
4. Run `make all` to ensure quality
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
**Avi Layani** - [alayani@redhat.com](mailto:alayani@redhat.com)
## Acknowledgments
- Inspired by the need for consistent time handling across Python projects
Raw data
{
"_id": null,
"home_page": null,
"name": "ALT-time-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Avi Layani <alayani@redhat.com>",
"keywords": "time, datetime, timezone, utilities, formatting",
"author": null,
"author_email": "Avi Layani <alayani@redhat.com>",
"download_url": "https://files.pythonhosted.org/packages/42/9e/1164b747ec4377895a27d7546ea76a58c846f72e9c225a119e847c29744f/alt_time_utils-0.1.1.tar.gz",
"platform": null,
"description": "# ALT-time-utils\n\nA collection of time-related utility functions for Python applications.\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://github.com/psf/black)\n\n## Features\n\n- \ud83c\udf0d **UTC-first design**: All timestamps are UTC by default with timezone awareness\n- \ud83d\udd04 **Timezone conversions**: Easy conversion between UTC and local time\n- \ud83d\udcc5 **Multiple formats**: ISO 8601, file-friendly timestamps, and human-readable durations\n- \ud83c\udff7\ufe0f **Type hints**: Full type annotations for better IDE support\n- \u2705 **Well tested**: 100% test coverage\n- \ud83d\ude80 **Zero dependencies**: Uses only Python standard library\n\n## Installation\n\n```bash\npip install ALT-time-utils\n```\n\n## Quick Start\n\n```python\nfrom alt_time_utils import (\n get_utc_timestamp,\n get_utc_timestamp_string,\n format_duration,\n local_to_utc,\n utc_to_local\n)\n\n# Get current UTC time\nutc_now = get_utc_timestamp()\nprint(utc_now) # 2025-01-15 12:30:45.123456+00:00\n\n# Get UTC timestamp as string with 'Z' suffix\nutc_string = get_utc_timestamp_string()\nprint(utc_string) # 2025-01-15T12:30:45.123456Z\n\n# Convert local time to UTC\nfrom datetime import datetime\nlocal_time = datetime.now()\nutc_time = local_to_utc(local_time)\n\n# Format duration in human-readable format\nduration = format_duration(3665.5)\nprint(duration) # 1h 1m 5.5s\n```\n\n## API Reference\n\n### Timestamp Functions\n\n#### `get_utc_timestamp() -> datetime`\nGet the current UTC timestamp with timezone info.\n\n```python\n>>> utc_time = get_utc_timestamp()\n>>> print(utc_time.tzinfo)\ndatetime.timezone.utc\n```\n\n#### `get_utc_timestamp_string() -> str`\nGet the current UTC timestamp as an ISO format string with 'Z' suffix.\n\n```python\n>>> timestamp = get_utc_timestamp_string()\n>>> print(timestamp)\n'2025-01-15T12:30:45.123456Z'\n```\n\n#### `get_local_timestamp() -> datetime`\nGet the current timestamp in the local timezone.\n\n```python\n>>> local_time = get_local_timestamp()\n>>> print(local_time.tzinfo)\n<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>\n```\n\n### Timezone Conversion\n\n#### `local_to_utc(local_dt: datetime) -> datetime`\nConvert a local datetime to UTC. Handles both naive and timezone-aware datetimes.\n\n```python\n>>> from datetime import datetime\n>>> local = datetime.now() # Naive datetime\n>>> utc = local_to_utc(local)\n>>> print(utc.tzinfo)\ndatetime.timezone.utc\n```\n\n#### `utc_to_local(utc_dt: datetime) -> datetime`\nConvert a UTC datetime to local timezone.\n\n```python\n>>> from datetime import datetime, timezone\n>>> utc = datetime.now(timezone.utc)\n>>> local = utc_to_local(utc)\n>>> print(local.tzinfo)\n<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>\n```\n\n### Formatting Functions\n\n#### `get_file_timestamp() -> str`\nGet timestamp formatted for filenames (YYYYMMDD_HHMMSS).\n\n```python\n>>> timestamp = get_file_timestamp()\n>>> print(timestamp)\n'20250115_123045'\n```\n\n#### `get_date_string() -> str`\nGet the current date as a string (YYYYMMDD).\n\n```python\n>>> date_str = get_date_string()\n>>> print(date_str)\n'20250115'\n```\n\n#### `get_time_string() -> str`\nGet the current time as a string (HHMMSS).\n\n```python\n>>> time_str = get_time_string()\n>>> print(time_str)\n'123045'\n```\n\n#### `format_duration(seconds: float) -> str`\nFormat a duration in seconds to a human-readable string.\n\n```python\n>>> format_duration(0.123)\n'123ms'\n>>> format_duration(45.6)\n'45.6s'\n>>> format_duration(3665.5)\n'1h 1m 5.5s'\n>>> format_duration(-5)\n'0s'\n```\n\n### Utility Functions\n\n#### `get_local_timezone_name() -> str`\nGet the name of the local timezone.\n\n```python\n>>> tz_name = get_local_timezone_name()\n>>> print(tz_name)\n'EST'\n```\n\n#### `get_local_utc_offset() -> str`\nGet the local timezone's UTC offset as a string.\n\n```python\n>>> offset = get_local_utc_offset()\n>>> print(offset)\n'-05:00'\n```\n\n#### `format_utc_timestamp(dt: datetime) -> str`\nFormat any datetime as UTC ISO string with 'Z' suffix.\n\n```python\n>>> from datetime import datetime\n>>> dt = datetime.now()\n>>> formatted = format_utc_timestamp(dt)\n>>> print(formatted)\n'2025-01-15T12:30:45.123456Z'\n```\n\n## Examples\n\n### Working with Log Files\n\n```python\nfrom alt_time_utils import get_file_timestamp, get_date_string\nimport os\n\n# Create timestamped log file\ntimestamp = get_file_timestamp()\nlog_file = f\"app_{timestamp}.log\"\n\n# Organize logs by date\ndate_dir = get_date_string()\nos.makedirs(f\"logs/{date_dir}\", exist_ok=True)\n```\n\n### Duration Tracking\n\n```python\nfrom alt_time_utils import get_utc_timestamp, format_duration\n\nstart_time = get_utc_timestamp()\n\n# ... do some work ...\n\nend_time = get_utc_timestamp()\nduration = (end_time - start_time).total_seconds()\nprint(f\"Operation took: {format_duration(duration)}\")\n```\n\n### Timezone-Aware Operations\n\n```python\nfrom alt_time_utils import local_to_utc, utc_to_local, get_local_utc_offset\nfrom datetime import datetime\n\n# Schedule something in local time, store in UTC\nlocal_scheduled = datetime(2025, 1, 20, 9, 0, 0) # 9 AM local\nutc_scheduled = local_to_utc(local_scheduled)\n\n# Display in user's timezone\nuser_local = utc_to_local(utc_scheduled)\noffset = get_local_utc_offset()\nprint(f\"Meeting at {user_local.strftime('%I:%M %p')} ({offset})\")\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/Avilir/time_utils.git\ncd time_utils\n\n# Set up development environment\n./scripts/setup_dev.sh\n\n# Or using make\nmake setup\n```\n\n### Running Tests\n\n```bash\n# Using make\nmake test\n\n# Using script\n./scripts/run_tests.sh\n\n# Or directly with pytest\npython -m pytest\n```\n\n### Code Quality\n\n```bash\n# Run all checks\nmake all\n\n# Individual checks\nmake lint # Run linting\nmake type-check # Run type checking\nmake format # Format code\n```\n\n### Building\n\n```bash\n# Build distributions\nmake build\n\n# Or using script\n./scripts/build.sh\n```\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Run `make all` to ensure quality\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Avi Layani** - [alayani@redhat.com](mailto:alayani@redhat.com)\n\n## Acknowledgments\n\n- Inspired by the need for consistent time handling across Python projects\n",
"bugtrack_url": null,
"license": null,
"summary": "A collection of time-related utility functions for Python",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/Avilir/time_utils/issues",
"Homepage": "https://github.com/Avilir/time_utils",
"Repository": "https://github.com/Avilir/time_utils"
},
"split_keywords": [
"time",
" datetime",
" timezone",
" utilities",
" formatting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cb1aead5745472bfd7ac6ad4e4a7288f4b6f1c1f67bfa28c20c754118680677d",
"md5": "c5439ce2fa516af20720aa7bb692320c",
"sha256": "d08bd69d00bcd65cb37232db1784ca91c163c36817311a0e10fb8126c88646e0"
},
"downloads": -1,
"filename": "alt_time_utils-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5439ce2fa516af20720aa7bb692320c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8263,
"upload_time": "2025-09-04T12:31:12",
"upload_time_iso_8601": "2025-09-04T12:31:12.326782Z",
"url": "https://files.pythonhosted.org/packages/cb/1a/ead5745472bfd7ac6ad4e4a7288f4b6f1c1f67bfa28c20c754118680677d/alt_time_utils-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "429e1164b747ec4377895a27d7546ea76a58c846f72e9c225a119e847c29744f",
"md5": "90aa241feb97767c92e8bd13941671e0",
"sha256": "92cb6f230afa3479421bb015a97f2e4cbdf69327c8c8bc83943d9b6d51c65e28"
},
"downloads": -1,
"filename": "alt_time_utils-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "90aa241feb97767c92e8bd13941671e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10016,
"upload_time": "2025-09-04T12:31:13",
"upload_time_iso_8601": "2025-09-04T12:31:13.699289Z",
"url": "https://files.pythonhosted.org/packages/42/9e/1164b747ec4377895a27d7546ea76a58c846f72e9c225a119e847c29744f/alt_time_utils-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 12:31:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Avilir",
"github_project": "time_utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "alt-time-utils"
}
JSON
