# Tools for creation and conversion from/to desired classification (the default is ISO 3166-1)
This project was inspired by **[pycountry](https://pypi.org/project/pycountry/)** and **[pycountry-convert](https://pypi.org/project/pycountry-convert/)** modules and is a port of the **Stata package** **[pyconvertu](https://ideas.repec.org/c/boc/bocode/s458892.html)** *(Stata module to convert a string variable into a classification from the default or user-provided JSON file with the help of Python 3)* written in Python 3 and ADO. The tools can, for example, be used together with **[pandas](https://pypi.org/project/pandas/)** to process **pandas.DataFrame()**, `data`, `index`, and / or `columns` (consult examples):
- ``convert(source_file=None, from_list=[], to_classification='')`` converts a **tuple** or a **list** into a classification from a built-in or user-defined JSON file using **regular expressions**.
- ``classification(source_file=None, from_classification='')`` returns a **list** created from a classification.
- ``info(source_file=None)`` prints metadata and sources from the built-in or user-defined JSON file.
## Parameters:
- `source_file` : *raw str* or *unicode*, optional.
Relative or absolute path to the user-defined JSON file.
- `from_list` : *sequence* of *iterable*.
Input data.
- `to_classification` : *str* or *unicode*.
'name_en' (English name), 'name_fr' (French name), 'iso3' (ISO 3166-1 alpha-3), 'iso2' (ISO 3166-1 alpha-2), or 'isoN' (ISO 3166-1 numeric).
- `from_classification` : *str* or *unicode*.
'name_en' (English name), 'name_fr' (French name), 'iso3' (ISO 3166-1 alpha-3), 'iso2' (ISO 3166-1 alpha-2), or 'isoN' (ISO 3166-1 numeric).
`source_file` (if defined) replaces the default classification (ISO 3166-1). The file must contain a list of dictionaries where `regex` is a compulsory key in each one. The default JSON file was prepared with the help of **[json](https://docs.python.org/3/library/json.html)** module:
```
[
{
"regex": "^(.*afgh.*|\\s*AFG\\s*|\\s*AF\\s*|\\s*4\\s*)$",
"name_en": "Afghanistan", # classification A
"name_fr": "Afghanistan (l')", # classification B
"iso3": "AFG", # ...
"iso2": "AF",
"isoN": "4"
},
...
{
"metadata": {
"name_en": "English short name",
"name_fr": "French short name",
"iso3": "alpha-3 code",
"iso2": "alpha-2 code",
"isoN": "numeric"
}
},
{
"sources": [
"[https://www.iso.org/iso-3166-country-codes.html](ISO 3166 COUNTRY CODES)",
"[https://en.wikipedia.org/wiki/List_of_alternative_country_names](ALTERNATIVE NAMES)"
]
}
]
```
## Returns:
- `l` : *list*.
Processed data.
## Examples:
```
import pandas as pd
from pyconvertu import convert
from pyconvertu import classification
from pyconvertu import info
# Create a pandas dataframe with ISO 3166-1 alpha-3 as `index'
data = [1, 2, 3, 4, 5, 6, 7]
iso3 = convert(
from_list=['Canada', 'France', 'Germany', 'Italy', 'Japan', 'United Kingdom', 'United States'],
to_classification='iso3'
)
pd.DataFrame(data, index=iso3)
# Create a pandas dataframe from available classifications
df = pd.DataFrame()
df['iso3'] = classification(from_classification='iso3')
for s in ['iso2', 'isoN', 'name_en', 'name_fr']:
df[s] = convert(
from_list=df['iso3'],
to_classification=s
)
print(df)
# Print information and metadata for the built-in JSON file and my_file.json
info()
info(source_file=r'my_file.json')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/econcz/pyconvertu",
"name": "pyconvertu",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "classification,ISO-3166,alpha-3,alpha-2,numeric,English,French,regular expressions",
"author": "econcz",
"author_email": "29724411+econcz@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/c6/e7/5ff22ea8cccc527ad56d8659849137d63b856507d5dbd9c13371b03789ea/pyconvertu-0.4.1.tar.gz",
"platform": null,
"description": "# Tools for creation and conversion from/to desired classification (the default is ISO 3166-1)\n\n\nThis project was inspired by **[pycountry](https://pypi.org/project/pycountry/)** and **[pycountry-convert](https://pypi.org/project/pycountry-convert/)** modules and is a port of the **Stata package** **[pyconvertu](https://ideas.repec.org/c/boc/bocode/s458892.html)** *(Stata module to convert a string variable into a classification from the default or user-provided JSON file with the help of Python 3)* written in Python 3 and ADO. The tools can, for example, be used together with **[pandas](https://pypi.org/project/pandas/)** to process **pandas.DataFrame()**, `data`, `index`, and / or `columns` (consult examples):\n\n- ``convert(source_file=None, from_list=[], to_classification='')`` converts a **tuple** or a **list** into a classification from a built-in or user-defined JSON file using **regular expressions**. \n- ``classification(source_file=None, from_classification='')`` returns a **list** created from a classification. \n- ``info(source_file=None)`` prints metadata and sources from the built-in or user-defined JSON file.\n\n\n## Parameters:\n- `source_file` : *raw str* or *unicode*, optional. \nRelative or absolute path to the user-defined JSON file.\n- `from_list` : *sequence* of *iterable*. \nInput data.\n- `to_classification` : *str* or *unicode*. \n'name_en' (English name), 'name_fr' (French name), 'iso3' (ISO 3166-1 alpha-3), 'iso2' (ISO 3166-1 alpha-2), or 'isoN' (ISO 3166-1 numeric).\n- `from_classification` : *str* or *unicode*. \n'name_en' (English name), 'name_fr' (French name), 'iso3' (ISO 3166-1 alpha-3), 'iso2' (ISO 3166-1 alpha-2), or 'isoN' (ISO 3166-1 numeric).\n\n\n`source_file` (if defined) replaces the default classification (ISO 3166-1). The file must contain a list of dictionaries where `regex` is a compulsory key in each one. The default JSON file was prepared with the help of **[json](https://docs.python.org/3/library/json.html)** module:\n```\n[\n {\n \"regex\": \"^(.*afgh.*|\\\\s*AFG\\\\s*|\\\\s*AF\\\\s*|\\\\s*4\\\\s*)$\",\n \"name_en\": \"Afghanistan\", # classification A\n \"name_fr\": \"Afghanistan (l')\", # classification B\n \"iso3\": \"AFG\", # ...\n \"iso2\": \"AF\",\n \"isoN\": \"4\"\n },\n ...\n {\n \"metadata\": {\n \"name_en\": \"English short name\",\n \"name_fr\": \"French short name\",\n \"iso3\": \"alpha-3 code\",\n \"iso2\": \"alpha-2 code\",\n \"isoN\": \"numeric\"\n }\n },\n {\n \"sources\": [\n \"[https://www.iso.org/iso-3166-country-codes.html](ISO 3166 COUNTRY CODES)\",\n \"[https://en.wikipedia.org/wiki/List_of_alternative_country_names](ALTERNATIVE NAMES)\"\n ]\n }\n]\n```\n\n\n## Returns:\n- `l` : *list*. \nProcessed data.\n\n\n## Examples:\n```\nimport pandas as pd\nfrom pyconvertu import convert\nfrom pyconvertu import classification\nfrom pyconvertu import info\n\n# Create a pandas dataframe with ISO 3166-1 alpha-3 as `index'\ndata = [1, 2, 3, 4, 5, 6, 7]\niso3 = convert(\n from_list=['Canada', 'France', 'Germany', 'Italy', 'Japan', 'United Kingdom', 'United States'],\n to_classification='iso3'\n)\npd.DataFrame(data, index=iso3)\n\n# Create a pandas dataframe from available classifications\ndf = pd.DataFrame()\ndf['iso3'] = classification(from_classification='iso3')\nfor s in ['iso2', 'isoN', 'name_en', 'name_fr']:\n df[s] = convert(\n from_list=df['iso3'],\n to_classification=s\n )\nprint(df)\n\n# Print information and metadata for the built-in JSON file and my_file.json\ninfo()\ninfo(source_file=r'my_file.json')\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tools for creation or conversion of lists from/to desired classification (the default is ISO 3166-1)",
"version": "0.4.1",
"project_urls": {
"Download": "https://github.com/econcz/pyconvertu/archive/pypi-0_4_1.tar.gz",
"Homepage": "https://github.com/econcz/pyconvertu"
},
"split_keywords": [
"classification",
"iso-3166",
"alpha-3",
"alpha-2",
"numeric",
"english",
"french",
"regular expressions"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c6e75ff22ea8cccc527ad56d8659849137d63b856507d5dbd9c13371b03789ea",
"md5": "4a3ed0bd4e42bb0637be24537ca4478a",
"sha256": "7a127b1f0b1c2536b13dbf61ad429e500bbf8d32067292b7a46f6181696b9088"
},
"downloads": -1,
"filename": "pyconvertu-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "4a3ed0bd4e42bb0637be24537ca4478a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17445,
"upload_time": "2024-02-22T13:48:30",
"upload_time_iso_8601": "2024-02-22T13:48:30.472845Z",
"url": "https://files.pythonhosted.org/packages/c6/e7/5ff22ea8cccc527ad56d8659849137d63b856507d5dbd9c13371b03789ea/pyconvertu-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-22 13:48:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "econcz",
"github_project": "pyconvertu",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyconvertu"
}
JSON
