Commits

Christian Theune committed 5dd4341

0.11 - support for country subdivisions (ISO 3166-2)

Comments (0)

Files changed (78)

+Changes
+=======
+
+
+0.10 (unreleased)
+----------------
+
+- Added support for country subdivisions (ISO 3166-2). 
+
+
+0.9
+---
+
+- Initial release
 Metadata-Version: 1.0
 Name: pycountry
-Version: 0.9
+Version: 0.10
 Summary: ISO country, subdivision, language, currency and script definitions and their translations
 Home-page: UNKNOWN
 Author: Christian Theune
         15924
         Scripts
         
-        The databases are imported from Debian's `pkg-isocodes` and made accessible
-        through a Python API.
+        The databases are imported from Debian's `pkg-isocodes`, packaged into
+        pycountry and made accessible through a Python API.
         
         Translation files for the various strings are included as well.
         
         Note that historic countries, defined by the ISO 3166-3 sub-standard are not
         included in this list.
         
+        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 subdivions can be accessed directly:
+        
+        >>> len(pycountry.subdivisions)
+        4548
+        >>> 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
+        'DE-ST'
+        >>> de_st.name
+        'Sachsen-Anhalt'
+        >>> de_st.type
+        '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
+        'AL-BU'
+        >>> al_br.name
+        u'Bulqiz\xeb'
+        >>> al_br.type
+        'District'
+        >>> al_br.parent_code
+        'AL 9'
+        >>> 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)
         ===================
         >>> aragonese.name
         'Aragonese'
         
-        
         Locales
         =======
         
-- Check unicode compatibility
-
-- Add support for country subdivisions.
+- Watch usability of ISO 3166-2 integration.
 
 setup(
     name='pycountry',
-    version='0.9',
+    version='0.10',
     author='Christian Theune',
     author_email='ct@gocept.com',
     description='ISO country, subdivision, language, currency and script '

src/pycountry.egg-info/PKG-INFO

 Metadata-Version: 1.0
 Name: pycountry
-Version: 0.9
+Version: 0.10
 Summary: ISO country, subdivision, language, currency and script definitions and their translations
 Home-page: UNKNOWN
 Author: Christian Theune
         15924
         Scripts
         
-        The databases are imported from Debian's `pkg-isocodes` and made accessible
-        through a Python API.
+        The databases are imported from Debian's `pkg-isocodes`, packaged into
+        pycountry and made accessible through a Python API.
         
         Translation files for the various strings are included as well.
         
         Note that historic countries, defined by the ISO 3166-3 sub-standard are not
         included in this list.
         
+        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 subdivions can be accessed directly:
+        
+        >>> len(pycountry.subdivisions)
+        4548
+        >>> 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
+        'DE-ST'
+        >>> de_st.name
+        'Sachsen-Anhalt'
+        >>> de_st.type
+        '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
+        'AL-BU'
+        >>> al_br.name
+        u'Bulqiz\xeb'
+        >>> al_br.type
+        'District'
+        >>> al_br.parent_code
+        'AL 9'
+        >>> 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)
         ===================
         >>> aragonese.name
         'Aragonese'
         
-        
         Locales
         =======
         

src/pycountry.egg-info/SOURCES.txt

+CHANGES.txt
 LICENSE.txt
 MANIFEST.in
 Makefile
 src/pycountry.egg-info/top_level.txt
 src/pycountry/databases/iso15924.xml
 src/pycountry/databases/iso3166.xml
+src/pycountry/databases/iso3166_2.xml
 src/pycountry/databases/iso4217.xml
 src/pycountry/databases/iso639.xml
 src/pycountry/locales/af/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/ar/LC_MESSAGES/iso639.po
 src/pycountry/locales/az/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/az/LC_MESSAGES/iso3166.po
+src/pycountry/locales/az/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/az/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/az/LC_MESSAGES/iso639.mo
 src/pycountry/locales/az/LC_MESSAGES/iso639.po
 src/pycountry/locales/be/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/bg/LC_MESSAGES/iso15924.po
 src/pycountry/locales/bg/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/bg/LC_MESSAGES/iso3166.po
+src/pycountry/locales/bg/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/bg/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/bg/LC_MESSAGES/iso639.mo
 src/pycountry/locales/bg/LC_MESSAGES/iso639.po
 src/pycountry/locales/bn/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/br/LC_MESSAGES/iso639.po
 src/pycountry/locales/bs/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/bs/LC_MESSAGES/iso3166.po
+src/pycountry/locales/bs/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/bs/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/bs/LC_MESSAGES/iso639.mo
 src/pycountry/locales/bs/LC_MESSAGES/iso639.po
 src/pycountry/locales/byn/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/byn/LC_MESSAGES/iso639.po
 src/pycountry/locales/ca/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/ca/LC_MESSAGES/iso3166.po
