# About The Project
[][pypi_proj]
[][pypi_proj]
[](https://github.com/AivGitHub/pycountries/blob/main/LICENSE.md)
[][documentation]
pycountries provides the ISO enums for the standards:
- [iso-4217](https://www.iso.org/iso-4217-currency-codes.html)
- [iso-3166](https://www.iso.org/iso-3166-country-codes.html)
- [iso-639](https://www.iso.org/iso-639-language-code)
pycountries can be used natively with pydantic >= 1.5 and python >= 3.8.
It makes really easy to use fastapi and other related libraries.
## Requirements
1. Python >= 3.8
## Installation
```bash
pip install pycountries
```
## Usage
Examples show how to use pycountries with pydantic + fastapi, but
you can use it with pydantic and any other libraries.
```bash
pip install fastapi
pip install pycountries
```
When you have all required libraries you can quickstart with this code:
```python
from decimal import Decimal
from fastapi import FastAPI
from pycountries import Country, Currency, Language
from pydantic import BaseModel, model_validator
app = FastAPI()
class IndexRequest(BaseModel):
country: Country
currency: Currency
amount: Decimal
language: Language
@model_validator(mode="after")
def validate_amount(self) -> "IndexRequest":
# TODO: Keep in mind, you need to handle exceptions raised by clean_amount method,
# otherwise Internal Server Error will be raised.
self.amount = self.currency.clean_amount(self.amount)
return self
class IndexResponse(BaseModel):
amount: Decimal
@app.post("/")
async def root(data: IndexRequest):
return IndexResponse(**data.model_dump())
```
### Request Examples
```bash
curl -X POST -H "Content-Type: application/json" -d '{"country":"US", "currency":"USD", "amount":"20.20", "language":"eng"}' http://127.0.0.1:8000
{"amount":"20.20"}
curl -X POST -H "Content-Type: application/json" -d '{"country":"US", "currency":"USD", "amount":"-20.20", "language":"eng"}' http://127.0.0.1:8000
Internal Server Error
```
### Phones
I'm still not sure about the logic, if you have any ideas please create a task
[here](https://github.com/koldakov/pycountries/issues).
The problem here is that calling code is not unique per country. For example,
at least 3 countries have code +1: United States, Canada, Barbados. To determine the country
we need to see a prefix - N numbers after country code. And, looks like these prefixes are quite
dynamic, so should be managed accordingly.
For now logic is:
1. Return first calling code match if prefix is not provided.
2. If prefix is provided return first prefix match, or first "candidate" if there are no exact prefix matches.
It is very useful if you want to show phone dynamically. See an example below for more info.
```python
from pycountries import Phone
# Return first match with different types
Phone(1) # Phone.BB
Phone("1") # Phone.BB
Phone("+1") # Phone.BB
# Result has changed, because results with prefixes in priority right now.
Phone(1, prefix=3) # Phone.UM
Phone(1, prefix=32) # Phone.UM
# Exact match found!
Phone(1, prefix=325) # Phone.US
```
## Motivation
There is a great library [pycountry](https://github.com/pycountry/pycountry), but it is incompatible with enums,
for sure enums can be generated dynamically, but python does not work good with dynamic enums, for example, you can not
inherit from enums, annotations will be broken, etc. pycountries solves these issues and more.
Soon pycountries will be providing other ISO standards related to countries.
## Development
```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
## Contributing
1. Fork the Project
2. Open a Pull Request
3. Or just read here: [contributing](https://docs.github.com/en/get-started/quickstart/contributing-to-projects)
<p align="right">(<a href="#top">back to top</a>)</p>
## Methodology
1. Do a lot, break a lot.
2. There are no difficult tasks, only interesting.
3. Mostly TBD.
<p align="right">(<a href="#top">back to top</a>)</p>
## Important
1. Quality.
2. Security.
3. Google first.
<p align="right">(<a href="#top">back to top</a>)</p>
## License
Distributed under the MIT License. See [LICENSE.md](LICENSE.md) for more information.
<p align="right">(<a href="#top">back to top</a>)</p>
## Buy me a coffee if you want to support me
https://www.buymeacoffee.com/aivCoffee
## Contact
Hi all,
How are you? Hope You've enjoyed the project.
There are my contacts:
- [Linkedin](https://www.linkedin.com/in/aiv/)
- [Send an Email](mailto:coldie322@gmail.com?subject=[GitHub]-qworpa)
Project Link: https://github.com/koldakov/pycountries
Best regards,
[Ivan Koldakov](https://www.linkedin.com/in/aiv/)
[pypi_proj]: https://pypi.org/project/pycountries/
[documentation]: https://pycountries.readthedocs.io
## Visitor counter
<img src="https://profile-counter.glitch.me/pycountries/count.svg" />
Raw data
{
"_id": null,
"home_page": "https://github.com/koldakov/pycountries",
"name": "pycountries",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "pydantic, fastapi, countries, currencies",
"author": "Ivan Koldakov",
"author_email": "Ivan Koldakov <ivan@koldakov.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/9e/bb076d792502a5078735620e668def60e6dadaffe160519c84df6163959a/pycountries-1.2.1.tar.gz",
"platform": null,
"description": "# About The Project\n[][pypi_proj]\n[][pypi_proj]\n[](https://github.com/AivGitHub/pycountries/blob/main/LICENSE.md)\n[][documentation]\n\npycountries provides the ISO enums for the standards:\n\n- [iso-4217](https://www.iso.org/iso-4217-currency-codes.html)\n- [iso-3166](https://www.iso.org/iso-3166-country-codes.html)\n- [iso-639](https://www.iso.org/iso-639-language-code)\n\npycountries can be used natively with pydantic >= 1.5 and python >= 3.8.\nIt makes really easy to use fastapi and other related libraries.\n\n## Requirements\n\n1. Python >= 3.8\n\n## Installation\n\n```bash\npip install pycountries\n```\n\n## Usage\n\nExamples show how to use pycountries with pydantic + fastapi, but\nyou can use it with pydantic and any other libraries.\n\n```bash\npip install fastapi\npip install pycountries\n```\n\nWhen you have all required libraries you can quickstart with this code:\n\n```python\nfrom decimal import Decimal\n\nfrom fastapi import FastAPI\nfrom pycountries import Country, Currency, Language\nfrom pydantic import BaseModel, model_validator\n\n\napp = FastAPI()\n\n\nclass IndexRequest(BaseModel):\n country: Country\n currency: Currency\n amount: Decimal\n language: Language\n\n @model_validator(mode=\"after\")\n def validate_amount(self) -> \"IndexRequest\":\n # TODO: Keep in mind, you need to handle exceptions raised by clean_amount method,\n # otherwise Internal Server Error will be raised.\n self.amount = self.currency.clean_amount(self.amount)\n return self\n\n\nclass IndexResponse(BaseModel):\n amount: Decimal\n\n\n@app.post(\"/\")\nasync def root(data: IndexRequest):\n return IndexResponse(**data.model_dump())\n```\n\n### Request Examples\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{\"country\":\"US\", \"currency\":\"USD\", \"amount\":\"20.20\", \"language\":\"eng\"}' http://127.0.0.1:8000\n{\"amount\":\"20.20\"}\ncurl -X POST -H \"Content-Type: application/json\" -d '{\"country\":\"US\", \"currency\":\"USD\", \"amount\":\"-20.20\", \"language\":\"eng\"}' http://127.0.0.1:8000\nInternal Server Error\n```\n\n### Phones\n\nI'm still not sure about the logic, if you have any ideas please create a task\n[here](https://github.com/koldakov/pycountries/issues).\n\nThe problem here is that calling code is not unique per country. For example,\nat least 3 countries have code +1: United States, Canada, Barbados. To determine the country\nwe need to see a prefix - N numbers after country code. And, looks like these prefixes are quite\ndynamic, so should be managed accordingly.\n\nFor now logic is:\n1. Return first calling code match if prefix is not provided.\n2. If prefix is provided return first prefix match, or first \"candidate\" if there are no exact prefix matches.\n\nIt is very useful if you want to show phone dynamically. See an example below for more info.\n\n```python\nfrom pycountries import Phone\n\n# Return first match with different types\nPhone(1) # Phone.BB\nPhone(\"1\") # Phone.BB\nPhone(\"+1\") # Phone.BB\n\n# Result has changed, because results with prefixes in priority right now.\nPhone(1, prefix=3) # Phone.UM\nPhone(1, prefix=32) # Phone.UM\n# Exact match found!\nPhone(1, prefix=325) # Phone.US\n```\n\n## Motivation\n\nThere is a great library [pycountry](https://github.com/pycountry/pycountry), but it is incompatible with enums,\nfor sure enums can be generated dynamically, but python does not work good with dynamic enums, for example, you can not\ninherit from enums, annotations will be broken, etc. pycountries solves these issues and more.\nSoon pycountries will be providing other ISO standards related to countries.\n\n## Development\n\n```bash\npython3.12 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n## Contributing\n\n1. Fork the Project\n2. Open a Pull Request\n3. Or just read here: [contributing](https://docs.github.com/en/get-started/quickstart/contributing-to-projects)\n\n<p align=\"right\">(<a href=\"#top\">back to top</a>)</p>\n\n## Methodology\n\n1. Do a lot, break a lot.\n2. There are no difficult tasks, only interesting.\n3. Mostly TBD.\n\n<p align=\"right\">(<a href=\"#top\">back to top</a>)</p>\n\n## Important\n\n1. Quality.\n2. Security.\n3. Google first.\n\n<p align=\"right\">(<a href=\"#top\">back to top</a>)</p>\n\n## License\n\nDistributed under the MIT License. See [LICENSE.md](LICENSE.md) for more information.\n\n<p align=\"right\">(<a href=\"#top\">back to top</a>)</p>\n\n## Buy me a coffee if you want to support me\n\nhttps://www.buymeacoffee.com/aivCoffee\n\n## Contact\n\nHi all,\n\nHow are you? Hope You've enjoyed the project.\n\nThere are my contacts:\n\n- [Linkedin](https://www.linkedin.com/in/aiv/)\n- [Send an Email](mailto:coldie322@gmail.com?subject=[GitHub]-qworpa)\n\nProject Link: https://github.com/koldakov/pycountries\n\nBest regards,\n\n[Ivan Koldakov](https://www.linkedin.com/in/aiv/)\n\n\n[pypi_proj]: https://pypi.org/project/pycountries/\n[documentation]: https://pycountries.readthedocs.io\n\n## Visitor counter\n\n<img src=\"https://profile-counter.glitch.me/pycountries/count.svg\" />\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "List of existing countries and currencies",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://github.com/koldakov/pycountries",
"Issues": "https://github.com/koldakov/pycountries/issues"
},
"split_keywords": [
"pydantic",
" fastapi",
" countries",
" currencies"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1fa0ffcad3bda64e23a2f348c2166bd80d5f8cef7a2918b0c82399385b00c89b",
"md5": "0dc6591897338bb8e1c5952bcd77f3be",
"sha256": "fb9d530ed1bc75a0ae7fafe8a6d069c672643636a0217fc81b0aa60016c6aeb0"
},
"downloads": -1,
"filename": "pycountries-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0dc6591897338bb8e1c5952bcd77f3be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 41835,
"upload_time": "2024-09-20T14:51:21",
"upload_time_iso_8601": "2024-09-20T14:51:21.271061Z",
"url": "https://files.pythonhosted.org/packages/1f/a0/ffcad3bda64e23a2f348c2166bd80d5f8cef7a2918b0c82399385b00c89b/pycountries-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e9ebb076d792502a5078735620e668def60e6dadaffe160519c84df6163959a",
"md5": "1837eb9d9e814401545bd4c4ada33fea",
"sha256": "2c885528a9b0efe631c5e70959453a79febcf00063676c4781c460c45bfd55e6"
},
"downloads": -1,
"filename": "pycountries-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "1837eb9d9e814401545bd4c4ada33fea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 45126,
"upload_time": "2024-09-20T14:51:22",
"upload_time_iso_8601": "2024-09-20T14:51:22.505384Z",
"url": "https://files.pythonhosted.org/packages/0e/9e/bb076d792502a5078735620e668def60e6dadaffe160519c84df6163959a/pycountries-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-20 14:51:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "koldakov",
"github_project": "pycountries",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pydantic",
"specs": [
[
"==",
"2.8.2"
]
]
},
{
"name": "pre-commit",
"specs": [
[
"==",
"3.7.1"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"71.0.3"
]
]
},
{
"name": "Sphinx",
"specs": [
[
"==",
"7.4.6"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.2.2"
]
]
}
],
"lcname": "pycountries"
}
JSON
