Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pycountry/pycountry

A Python library to access ISO country, subdivision, language, currency and script definitions and their translations.
https://github.com/pycountry/pycountry

Last synced: 14 days ago
JSON representation

A Python library to access ISO country, subdivision, language, currency and script definitions and their translations.

Awesome Lists containing this project

README 

        
###########

 pycountry

###########



..

   image:g: https://travis-ci.org/flyingcircusio/pycountry.svg?branch=master



pycountry provides the ISO databases for the standards:



-  `639-3 `_ Languages

-  `3166 `_ Codes for

   representation of names of countries and their subdivisions

-  `3166-1 `_ Countries

-  `3166-3 `_ Deleted

   countries

-  `3166-2 `_ Subdivisions of

   countries

-  `4217 `_ Currencies

-  `15924 `_ Scripts



The package includes a copy from Debian's `pkg-isocodes

`_ and makes the data

accessible through a Python API.



Translation files for the various strings are included as well.



********************

 Data update policy

********************



No changes to the data will be accepted into pycountry. This is a pure

wrapper around the ISO standard using the ``pkg-isocodes`` database from

Debian *as is*. If you need changes to the political situation in the

world, please talk to the ISO or Debian people, not me.



******************************

 Donations / Monetary Support

******************************



This is a small project that I maintain in my personal time. I am not

interested in personal financial gain. However, if you would like to

support the project then I would love if you would donate to `Feminist

Frequency `_ instead. Also, let

the world know you did so, so that others can follow your path.



***************

 Contributions

***************



The code lives in a `git repository on GitHub