+src/pycountry/locales/ca/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/ca/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/ca/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/ca/LC_MESSAGES/iso4217.po
 src/pycountry/locales/ca/LC_MESSAGES/iso639.mo
 src/pycountry/locales/ca/LC_MESSAGES/iso639.po
 src/pycountry/locales/cs/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/cs/LC_MESSAGES/iso3166.po
+src/pycountry/locales/cs/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/cs/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/cs/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/cs/LC_MESSAGES/iso4217.po
 src/pycountry/locales/cs/LC_MESSAGES/iso639.mo
 src/pycountry/locales/da/LC_MESSAGES/iso15924.po
 src/pycountry/locales/da/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/da/LC_MESSAGES/iso3166.po
+src/pycountry/locales/da/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/da/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/da/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/da/LC_MESSAGES/iso4217.po
 src/pycountry/locales/da/LC_MESSAGES/iso639.mo
 src/pycountry/locales/el/LC_MESSAGES/iso15924.po
 src/pycountry/locales/el/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/el/LC_MESSAGES/iso3166.po
+src/pycountry/locales/el/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/el/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/el/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/el/LC_MESSAGES/iso4217.po
 src/pycountry/locales/el/LC_MESSAGES/iso639.mo
 src/pycountry/locales/el/LC_MESSAGES/iso639.po
+src/pycountry/locales/en/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/en/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/eo/LC_MESSAGES/iso15924.mo
 src/pycountry/locales/eo/LC_MESSAGES/iso15924.po
 src/pycountry/locales/eo/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/eo/LC_MESSAGES/iso3166.po
+src/pycountry/locales/eo/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/eo/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/eo/LC_MESSAGES/iso639.mo
 src/pycountry/locales/eo/LC_MESSAGES/iso639.po
 src/pycountry/locales/es/LC_MESSAGES/iso15924.mo
 src/pycountry/locales/es/LC_MESSAGES/iso15924.po
 src/pycountry/locales/es/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/es/LC_MESSAGES/iso3166.po
+src/pycountry/locales/es/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/es/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/es/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/es/LC_MESSAGES/iso4217.po
 src/pycountry/locales/es/LC_MESSAGES/iso639.mo
 src/pycountry/locales/et/LC_MESSAGES/iso639.po
 src/pycountry/locales/eu/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/eu/LC_MESSAGES/iso3166.po
+src/pycountry/locales/eu/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/eu/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/eu/LC_MESSAGES/iso639.mo
 src/pycountry/locales/eu/LC_MESSAGES/iso639.po
 src/pycountry/locales/fa/LC_MESSAGES/iso15924.mo
 src/pycountry/locales/fr/LC_MESSAGES/iso15924.po
 src/pycountry/locales/fr/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/fr/LC_MESSAGES/iso3166.po
+src/pycountry/locales/fr/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/fr/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/fr/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/fr/LC_MESSAGES/iso4217.po
 src/pycountry/locales/fr/LC_MESSAGES/iso639.mo
 src/pycountry/locales/fr/LC_MESSAGES/iso639.po
 src/pycountry/locales/ga/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/ga/LC_MESSAGES/iso3166.po
+src/pycountry/locales/ga/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/ga/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/ga/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/ga/LC_MESSAGES/iso4217.po
 src/pycountry/locales/ga/LC_MESSAGES/iso639.mo
 src/pycountry/locales/hu/LC_MESSAGES/iso15924.po
 src/pycountry/locales/hu/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/hu/LC_MESSAGES/iso3166.po
+src/pycountry/locales/hu/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/hu/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/hu/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/hu/LC_MESSAGES/iso4217.po
 src/pycountry/locales/hu/LC_MESSAGES/iso639.mo
 src/pycountry/locales/hy/LC_MESSAGES/iso3166.po
 src/pycountry/locales/id/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/id/LC_MESSAGES/iso3166.po
+src/pycountry/locales/id/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/id/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/id/LC_MESSAGES/iso639.mo
 src/pycountry/locales/id/LC_MESSAGES/iso639.po
 src/pycountry/locales/is/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/it/LC_MESSAGES/iso15924.po
 src/pycountry/locales/it/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/it/LC_MESSAGES/iso3166.po
+src/pycountry/locales/it/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/it/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/it/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/it/LC_MESSAGES/iso4217.po
 src/pycountry/locales/it/LC_MESSAGES/iso639.mo
 src/pycountry/locales/ja/LC_MESSAGES/iso15924.po
 src/pycountry/locales/ja/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/ja/LC_MESSAGES/iso3166.po
