| Name | time-helper JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | A Python time helper library |
| upload_time | 2025-07-21 10:15:25 |
| maintainer | Felix Geilert |
| docs_url | None |
| author | Felix Geilert |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2022 Felix Geilert
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
helper
time
timezone
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Time Helper
A lightweight Python library for effortless datetime handling with timezone support. Built for simplicity and flexibility, it provides a comprehensive set of utilities for parsing, converting, and manipulating dates and times.
**Key Features:**
- 🌍 **Timezone-aware operations** with abbreviation support (e.g., IST, PST, CET)
- 🔄 **Universal datetime parsing** from strings, timestamps, and various formats
- 📊 **Optional pandas/numpy integration** for DataFrame operations
- 🎯 **Simple, intuitive API** with one-line conversions
- 🐍 **Modern Python 3.10+** with full type hints
## Installation
### Basic Installation
For core datetime functionality without heavy dependencies:
```bash
# Using pip
pip install time-helper
# Using uv (recommended)
uv add time-helper
```
### With Optional Dependencies
Add pandas and/or numpy support for DataFrame operations and advanced array handling:
```bash
# With pandas support (includes DataFrame/Series datetime operations)
pip install time-helper[pandas]
uv add time-helper[pandas]
# With numpy support (for numpy datetime64 conversions)
pip install time-helper[numpy]
uv add time-helper[numpy]
# With both pandas and numpy
pip install time-helper[pandas,numpy]
uv add time-helper[pandas,numpy]
```
## Quick Start
```python
from time_helper import any_to_datetime, make_aware, round_time
# Parse any datetime format automatically
dt = any_to_datetime("2024-03-15 10:30:45")
dt = any_to_datetime(1710501045) # Unix timestamp
dt = any_to_datetime("15/03/2024", date_format="%d/%m/%Y")
# Make timezone-aware (auto-detects system timezone)
aware_dt = make_aware("2024-03-15")
# > datetime.datetime(2024, 3, 15, 0, 0, tzinfo=ZoneInfo('America/New_York'))
# Convert between timezones using abbreviations
from time_helper import localize_datetime
tokyo_time = localize_datetime(aware_dt, "JST") # Japan Standard Time
delhi_time = localize_datetime(aware_dt, "IST") # Indian Standard Time
# Round to nearest hour, day, week, etc.
rounded = round_time(dt, "H") # Hour
rounded = round_time(dt, "D", max_out=True) # End of day (23:59:59.999999)
```
## Features
### 🔄 Universal DateTime Parsing
The `any_to_datetime` function intelligently parses various datetime formats:
```python
from time_helper import any_to_datetime
from datetime import date
# Parse different formats automatically
dt = any_to_datetime("2024-03-19") # ISO date
dt = any_to_datetime("2024-03-19 20:15:30") # ISO datetime
dt = any_to_datetime("19/03/2024", date_format="%d/%m/%Y") # Custom format
dt = any_to_datetime(1710501045) # Unix timestamp
dt = any_to_datetime(date(2024, 3, 19)) # Python date object
dt = any_to_datetime("2024-03-19T15:30:00.123Z") # ISO with milliseconds
```
### 🌍 Timezone Operations
Seamlessly work with timezones using names or abbreviations:
```python
from time_helper import make_aware, make_unaware, localize_datetime, current_timezone
# Auto-detect system timezone
current_tz = current_timezone()
# Make timezone-aware using system timezone
aware_dt = make_aware("2024-03-15")
# Explicit timezone
utc_dt = make_aware("2024-03-15", "UTC")
tokyo_dt = make_aware("2024-03-15", "Asia/Tokyo")
# Use timezone abbreviations (automatically mapped)
ist_dt = make_aware("2024-03-15", "IST") # Maps to Asia/Kolkata
pst_dt = make_aware("2024-03-15", "PST") # Maps to America/Los_Angeles
# Convert between timezones
ny_time = localize_datetime(utc_dt, "America/New_York")
berlin_time = localize_datetime(utc_dt, "Europe/Berlin")
# Remove timezone information
unaware_dt = make_unaware(aware_dt) # Keeps the time as-is
unaware_utc = make_unaware(berlin_time, "UTC") # Converts to UTC first
```
### ⏰ DateTime Operations
Powerful operations for datetime manipulation:
```python
from time_helper import round_time, time_diff
# Round to various frequencies
dt = any_to_datetime("2024-03-15 14:35:27.123456")
# Round down (floor)
hour_start = round_time(dt, "H") # 2024-03-15 14:00:00
day_start = round_time(dt, "D") # 2024-03-15 00:00:00
week_start = round_time(dt, "W") # 2024-03-11 00:00:00 (Monday)
month_start = round_time(dt, "m") # 2024-03-01 00:00:00
year_start = round_time(dt, "Y") # 2024-01-01 00:00:00
# Round up (ceiling) with max_out=True
hour_end = round_time(dt, "H", max_out=True) # 2024-03-15 14:59:59.999999
day_end = round_time(dt, "D", max_out=True) # 2024-03-15 23:59:59.999999
week_end = round_time(dt, "W", max_out=True) # 2024-03-17 23:59:59.999999
# Calculate timezone-aware differences
tokyo = make_aware("2024-03-15 10:00", "Asia/Tokyo")
london = make_aware("2024-03-15 10:00", "Europe/London")
diff = time_diff(tokyo, london) # -9 hours difference
```
### 📊 Pandas Integration (Optional)
When pandas is installed, additional DataFrame operations become available:
```python
import pandas as pd
from time_helper import make_aware, has_timezone
# Create sample DataFrame
df = pd.DataFrame({
'timestamp': ['2024-03-15 10:00', '2024-03-16 15:30'],
'event': ['start', 'end']
})
# Make timezone-aware
df = make_aware(df, col='timestamp', tz='UTC')
# Check timezone presence
has_tz = has_timezone(df, 'timestamp') # True
# Convert timezone
df = make_aware(df, col='timestamp', tz='America/New_York')
```
### 📈 Time Range Operations
Create and manipulate time intervals:
```python
from time_helper import create_intervals, time_to_interval
from datetime import datetime, timedelta
start = datetime(2024, 3, 15, 9, 0)
end = datetime(2024, 3, 15, 17, 0)
# Create hourly intervals
hourly = create_intervals(start, end, interval=timedelta(hours=1))
# [(datetime(2024, 3, 15, 9, 0), datetime(2024, 3, 15, 10, 0)),
# (datetime(2024, 3, 15, 10, 0), datetime(2024, 3, 15, 11, 0)), ...]
# Convert time to position in day (0.0 = midnight, 0.5 = noon)
noon = datetime(2024, 3, 15, 12, 0)
pos = time_to_interval(noon, offset=0) # 0.0 (noon centered)
pos = time_to_interval(noon, offset=0, zero_center=False) # 0.5
```
## Development
Install for development with all optional dependencies:
```bash
# Clone the repository
git clone https://github.com/felixnext/python-time-helper.git
cd python-time-helper
# Install with all extras using uv
uv sync --all-extras
# Run tests
uv run pytest
# Run linting and type checking
uv run ruff check .
uv run mypy time_helper
```
## DateTimeWrapper
The library includes a `DateTimeWrapper` class that provides a fluent, object-oriented interface for datetime operations:
```python
from time_helper import DateTimeWrapper
# Create wrapper from various inputs
dtw = DateTimeWrapper("2024-03-15 10:30:00")
dtw = DateTimeWrapper(datetime.now())
dtw = DateTimeWrapper(date(2024, 3, 15))
dtw = DateTimeWrapper(1710501045) # Unix timestamp
# Chainable operations
result = (DateTimeWrapper("2024-03-15 10:35:45")
.make_aware("UTC")
.round("H")
.localize("Asia/Tokyo")
.to_string("%Y-%m-%d %H:%M %Z"))
# Arithmetic operations
tomorrow = dtw + timedelta(days=1)
yesterday = dtw - timedelta(days=1)
diff = tomorrow - yesterday # Returns timedelta
# Comparison operations
if dtw > DateTimeWrapper("2024-01-01"):
print("After new year")
# Direct property access
print(f"Year: {dtw.year}, Month: {dtw.month}, Day: {dtw.day}")
print(f"Weekday: {dtw.weekday}") # 0=Monday, 6=Sunday
# Timezone operations
aware = dtw.make_aware("EST")
unaware = aware.make_unaware()
tokyo = aware.localize("Asia/Tokyo")
# String conversion
iso_str = dtw.to_string() # ISO format
custom_str = dtw.to_string("%B %d, %Y") # "March 15, 2024"
unix_ts = dtw.to_timestamp() # Unix timestamp
```
## DST Support
The library includes comprehensive Daylight Saving Time (DST) support for handling timezone transitions:
```python
from time_helper import is_dst_active, get_dst_transitions, next_dst_transition, make_aware
# Check if DST is currently active
summer_time = make_aware("2024-07-15 12:00:00", "Europe/Berlin")
is_dst_active(summer_time) # True (CEST is active)
winter_time = make_aware("2024-01-15 12:00:00", "Europe/Berlin")
is_dst_active(winter_time) # False (CET is active)
# Get all DST transitions for a timezone in a given year
transitions = get_dst_transitions("Europe/Berlin", 2024)
# [
# {"type": "spring_forward", "date": datetime(2024, 3, 31, 2, 0, ...)},
# {"type": "fall_back", "date": datetime(2024, 10, 27, 3, 0, ...)}
# ]
# Find the next DST transition from a given datetime
winter_dt = make_aware("2024-02-15 12:00:00", "Europe/Berlin")
next_trans = next_dst_transition(winter_dt)
# {"type": "spring_forward", "date": datetime(2024, 3, 31, 2, 0, ...)}
summer_dt = make_aware("2024-07-15 12:00:00", "Europe/Berlin")
next_trans = next_dst_transition(summer_dt)
# {"type": "fall_back", "date": datetime(2024, 10, 27, 3, 0, ...)}
```
**DST Features:**
- Automatic handling of "spring forward" and "fall back" transitions
- Support for ambiguous times (when clocks fall back)
- Robust handling of non-existent times (when clocks spring forward)
- Works with all timezone databases that support DST
## Natural Language Parsing
The library supports parsing natural language datetime expressions for intuitive date and time manipulation:
```python
from time_helper import parse_natural, DateTimeWrapper
from datetime import datetime
# Basic relative expressions
ref_date = datetime(2024, 7, 15, 12, 0, 0) # Monday, July 15, 2024
# Time references
now = parse_natural("now")
today = parse_natural("today", reference=ref_date)
tomorrow = parse_natural("tomorrow", reference=ref_date)
yesterday = parse_natural("yesterday", reference=ref_date)
# Weekday references
monday = parse_natural("monday", reference=ref_date) # Current Monday
next_monday = parse_natural("next monday", reference=ref_date) # Next Monday
last_friday = parse_natural("last friday", reference=ref_date) # Previous Friday
# Time expressions
morning = parse_natural("morning", reference=ref_date) # 9:00 AM
afternoon = parse_natural("afternoon", reference=ref_date) # 2:00 PM
evening = parse_natural("evening", reference=ref_date) # 7:00 PM
night = parse_natural("night", reference=ref_date) # 10:00 PM
# Specific times
nine_am = parse_natural("9am", reference=ref_date)
two_thirty_pm = parse_natural("2:30pm", reference=ref_date)
noon = parse_natural("noon", reference=ref_date)
midnight = parse_natural("midnight", reference=ref_date)
# Complex expressions
tomorrow_9am = parse_natural("tomorrow at 9am", reference=ref_date)
next_week = parse_natural("next week", reference=ref_date)
last_month = parse_natural("last month", reference=ref_date)
# Relative time offsets
in_2_hours = parse_natural("in 2 hours", reference=ref_date)
in_30_minutes = parse_natural("in 30 minutes", reference=ref_date)
2_days_ago = parse_natural("2 days ago", reference=ref_date)
1_week_ago = parse_natural("1 week ago", reference=ref_date)
# Business day references
next_business_day = parse_natural("next business day", reference=ref_date)
last_business_day = parse_natural("last business day", reference=ref_date)
# Weekend references
this_weekend = parse_natural("this weekend", reference=ref_date)
next_weekend = parse_natural("next weekend", reference=ref_date)
# Date boundaries
beginning_of_month = parse_natural("beginning of month", reference=ref_date)
end_of_month = parse_natural("end of month", reference=ref_date)
beginning_of_year = parse_natural("beginning of year", reference=ref_date)
end_of_year = parse_natural("end of year", reference=ref_date)
# Ordinal expressions
first_of_month = parse_natural("first of the month", reference=ref_date)
15th_next_month = parse_natural("15th of next month", reference=ref_date)
```
### Natural Language with DateTimeWrapper
The `DateTimeWrapper` class supports natural language parsing and provides additional methods for natural language operations:
```python
from time_helper import DateTimeWrapper
from datetime import timedelta
# Create wrapper with natural language
dtw = DateTimeWrapper("tomorrow at 9am")
dtw = DateTimeWrapper("next monday")
dtw = DateTimeWrapper("in 2 hours")
# Chain operations with natural language
result = (DateTimeWrapper("tomorrow at 9am")
.make_aware("UTC")
.round("H")
.localize("Asia/Tokyo"))
# Use natural language parsing with timedelta for offsets
dtw = DateTimeWrapper("2024-07-15 12:00:00")
tomorrow = dtw + timedelta(days=1)
next_week = dtw + timedelta(weeks=1)
in_2_hours = dtw + timedelta(hours=2)
```
**Supported Natural Language Patterns:**
- Time references: "now", "today", "tomorrow", "yesterday"
- Weekdays: "monday", "tuesday", etc. with "next" and "last" modifiers
- Time of day: "morning", "afternoon", "evening", "night", "noon", "midnight"
- Specific times: "9am", "2:30pm", "14:30"
- Time ranges: "this weekend", "next weekend", "next week", "last month"
- Relative offsets: "in 2 hours", "3 days ago", "1 week ago"
- Business days: "next business day", "last business day"
- Date boundaries: "beginning of month", "end of year"
- Ordinals: "first of the month", "15th of next month"
- Complex expressions: "tomorrow at 9am", "next monday at 2:30pm"
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "time-helper",
"maintainer": "Felix Geilert",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "datetime, helper, time, timezone",
"author": "Felix Geilert",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/92/18/d2d6cdc1b95e4d3c6d791f3060eadc0f036344c7ce65c2ad010dea5014c4/time_helper-0.3.1.tar.gz",
"platform": null,
"description": "# Time Helper\n\nA lightweight Python library for effortless datetime handling with timezone support. Built for simplicity and flexibility, it provides a comprehensive set of utilities for parsing, converting, and manipulating dates and times.\n\n**Key Features:**\n- \ud83c\udf0d **Timezone-aware operations** with abbreviation support (e.g., IST, PST, CET)\n- \ud83d\udd04 **Universal datetime parsing** from strings, timestamps, and various formats\n- \ud83d\udcca **Optional pandas/numpy integration** for DataFrame operations\n- \ud83c\udfaf **Simple, intuitive API** with one-line conversions\n- \ud83d\udc0d **Modern Python 3.10+** with full type hints\n\n## Installation\n\n### Basic Installation\n\nFor core datetime functionality without heavy dependencies:\n\n```bash\n# Using pip\npip install time-helper\n\n# Using uv (recommended)\nuv add time-helper\n```\n\n### With Optional Dependencies\n\nAdd pandas and/or numpy support for DataFrame operations and advanced array handling:\n\n```bash\n# With pandas support (includes DataFrame/Series datetime operations)\npip install time-helper[pandas]\nuv add time-helper[pandas]\n\n# With numpy support (for numpy datetime64 conversions)\npip install time-helper[numpy]\nuv add time-helper[numpy]\n\n# With both pandas and numpy\npip install time-helper[pandas,numpy]\nuv add time-helper[pandas,numpy]\n```\n\n## Quick Start\n\n```python\nfrom time_helper import any_to_datetime, make_aware, round_time\n\n# Parse any datetime format automatically\ndt = any_to_datetime(\"2024-03-15 10:30:45\")\ndt = any_to_datetime(1710501045) # Unix timestamp\ndt = any_to_datetime(\"15/03/2024\", date_format=\"%d/%m/%Y\")\n\n# Make timezone-aware (auto-detects system timezone)\naware_dt = make_aware(\"2024-03-15\")\n# > datetime.datetime(2024, 3, 15, 0, 0, tzinfo=ZoneInfo('America/New_York'))\n\n# Convert between timezones using abbreviations\nfrom time_helper import localize_datetime\ntokyo_time = localize_datetime(aware_dt, \"JST\") # Japan Standard Time\ndelhi_time = localize_datetime(aware_dt, \"IST\") # Indian Standard Time\n\n# Round to nearest hour, day, week, etc.\nrounded = round_time(dt, \"H\") # Hour\nrounded = round_time(dt, \"D\", max_out=True) # End of day (23:59:59.999999)\n```\n\n## Features\n\n### \ud83d\udd04 Universal DateTime Parsing\n\nThe `any_to_datetime` function intelligently parses various datetime formats:\n\n```python\nfrom time_helper import any_to_datetime\nfrom datetime import date\n\n# Parse different formats automatically\ndt = any_to_datetime(\"2024-03-19\") # ISO date\ndt = any_to_datetime(\"2024-03-19 20:15:30\") # ISO datetime\ndt = any_to_datetime(\"19/03/2024\", date_format=\"%d/%m/%Y\") # Custom format\ndt = any_to_datetime(1710501045) # Unix timestamp\ndt = any_to_datetime(date(2024, 3, 19)) # Python date object\ndt = any_to_datetime(\"2024-03-19T15:30:00.123Z\") # ISO with milliseconds\n```\n\n### \ud83c\udf0d Timezone Operations\n\nSeamlessly work with timezones using names or abbreviations:\n\n```python\nfrom time_helper import make_aware, make_unaware, localize_datetime, current_timezone\n\n# Auto-detect system timezone\ncurrent_tz = current_timezone()\n\n# Make timezone-aware using system timezone\naware_dt = make_aware(\"2024-03-15\")\n\n# Explicit timezone\nutc_dt = make_aware(\"2024-03-15\", \"UTC\")\ntokyo_dt = make_aware(\"2024-03-15\", \"Asia/Tokyo\")\n\n# Use timezone abbreviations (automatically mapped)\nist_dt = make_aware(\"2024-03-15\", \"IST\") # Maps to Asia/Kolkata\npst_dt = make_aware(\"2024-03-15\", \"PST\") # Maps to America/Los_Angeles\n\n# Convert between timezones\nny_time = localize_datetime(utc_dt, \"America/New_York\")\nberlin_time = localize_datetime(utc_dt, \"Europe/Berlin\")\n\n# Remove timezone information\nunaware_dt = make_unaware(aware_dt) # Keeps the time as-is\nunaware_utc = make_unaware(berlin_time, \"UTC\") # Converts to UTC first\n```\n\n### \u23f0 DateTime Operations\n\nPowerful operations for datetime manipulation:\n\n```python\nfrom time_helper import round_time, time_diff\n\n# Round to various frequencies\ndt = any_to_datetime(\"2024-03-15 14:35:27.123456\")\n\n# Round down (floor)\nhour_start = round_time(dt, \"H\") # 2024-03-15 14:00:00\nday_start = round_time(dt, \"D\") # 2024-03-15 00:00:00\nweek_start = round_time(dt, \"W\") # 2024-03-11 00:00:00 (Monday)\nmonth_start = round_time(dt, \"m\") # 2024-03-01 00:00:00\nyear_start = round_time(dt, \"Y\") # 2024-01-01 00:00:00\n\n# Round up (ceiling) with max_out=True\nhour_end = round_time(dt, \"H\", max_out=True) # 2024-03-15 14:59:59.999999\nday_end = round_time(dt, \"D\", max_out=True) # 2024-03-15 23:59:59.999999\nweek_end = round_time(dt, \"W\", max_out=True) # 2024-03-17 23:59:59.999999\n\n# Calculate timezone-aware differences\ntokyo = make_aware(\"2024-03-15 10:00\", \"Asia/Tokyo\")\nlondon = make_aware(\"2024-03-15 10:00\", \"Europe/London\")\ndiff = time_diff(tokyo, london) # -9 hours difference\n```\n\n### \ud83d\udcca Pandas Integration (Optional)\n\nWhen pandas is installed, additional DataFrame operations become available:\n\n```python\nimport pandas as pd\nfrom time_helper import make_aware, has_timezone\n\n# Create sample DataFrame\ndf = pd.DataFrame({\n 'timestamp': ['2024-03-15 10:00', '2024-03-16 15:30'],\n 'event': ['start', 'end']\n})\n\n# Make timezone-aware\ndf = make_aware(df, col='timestamp', tz='UTC')\n\n# Check timezone presence\nhas_tz = has_timezone(df, 'timestamp') # True\n\n# Convert timezone\ndf = make_aware(df, col='timestamp', tz='America/New_York')\n```\n\n### \ud83d\udcc8 Time Range Operations\n\nCreate and manipulate time intervals:\n\n```python\nfrom time_helper import create_intervals, time_to_interval\nfrom datetime import datetime, timedelta\n\nstart = datetime(2024, 3, 15, 9, 0)\nend = datetime(2024, 3, 15, 17, 0)\n\n# Create hourly intervals\nhourly = create_intervals(start, end, interval=timedelta(hours=1))\n# [(datetime(2024, 3, 15, 9, 0), datetime(2024, 3, 15, 10, 0)),\n# (datetime(2024, 3, 15, 10, 0), datetime(2024, 3, 15, 11, 0)), ...]\n\n# Convert time to position in day (0.0 = midnight, 0.5 = noon)\nnoon = datetime(2024, 3, 15, 12, 0)\npos = time_to_interval(noon, offset=0) # 0.0 (noon centered)\npos = time_to_interval(noon, offset=0, zero_center=False) # 0.5\n```\n\n## Development\n\nInstall for development with all optional dependencies:\n\n```bash\n# Clone the repository\ngit clone https://github.com/felixnext/python-time-helper.git\ncd python-time-helper\n\n# Install with all extras using uv\nuv sync --all-extras\n\n# Run tests\nuv run pytest\n\n# Run linting and type checking\nuv run ruff check .\nuv run mypy time_helper\n```\n\n## DateTimeWrapper\n\nThe library includes a `DateTimeWrapper` class that provides a fluent, object-oriented interface for datetime operations:\n\n```python\nfrom time_helper import DateTimeWrapper\n\n# Create wrapper from various inputs\ndtw = DateTimeWrapper(\"2024-03-15 10:30:00\")\ndtw = DateTimeWrapper(datetime.now())\ndtw = DateTimeWrapper(date(2024, 3, 15))\ndtw = DateTimeWrapper(1710501045) # Unix timestamp\n\n# Chainable operations\nresult = (DateTimeWrapper(\"2024-03-15 10:35:45\")\n .make_aware(\"UTC\")\n .round(\"H\")\n .localize(\"Asia/Tokyo\")\n .to_string(\"%Y-%m-%d %H:%M %Z\"))\n\n# Arithmetic operations\ntomorrow = dtw + timedelta(days=1)\nyesterday = dtw - timedelta(days=1)\ndiff = tomorrow - yesterday # Returns timedelta\n\n# Comparison operations\nif dtw > DateTimeWrapper(\"2024-01-01\"):\n print(\"After new year\")\n\n# Direct property access\nprint(f\"Year: {dtw.year}, Month: {dtw.month}, Day: {dtw.day}\")\nprint(f\"Weekday: {dtw.weekday}\") # 0=Monday, 6=Sunday\n\n# Timezone operations\naware = dtw.make_aware(\"EST\")\nunaware = aware.make_unaware()\ntokyo = aware.localize(\"Asia/Tokyo\")\n\n# String conversion\niso_str = dtw.to_string() # ISO format\ncustom_str = dtw.to_string(\"%B %d, %Y\") # \"March 15, 2024\"\nunix_ts = dtw.to_timestamp() # Unix timestamp\n```\n\n## DST Support\n\nThe library includes comprehensive Daylight Saving Time (DST) support for handling timezone transitions:\n\n```python\nfrom time_helper import is_dst_active, get_dst_transitions, next_dst_transition, make_aware\n\n# Check if DST is currently active\nsummer_time = make_aware(\"2024-07-15 12:00:00\", \"Europe/Berlin\")\nis_dst_active(summer_time) # True (CEST is active)\n\nwinter_time = make_aware(\"2024-01-15 12:00:00\", \"Europe/Berlin\")\nis_dst_active(winter_time) # False (CET is active)\n\n# Get all DST transitions for a timezone in a given year\ntransitions = get_dst_transitions(\"Europe/Berlin\", 2024)\n# [\n# {\"type\": \"spring_forward\", \"date\": datetime(2024, 3, 31, 2, 0, ...)},\n# {\"type\": \"fall_back\", \"date\": datetime(2024, 10, 27, 3, 0, ...)}\n# ]\n\n# Find the next DST transition from a given datetime\nwinter_dt = make_aware(\"2024-02-15 12:00:00\", \"Europe/Berlin\")\nnext_trans = next_dst_transition(winter_dt)\n# {\"type\": \"spring_forward\", \"date\": datetime(2024, 3, 31, 2, 0, ...)}\n\nsummer_dt = make_aware(\"2024-07-15 12:00:00\", \"Europe/Berlin\")\nnext_trans = next_dst_transition(summer_dt)\n# {\"type\": \"fall_back\", \"date\": datetime(2024, 10, 27, 3, 0, ...)}\n```\n\n**DST Features:**\n- Automatic handling of \"spring forward\" and \"fall back\" transitions\n- Support for ambiguous times (when clocks fall back)\n- Robust handling of non-existent times (when clocks spring forward)\n- Works with all timezone databases that support DST\n\n## Natural Language Parsing\n\nThe library supports parsing natural language datetime expressions for intuitive date and time manipulation:\n\n```python\nfrom time_helper import parse_natural, DateTimeWrapper\nfrom datetime import datetime\n\n# Basic relative expressions\nref_date = datetime(2024, 7, 15, 12, 0, 0) # Monday, July 15, 2024\n\n# Time references\nnow = parse_natural(\"now\")\ntoday = parse_natural(\"today\", reference=ref_date)\ntomorrow = parse_natural(\"tomorrow\", reference=ref_date)\nyesterday = parse_natural(\"yesterday\", reference=ref_date)\n\n# Weekday references\nmonday = parse_natural(\"monday\", reference=ref_date) # Current Monday\nnext_monday = parse_natural(\"next monday\", reference=ref_date) # Next Monday\nlast_friday = parse_natural(\"last friday\", reference=ref_date) # Previous Friday\n\n# Time expressions\nmorning = parse_natural(\"morning\", reference=ref_date) # 9:00 AM\nafternoon = parse_natural(\"afternoon\", reference=ref_date) # 2:00 PM\nevening = parse_natural(\"evening\", reference=ref_date) # 7:00 PM\nnight = parse_natural(\"night\", reference=ref_date) # 10:00 PM\n\n# Specific times\nnine_am = parse_natural(\"9am\", reference=ref_date)\ntwo_thirty_pm = parse_natural(\"2:30pm\", reference=ref_date)\nnoon = parse_natural(\"noon\", reference=ref_date)\nmidnight = parse_natural(\"midnight\", reference=ref_date)\n\n# Complex expressions\ntomorrow_9am = parse_natural(\"tomorrow at 9am\", reference=ref_date)\nnext_week = parse_natural(\"next week\", reference=ref_date)\nlast_month = parse_natural(\"last month\", reference=ref_date)\n\n# Relative time offsets\nin_2_hours = parse_natural(\"in 2 hours\", reference=ref_date)\nin_30_minutes = parse_natural(\"in 30 minutes\", reference=ref_date)\n2_days_ago = parse_natural(\"2 days ago\", reference=ref_date)\n1_week_ago = parse_natural(\"1 week ago\", reference=ref_date)\n\n# Business day references\nnext_business_day = parse_natural(\"next business day\", reference=ref_date)\nlast_business_day = parse_natural(\"last business day\", reference=ref_date)\n\n# Weekend references\nthis_weekend = parse_natural(\"this weekend\", reference=ref_date)\nnext_weekend = parse_natural(\"next weekend\", reference=ref_date)\n\n# Date boundaries\nbeginning_of_month = parse_natural(\"beginning of month\", reference=ref_date)\nend_of_month = parse_natural(\"end of month\", reference=ref_date)\nbeginning_of_year = parse_natural(\"beginning of year\", reference=ref_date)\nend_of_year = parse_natural(\"end of year\", reference=ref_date)\n\n# Ordinal expressions\nfirst_of_month = parse_natural(\"first of the month\", reference=ref_date)\n15th_next_month = parse_natural(\"15th of next month\", reference=ref_date)\n```\n\n### Natural Language with DateTimeWrapper\n\nThe `DateTimeWrapper` class supports natural language parsing and provides additional methods for natural language operations:\n\n```python\nfrom time_helper import DateTimeWrapper\nfrom datetime import timedelta\n\n# Create wrapper with natural language\ndtw = DateTimeWrapper(\"tomorrow at 9am\")\ndtw = DateTimeWrapper(\"next monday\")\ndtw = DateTimeWrapper(\"in 2 hours\")\n\n# Chain operations with natural language\nresult = (DateTimeWrapper(\"tomorrow at 9am\")\n .make_aware(\"UTC\")\n .round(\"H\")\n .localize(\"Asia/Tokyo\"))\n\n# Use natural language parsing with timedelta for offsets\ndtw = DateTimeWrapper(\"2024-07-15 12:00:00\")\ntomorrow = dtw + timedelta(days=1)\nnext_week = dtw + timedelta(weeks=1)\nin_2_hours = dtw + timedelta(hours=2)\n```\n\n**Supported Natural Language Patterns:**\n- Time references: \"now\", \"today\", \"tomorrow\", \"yesterday\"\n- Weekdays: \"monday\", \"tuesday\", etc. with \"next\" and \"last\" modifiers\n- Time of day: \"morning\", \"afternoon\", \"evening\", \"night\", \"noon\", \"midnight\"\n- Specific times: \"9am\", \"2:30pm\", \"14:30\"\n- Time ranges: \"this weekend\", \"next weekend\", \"next week\", \"last month\"\n- Relative offsets: \"in 2 hours\", \"3 days ago\", \"1 week ago\"\n- Business days: \"next business day\", \"last business day\"\n- Date boundaries: \"beginning of month\", \"end of year\"\n- Ordinals: \"first of the month\", \"15th of next month\"\n- Complex expressions: \"tomorrow at 9am\", \"next monday at 2:30pm\"\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2022 Felix Geilert\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 Python time helper library",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/felixnext/python-time-helper",
"Issues": "https://github.com/felixnext/python-time-helper/issues",
"Repository": "https://github.com/felixnext/python-time-helper"
},
"split_keywords": [
"datetime",
" helper",
" time",
" timezone"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "86fb88496da9dbf8cb14cbc868f59f0f3e04cf1fb4e003045e54716dacaf6e63",
"md5": "c5c6314525dce83ffad4cac79bd297e5",
"sha256": "bcc700e995d0f44466b51e74fd00c6f43dd05e4331fc4ab302e33983fa6e33ae"
},
"downloads": -1,
"filename": "time_helper-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5c6314525dce83ffad4cac79bd297e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22395,
"upload_time": "2025-07-21T10:15:23",
"upload_time_iso_8601": "2025-07-21T10:15:23.963363Z",
"url": "https://files.pythonhosted.org/packages/86/fb/88496da9dbf8cb14cbc868f59f0f3e04cf1fb4e003045e54716dacaf6e63/time_helper-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9218d2d6cdc1b95e4d3c6d791f3060eadc0f036344c7ce65c2ad010dea5014c4",
"md5": "1905ce5d1fbc87557f0d28dd450a58ba",
"sha256": "e4175d6896bc021f5ea55a109f63773bf61468b91c0f65e7cf54196f2b422081"
},
"downloads": -1,
"filename": "time_helper-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "1905ce5d1fbc87557f0d28dd450a58ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 84922,
"upload_time": "2025-07-21T10:15:25",
"upload_time_iso_8601": "2025-07-21T10:15:25.172646Z",
"url": "https://files.pythonhosted.org/packages/92/18/d2d6cdc1b95e4d3c6d791f3060eadc0f036344c7ce65c2ad010dea5014c4/time_helper-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 10:15:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "felixnext",
"github_project": "python-time-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "time-helper"
}
