# World Time Converter
A powerful Python library for handling worldwide time conversions, business hours calculations, and timezone management. Perfect for applications dealing with international time coordination, business hours overlap, and holiday scheduling.
## 🌟 Key Features
- 🌍 **Global Timezone Support**: Convert times between any cities worldwide
- 💼 **Business Hours Management**: Calculate working hours overlap across timezones
- 📅 **Holiday Handling**: Manage holidays and business days
- ⚡ **DST Aware**: Automatic handling of Daylight Saving Time transitions
- 🔍 **Type Hints**: Full typing support for better development experience
- 🛠️ **Extensible**: Easy to customize and extend
## 📦 Installation
```bash
pip install worldtimeconverter
```
## 🚀 Quick Start
```python
from worldtimeconverter import WorldTimeConverter
from worldtimeconverter.types import BusinessHours, HolidayDefinition
from datetime import datetime
# Get current time in any city
london = WorldTimeConverter.get_current_time('London')
print(f"London: {london.formatted_date_time}")
# Output: London: Friday, March 15, 2024 2:30:45 PM GMT
# Convert between cities
tokyo = WorldTimeConverter.convert_time(
datetime.now(),
'London',
'Tokyo'
)
print(f"Tokyo: {tokyo.formatted_date_time}")
# Output: Tokyo: Saturday, March 16, 2024 11:30:45 PM JST
```
## 💡 Advanced Usage
### 🕒 Time Conversion & Formatting
```python
# Multiple ways to specify time
from datetime import datetime
# 1. Using timestamp string
time1 = WorldTimeConverter.convert_time(
"2024-03-15 14:30:00",
'New_York',
'Singapore'
)
# 2. Using Unix timestamp
time2 = WorldTimeConverter.convert_time(
1710512345, # Unix timestamp
'London',
'Dubai'
)
# 3. Using datetime object
time3 = WorldTimeConverter.convert_time(
datetime.now(),
'Paris',
'Sydney'
)
# Custom formatting
formatted = WorldTimeConverter.convert_time(
datetime.now(),
'London',
'Tokyo',
format='%Y-%m-%d %H:%M:%S %Z'
)
```
### 💼 Business Hours Management
```python
# Define business hours
london_hours = BusinessHours(
start="09:00",
end="17:00",
timezone="Europe/London"
)
tokyo_hours = BusinessHours(
start="09:00",
end="18:00",
timezone="Asia/Tokyo"
)
# Calculate overlap
overlap = WorldTimeConverter.find_working_hours_overlap(
'London',
'Tokyo',
london_hours,
tokyo_hours
)
print(f"""
Working Hours Overlap:
Start: {overlap.start_time}
End: {overlap.end_time}
Duration: {overlap.overlap_duration.hours}h {overlap.overlap_duration.minutes}m
Working Days: {', '.join(overlap.working_days)}
""")
```
### 📅 Holiday Management
```python
# Define holidays
christmas = HolidayDefinition(
name="Christmas Day",
date="2024-12-25",
recurring=True,
type="public"
)
new_year = HolidayDefinition(
name="New Year's Day",
date="2024-01-01",
recurring=True,
type="public"
)
# Add holidays to cities
WorldTimeConverter.add_holiday('London', christmas)
WorldTimeConverter.add_holiday('London', new_year)
# Check holidays
is_christmas = WorldTimeConverter.is_holiday(
'London',
datetime(2024, 12, 25)
)
# Calculate business days
business_days = WorldTimeConverter.get_business_days_between(
'London',
'2024-01-01',
'2024-01-10',
skip_holidays=True
)
```
### 🌐 Timezone Information
```python
# Get detailed city information
city_info = WorldTimeConverter.get_city_info('London')
print(f"""
City: {city_info.city_name}
Timezone: {city_info.timezone}
Current Offset: {city_info.current_offset}
DST Active: {city_info.is_dst}
Region: {city_info.region}
Subregion: {city_info.subregion}
""")
```
## 📋 Type Definitions
```python
from dataclasses import dataclass
from typing import List
@dataclass
class TimeResult:
city_name: str
timezone: str
local_time: str
utc_offset: str
date: str
day_of_week: str
is_dst: bool
epoch: int
iso8601: str
formatted_date_time: str
@dataclass
class BusinessHours:
start: str # HH:MM format
end: str # HH:MM format
timezone: str
@dataclass
class HolidayDefinition:
name: str
date: str # YYYY-MM-DD format
recurring: bool
type: str
```
## 🔍 Error Handling
```python
from worldtimeconverter.exceptions import InvalidCityError, InvalidTimeFormatError
try:
time = WorldTimeConverter.get_current_time('InvalidCity')
except InvalidCityError as e:
print(f"City error: {e}")
try:
hours = BusinessHours(start="9:00", end="17:00", timezone="Europe/London")
except InvalidTimeFormatError as e:
print(f"Time format error: {e}")
```
## 🤝 Contributing
We welcome contributions! Here's how you can help:
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 📚 Documentation
For more detailed documentation and examples, visit our [GitHub Wiki](https://github.com/OrenGrinker/worldtimeconverter/wiki).
Raw data
{
"_id": null,
"home_page": "https://github.com/OrenGrinker/worldtimeconverter",
"name": "worldtimeconverter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "timezone, time-conversion, business-hours, working-hours, holiday-calendar, python, pytz, time-management, date-time, world-clock",
"author": "Oren Grinker",
"author_email": "orengr4@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/60/d2/417537b414aea56e14d2c591dd6f369911edfadd962e4847934943dbc05d/worldtimeconverter-1.0.3.tar.gz",
"platform": null,
"description": "# World Time Converter\n\n\n\n\n\n\nA powerful Python library for handling worldwide time conversions, business hours calculations, and timezone management. Perfect for applications dealing with international time coordination, business hours overlap, and holiday scheduling.\n\n## \ud83c\udf1f Key Features\n\n- \ud83c\udf0d **Global Timezone Support**: Convert times between any cities worldwide\n- \ud83d\udcbc **Business Hours Management**: Calculate working hours overlap across timezones\n- \ud83d\udcc5 **Holiday Handling**: Manage holidays and business days\n- \u26a1 **DST Aware**: Automatic handling of Daylight Saving Time transitions\n- \ud83d\udd0d **Type Hints**: Full typing support for better development experience\n- \ud83d\udee0\ufe0f **Extensible**: Easy to customize and extend\n\n## \ud83d\udce6 Installation\n\n```bash\npip install worldtimeconverter\n```\n\n## \ud83d\ude80 Quick Start\n\n```python\nfrom worldtimeconverter import WorldTimeConverter\nfrom worldtimeconverter.types import BusinessHours, HolidayDefinition\nfrom datetime import datetime\n\n# Get current time in any city\nlondon = WorldTimeConverter.get_current_time('London')\nprint(f\"London: {london.formatted_date_time}\")\n# Output: London: Friday, March 15, 2024 2:30:45 PM GMT\n\n# Convert between cities\ntokyo = WorldTimeConverter.convert_time(\n datetime.now(),\n 'London',\n 'Tokyo'\n)\nprint(f\"Tokyo: {tokyo.formatted_date_time}\")\n# Output: Tokyo: Saturday, March 16, 2024 11:30:45 PM JST\n```\n\n## \ud83d\udca1 Advanced Usage\n\n### \ud83d\udd52 Time Conversion & Formatting\n\n```python\n# Multiple ways to specify time\nfrom datetime import datetime\n\n# 1. Using timestamp string\ntime1 = WorldTimeConverter.convert_time(\n \"2024-03-15 14:30:00\",\n 'New_York',\n 'Singapore'\n)\n\n# 2. Using Unix timestamp\ntime2 = WorldTimeConverter.convert_time(\n 1710512345, # Unix timestamp\n 'London',\n 'Dubai'\n)\n\n# 3. Using datetime object\ntime3 = WorldTimeConverter.convert_time(\n datetime.now(),\n 'Paris',\n 'Sydney'\n)\n\n# Custom formatting\nformatted = WorldTimeConverter.convert_time(\n datetime.now(),\n 'London',\n 'Tokyo',\n format='%Y-%m-%d %H:%M:%S %Z'\n)\n```\n\n### \ud83d\udcbc Business Hours Management\n\n```python\n# Define business hours\nlondon_hours = BusinessHours(\n start=\"09:00\",\n end=\"17:00\",\n timezone=\"Europe/London\"\n)\n\ntokyo_hours = BusinessHours(\n start=\"09:00\",\n end=\"18:00\",\n timezone=\"Asia/Tokyo\"\n)\n\n# Calculate overlap\noverlap = WorldTimeConverter.find_working_hours_overlap(\n 'London',\n 'Tokyo',\n london_hours,\n tokyo_hours\n)\n\nprint(f\"\"\"\nWorking Hours Overlap:\nStart: {overlap.start_time}\nEnd: {overlap.end_time}\nDuration: {overlap.overlap_duration.hours}h {overlap.overlap_duration.minutes}m\nWorking Days: {', '.join(overlap.working_days)}\n\"\"\")\n```\n\n### \ud83d\udcc5 Holiday Management\n\n```python\n# Define holidays\nchristmas = HolidayDefinition(\n name=\"Christmas Day\",\n date=\"2024-12-25\",\n recurring=True,\n type=\"public\"\n)\n\nnew_year = HolidayDefinition(\n name=\"New Year's Day\",\n date=\"2024-01-01\",\n recurring=True,\n type=\"public\"\n)\n\n# Add holidays to cities\nWorldTimeConverter.add_holiday('London', christmas)\nWorldTimeConverter.add_holiday('London', new_year)\n\n# Check holidays\nis_christmas = WorldTimeConverter.is_holiday(\n 'London',\n datetime(2024, 12, 25)\n)\n\n# Calculate business days\nbusiness_days = WorldTimeConverter.get_business_days_between(\n 'London',\n '2024-01-01',\n '2024-01-10',\n skip_holidays=True\n)\n```\n\n### \ud83c\udf10 Timezone Information\n\n```python\n# Get detailed city information\ncity_info = WorldTimeConverter.get_city_info('London')\nprint(f\"\"\"\nCity: {city_info.city_name}\nTimezone: {city_info.timezone}\nCurrent Offset: {city_info.current_offset}\nDST Active: {city_info.is_dst}\nRegion: {city_info.region}\nSubregion: {city_info.subregion}\n\"\"\")\n```\n\n## \ud83d\udccb Type Definitions\n\n```python\nfrom dataclasses import dataclass\nfrom typing import List\n\n@dataclass\nclass TimeResult:\n city_name: str\n timezone: str\n local_time: str\n utc_offset: str\n date: str\n day_of_week: str\n is_dst: bool\n epoch: int\n iso8601: str\n formatted_date_time: str\n\n@dataclass\nclass BusinessHours:\n start: str # HH:MM format\n end: str # HH:MM format\n timezone: str\n\n@dataclass\nclass HolidayDefinition:\n name: str\n date: str # YYYY-MM-DD format\n recurring: bool\n type: str\n```\n\n## \ud83d\udd0d Error Handling\n\n```python\nfrom worldtimeconverter.exceptions import InvalidCityError, InvalidTimeFormatError\n\ntry:\n time = WorldTimeConverter.get_current_time('InvalidCity')\nexcept InvalidCityError as e:\n print(f\"City error: {e}\")\n\ntry:\n hours = BusinessHours(start=\"9:00\", end=\"17:00\", timezone=\"Europe/London\")\nexcept InvalidTimeFormatError as e:\n print(f\"Time format error: {e}\")\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here's how you can help:\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udcda Documentation\n\nFor more detailed documentation and examples, visit our [GitHub Wiki](https://github.com/OrenGrinker/worldtimeconverter/wiki).\n",
"bugtrack_url": null,
"license": null,
"summary": "Advanced time conversion and timezone management library",
"version": "1.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/OrenGrinker/worldtimeconverter/issues",
"Homepage": "https://github.com/OrenGrinker/worldtimeconverter"
},
"split_keywords": [
"timezone",
" time-conversion",
" business-hours",
" working-hours",
" holiday-calendar",
" python",
" pytz",
" time-management",
" date-time",
" world-clock"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c7a498608a547025d073ea8a3472d56b8dacc29ddaf0f8f540a91cb57df6f97",
"md5": "c688ef0e2075e9c739d1958c2c35122d",
"sha256": "a629e1c022efe5a27995c3419b296891480e7c8e79e5a7a08de14d5c04205c93"
},
"downloads": -1,
"filename": "worldtimeconverter-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c688ef0e2075e9c739d1958c2c35122d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7682,
"upload_time": "2024-11-23T18:49:35",
"upload_time_iso_8601": "2024-11-23T18:49:35.024594Z",
"url": "https://files.pythonhosted.org/packages/0c/7a/498608a547025d073ea8a3472d56b8dacc29ddaf0f8f540a91cb57df6f97/worldtimeconverter-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "60d2417537b414aea56e14d2c591dd6f369911edfadd962e4847934943dbc05d",
"md5": "099cb656f018cfc30c97221c7fab8585",
"sha256": "fb50a4569be0f93b4e75fd7fb83621816f89f9adab4ad8b37ee40ea1420c16f9"
},
"downloads": -1,
"filename": "worldtimeconverter-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "099cb656f018cfc30c97221c7fab8585",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 9728,
"upload_time": "2024-11-23T18:49:36",
"upload_time_iso_8601": "2024-11-23T18:49:36.341341Z",
"url": "https://files.pythonhosted.org/packages/60/d2/417537b414aea56e14d2c591dd6f369911edfadd962e4847934943dbc05d/worldtimeconverter-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 18:49:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OrenGrinker",
"github_project": "worldtimeconverter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "worldtimeconverter"
}
JSON
