Metadata-Version: 2.1
Name: pycountry
Version: 1.18
Summary: ISO country, subdivision, language, currency and script definitions and their translations
Home-page: UNKNOWN
Author: Christian Theune
Author-email: ct@flyingcircus.io
License: LGPL 2.1
Keywords: country subdivision language currency iso 3166 639 4217 15924 3166-2
Platform: UNKNOWN
License-File: LICENSE.txt

=========
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://drone.io/bitbucket.org/flyingcircus/pycountry/status.png
       :target: https://drone.io/bitbucket.org/flyingcircus/pycountry/latest)

The code lives in a `bitbucket Mercurial repository
<https://bitbucket.org/flyingcircus/pycountry>`_, and issues must be reported in
`project bugtracker
<https://bitbucket.org/flyingcircus/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)
  7874
  >>> list(pycountry.languages)[0]
  <pycountry.db.Language object at 0x...>

  >>> aragonese = pycountry.languages.get(iso639_1_code='an')
  >>> aragonese.iso639_1_code
  u'an'
  >>> aragonese.iso639_2T_code
  u'arg'
  >>> aragonese.iso639_3_code
  u'arg'
  >>> aragonese.name
  u'Aragonese'

  >>> bengali = pycountry.languages.get(iso639_1_code='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'

Changes
=======

1.18 (2015-11-04)
-----------------

- Update to iso-codes 3.63.

- Add Python 3.5 to the tox configuration.


1.17 (2015-10-07)
-----------------

- Fix memory leak of XML dom elements. Thanks to @rhathe for noticing
  the superfluous memory consumption. (Fixes #13377)


1.16 (2015-10-06)
-----------------

- Update to iso-codes 3.62.

- Big initial performance improvement after initial draft from
  @lucaswiman. We're now lazy loading the databases which makes
  pycountry import extremely cheap and after that we only load
  the databases you actually use.


1.15 (2015-09-08)
-----------------

- Update to iso-codes 3.61.


1.14 (2015-08-09)
-----------------

- Update to iso-codes 3.60.


1.13 (2015-07-19)
-----------------

- Stop bundling the source PO files in the sdist to make the distribution
  smaller. (#13371)

- Update to iso-codes 3.59.

- Ensure immediate closing of file descriptors when loading
  a database (as requested in #13106).


1.12 (2015-06-13)
-----------------

- Add support for ISO 639 3, dropping the old ISO 639 support.
  This is an incompatible API change! (Thanks to Justin Wagner for
  the work!)


1.11 (2015-06-13)
-----------------

- Update to iso-codes 3.58.


1.10 (2014-11-10)
-----------------

- Parent-less top-level subdivisions no longer raise a ``KeyError: None``
  exception on ``parent`` attribute lookup. Normalize return value to ``None``
  instead.

1.9 (2014-11-10)
----------------


- Update to iso-codes 3.57.


1.8 (2014-07-06)
----------------

- Update to iso-codes 3.55.


1.7 (2014-06-24)
----------------

- Update to iso-codes 3.54.

- Change database access to better support setuptools and py2exe (and similar
  tools). Thanks to @MarioVilas.


1.6 (2014-05-02)
----------------

- Update to isocodes 3.52.

- Add Python 3.4 tox testing.
  Supported Python versions are now: 2.6, 2.7, 3.3, 3.4

1.5 (2014-04-03)
----------------

- Update to isocodes 3.52.


1.4 (2014-02-07)
----------------

- Upgrade to isocodes 3.51.


1.3 (2013-12-11)
----------------

- Upgrade to isocodes 3.49

- Downgrade another warning message for the databases to 'debug' as users of
  the library can't really do anything about it (except nagging upstream DB
  maintainers).

1.2 (2013-11-06)
----------------

- Downgrade the warning message about duplication in the databases to 'debug'
  as users of the library can't really do anything about it (except nagging
  upstream DB maintainers).

1.1 (2013-10-04)
----------------

- Update database to isocodes 3.47


1.0 (2013-09-02)
----------------

- Update database to isocodes 3.46


0.19 (2013-08-20)
-----------------

- Provide acess to historical country information (ISO 3166-3). Thanks to
  @pferreir who provided the pull request.


0.18 (2013-08-02)
-----------------

- Switch buildout to 2.2, enforce using setuptools

- Update to iso-codes 3.45.

0.17 (2013-07-10)
-----------------

- Refactor dependencies to avoid test dependencies screwing up other peoples'
  projects by accidentally installing plugins.


0.16 (2013-07-02)
-----------------

- Update to iso-codes 3.44.


0.15 (2013-06-22)
-----------------

- Update to iso-codes 3.43.

- Switch testing to pytest.

- Make Python 3 compatible.


0.14.8 (2013-02-25)
-------------------

- Update to iso-codes 3.41.


0.14.7 (2012-11-03)
-------------------

- Update to iso-codes 3.40.

- Adapt Language objects to include `common_name` attribute added in iso-codes
  3.40.

0.14.6 (2012-10-02)
-------------------

- Update to iso-codes 3.39.


0.14.5 (2012-09-14)
-------------------

- Re-add the patch that should have been 0.14.4. Migrating to mercurial caused
  me to miss it.


0.14.4 (2012-09-14)
-------------------

- Explicitly unlink DOM tree to support (faster) memory deallocation. Thanks to
  Romuald Brunet.


0.14.3 (2012-09-04)
-------------------

- Update data to iso-codes 3.38.


0.14.2 (2012-07-18)
-------------------

- Update data to iso-codes 3.37.


0.14.1 (2011-07-15)
-------------------

- Nothing changed yet.


0.14 (2011-07-06)
-----------------

- Update data to iso-codes 3.26.


0.13 (2010-04-23)
-----------------

- Applied patch from Pedro Araujo which removes the somewhat superfluous
  dependency on lxml to the builtin minidom. This seems to consistently turn
  all strings into unicode even if they only contain ASCII characters.


0.12.1 (2010-04-21)
-------------------

- Remedy brown-bag release 0.12 which was missing all data files due to a bad
  interaction between the build system for the data and zest.releaeser's
  full-release script.


0.12 (2010-04-20)
-----------------

- Follow Debian repository to git.

- Upgrade data to revision 770fa9cd603f90f9fb982b32fe6f45d253f1d33e as
  requested by #5488 and others.

- Reflect subdivision changes with how they reference their parents in the XML
  (they used to use space as a separator but now use a hyphen).

- Refactor index building structures a bit.

- Remove superfluous 'code' index from subdivision database. (Together with
  the data upgrade this also gets rid of all the annoying warnings as
  described in #6667).

- Some light PEP 8 improvements.

0.11 (2009-03-03)
-----------------

- Updated Debian repository to r1752.


0.10 (2008-06-26)
-----------------

- Added support for country subdivisions (ISO 3166-2).


0.9
---

- Initial release