`_, and issues must be reported

in there as well.



************************

 Countries (ISO 3166-1)

************************



Countries are accessible through a database object that is already

configured upon import of pycountry and works as an iterable:



.. code:: pycon



   >>> import pycountry

   >>> len(pycountry.countries)

   249

   >>> list(pycountry.countries)[0]

   Country(alpha_2='AF', alpha_3='AFG', name='Afghanistan', numeric='004', official_name='Islamic Republic of Afghanistan')



Specific countries can be looked up by their various codes and provide

the information included in the standard as attributes:



.. code:: pycon



   >>> germany = pycountry.countries.get(alpha_2='DE')

   >>> germany

   Country(alpha_2='DE', alpha_3='DEU', name='Germany', numeric='276', official_name='Federal Republic of Germany')

   >>> germany.alpha_2

   'DE'

   >>> germany.alpha_3

   'DEU'

   >>> germany.numeric

   '276'

   >>> germany.name

   'Germany'

   >>> germany.official_name

   'Federal Republic of Germany'



There's also a "fuzzy" search to help people discover "proper" countries

for names that might only actually be subdivisions. The fuzziness also

includes normalizing unicode accents. There's also a bit of

prioritization included to prefer matches on country names before

subdivision names and have countries with more matches be listed before

ones with fewer matches:



.. code:: pycon



   >>> pycountry.countries.search_fuzzy('England')

   [Country(alpha_2='GB', alpha_3='GBR', name='United Kingdom', numeric='826', official_name='United Kingdom of Great Britain and Northern Ireland')]



   >>> pycountry.countries.search_fuzzy('Cote')

   [Country(alpha_2='CI', alpha_3='CIV', name="Côte d'Ivoire", numeric='384', official_name="Republic of Côte d'Ivoire"),

    Country(alpha_2='FR', alpha_3='FRA', name='France', numeric='250', official_name='French Republic'),

    Country(alpha_2='HN', alpha_3='HND', name='Honduras', numeric='340', official_name='Republic of Honduras')]



Attributes for the country class can be accessed using the

``__getattr__`` method. If the requested attribute is a key for the

country class, it will return the corresponding value. In the special

cases of missing 'common_name' or 'official_name' attributes,

``__getattr__`` will return 'name'. Here are some examples:



.. code:: pycon



   >>> aland = pycountry.countries.get(alpha_2='AX')



   >>> print(aland)

   Country(alpha_2='AX', alpha_3='ALA', flag='🇦🇽', name='Åland Islands', numeric='248')



   >>> aland.common_name

   UserWarning: Country's common_name not found. Country name provided instead.

     warnings.warn(warning_message, UserWarning)

   'Åland Islands'



   >>> aland.official_name

   Country's official_name not found. Country name provided instead.

     warnings.warn(warning_message, UserWarning)

   'Åland Islands'



   >>> aland.flag

   '🇦🇽'



   >>> aland.foo  # Raises AttributeError



*********************************

 Historic Countries (ISO 3166-3)

*********************************



The ``historic_countries`` database contains former countries that have

been removed from the standard and are now included in ISO 3166-3,

excluding existing ones:



.. code:: pycon



   >>> ussr = pycountry.historic_countries.get(alpha_3='SUN')

   >>> ussr

   Country(alpha_3='SUN', alpha_4='SUHH', withdrawal_date='1992-08-30', name='USSR, Union of Soviet Socialist Republics', numeric='810')

   >>> ussr.alpha_4

   'SUHH'

   >>> ussr.alpha_3

   'SUN'

   >>> ussr.name

   'USSR, Union of Soviet Socialist Republics'

   >>> ussr.withdrawal_date

   '1992-08-30'



***********************************

 Country subdivisions (ISO 3166-2)

***********************************



The country subdivisions are a little more complex than the countries

itself because they provide a nested and typed structure.



All subdivisons can be accessed directly:



.. code:: pycon



   >>> len(pycountry.subdivisions)

   4847

   >>> list(pycountry.subdivisions)[0]

   Subdivision(code='AD-07', country_code='AD', name='Andorra la Vella', parent_code=None, type='Parish')



Subdivisions can be accessed using their unique code. The resulting

object will provide at least their code, name and type:



.. code:: pycon



   >>> de_st = pycountry.subdivisions.get(code='DE-ST')

   >>> de_st.code

   'DE-ST'

   >>> de_st.name

   'Sachsen-Anhalt'

   >>> de_st.type

   'State'

   >>> de_st.country

   Country(alpha_2='DE', alpha_3='DEU', name='Germany', numeric='276', official_name='Federal Republic of Germany')



Some subdivisions specify another subdivision as a parent:



.. code:: pycon



   >>> al_br = pycountry.subdivisions.get(code='AL-BU')

   >>> al_br.code

   'AL-BU'

   >>> al_br.name

   'Bulqiz\xeb'

   >>> al_br.type

   'District'

   >>> al_br.parent_code

   'AL-09'

   >>> al_br.parent

   Subdivision(code='AL-09', country_code='AL', name='Dib\xebr', parent_code=None, type='County')

   >>> al_br.parent.name

   'Dib\xebr'



The divisions of a single country can be queried using the country_code

index:



.. code:: pycon



   >>> len(pycountry.subdivisions.get(country_code='DE'))

   16



   >>> len(pycountry.subdivisions.get(country_code='US'))

   57



Similar to countries, the ``search_fuzzy`` method has been implemented

for subdivisions to facilitate finding relevant subdivision entries.

This method includes unicode normalization for accents and prioritizes

matches on subdivision names. The search algorithm is designed to return

more relevant matches first:



This method is especially useful for cases where the exact name or code

of the subdivision is not known.



.. code:: pycon



   >>> pycountry.subdivisions.search_fuzzy('York')

     [Subdivision(code='GB-YOR', country_code='GB', name='York', parent='GB-ENG', parent_code='GB-GB-ENG', type='Unitary authority')

     Subdivision(code='GB-ERY', country_code='GB', name='East Riding of Yorkshire', parent='GB-ENG', parent_code='GB-GB-ENG', type='Unitary authority')

     Subdivision(code='GB-NYK', country_code='GB', name='North Yorkshire', parent='GB-ENG', parent_code='GB-GB-ENG', type='Two-tier county')

     Subdivision(code='US-NY', country_code='US', name='New York', parent_code=None, type='State')]



*********************

 Scripts (ISO 15924)

*********************



Scripts are available from a database similar to the countries:



.. code:: pycon



   >>> len(pycountry.scripts)

   169

   >>> list(pycountry.scripts)[0]

   Script(alpha_4='Afak', name='Afaka', numeric='439')



   >>> latin = pycountry.scripts.get(name='Latin')

   >>> latin

   Script(alpha_4='Latn', name='Latin', numeric='215')

   >>> latin.alpha4

   'Latn'

   >>> latin.name

   'Latin'

   >>> latin.numeric

   '215'



***********************

 Currencies (ISO 4217)

***********************



The currencies database is, again, similar to the ones before:



.. code:: pycon



   >>> len(pycountry.currencies)

   182

   >>> list(pycountry.currencies)[0]

   Currency(alpha_3='AED', name='UAE Dirham', numeric='784')

   >>> argentine_peso = pycountry.currencies.get(alpha_3='ARS')

   >>> argentine_peso

   Currency(alpha_3='ARS', name='Argentine Peso', numeric='032')

   >>> argentine_peso.alpha_3

   'ARS'

   >>> argentine_peso.name

   'Argentine Peso'

   >>> argentine_peso.numeric

   '032'



***********************

 Languages (ISO 639-3)

***********************



The languages database is similar too:



.. code:: pycon



   >>> len(pycountry.languages)

   7874

   >>> list(pycountry.languages)[0]

   Language(alpha_3='aaa', name='Ghotuo', scope='I', type='L')



   >>> aragonese = pycountry.languages.get(alpha_2='an')

   >>> aragonese.alpha_2

   'an'

   >>> aragonese.alpha_3

   'arg'

   >>> aragonese.name

   'Aragonese'



   >>> bengali = pycountry.languages.get(alpha_2='bn')

   >>> bengali.name

   'Bengali'

   >>> bengali.common_name

   'Bangla'



*********

 Locales

*********



Locales are available in the ``pycountry.LOCALES_DIR`` subdirectory of

this package. The translation domains are called ``isoXXX`` according to

the standard they provide translations for. The directory is structured

in a way compatible to Python's gettext module.



Here is an example translating language names:



.. code:: pycon



   >>> import gettext

   >>> german = gettext.translation('iso3166-1', pycountry.LOCALES_DIR,

   ...                              languages=['de'])

   >>> german.install()

   >>> _('Germany')

   'Deutschland'



*********

 Lookups

*********



For each database (countries, languages, scripts, etc.), you can also

look up entities case insensitively without knowing which key the value

may match. For example:



.. code:: pycon



   >>> pycountry.countries.lookup('de')

   



The search ends with the first match, which is returned.



********************

 Dict Compatibility

********************



You can cast each object type into a ``dict``:



.. code:: pycon



   >>> country = pycountry.countries.lookup('de')

   >>> dict(country)

   {'alpha_2': 'DE', 'name': 'Germany', ...}



******************

 Custom Countries

******************



While pycountry will not be adding non-ISO values to its standard

library, you can add or remove entries at runtime to fit your needs.



Add a non-ISO country:



.. code:: pycon



   >>> pycountry.countries.add_entry(alpha_2="XK", alpha_3="XXK", name="Kosovo", numeric="926")



Remove a country from a database:



.. code:: pycon



   >>> pycountry.countries.remove_entry(alpha_2="XK")



***************************

 PyInstaller Compatibility

***************************



Some users have reported issues using PyCountry with PyInstaller

guidance on how to handle the issues can be found in the `PyInstaller

Google Group

`_.