+src/pycountry/locales/ja/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/ja/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/ja/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/ja/LC_MESSAGES/iso4217.po
 src/pycountry/locales/ja/LC_MESSAGES/iso639.mo
 src/pycountry/locales/ko/LC_MESSAGES/iso15924.po
 src/pycountry/locales/ko/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/ko/LC_MESSAGES/iso3166.po
+src/pycountry/locales/ko/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/ko/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/ko/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/ko/LC_MESSAGES/iso4217.po
 src/pycountry/locales/ko/LC_MESSAGES/iso639.mo
 src/pycountry/locales/lt/LC_MESSAGES/iso15924.po
 src/pycountry/locales/lt/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/lt/LC_MESSAGES/iso3166.po
+src/pycountry/locales/lt/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/lt/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/lt/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/lt/LC_MESSAGES/iso4217.po
 src/pycountry/locales/lt/LC_MESSAGES/iso639.mo
 src/pycountry/locales/lt/LC_MESSAGES/iso639.po
 src/pycountry/locales/lv/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/lv/LC_MESSAGES/iso3166.po
+src/pycountry/locales/lv/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/lv/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/lv/LC_MESSAGES/iso639.mo
 src/pycountry/locales/lv/LC_MESSAGES/iso639.po
 src/pycountry/locales/mi/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/nl/LC_MESSAGES/iso15924.po
 src/pycountry/locales/nl/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/nl/LC_MESSAGES/iso3166.po
+src/pycountry/locales/nl/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/nl/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/nl/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/nl/LC_MESSAGES/iso4217.po
 src/pycountry/locales/nl/LC_MESSAGES/iso639.mo
 src/pycountry/locales/nn/LC_MESSAGES/iso639.po
 src/pycountry/locales/nso/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/nso/LC_MESSAGES/iso3166.po
+src/pycountry/locales/nso/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/nso/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/nso/LC_MESSAGES/iso639.mo
 src/pycountry/locales/nso/LC_MESSAGES/iso639.po
 src/pycountry/locales/oc/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/pl/LC_MESSAGES/iso15924.po
 src/pycountry/locales/pl/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/pl/LC_MESSAGES/iso3166.po
+src/pycountry/locales/pl/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/pl/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/pl/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/pl/LC_MESSAGES/iso4217.po
 src/pycountry/locales/pl/LC_MESSAGES/iso639.mo
 src/pycountry/locales/sk/LC_MESSAGES/iso15924.po
 src/pycountry/locales/sk/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/sk/LC_MESSAGES/iso3166.po
+src/pycountry/locales/sk/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/sk/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/sk/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/sk/LC_MESSAGES/iso4217.po
 src/pycountry/locales/sk/LC_MESSAGES/iso639.mo
 src/pycountry/locales/sl/LC_MESSAGES/iso15924.po
 src/pycountry/locales/sl/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/sl/LC_MESSAGES/iso3166.po
+src/pycountry/locales/sl/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/sl/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/sl/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/sl/LC_MESSAGES/iso4217.po
 src/pycountry/locales/sl/LC_MESSAGES/iso639.mo
 src/pycountry/locales/sr/LC_MESSAGES/iso15924.po
 src/pycountry/locales/sr/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/sr/LC_MESSAGES/iso3166.po
+src/pycountry/locales/sr/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/sr/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/sr/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/sr/LC_MESSAGES/iso4217.po
 src/pycountry/locales/sr/LC_MESSAGES/iso639.mo
 src/pycountry/locales/sv/LC_MESSAGES/iso15924.po
 src/pycountry/locales/sv/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/sv/LC_MESSAGES/iso3166.po
+src/pycountry/locales/sv/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/sv/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/sv/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/sv/LC_MESSAGES/iso4217.po
 src/pycountry/locales/sv/LC_MESSAGES/iso639.mo
 src/pycountry/locales/th/LC_MESSAGES/iso15924.po
 src/pycountry/locales/th/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/th/LC_MESSAGES/iso3166.po
+src/pycountry/locales/th/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/th/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/th/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/th/LC_MESSAGES/iso4217.po
 src/pycountry/locales/th/LC_MESSAGES/iso639.mo
 src/pycountry/locales/tr/LC_MESSAGES/iso15924.po
 src/pycountry/locales/tr/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/tr/LC_MESSAGES/iso3166.po
+src/pycountry/locales/tr/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/tr/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/tr/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/tr/LC_MESSAGES/iso4217.po
 src/pycountry/locales/tr/LC_MESSAGES/iso639.mo
 src/pycountry/locales/uk/LC_MESSAGES/iso15924.po
 src/pycountry/locales/uk/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/uk/LC_MESSAGES/iso3166.po
