=========
pycountry
=========

pycountry provides the ISO databases for the standards:

639
  Languages

3166
  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 politicial situation in the world, please talk to
the ISO or Debian people, not me.

Build status
============

pycountry
    .. image:: https://builds.gocept.com/job/pycountry/badge/icon
       :target: https://builds.gocept.com/job/pycountry/

The code lives in a `bitbucket Mercurial repository
<https://bitbucket.org/gocept/pycountry>`_, and issues must be reported in
`project bugtracker
<https://bitbucket.org/gocept/pycountry/issues?status=new&status=open>`_.

Countries (ISO 3166)
====================

Countries are accessible through a database object that is already configured
upon import of pycountry and works as an iterable:

  >>> import pycountry
  >>> len(pycountry.countries)
  249
  >>> list(pycountry.countries)[0]
  <pycountry.db.Country object at 0x...>

Specific countries can be looked up by their various codes and provide the
information included in the standard as attributes:

  >>> germany = pycountry.countries.get(alpha2='DE')
  >>> germany
  <pycountry.db.Country object at 0x...>
  >>> germany.alpha2
  u'DE'
  >>> germany.alpha3
  u'DEU'
  >>> germany.numeric
  u'276'
  >>> germany.name
  u'Germany'
  >>> germany.official_name
  u'Federal Republic of Germany'

The `historic_countries` database contains former countries that have been
removed from the standard and are now included in ISO 3166-3, in addition
to the existing ones:

 >>> ussr = pycountry.historic_countries.get(alpha2='SU')
 >>> ussr
 <pycountry.db.Country object at 0x...>
 >>> ussr.alpha4
 u'SUHH'
 >>> ussr.alpha3
 u'SUN'
 >>> ussr.name
 u'USSR, Union of Soviet Socialist Republics'
 >>> ussr.date_withdrawn
 u'1992-08-30'
 >>> ussr.deleted
 True
 >>> russia = pycountry.historic_countries.get(alpha2='RU')
 >>> russia
 <pycountry.db.Country object at 0x...>
 >>> russia.name
 u'Russian Federation'
 >>> russia.deleted
 False


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:

  >>> len(pycountry.subdivisions)
  4847
  >>> list(pycountry.subdivisions)[0]
  <pycountry.db.Subdivision object at 0x...>

Subdivisions can be accessed using their unique code and provide at least
their code, name and type:

  >>> de_st= pycountry.subdivisions.get(code='DE-ST')
  >>> de_st.code
  u'DE-ST'
  >>> de_st.name
  u'Sachsen-Anhalt'
  >>> de_st.type
  u'State'
  >>> de_st.country
  <pycountry.db.Country object at 0x...>

Some subdivisions specify another subdivision as a parent:

  >>> al_br = pycountry.subdivisions.get(code='AL-BU')
  >>> al_br.code
  u'AL-BU'
  >>> al_br.name
  u'Bulqiz\xeb'
  >>> al_br.type
  u'District'
  >>> al_br.parent_code
  u'AL-09'
  >>> al_br.parent
  <pycountry.db.Subdivision object at 0x...>
  >>> al_br.parent.name
  u'Dib\xebr'

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

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

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


Scripts (ISO 15924)
===================

Scripts are available from a database similar to the countries:

  >>> len(pycountry.scripts)
  163
  >>> list(pycountry.scripts)[0]
  <pycountry.db.Script object at 0x...>

  >>> latin = pycountry.scripts.get(name='Latin')
  >>> latin
  <pycountry.db.Script object at 0x...>
  >>> latin.alpha4
  u'Latn'
  >>> latin.name
  u'Latin'
  >>> latin.numeric
  u'215'


Currencies (ISO 4217)
=====================

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

  >>> len(pycountry.currencies)
  182
  >>> list(pycountry.currencies)[0]
  <pycountry.db.Currency object at 0x...>

  >>> argentine_peso = pycountry.currencies.get(letter='ARS')
  >>> argentine_peso
  <pycountry.db.Currency object at 0x...>
  >>> argentine_peso.letter
  u'ARS'
  >>> argentine_peso.name
  u'Argentine Peso'
  >>> argentine_peso.numeric
  u'032'


Languages (ISO 639)
===================

The languages database is similar too:

  >>> len(pycountry.languages)
  487
  >>> list(pycountry.languages)[0]
  <pycountry.db.Language object at 0x...>

  >>> aragonese = pycountry.languages.get(alpha2='an')
  >>> aragonese.alpha2
  u'an'
  >>> aragonese.bibliographic
  u'arg'
  >>> aragonese.terminology
  u'arg'
  >>> aragonese.name
  u'Aragonese'

  >>> bengali = pycountry.languages.get(alpha2='bn')
  >>> bengali.name
  u'Bengali'
  >>> bengali.common_name
  u'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:

  >>> import gettext
  >>> german = gettext.translation('iso3166', pycountry.LOCALES_DIR,
  ...                              languages=['de'])
  >>> german.install()
  >>> _('Germany')
  'Deutschland'
