Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A convenience API for transformations between different ISO 3166 country codes.

Project Description

incf.countryutils provides a convenience API on top of a list of countries by continent (data_file) as found on Wikipedia (a copy is included in the distribution).

It supports transformations between the different types of country codes and names like in:

>>> from incf.countryutils import transformations
>>> transformations.cca2_to_ccn('de')
>>> transformations.ccn_to_cn(276)

Country codes supported are numeric (ccn; internal reference format), two letter country codes (cca2), and three letter country codes (cca3). In addition, incf.countryutils knows the simple English name of each country (cn) as well as the official English name.

Transformation names follow the pattern <f1>_to_<f2> where f1 and f2 refer to country codes or names. All transformations to and from the reference format (ccn) are provided.

When providing a numeric country code as an argument integer as well as string representations are accepted.

Moreover, there are some combined transformations available for convenience. Most notably this is <any country code>_to_<simple or official name>:

>>> transformations.cc_to_cn('FR')
>>> transformations.cc_to_cn('FRa')
>>> transformations.cc_to_cn('250')
>>> transformations.cc_to_cn(250)
>>> transformations.cc_to_con(250)
'French Republic France'

Lookup by name is only supported for the simple English name:

>>> transformations.cn_to_ccn('Italy')
>>> transformations.ccn_to_con('380')
'Italian Republic Italy'


Based on the data from Wikipedia incf.countryutils allows looking up the continent a country belongs to (ctn: continent name; ctca2: two letter continent code):

>>> transformations.cn_to_ctn('Italy')
>>> transformations.cca_to_ctn('us')
'North America'

Continents have two letter codes as well like in:

>>> transformations.cca_to_ctca2('usa')

Given a continent, one can obtain its constituent countries:

>>> transformations.ctca2_to_ccn('AN')
['010', '074', '260', '334', '239']

Alternative API (OO)

There is an alternative, more object-oriented API based on the notion of Country and Continent types. On creation, a country or continent needs to be passed a name or code:

>>> from incf.countryutils.datatypes import Country
>>> china = Country('China')
>>> china
<incf.countryutils.datatypes.Country object at 0x...>

The country’s names and codes are available as attributes:

>>> china.official_name
"People's Republic of China"
>>> china.numeric
>>> china.alpha2
>>> china.alpha3

and the continent property refers to a corresponding Continent instance:

>>> china.continent
<incf.countryutils.datatypes.Continent object at 0x...>

which in turn has the following attributes:

>>> china.continent.alpha2

Asking a continent for its constituent countries returns a generator object returning country instances in turn:

>>> china.continent.countries
<generator object at 0x...>
<incf.countryutils.datatypes.Country object at 0x...>
>>> [ for c in china.continent.countries]
['Afghanistan', 'Armenia', 'Azerbaijan', 'Bahrain', ...]


1.0 - (2009-04-20)

  • Initial release
Release History

Release History

This version
History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
incf.countryutils-1.0.tar.gz (21.6 kB) Copy SHA256 Checksum SHA256 Source Apr 20, 2009

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting