### Timezone Trout
This library tries to solve the common problem of figuring out what time zone
a specific address or a phone number is in. It does so by using several
mappings that are generated with the help of [pytz](http://pytz.sourceforge.net/),
[Geonames.org](https://www.geonames.org/postal-codes/postal-codes-us.html),
and [TimezoneFinder](https://github.com/MrMinimal64/timezonefinder)
Current version is fairly accurate for the United States, Canada, Australia, and
countries which fit within a single time zone.
Vocabulary used in this library:
* PST - time zone name
* America/Los_Angeles - time zone identifier
* UTC-07:00 or -420 - UTC offset (the latter given in minutes)
* DST - Daylight Saving Time
The US Zipcode data is provided by www.geonames.org under the Creative Commons Attribution 3.0 License.
Starting in `v1.0.0`, this library requires Python version 3.6 or above.
#### Examples
```
>>> tztrout.tz_ids_for_phone('+16503334444')
[u'America/Los_Angeles']
>>> tztrout.tz_ids_for_phone('+49 (0)711 400 40990')
[u'Europe/Berlin', u'Europe/Busingen']
```
```
>>> tztrout.tz_ids_for_address('US', state='CA')
[u'America/Los_Angeles']
>>> tztrout.tz_ids_for_address('PL')
[u'Europe/Warsaw']
>>> tztrout.tz_ids_for_address('CN')
[
u'Asia/Shanghai',
u'Asia/Harbin',
u'Asia/Chongqing',
u'Asia/Urumqi',
u'Asia/Kashgar'
]
```
```
>>> import tztrout
>>> tztrout.tz_ids_for_tz_name('PDT') # ran during DST
[
u'America/Dawson',
u'America/Los_Angeles',
u'America/Santa_Isabel',
u'America/Tijuana',
u'America/Vancouver',
u'America/Whitehorse',
u'Canada/Pacific',
u'US/Pacific'
]
>>> tztrout.tz_ids_for_tz_name('PDT') # ran outside of the DST period
[]
```
```
>>> tztrout.local_time_for_phone('+1 (650) 333-4444')
datetime.datetime(2013, 9, 16, 17, 45, 43, 0000000, tzinfo=<DstTzInfo 'America/Los_Angeles' PDT-1 day, 17:00:00 DST>)
>>> tztrout.local_time_for_phone('+48 601 941 311)
datetime.datetime(2013, 9, 17, 2, 45, 43, 0000000, tzinfo=<DstTzInfo 'Europe/Warsaw' CEST+2:00:00 DST>)
```
```
>>> tztrout.local_time_for_address('US', state='CA')
datetime.datetime(2013, 9, 16, 17, 45, 43, 0000000, tzinfo=<DstTzInfo 'America/Los_Angeles' PDT-1 day, 17:00:00 DST>)
>>> tztrout.local_time_for_address('PL')
datetime.datetime(2013, 9, 17, 2, 45, 43, 0000000, tzinfo=<DstTzInfo 'Europe/Warsaw' CEST+2:00:00 DST>)
```
```
>>> tztrout.tz_ids_for_offset(-7 * 60) # during DST
[
u'America/Creston',
u'America/Dawson',
u'America/Dawson_Creek',
u'America/Hermosillo',
u'America/Los_Angeles',
u'America/Phoenix',
u'America/Santa_Isabel',
u'America/Tijuana',
u'America/Vancouver',
u'America/Whitehorse',
u'Canada/Pacific',
u'US/Arizona',
u'US/Pacific'
]
>>> tztrout.tz_ids_for_offset(+2 * 60) # during DST
[
"Africa/Blantyre",
"Africa/Bujumbura",
"Africa/Cairo",
"Africa/Ceuta",
"Africa/Gaborone",
"Africa/Harare",
"Africa/Johannesburg",
"Africa/Kigali",
"Africa/Lubumbashi",
"Africa/Lusaka",
"Africa/Maputo",
"Africa/Maseru",
"Africa/Mbabane",
"Africa/Tripoli",
"Africa/Windhoek",
"Arctic/Longyearbyen",
"Europe/Amsterdam",
"Europe/Andorra",
"Europe/Belgrade",
"Europe/Berlin",
"Europe/Bratislava",
"Europe/Brussels",
"Europe/Budapest",
"Europe/Busingen",
"Europe/Copenhagen",
"Europe/Gibraltar",
"Europe/Ljubljana",
"Europe/Luxembourg",
"Europe/Madrid",
"Europe/Malta",
"Europe/Monaco",
"Europe/Oslo",
"Europe/Paris",
"Europe/Podgorica",
"Europe/Prague",
"Europe/Rome",
"Europe/San_Marino",
"Europe/Sarajevo",
"Europe/Skopje",
"Europe/Stockholm",
"Europe/Tirane",
"Europe/Vaduz",
"Europe/Vatican",
"Europe/Vienna",
"Europe/Warsaw",
"Europe/Zagreb",
"Europe/Zurich"
]
```
#### Testing
Just run `pytest`
#### Regenerating the data
Time zones, addresses, and phone numbers are in a constant flux and hence the
data used by this library needs to be regenerated periodically. To do so,
upgrade the `pytz` and `timezonefinder` dependencies, and run `python
regenerate_data.py`. If this doesn't fix the problem, consider opening an issue
or adding an exception in `data_exceptions.py`.
#### Known Issues
* Australian Central Western Standard Time (CWST) is treated as Australian Central Standard Time (ACST). See [Australian anomalies](http://en.wikipedia.org/wiki/Time_in_Australia#Anomalies) for more details.
* Lord Howe Standard Time (LHST) is treated as Australian Eastern Standard Time (AEST). In reality, they're 30 minutes apart.
* The whole state of British Columbia (Canada) is recognized as Pacific Time, although a small portion of its south-east territory should be recognized as Mountain Time.
* The whole state of Ontario (Canada) is recognized as Eastern Time, although a small portion of its west territory should be recognized as Central Time.
* All +1 867 phone numbers are recognized as Mountain Time, although this prefix is shared by three Canadian territories in the Arctic far north, spanning across Pacific, Mountain, and Central Time.
## Releasing a New Version
1. Make sure the code has been thoroughly reviewed and tested in a realistic production environment.
1. Update ``setup.py`` and ``CHANGELOG.md``. Make sure you include any breaking changes.
1. Run ``python setup.py sdist`` and ``twine upload dist/<PACKAGE_TO_UPLOAD>``.
1. Push a new tag pointing to the released commit, format: ``v0.13`` for example.
Raw data
{
"_id": null,
"home_page": "http://github.com/closeio/tz-trout",
"name": "tz-trout",
"maintainer": "Close.io",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "engineering@close.io",
"keywords": "",
"author": "Close.io",
"author_email": "engineering@close.io",
"download_url": "https://files.pythonhosted.org/packages/6f/d2/53a81150b9f344dd680f64683649d465827fec38dfd7d303c9b58afce5b4/tz-trout-1.0.4.tar.gz",
"platform": "any",
"description": "### Timezone Trout\n\nThis library tries to solve the common problem of figuring out what time zone\na specific address or a phone number is in. It does so by using several\nmappings that are generated with the help of [pytz](http://pytz.sourceforge.net/),\n[Geonames.org](https://www.geonames.org/postal-codes/postal-codes-us.html),\nand [TimezoneFinder](https://github.com/MrMinimal64/timezonefinder)\n\nCurrent version is fairly accurate for the United States, Canada, Australia, and\ncountries which fit within a single time zone.\n\nVocabulary used in this library:\n* PST - time zone name\n* America/Los_Angeles - time zone identifier\n* UTC-07:00 or -420 - UTC offset (the latter given in minutes)\n* DST - Daylight Saving Time\n\nThe US Zipcode data is provided by www.geonames.org under the Creative Commons Attribution 3.0 License.\n\nStarting in `v1.0.0`, this library requires Python version 3.6 or above.\n\n#### Examples\n```\n>>> tztrout.tz_ids_for_phone('+16503334444')\n[u'America/Los_Angeles']\n>>> tztrout.tz_ids_for_phone('+49 (0)711 400 40990')\n[u'Europe/Berlin', u'Europe/Busingen']\n```\n\n```\n>>> tztrout.tz_ids_for_address('US', state='CA')\n[u'America/Los_Angeles']\n>>> tztrout.tz_ids_for_address('PL')\n[u'Europe/Warsaw']\n>>> tztrout.tz_ids_for_address('CN')\n[\n u'Asia/Shanghai',\n u'Asia/Harbin',\n u'Asia/Chongqing',\n u'Asia/Urumqi',\n u'Asia/Kashgar'\n]\n```\n\n```\n>>> import tztrout\n>>> tztrout.tz_ids_for_tz_name('PDT') # ran during DST\n[\n u'America/Dawson',\n u'America/Los_Angeles',\n u'America/Santa_Isabel',\n u'America/Tijuana',\n u'America/Vancouver',\n u'America/Whitehorse',\n u'Canada/Pacific',\n u'US/Pacific'\n]\n>>> tztrout.tz_ids_for_tz_name('PDT') # ran outside of the DST period\n[]\n```\n\n```\n>>> tztrout.local_time_for_phone('+1 (650) 333-4444')\ndatetime.datetime(2013, 9, 16, 17, 45, 43, 0000000, tzinfo=<DstTzInfo 'America/Los_Angeles' PDT-1 day, 17:00:00 DST>)\n\n>>> tztrout.local_time_for_phone('+48 601 941 311)\ndatetime.datetime(2013, 9, 17, 2, 45, 43, 0000000, tzinfo=<DstTzInfo 'Europe/Warsaw' CEST+2:00:00 DST>)\n```\n\n```\n>>> tztrout.local_time_for_address('US', state='CA')\ndatetime.datetime(2013, 9, 16, 17, 45, 43, 0000000, tzinfo=<DstTzInfo 'America/Los_Angeles' PDT-1 day, 17:00:00 DST>)\n>>> tztrout.local_time_for_address('PL')\ndatetime.datetime(2013, 9, 17, 2, 45, 43, 0000000, tzinfo=<DstTzInfo 'Europe/Warsaw' CEST+2:00:00 DST>)\n```\n\n```\n>>> tztrout.tz_ids_for_offset(-7 * 60) # during DST\n[\n u'America/Creston',\n u'America/Dawson',\n u'America/Dawson_Creek',\n u'America/Hermosillo',\n u'America/Los_Angeles',\n u'America/Phoenix',\n u'America/Santa_Isabel',\n u'America/Tijuana',\n u'America/Vancouver',\n u'America/Whitehorse',\n u'Canada/Pacific',\n u'US/Arizona',\n u'US/Pacific'\n]\n>>> tztrout.tz_ids_for_offset(+2 * 60) # during DST\n[\n \"Africa/Blantyre\",\n \"Africa/Bujumbura\",\n \"Africa/Cairo\",\n \"Africa/Ceuta\",\n \"Africa/Gaborone\",\n \"Africa/Harare\",\n \"Africa/Johannesburg\",\n \"Africa/Kigali\",\n \"Africa/Lubumbashi\",\n \"Africa/Lusaka\",\n \"Africa/Maputo\",\n \"Africa/Maseru\",\n \"Africa/Mbabane\",\n \"Africa/Tripoli\",\n \"Africa/Windhoek\",\n \"Arctic/Longyearbyen\",\n \"Europe/Amsterdam\",\n \"Europe/Andorra\",\n \"Europe/Belgrade\",\n \"Europe/Berlin\",\n \"Europe/Bratislava\",\n \"Europe/Brussels\",\n \"Europe/Budapest\",\n \"Europe/Busingen\",\n \"Europe/Copenhagen\",\n \"Europe/Gibraltar\",\n \"Europe/Ljubljana\",\n \"Europe/Luxembourg\",\n \"Europe/Madrid\",\n \"Europe/Malta\",\n \"Europe/Monaco\",\n \"Europe/Oslo\",\n \"Europe/Paris\",\n \"Europe/Podgorica\",\n \"Europe/Prague\",\n \"Europe/Rome\",\n \"Europe/San_Marino\",\n \"Europe/Sarajevo\",\n \"Europe/Skopje\",\n \"Europe/Stockholm\",\n \"Europe/Tirane\",\n \"Europe/Vaduz\",\n \"Europe/Vatican\",\n \"Europe/Vienna\",\n \"Europe/Warsaw\",\n \"Europe/Zagreb\",\n \"Europe/Zurich\"\n]\n```\n\n#### Testing\n\nJust run `pytest`\n\n#### Regenerating the data\n\nTime zones, addresses, and phone numbers are in a constant flux and hence the\ndata used by this library needs to be regenerated periodically. To do so,\nupgrade the `pytz` and `timezonefinder` dependencies, and run `python\nregenerate_data.py`. If this doesn't fix the problem, consider opening an issue\nor adding an exception in `data_exceptions.py`.\n\n\n#### Known Issues\n\n* Australian Central Western Standard Time (CWST) is treated as Australian Central Standard Time (ACST). See [Australian anomalies](http://en.wikipedia.org/wiki/Time_in_Australia#Anomalies) for more details.\n* Lord Howe Standard Time (LHST) is treated as Australian Eastern Standard Time (AEST). In reality, they're 30 minutes apart.\n* The whole state of British Columbia (Canada) is recognized as Pacific Time, although a small portion of its south-east territory should be recognized as Mountain Time.\n* The whole state of Ontario (Canada) is recognized as Eastern Time, although a small portion of its west territory should be recognized as Central Time.\n* All +1 867 phone numbers are recognized as Mountain Time, although this prefix is shared by three Canadian territories in the Arctic far north, spanning across Pacific, Mountain, and Central Time.\n\n## Releasing a New Version\n\n1. Make sure the code has been thoroughly reviewed and tested in a realistic production environment.\n1. Update ``setup.py`` and ``CHANGELOG.md``. Make sure you include any breaking changes.\n1. Run ``python setup.py sdist`` and ``twine upload dist/<PACKAGE_TO_UPLOAD>``.\n1. Push a new tag pointing to the released commit, format: ``v0.13`` for example.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Helps you figure out the time zone based on an address or a phone number.",
"version": "1.0.4",
"project_urls": {
"Homepage": "http://github.com/closeio/tz-trout"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6fd253a81150b9f344dd680f64683649d465827fec38dfd7d303c9b58afce5b4",
"md5": "ff19649298b50a44bccdd90712d11987",
"sha256": "a6d3c55afa0334a5a325d3ca87c03fdc078c9f27ac7b1b085054e2e4b0d53b1d"
},
"downloads": -1,
"filename": "tz-trout-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "ff19649298b50a44bccdd90712d11987",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 759568,
"upload_time": "2023-09-08T09:52:29",
"upload_time_iso_8601": "2023-09-08T09:52:29.877496Z",
"url": "https://files.pythonhosted.org/packages/6f/d2/53a81150b9f344dd680f64683649d465827fec38dfd7d303c9b58afce5b4/tz-trout-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-08 09:52:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "closeio",
"github_project": "tz-trout",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [
{
"name": "pytz",
"specs": [
[
"==",
"2023.3"
]
]
},
{
"name": "phonenumbers",
"specs": [
[
"==",
"8.13.19"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.8.2"
]
]
},
{
"name": "timezonefinder",
"specs": [
[
"==",
"6.2.0"
]
]
}
],
"lcname": "tz-trout"
}
JSON
