Class `CountryCodes()` to search and convert between `iso` and `fips` country codes.
from fastcore.test import test_eq
from nbdev.showdoc import show_doc

Solution to a problem

Joshua Project uses FIPS codes (US Federal Information Processing Standard) for countries.

FIPS 10-4 (April 1995) -- Countries, Dependencies, Areas of Special Sovereignty, and TheirPrincipal Administrative Divisions.

However, FIPS 10-4 was withdrawn by NIST on September 2, 2008 in favor of the international ISO 3166 standard.

In the meantime, as of Jan 2020 Joshua Project has no plans to switch onto ISO codes, I was notified. sigh

Sadly, FIPS in 60% cases differs from the ISO.

This library provides a CountryCodes() class to workaround this discrepancy.

Wherever the library uses the term iso code, ISO 3166 alpha 2 country code is implied as defined here: https://www.iso.org/obp/ui/

from joshuaproject.countrycodes import CountryCodes

class CountryCodes[source]

CountryCodes()

Returns FIPS and ISO 3166 alpha 2 country codes for cname and converts between.

cc = CountryCodes()

test_eq(len(cc),len(cc.data))
len(cc)

249

CountryCodes.head[source]

CountryCodes.head(rows=10)

Returns first rows.

cc.head(5)
cname FIPS ISO
0 Afghanistan AF AF
1 Aland Islands NaN AX
2 Albania AL AL
3 Algeria AG DZ
4 American Samoa AQ AS 
cc.data[cc.data.FIPS.isna()]
cname FIPS ISO
1 Aland Islands NaN AX
27 Bonaire, Sint Eustatius and Saba NaN BQ
236 United States Minor Outlying Islands NaN UM

CountryCodes.tail[source]

CountryCodes.tail(rows=10)

Returns last rows.

cc.tail(5)
cname FIPS ISO
244 Wallis and Futuna WF WF
245 Western Sahara WI EH
246 Yemen YM YE
247 Zambia ZA ZM
248 Zimbabwe ZI ZW

CountryCodes.__getitem__[source]

CountryCodes.__getitem__(idx)

Return idxth element of data.

cc[101]

cname    Iceland
FIPS          IC
ISO           IS
Name: 101, dtype: object
test_eq(cc[101].cname, 'Iceland')
test_eq(cc[101].FIPS,'IC')
test_eq(cc[101].ISO, 'IS')

Also supports slicing.

cc[10:13]
cname FIPS ISO
10 Argentina AR AR
11 Armenia AM AM
12 Aruba AA AW

CountryCodes.like[source]

CountryCodes.like(cname:str, mx:int=None)

Returns a list of dict with mx entries with country name like cname.

cc.like('United')

[{'cname': 'Tanzania, United Republic of', 'FIPS': 'TZ', 'ISO': 'TZ'},
 {'cname': 'United Arab Emirates', 'FIPS': 'AE', 'ISO': 'AE'},
 {'cname': 'United Kingdom', 'FIPS': 'UK', 'ISO': 'GB'},
 {'cname': 'United States', 'FIPS': 'US', 'ISO': 'US'},
 {'cname': 'United States Minor Outlying Islands', 'FIPS': nan, 'ISO': 'UM'}]
test_eq(cc.like('Russia'),[{'cname': 'Russian Federation', 'FIPS': 'RS', 'ISO': 'RU'}])

test_eq(cc.like('United',2),
        [{'cname': 'Tanzania, United Republic of', 'FIPS': 'TZ', 'ISO': 'TZ'},
         {'cname': 'United Arab Emirates', 'FIPS': 'AE', 'ISO': 'AE'}])

test_eq(cc.like('Non-existing'),[])

CountryCodes.iso[source]

CountryCodes.iso(cname:str)

Returns iso code of cname.

test_eq(cc.iso('Russia'), 'RU')

CountryCodes.fips[source]

CountryCodes.fips(cname:str)

Returns fips code of cname.

Note that two forms of calls are possible:

test_eq(cc.fips('Russia'), 'RS')
test_eq(cc('Russia'), 'RS')