pyconvertu


Namepyconvertu JSON
Version 0.4.1 PyPI version JSON
download
home_pagehttps://github.com/econcz/pyconvertu
SummaryTools for creation or conversion of lists from/to desired classification (the default is ISO 3166-1)
upload_time2024-02-22 13:48:30
maintainer
docs_urlNone
authoreconcz
requires_python
licenseMIT
keywords classification iso-3166 alpha-3 alpha-2 numeric english french regular expressions
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.20081s