1=========
2pycountry
3=========
4
5pycountry provides the ISO databases for the standards:
6
7639-3
8 Languages
9
103166
11 Countries
12
133166-3
14 Deleted countries
15
163166-2
17 Subdivisions of countries
18
194217
20 Currencies
21
2215924
23 Scripts
24
25The package includes a copy from Debian's `pkg-isocodes` and makes the data
26accessible through a Python API.
27
28Translation files for the various strings are included as well.
29
30Data update policy
31==================
32
33No changes to the data will be accepted into pycountry. This is a pure wrapper
34around the ISO standard using the `pkg-isocodes` database from Debian *as is*.
35If you need changes to the politicial situation in the world, please talk to
36the ISO or Debian people, not me.
37
38Donations / Monetary Support
39============================
40
41This is a small project that I maintain in my personal time. I am not
42interested in personal financial gain. However, if you would like to support
43the project then I would love if you would donate to `Feminist Frequency
44<https://feministfrequency.com/donate/>`_ instead. Also, let the world know you
45did so, so that others can follow your path.
46
47Contributions
48=============
49
50The code lives in a `bitbucket Mercurial repository
51<https://bitbucket.org/flyingcircus/pycountry>`_, and issues must be reported in
52`project bugtracker
53<https://bitbucket.org/flyingcircus/pycountry/issues?status=new&status=open>`_.
54
55Countries (ISO 3166)
56====================
57
58Countries are accessible through a database object that is already configured
59upon import of pycountry and works as an iterable:
60
61 >>> import pycountry
62 >>> len(pycountry.countries)
63 249
64 >>> list(pycountry.countries)[0]
65 Country(alpha_2='AF', alpha_3='AFG', name='Afghanistan', numeric='004', official_name='Islamic Republic of Afghanistan')
66
67Specific countries can be looked up by their various codes and provide the
68information included in the standard as attributes:
69
70 >>> germany = pycountry.countries.get(alpha_2='DE')
71 >>> germany
72 Country(alpha_2='DE', alpha_3='DEU', name='Germany', numeric='276', official_name='Federal Republic of Germany')
73 >>> germany.alpha_2
74 'DE'
75 >>> germany.alpha_3
76 'DEU'
77 >>> germany.numeric
78 '276'
79 >>> germany.name
80 'Germany'
81 >>> germany.official_name
82 'Federal Republic of Germany'
83
84The `historic_countries` database contains former countries that have been
85removed from the standard and are now included in ISO 3166-3, excluding
86existing ones:
87
88 >>> ussr = pycountry.historic_countries.get(alpha_3='SUN')
89 >>> ussr
90 Country(alpha_3='SUN', alpha_4='SUHH', withdrawal_date='1992-08-30', name='USSR, Union of Soviet Socialist Republics', numeric='810')
91 >>> ussr.alpha_4
92 'SUHH'
93 >>> ussr.alpha_3
94 'SUN'
95 >>> ussr.name
96 'USSR, Union of Soviet Socialist Republics'
97 >>> ussr.withdrawal_date
98 '1992-08-30'
99
100
101Country subdivisions (ISO 3166-2)
102=================================
103
104The country subdivisions are a little more complex than the countries itself
105because they provide a nested and typed structure.
106
107All subdivisons can be accessed directly:
108
109 >>> len(pycountry.subdivisions)
110 4847
111 >>> list(pycountry.subdivisions)[0]
112 Subdivision(code='AD-07', country_code='AD', name='Andorra la Vella', parent_code=None, type='Parish')
113
114Subdivisions can be accessed using their unique code and provide at least
115their code, name and type:
116
117 >>> de_st = pycountry.subdivisions.get(code='DE-ST')
118 >>> de_st.code
119 'DE-ST'
120 >>> de_st.name
121 'Sachsen-Anhalt'
122 >>> de_st.type
123 'State'
124 >>> de_st.country
125 Country(alpha_2='DE', alpha_3='DEU', name='Germany', numeric='276', official_name='Federal Republic of Germany')
126
127Some subdivisions specify another subdivision as a parent:
128
129 >>> al_br = pycountry.subdivisions.get(code='AL-BU')
130 >>> al_br.code
131 'AL-BU'
132 >>> al_br.name
133 'Bulqiz\xeb'
134 >>> al_br.type
135 'District'
136 >>> al_br.parent_code
137 'AL-09'
138 >>> al_br.parent
139 Subdivision(code='AL-09', country_code='AL', name='Dib\xebr', parent_code=None, type='County')
140 >>> al_br.parent.name
141 'Dib\xebr'
142
143The divisions of a single country can be queried using the country_code index:
144
145 >>> len(pycountry.subdivisions.get(country_code='DE'))
146 16
147
148 >>> len(pycountry.subdivisions.get(country_code='US'))
149 57
150
151
152Scripts (ISO 15924)
153===================
154
155Scripts are available from a database similar to the countries:
156
157 >>> len(pycountry.scripts)
158 169
159 >>> list(pycountry.scripts)[0]
160 Script(alpha_4='Afak', name='Afaka', numeric='439')
161
162 >>> latin = pycountry.scripts.get(name='Latin')
163 >>> latin
164 Script(alpha_4='Latn', name='Latin', numeric='215')
165 >>> latin.alpha4
166 'Latn'
167 >>> latin.name
168 'Latin'
169 >>> latin.numeric
170 '215'
171
172
173Currencies (ISO 4217)
174=====================
175
176The currencies database is, again, similar to the ones before:
177
178 >>> len(pycountry.currencies)
179 182
180 >>> list(pycountry.currencies)[0]
181 Currency(alpha_3='AED', name='UAE Dirham', numeric='784')
182 >>> argentine_peso = pycountry.currencies.get(alpha_3='ARS')
183 >>> argentine_peso
184 Currency(alpha_3='ARS', name='Argentine Peso', numeric='032')
185 >>> argentine_peso.alpha_3
186 'ARS'
187 >>> argentine_peso.name
188 'Argentine Peso'
189 >>> argentine_peso.numeric
190 '032'
191
192
193Languages (ISO 639-3)
194=====================
195
196The languages database is similar too:
197
198 >>> len(pycountry.languages)
199 7874
200 >>> list(pycountry.languages)[0]
201 Language(alpha_3='aaa', name='Ghotuo', scope='I', type='L')
202
203 >>> aragonese = pycountry.languages.get(alpha_2='an')
204 >>> aragonese.alpha_2
205 'an'
206 >>> aragonese.alpha_3
207 'arg'
208 >>> aragonese.name
209 'Aragonese'
210
211 >>> bengali = pycountry.languages.get(alpha_2='bn')
212 >>> bengali.name
213 'Bengali'
214 >>> bengali.common_name
215 'Bangla'
216
217Locales
218=======
219
220Locales are available in the `pycountry.LOCALES_DIR` subdirectory of this
221package. The translation domains are called `isoXXX` according to the standard
222they provide translations for. The directory is structured in a way compatible
223to Python's gettext module.
224
225Here is an example translating language names:
226
227 >>> import gettext
228 >>> german = gettext.translation('iso3166', pycountry.LOCALES_DIR,
229 ... languages=['de'])
230 >>> german.install()
231 >>> _('Germany')
232 'Deutschland'
233
234Lookups
235=======
236
237For each database (countries, languages, scripts, etc.), you can also look up
238entities case insensitively without knowing which key the value may match. For
239example:
240
241 >>> pycountry.countries.lookup('de')
242 <pycountry.db.Country object at 0x...>
243
244The search ends with the first match, which is returned.
245