+src/pycountry/locales/uk/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/uk/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/uk/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/uk/LC_MESSAGES/iso4217.po
 src/pycountry/locales/uk/LC_MESSAGES/iso639.mo
 src/pycountry/locales/uk/LC_MESSAGES/iso639.po
 src/pycountry/locales/ve/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/ve/LC_MESSAGES/iso3166.po
+src/pycountry/locales/ve/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/ve/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/ve/LC_MESSAGES/iso639.mo
 src/pycountry/locales/ve/LC_MESSAGES/iso639.po
 src/pycountry/locales/vi/LC_MESSAGES/iso15924.mo
 src/pycountry/locales/vi/LC_MESSAGES/iso15924.po
 src/pycountry/locales/vi/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/vi/LC_MESSAGES/iso3166.po
+src/pycountry/locales/vi/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/vi/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/vi/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/vi/LC_MESSAGES/iso4217.po
 src/pycountry/locales/vi/LC_MESSAGES/iso639.mo
 src/pycountry/locales/vi/LC_MESSAGES/iso639.po
 src/pycountry/locales/wa/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/wa/LC_MESSAGES/iso3166.po
+src/pycountry/locales/wa/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/wa/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/wa/LC_MESSAGES/iso639.mo
 src/pycountry/locales/wa/LC_MESSAGES/iso639.po
 src/pycountry/locales/wal/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/zh_CN/LC_MESSAGES/iso15924.po
 src/pycountry/locales/zh_CN/LC_MESSAGES/iso3166.mo
 src/pycountry/locales/zh_CN/LC_MESSAGES/iso3166.po
+src/pycountry/locales/zh_CN/LC_MESSAGES/iso3166_2.mo
+src/pycountry/locales/zh_CN/LC_MESSAGES/iso3166_2.po
 src/pycountry/locales/zh_CN/LC_MESSAGES/iso4217.mo
 src/pycountry/locales/zh_CN/LC_MESSAGES/iso4217.po
 src/pycountry/locales/zh_CN/LC_MESSAGES/iso639.mo

src/pycountry/README.txt

 15924
   Scripts
 
-The databases are imported from Debian's `pkg-isocodes` and made accessible
-through a Python API.
+The databases are imported from Debian's `pkg-isocodes`, packaged into
+pycountry and made accessible through a Python API.
 
 Translation files for the various strings are included as well.
 
 Note that historic countries, defined by the ISO 3166-3 sub-standard are not
 included in this list.
 
+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 subdivions can be accessed directly:
+
+  >>> len(pycountry.subdivisions)
+  4548
+  >>> 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
+  'DE-ST'
+  >>> de_st.name
+  'Sachsen-Anhalt'
+  >>> de_st.type
+  '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
+  'AL-BU'
+  >>> al_br.name
+  u'Bulqiz\xeb'
+  >>> al_br.type
+  'District'
+  >>> al_br.parent_code
+  'AL 9'
+  >>> 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)
 ===================
   >>> aragonese.name
   'Aragonese'
 
-
 Locales
 =======
 

src/pycountry/__init__.py

     xml_tag = 'iso_639_entry'
 
 
+class Subdivision(pycountry.db.Data):
+
+    parent_code = None
+
+    def __init__(self, element, **kw):
+        super(Subdivision, self).__init__(element, **kw)
+        self.type = element.getparent().get('type')
+        self.country_code = self.code.split('-')[0]
+        if self.parent_code is not None:
+            self.parent_code = '%s %s' % (self.country_code, self.parent_code)
+
+    @property
+    def country(self):
+        return countries.get(alpha2=self.country_code)
+
+    @property
+    def parent(self):
+        return subdivisions.get(code=self.parent_code)
+
+
+class Subdivisions(pycountry.db.Database):
+
+    xml_tag = 'iso_3166_2_entry'
+    data_class_base = Subdivision
+    data_class_name = 'Subdivision'
+    field_map = dict(code='code',
+                     name='name',
+                     parent='parent_code')
+
+    def __init__(self, *args, **kw):
+        super(Subdivisions, self).__init__(*args, **kw)
+
+        self.indices['country_code'] = {}
+        # Add the country code to the index:
+        for subdivision in self:
+            divs = self.indices['country_code'].setdefault(
+                subdivision.country_code, set())
+            divs.add(subdivision)
+
+
 countries = Countries(os.path.join(DATABASE_DIR, 'iso3166.xml'))
 scripts = Scripts(os.path.join(DATABASE_DIR, 'iso15924.xml'))
 currencies  = Currencies(os.path.join(DATABASE_DIR, 'iso4217.xml'))
 languages = Languages(os.path.join(DATABASE_DIR, 'iso639.xml'))
+subdivisions = Subdivisions(os.path.join(DATABASE_DIR, 'iso3166_2.xml'))