Merge 2d2ec82 into ea609f5

README.rst

@@ -1,14 +1,19 @@
 |Build_Status| |Coverage_Status|
 
 The HDX Python Country Library provides country mappings including ISO 2 and ISO 3
-letter codes (ISO 3166) and regions using live official data from the `UNStats M49`_
-website and `World Bank`_ api with fallbacks to internal static files if there is any
-problem with retrieving data from the urls and also for a few special case locations.
-(Also it is possible to force the use of the internal static files.)
+letter codes (ISO 3166) and regions using live official data from the `UN OCHA`_
+feed with fallbacks to an internal static file if there is any problem with retrieving
+data from the url. (Also it is possible to force the use of the internal static files.)
 
 There is a fuzzy matching look up that can handle abbreviations in country names like
 Dem. for Democratic and Rep. for Republic.
 
+Version 2.x.x of the library is a significant change from version 1.x.x which
+sourced its data from different feeds (UN Stats and the World Bank). Consequently,
+although most of the api calls work the same way in 2.x.x, the ones that return
+full country information do so in a different format to 1.x.x. The format they use is
+a dictionary using `Humanitarian Exchange Language`_ (HXL) hashtags as keys.
+
 This library is part of the `Humanitarian Data Exchange`_ (HDX) project. If you have
 humanitarian related data, please upload your datasets to HDX.
 
@@ -37,7 +42,6 @@ The usage of the country mappings functionality is best illustrated by some exam
     # in internal dictionaries for future use.
     Country.get_country_name_from_iso2('Pl')  # returns 'Poland'
     Country.get_iso3_country_code('UZBEKISTAN')  # returns 'UZB'
-    Country.get_country_name_from_ison(4)  # returns 'Afghanistan'
     Country.get_country_name_from_m49(4)  # returns 'Afghanistan'
 
     Country.get_iso3_country_code_fuzzy('Sierra')
@@ -46,12 +50,21 @@ The usage of the country mappings functionality is best illustrated by some exam
     # returns ('CZE', False)
 
     Country.get_country_info_from_iso2('jp')
-    # {'ISO-alpha2 Code': 'JP', 'ISO-numeric Code': '392', 'Sub-region Name': 'Eastern Asia',
-    # 'M49 Code': '392', 'ISO-alpha3 Code': 'JPN', 'Developed / Developing Countries': 'Developed',
-    # 'Land Locked Developing Countries (LLDC)': '', 'Global Name': 'World', 'Region Name': 'Asia',
-    # 'Least Developed Countries (LDC)': '', 'Intermediate Region Code': '', 'Region Code': '142',
-    # 'Country or Area': 'Japan', 'Sub-region Code': '030', 'Intermediate Region Name': '',
-    # 'Small Island Developing States (SIDS)': '', 'Global Code': '001', 'Capital City': 'Tokyo'}
+    # Returns dictionary with HXL hashtags as keys. For more on HXL, see http://hxlstandard.org/
+    # {'#country+alt+i_ar+name+v_unterm': 'اليابان', '#country+alt+i_en+name+v_unterm': 'Japan',
+    # '#country+alt+i_es+name+v_unterm': 'Japón (el)', '#country+alt+i_fr+name+v_unterm': 'Japon (le)',
+    # '#country+alt+i_ru+name+v_unterm': 'Япония', '#country+alt+i_zh+name+v_unterm': '日本',
+    # '#country+alt+name+v_fts': '', '#country+alt+name+v_hrinfo_country': '',
+    # '#country+alt+name+v_iso': '', '#country+alt+name+v_m49': '',
+    # '#country+alt+name+v_reliefweb': '', '#country+alt+name+v_unterm': '',
+    # '#country+code+num+v_m49': '392', '#country+code+v_fts': '112',
+    # '#country+code+v_hrinfo_country': '292', '#country+code+v_iso2': 'JP',
+    # '#country+code+v_iso3': 'JPN', '#country+code+v_reliefweb': '128',
+    # '#country+name+preferred': 'Japan', '#country+name+short+v_reliefweb': '',
+    # '#country+regex': 'japan', '#geo+admin_level': '0', '#geo+lat': '37.63209801',
+    # '#geo+lon': '138.0812256', '#meta+id': '112', '#region+code+intermediate': '',
+    # '#region+code+main': '142', '#region+code+sub': '30', '#region+intermediate+name+preferred': '',
+    # '#region+main+name+preferred': 'Asia', '#region+name+preferred+sub': 'Eastern Asia'}
 
     Country.get_countries_in_region('Channel Islands')
     # ['GGY', 'JEY']
@@ -74,5 +87,6 @@ subregions as specified on the `UNStats M49`_ website.
     :target: https://coveralls.io/github/OCHA-DAP/hdx-python-country?branch=master
 
 .. _Humanitarian Data Exchange: https://data.humdata.org/
+.. _Humanitarian Exchange Language: http://hxlstandard.org/
+.. _UN OCHA: https://vocabulary.unocha.org/
 .. _UNStats M49: https://unstats.un.org/unsd/methodology/m49/overview/
-.. _World Bank: http://api.worldbank.org/countries?format=json&per_page=10000

requirements.txt

@@ -1 +1,3 @@
-hdx-python-utilities==1.6.8
+hdx-python-utilities==1.6.8
+libhxl==4.5.1;python_version<'3'
+libhxl==4.13.2;python_version>='3'

setup.py

@@ -52,7 +52,9 @@ def get_readme():
     return readme_file.read()
 
 
-requirements = ['hdx-python-utilities>=1.6.8']
+requirements = ['hdx-python-utilities>=1.6.8',
+                'libhxl==4.5.1;python_version<"3"',
+                'libhxl>=4.13.2:python_version>="3"']
 
 classifiers = [
     "Development Status :: 5 - Production/Stable",