###########
pycountry
###########

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

pycountry provides the ISO databases for the standards:

639-3 <https://en.wikipedia.org/wiki/ISO_639-3>_ Languages
3166 <https://en.wikipedia.org/wiki/ISO_3166>_ Codes for
representation of names of countries and their subdivisions
3166-1 <https://en.wikipedia.org/wiki/ISO_3166-1>_ Countries
3166-3 <https://en.wikipedia.org/wiki/ISO_3166-3>_ Deleted
countries
3166-2 <https://en.wikipedia.org/wiki/ISO_3166-2>_ Subdivisions of
countries
4217 <https://en.wikipedia.org/wiki/ISO_4217>_ Currencies
15924 <https://en.wikipedia.org/wiki/ISO_15924>_ Scripts

The package includes a copy from Debian's pkg-isocodes <https://salsa.debian.org/iso-codes-team/iso-codes>_ 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 <https://feministfrequency.com/donate/>_ 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 <https://github.com/pycountry/pycountry>_, 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')
<pycountry.db.Country object at 0x...>

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 <https://groups.google.com/g/pyinstaller/c/OYhJdeZ9010/m/vLhYAWUzAQAJ>_.

Package profile

pycountry

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description