| Name | simpleiso3166 JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Simple, strongly typed access to ISO 3166-1 and 3116-2 |
| upload_time | 2024-04-03 16:38:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
3166
country
iso
subdivision
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# simpleiso3166
[](https://pypi.org/project/simpleiso3166)
[](https://pypi.org/project/simpleiso3166)
[](https://codecov.io/github/stumpylog/simpleiso3166)
---
**Table of Contents**
- [Installation](#installation)
- [License](#license)
- [Features](#features)
- [Why](#why)
- [Usage](#usage)
- [Country Based Interface](#country-based-interface)
- [Subdivision Based Interface](#subdivision-based-interface)
- [Roadmap](#roadmap)
## Installation
```console
pip install simpleiso3166
```
For the searching by partial name, include the extra:
```console
pip install simpleiso3166[search]
```
## License
`simpleiso3166` is distributed under the terms of the [MPL-2.0](https://spdx.org/licenses/MPL-2.0.html) license.
## Features
- Strongly typed interface to ISO 3166-1 countries and ISO 3166-2 subdivisions (e.g. states, provinces)
- No JSON parsing at runtime, fully defined in Python
- Includes defined types to allow integration with libraries like Pydantic for validation of code validity
- Lazy loading of subdivision data on demand for reduced memory usage
- Searching for countries by exact or partial name
- Searching for subdivisions by exact or partial name
- Supports Python 3.9+
- On Python 3.10 and newer, uses `slots` to efficiently store country and subdivision data
### Why?
This library was created as a way to provide strongly typed access to the ISO 3166 standard, which is used to define country codes and subdivision codes.
It's designed to be lightweight and easy to use in Python projects.
Other existing libraries include [pycountry](https://github.com/pycountry/pycountry), but they don't provide the same
strongly typed interface as this library does. They also load JSON files at runtime, which can be a performance issue and takes
memory.
## Usage
### Country Based Interface
If you know the country's code:
```python
country = Country.from_alpha2("US")
assert country.name == "United States of America"
assert country.common_name == "United States"
# Subdivision data isn't loaded until the first ask for it
assert len(list(country.subdivisions)) == 57
```
If you need to search for the country:
```python
results = list(Country.from_partial_name("Kingdom"))
assert len(results) == 17
assert results[0].alpha2 == "BE"
assert results[0].name == "Kingdom of Belgium"
assert results[0].common_name == "Belgium"
assert results[10].alpha2 == "NL"
assert results[10].name == "Kingdom of the Netherlands"
assert results[10].common_name == "Netherlands"
assert results[16].alpha2 == "TO"
assert results[16].name == "Kingdom of Tonga"
assert results[16].common_name == "Tonga"
```
Access a particular subdivision:
```python
country = Country.from_alpha2("DE")
# You can check this subdivision code is in this country
assert country.contains_subdivision("DE-BW")
# This will return None if the subdivision isn't valid
subdivision = country.get_subdivision("DE-BW")
assert subdivision.name == "Baden-Württemberg"
```
### Subdivision Based Interface
Search for a subdivision by name. This will have to load ALL subdivision data though:
```python
results = list(Subdivision.search_by_name("Connecticut"))
assert len(results) == 1
assert results[0] == "US-CT"
```
## Roadmap
### Improved Searching
This is partly implemented, but more aliases would be helpful
- Search using common aliases for countries (e.g. "USA" for "United States of America")
- Extended searching for subdivisions by common aliases (eg "DC" for "Washington DC")
- Search using re-ordered names (e.g. "The Democratic Republic of the Congo" for instead of "Congo, The Democratic Republic of the")
### ISO 3166-3
- Access to deleted country data
Raw data
{
"_id": null,
"home_page": null,
"name": "simpleiso3166",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "3166, country, iso, subdivision",
"author": null,
"author_email": "Trenton H <rda0128ou@mozmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8d/87/f3b30e9abf5481831af56063083b7eab990339a135247692381de8eccd4b/simpleiso3166-0.1.0.tar.gz",
"platform": null,
"description": "# simpleiso3166\n\n[](https://pypi.org/project/simpleiso3166)\n[](https://pypi.org/project/simpleiso3166)\n[](https://codecov.io/github/stumpylog/simpleiso3166)\n\n---\n\n**Table of Contents**\n\n- [Installation](#installation)\n- [License](#license)\n- [Features](#features)\n - [Why](#why)\n- [Usage](#usage)\n - [Country Based Interface](#country-based-interface)\n - [Subdivision Based Interface](#subdivision-based-interface)\n- [Roadmap](#roadmap)\n\n## Installation\n\n```console\npip install simpleiso3166\n```\n\nFor the searching by partial name, include the extra:\n\n```console\npip install simpleiso3166[search]\n```\n\n## License\n\n`simpleiso3166` is distributed under the terms of the [MPL-2.0](https://spdx.org/licenses/MPL-2.0.html) license.\n\n## Features\n\n- Strongly typed interface to ISO 3166-1 countries and ISO 3166-2 subdivisions (e.g. states, provinces)\n- No JSON parsing at runtime, fully defined in Python\n- Includes defined types to allow integration with libraries like Pydantic for validation of code validity\n- Lazy loading of subdivision data on demand for reduced memory usage\n- Searching for countries by exact or partial name\n- Searching for subdivisions by exact or partial name\n- Supports Python 3.9+\n- On Python 3.10 and newer, uses `slots` to efficiently store country and subdivision data\n\n### Why?\n\nThis library was created as a way to provide strongly typed access to the ISO 3166 standard, which is used to define country codes and subdivision codes.\nIt's designed to be lightweight and easy to use in Python projects.\n\nOther existing libraries include [pycountry](https://github.com/pycountry/pycountry), but they don't provide the same\nstrongly typed interface as this library does. They also load JSON files at runtime, which can be a performance issue and takes\nmemory.\n\n## Usage\n\n### Country Based Interface\n\nIf you know the country's code:\n\n```python\ncountry = Country.from_alpha2(\"US\")\n\nassert country.name == \"United States of America\"\nassert country.common_name == \"United States\"\n\n# Subdivision data isn't loaded until the first ask for it\nassert len(list(country.subdivisions)) == 57\n```\n\nIf you need to search for the country:\n\n```python\nresults = list(Country.from_partial_name(\"Kingdom\"))\n\nassert len(results) == 17\nassert results[0].alpha2 == \"BE\"\nassert results[0].name == \"Kingdom of Belgium\"\nassert results[0].common_name == \"Belgium\"\n\nassert results[10].alpha2 == \"NL\"\nassert results[10].name == \"Kingdom of the Netherlands\"\nassert results[10].common_name == \"Netherlands\"\n\nassert results[16].alpha2 == \"TO\"\nassert results[16].name == \"Kingdom of Tonga\"\nassert results[16].common_name == \"Tonga\"\n```\n\nAccess a particular subdivision:\n\n```python\ncountry = Country.from_alpha2(\"DE\")\n\n# You can check this subdivision code is in this country\nassert country.contains_subdivision(\"DE-BW\")\n\n# This will return None if the subdivision isn't valid\nsubdivision = country.get_subdivision(\"DE-BW\")\nassert subdivision.name == \"Baden-W\u00fcrttemberg\"\n```\n\n### Subdivision Based Interface\n\nSearch for a subdivision by name. This will have to load ALL subdivision data though:\n\n```python\nresults = list(Subdivision.search_by_name(\"Connecticut\"))\n\nassert len(results) == 1\nassert results[0] == \"US-CT\"\n```\n\n## Roadmap\n\n### Improved Searching\n\nThis is partly implemented, but more aliases would be helpful\n\n- Search using common aliases for countries (e.g. \"USA\" for \"United States of America\")\n- Extended searching for subdivisions by common aliases (eg \"DC\" for \"Washington DC\")\n- Search using re-ordered names (e.g. \"The Democratic Republic of the Congo\" for instead of \"Congo, The Democratic Republic of the\")\n\n### ISO 3166-3\n\n- Access to deleted country data\n",
"bugtrack_url": null,
"license": null,
"summary": "Simple, strongly typed access to ISO 3166-1 and 3116-2",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/stumpylog/simpleiso3166/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/stumpylog/simpleiso3166#readme",
"Issues": "https://github.com/stumpylog/simpleiso3166/issues",
"Source": "https://github.com/stumpylog/simpleiso3166"
},
"split_keywords": [
"3166",
" country",
" iso",
" subdivision"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8af0b3ef3ec95b86da85a863642065c228e42f884caa0c47202be90c208c33f0",
"md5": "2d445ef551051f701a4268e7a3f8ada0",
"sha256": "9c72ce88896c72b08717129b6aee5cfa979263b79f94bf7ecfd0a68028dc1481"
},
"downloads": -1,
"filename": "simpleiso3166-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d445ef551051f701a4268e7a3f8ada0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 238180,
"upload_time": "2024-04-03T16:38:29",
"upload_time_iso_8601": "2024-04-03T16:38:29.199783Z",
"url": "https://files.pythonhosted.org/packages/8a/f0/b3ef3ec95b86da85a863642065c228e42f884caa0c47202be90c208c33f0/simpleiso3166-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8d87f3b30e9abf5481831af56063083b7eab990339a135247692381de8eccd4b",
"md5": "9342177d8049b88d561976c2bd375aa3",
"sha256": "eed88e04d215864a8a48719dc290d595269f470a3cc676d9c17ffa01f71fcc65"
},
"downloads": -1,
"filename": "simpleiso3166-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "9342177d8049b88d561976c2bd375aa3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 131056,
"upload_time": "2024-04-03T16:38:30",
"upload_time_iso_8601": "2024-04-03T16:38:30.691460Z",
"url": "https://files.pythonhosted.org/packages/8d/87/f3b30e9abf5481831af56063083b7eab990339a135247692381de8eccd4b/simpleiso3166-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-03 16:38:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stumpylog",
"github_project": "simpleiso3166",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "simpleiso3166"
}
