Debian Codegraph @

django_countries.egg-info/PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: django-countries
3 Version: 7.6.1
4 Summary: Provides a country field for Django models.
5 Home-page: https://github.com/SmileyChris/django-countries/
6 Author: Chris Beaven
7 Author-email: [email protected]
8 License: MIT
9 Project-URL: Change Log, https://github.com/SmileyChris/django-countries/blob/main/CHANGES.rst
10 Project-URL: Source Code, https://github.com/SmileyChris/django-countries
11 Keywords: django,countries,flags
12 Classifier: Development Status :: 5 - Production/Stable
13 Classifier: Environment :: Web Environment
14 Classifier: Intended Audience :: Developers
15 Classifier: License :: OSI Approved :: MIT License
16 Classifier: Operating System :: OS Independent
17 Classifier: Programming Language :: Python
18 Classifier: Programming Language :: Python :: 3 :: Only
19 Classifier: Programming Language :: Python :: 3.7
20 Classifier: Programming Language :: Python :: 3.8
21 Classifier: Programming Language :: Python :: 3.9
22 Classifier: Programming Language :: Python :: 3.10
23 Classifier: Programming Language :: Python :: 3.11
24 Classifier: Framework :: Django
25 Classifier: Framework :: Django :: 3.2
26 Classifier: Framework :: Django :: 4.0
27 Classifier: Framework :: Django :: 4.1
28 Classifier: Framework :: Django :: 4.2
29 Classifier: Framework :: Django :: 5.0
30 Provides-Extra: maintainer
31 Provides-Extra: dev
32 Provides-Extra: test
33 Provides-Extra: pyuca
34 License-File: LICENSE
35
36 ================
37 Django Countries
38 ================
39
40 .. image:: https://badge.fury.io/py/django-countries.svg
41 :alt: PyPI version
42 :target: https://badge.fury.io/py/django-countries
43
44 .. image:: https://github.com/SmileyChris/django-countries/actions/workflows/tests.yml/badge.svg
45 :alt: Build status
46 :target: https://github.com/SmileyChris/django-countries/actions/workflows/tests.yml
47
48 A Django application that provides country choices for use with forms, flag
49 icons static files, and a country field for models.
50
51 Country names are translated using Django's standard ``gettext``. If you would
52 like to help by adding a translation, please visit
53 https://www.transifex.com/smileychris/django-countries/
54
55
56 .. contents::
57 :local:
58 :backlinks: none
59
60
61 Installation
62 ============
63
64 1. ``pip install django-countries``
65
66 For more accurate sorting of translated country names, install it with the
67 optional pyuca_ package:
68
69 ``pip install django-countries[pyuca]``
70
71 2. Add ``django_countries`` to ``INSTALLED_APPS``
72
73 .. _pyuca: https://pypi.python.org/pypi/pyuca/
74
75
76 CountryField
77 ============
78
79 A country field for Django models that provides all ISO 3166-1 countries as
80 choices.
81
82 ``CountryField`` is based on Django's ``CharField``, providing choices
83 corresponding to the official ISO 3166-1 list of countries (with a default
84 ``max_length`` of 2).
85
86 Consider the following model using a ``CountryField``:
87
88 .. code:: python
89
90 from django.db import models
91 from django_countries.fields import CountryField
92
93 class Person(models.Model):
94 name = models.CharField(max_length=100)
95 country = CountryField()
96
97 Any ``Person`` instance will have a ``country`` attribute that you can use to
98 get details of the person's country:
99
100 .. code:: python
101
102 >>> person = Person(name="Chris", country="NZ")
103 >>> person.country
104 Country(code='NZ')
105 >>> person.country.name
106 'New Zealand'
107 >>> person.country.flag
108 '/static/flags/nz.gif'
109
110 This object (``person.country`` in the example) is a ``Country`` instance,
111 which is described below.
112
113 Use ``blank_label`` to set the label for the initial blank choice shown in
114 forms:
115
116 .. code:: python
117
118 country = CountryField(blank_label="(select country)")
119
120 You can filter using the full English country names in addition to country
121 codes, even though only the country codes are stored in the database by using
122 the queryset lookups ``contains``, ``startswith``, ``endswith``, ``regex``, or
123 their case insensitive versions. Use ``__name`` or ``__iname`` for the
124 ``exact``/``iexact`` equivalent:
125
126 .. code:: python
127
128 >>> Person.objects.filter(country__name="New Zealand").count()
129 1
130 >>> Person.objects.filter(country__icontains="zealand").count()
131 1
132
133
134 Multi-choice
135 ------------
136
137 This field can also allow multiple selections of countries (saved as a comma
138 separated string). The field will always output a list of countries in this
139 mode. For example:
140
141 .. code:: python
142
143 class Incident(models.Model):
144 title = models.CharField(max_length=100)
145 countries = CountryField(multiple=True)
146
147 >>> for country in Incident.objects.get(title="Pavlova dispute").countries:
148 ... print(country.name)
149 Australia
150 New Zealand
151
152 By default, countries are stored sorted for data consistency, and any
153 duplicates are removed. These behaviours can be overridden by using the field
154 arguments ``multiple_sort=False`` and ``multiple_unique=False`` respectively.
155
156
157 The ``Country`` object
158 ----------------------
159
160 An object used to represent a country, instantiated with a two character
161 country code, three character code, or numeric code.
162
163 It can be compared to other objects as if it was a string containing the
164 country code and when evaluated as text, returns the country code.
165
166 name
167 Contains the full country name.
168
169 flag
170 Contains a URL to the flag. If you page could have lots of different flags
171 then consider using ``flag_css`` instead to avoid excessive HTTP requests.
172
173 flag_css
174 Output the css classes needed to display an HTML element as the correct flag
175 from within a single sprite image that contains all flags. For example:
176
177 .. code:: jinja
178
179 <link rel="stylesheet" href="{% static 'flags/sprite.css' %}">
180 <i class="{{ country.flag_css }}"></i>
181
182 For multiple flag resolutions, use ``sprite-hq.css`` instead and add the
183 ``flag2x``, ``flag3x``, or ``flag4x`` class. For example:
184
185 .. code:: jinja
186
187 <link rel="stylesheet" href="{% static 'flags/sprite-hq.css' %}">
188 Normal: <i class="{{ country.flag_css }}"></i>
189 Bigger: <i class="flag2x {{ country.flag_css }}"></i>
190
191 You might also want to consider using ``aria-label`` for better
192 accessibility:
193
194 .. code:: jinja
195
196 <i class="{{ country.flag_css }}"
197 aria-label="{% blocktrans with country_code=country.code %}
198 {{ country_code }} flag
199 {% endblocktrans %}"></i>
200
201 unicode_flag
202 A unicode glyph for the flag for this country. Currently well-supported in
203 iOS and OS X. See https://en.wikipedia.org/wiki/Regional_Indicator_Symbol
204 for details.
205
206 code
207 The two letter country code for this country.
208
209 alpha3
210 The three letter country code for this country.
211
212 numeric
213 The numeric country code for this country (as an integer).
214
215 numeric_padded
216 The numeric country code as a three character 0-padded string.
217
218 ioc_code
219 The three letter International Olympic Committee country code.
220
221
222 ``CountrySelectWidget``
223 -----------------------
224
225 A widget is included that can show the flag image after the select box
226 (updated with JavaScript when the selection changes).
227
228 When you create your form, you can use this custom widget like normal:
229
230 .. code:: python
231
232 from django_countries.widgets import CountrySelectWidget
233
234 class PersonForm(forms.ModelForm):
235 class Meta:
236 model = models.Person
237 fields = ("name", "country")
238 widgets = {"country": CountrySelectWidget()}
239
240 Pass a ``layout`` text argument to the widget to change the positioning of the
241 flag and widget. The default layout is:
242
243 .. code:: python
244
245 '{widget}<img class="country-select-flag" id="{flag_id}" style="margin: 6px 4px 0" src="{country.flag}">'
246
247
248 Custom forms
249 ============
250
251 If you want to use the countries in a custom form, use the model field's custom
252 form field to ensure the translatable strings for the country choices are left
253 lazy until the widget renders:
254
255 .. code:: python
256
257 from django_countries.fields import CountryField
258
259 class CustomForm(forms.Form):
260 country = CountryField().formfield()
261
262 Use ``CountryField(blank=True)`` for non-required form fields, and
263 ``CountryField(blank_label="(Select country)")`` to use a custom label for the
264 initial blank option.
265
266 You can also use the CountrySelectWidget_ as the widget for this field if you
267 want the flag image after the select box.
268
269
270 Get the countries from Python
271 =============================
272
273 Use the ``django_countries.countries`` object instance as an iterator of ISO
274 3166-1 country codes and names (sorted by name).
275
276 For example:
277
278 .. code:: python
279
280 >>> from django_countries import countries
281 >>> dict(countries)["NZ"]
282 'New Zealand'
283
284 >>> for code, name in list(countries)[:3]:
285 ... print(f"{name} ({code})")
286 ...
287 Afghanistan (AF)
288 Åland Islands (AX)
289 Albania (AL)
290
291
292 Template Tags
293 =============
294
295 If you have your country code stored in a different place than a
296 ``CountryField`` you can use the template tag to get a ``Country`` object and
297 have access to all of its properties:
298
299 .. code:: jinja
300
301 {% load countries %}
302 {% get_country 'BR' as country %}
303 {{ country.name }}
304
305 If you need a list of countries, there's also a simple tag for that:
306
307 .. code:: jinja
308
309 {% load countries %}
310 {% get_countries as countries %}
311 <select>
312 {% for country in countries %}
313 <option value="{{ country.code }}">{{ country.name }}</option>
314 {% endfor %}
315 </select>
316
317
318 Customization
319 =============
320
321 Customize the country list
322 --------------------------
323
324 Country names are taken from the official ISO 3166-1 list, with some country
325 names being replaced with their more common usage (such as "Bolivia" instead
326 of "Bolivia, Plurinational State of").
327
328 To retain the official ISO 3166-1 naming for all fields, set the
329 ``COUNTRIES_COMMON_NAMES`` setting to ``False``.
330
331 If your project requires the use of alternative names, the inclusion or
332 exclusion of specific countries then set the ``COUNTRIES_OVERRIDE`` setting to
333 a dictionary of names which override the defaults. The values can also use a
334 more `complex dictionary format`_.
335
336 Note that you will need to handle translation of customised country names.
337
338 Setting a country's name to ``None`` will exclude it from the country list.
339 For example:
340
341 .. code:: python
342
343 from django.utils.translation import gettext_lazy as _
344
345 COUNTRIES_OVERRIDE = {
346 "NZ": _("Middle Earth"),
347 "AU": None,
348 "US": {
349 "names": [
350 _("United States of America"),
351 _("America"),
352 ],
353 },
354 }
355
356 If you have a specific list of countries that should be used, use
357 ``COUNTRIES_ONLY``:
358
359 .. code:: python
360
361 COUNTRIES_ONLY = ["NZ", "AU"]
362
363 or to specify your own country names, use a dictionary or two-tuple list
364 (string items will use the standard country name):
365
366 .. code:: python
367
368 COUNTRIES_ONLY = [
369 "US",
370 "GB",
371 ("NZ", _("Middle Earth")),
372 ("AU", _("Desert")),
373 ]
374
375
376 Show certain countries first
377 ----------------------------
378
379 Provide a list of country codes as the ``COUNTRIES_FIRST`` setting and they
380 will be shown first in the countries list (in the order specified) before all
381 the alphanumerically sorted countries.
382
383 If you want to sort these initial countries too, set the
384 ``COUNTRIES_FIRST_SORT`` setting to ``True``.
385
386 By default, these initial countries are not repeated again in the
387 alphanumerically sorted list. If you would like them to be repeated, set the
388 ``COUNTRIES_FIRST_REPEAT`` setting to ``True``.
389
390 Finally, you can optionally separate these "first" countries with an empty
391 choice by providing the choice label as the ``COUNTRIES_FIRST_BREAK`` setting.
392
393
394 Customize the flag URL
395 ----------------------
396
397 The ``COUNTRIES_FLAG_URL`` setting can be used to set the url for the flag
398 image assets. It defaults to:
399
400 .. code:: python
401
402 COUNTRIES_FLAG_URL = "flags/{code}.gif"
403
404 The URL can be relative to the STATIC_URL setting, or an absolute URL.
405
406 The location is parsed using Python's string formatting and is passed the
407 following arguments:
408
409 * ``code``
410 * ``code_upper``
411
412 For example: ``COUNTRIES_FLAG_URL = "flags/16x10/{code_upper}.png"``
413
414 No checking is done to ensure that a static flag actually exists.
415
416 Alternatively, you can specify a different URL on a specific ``CountryField``:
417
418 .. code:: python
419
420 class Person(models.Model):
421 name = models.CharField(max_length=100)
422 country = CountryField(
423 countries_flag_url="//flags.example.com/{code}.png")
424
425
426 Single field customization
427 --------------------------
428
429 To customize an individual field, rather than rely on project level settings,
430 create a ``Countries`` subclass which overrides settings.
431
432 To override a setting, give the class an attribute matching the lowercased
433 setting without the ``COUNTRIES_`` prefix.
434
435 Then just reference this class in a field. For example, this ``CountryField``
436 uses a custom country list that only includes the G8 countries:
437
438 .. code:: python
439
440 from django_countries import Countries
441
442 class G8Countries(Countries):
443 only = [
444 "CA", "FR", "DE", "IT", "JP", "RU", "GB",
445 ("EU", _("European Union"))
446 ]
447
448 class Vote(models.Model):
449 country = CountryField(countries=G8Countries)
450 approve = models.BooleanField()
451
452
453 Complex dictionary format
454 -------------------------
455
456 For ``COUNTRIES_ONLY`` and ``COUNTRIES_OVERRIDE``, you can also provide a
457 dictionary rather than just a translatable string for the country name.
458
459 The options within the dictionary are:
460
461 ``name`` or ``names`` (required)
462 Either a single translatable name for this country or a list of multiple
463 translatable names. If using multiple names, the first name takes preference
464 when using ``COUNTRIES_FIRST`` or the ``Country.name``.
465
466 ``alpha3`` (optional)
467 An ISO 3166-1 three character code (or an empty string to nullify an existing
468 code for this country.
469
470 ``numeric`` (optional)
471 An ISO 3166-1 numeric country code (or ``None`` to nullify an existing code
472 for this country. The numeric codes 900 to 999 are left available by the
473 standard for user-assignment.
474
475 ``ioc_code`` (optional)
476 The country's International Olympic Committee code (or an empty string to
477 nullify an existing code).
478
479
480 ``Country`` object external plugins
481 -----------------------------------
482
483 Other Python packages can add attributes to the Country_ object by using entry
484 points in their setup script.
485
486 .. _Country: `The Country object`_
487
488 For example, you could create a ``django_countries_phone`` package which had a
489 with the following entry point in the ``setup.py`` file. The entry point name
490 (``phone``) will be the new attribute name on the Country object. The attribute
491 value will be the return value of the ``get_phone`` function (called with the
492 Country instance as the sole argument).
493
494 .. code:: python
495
496 setup(
497 ...
498 entry_points={
499 "django_countries.Country": "phone = django_countries_phone.get_phone"
500 },
501 ...
502 )
503
504
505
506 Django Rest Framework
507 =====================
508
509 Django Countries ships with a ``CountryFieldMixin`` to make the
510 `CountryField`_ model field compatible with DRF serializers. Use the following
511 mixin with your model serializer:
512
513 .. code:: python
514
515 from django_countries.serializers import CountryFieldMixin
516
517 class CountrySerializer(CountryFieldMixin, serializers.ModelSerializer):
518
519 class Meta:
520 model = models.Person
521 fields = ("name", "email", "country")
522
523 This mixin handles both standard and `multi-choice`_ country fields.
524
525
526 Django Rest Framework field
527 ---------------------------
528
529 For lower level use (or when not dealing with model fields), you can use the
530 included ``CountryField`` serializer field. For example:
531
532 .. code:: python
533
534 from django_countries.serializer_fields import CountryField
535
536 class CountrySerializer(serializers.Serializer):
537 country = CountryField()
538
539 You can optionally instantiate the field with the ``countries`` argument to
540 specify a custom Countries_ instance.
541
542 .. _Countries: `Single field customization`_
543
544 REST output format
545 ^^^^^^^^^^^^^^^^^^
546
547 By default, the field will output just the country code. To output the full
548 country name instead, instantiate the field with ``name_only=True``.
549
550 If you would rather have more verbose output, instantiate the field with
551 ``country_dict=True``, which will result in the field having the following
552 output structure:
553
554 .. code:: json
555
556 {"code": "NZ", "name": "New Zealand"}
557
558 Either the code or this dict output structure are acceptable as input
559 irregardless of the ``country_dict`` argument's value.
560
561
562 OPTIONS request
563 ---------------
564
565 When you request OPTIONS against a resource (using the DRF `metadata support`_)
566 the countries will be returned in the response as choices:
567
568 .. code:: text
569
570 OPTIONS /api/address/ HTTP/1.1
571
572 HTTP/1.1 200 OK
573 Content-Type: application/json
574 Allow: GET, POST, HEAD, OPTIONS
575
576 {
577 "actions": {
578 "POST": {
579 "country": {
580 "type": "choice",
581 "label": "Country",
582 "choices": [
583 {
584 "display_name": "Australia",
585 "value": "AU"
586 },
587 [...]
588 {
589 "display_name": "United Kingdom",
590 "value": "GB"
591 }
592 ]
593 }
594 }
595
596 .. _metadata support: http://www.django-rest-framework.org/api-guide/metadata/
597
598
599
600 GraphQL
601 =======
602
603 A ``Country`` graphene object type is included that can be used when generating
604 your schema.
605
606 .. code:: python
607
608 import graphene
609 from graphene_django.types import DjangoObjectType
610 from django_countries.graphql.types import Country
611
612 class Person(ObjectType):
613 country = graphene.Field(Country)
614
615 class Meta:
616 model = models.Person
617 fields = ["name", "country"]
618
619 The object type has the following fields available:
620
621 * ``name`` for the full country name
622 * ``code`` for the ISO 3166-1 two character country code
623 * ``alpha3`` for the ISO 3166-1 three character country code
624 * ``numeric`` for the ISO 3166-1 numeric country code
625 * ``iocCode`` for the International Olympic Committee country code
626
627 ==========
628 Change Log
629 ==========
630
631 This log shows interesting changes that happen for each version, latest
632 versions first. It can be assumed that translations have been updated each
633 release, and any new translations added.
634
635 7.6.1 (2 April 2024)
636 ====================
637
638 - Fix a TypeError when no country is selected, introduced in the Django 5 fix.
639
640
641 7.6 (27 March 2024)
642 ===================
643
644 - Replace deprecated ``pkg_resources.iter_entry_points`` with
645 ``importlib_metadata``.
646
647 - Support Django 5.0.
648
649 7.5.1 (1 February 2023)
650 =======================
651
652 - Make ``CountryField`` queryset filters also work with country codes in
653 addition to names.
654
655 - Switch to ``pyproject.toml`` rather than ``setup.py`` to fix installation
656 issues with pip 23.0+.
657
658
659 7.5 (12 December 2022)
660 ======================
661
662 - Rename Turkey to Türkiye.
663
664 - A change in v7.4 introduced multi-choice countries being stored sorted and
665 deduplicated. This remains the default behaviour going forwards, but these
666 can now be overridden via arguments on the ``CountryField``.
667
668 - Improve translation fallback handling, fixing a threading race condition that
669 could cause odd translation issues. Thanks to Jan Wróblewski and Antoine
670 Fontaine for their help in resolving this.
671 This also fixes translation issues with older Python 3.6/3.7 versions.
672
673 - Add Python 3.11, drop Python 3.6 and Django 2.2 support.
674
675
676 7.4.2 (10 October 2022)
677 =======================
678
679 - Fix error when using ``USE_I18N = False``.
680
681
682 7.4.1 (7 October 2022)
683 ======================
684
685 - Fix broken translations due to last common country names fix.
686
687
688 7.4 (7 October 2022)
689 ====================
690
691 - Fixed Traditional Chinese translation (needed to be ``locale/zh_Hant``).
692
693 - Update flag of Honduras.
694
695 - Add Django 4.0 and 4.1 to the test matrix, dropping 3.0 and 3.1
696
697 - Add Django Rest Framework 3.13 and 3.14, dropping 3.11.
698
699 - Multi-choice countries are now stored sorted and with duplicates stripped.
700 Thanks flbraun and Jens Diemer!
701
702 - Fix common country names not being honoured in non-English translations (only
703 fixed for Python 3.8+).
704
705
706 7.3.2 (4 March 2022)
707 ====================
708
709 - Fix slowdown introduced in v7.3 caused by always using country name lookups
710 for field comparisons. ``filter(country="New Zealand")`` will no longer match
711 now, but instead new ``__name`` and ``__iname`` filters have been added to
712 achieve this.
713
714
715 7.3.1 (1 March 2022)
716 ====================
717
718 - Typing compatibility fixes for Python <3.9.
719
720
721 7.3 (28 February 2022)
722 ======================
723
724 - Make full English country names work in database lookups, for example,
725 ``Person.objects.filter(country__icontains="zealand")``.
726
727
728 7.2.1 (11 May 2021)
729 ===================
730
731 - Fix Latin translations.
732
733
734 7.2 (10 May 2021)
735 =================
736
737 - Allow the character field to work with custom country codes that are not 2
738 characters (such as "GB-WLS").
739
740 - Fix compatibility with ``django-migrations-ignore-attrs`` library.
741
742
743 7.1 (17 March 2021)
744 ===================
745
746 - Allow customising the ``str_attr`` of Country objects returned from a
747 CountryField via a new ``countries_str_attr`` keyword argument (thanks C.
748 Quentin).
749
750 - Add ``pyuca`` as an extra dependency, so that it can be installed like
751 ``pip install django-countries[pyuca]``.
752
753 - Add Django 3.2 support.
754
755
756 7.0 (5 December 2020)
757 =====================
758
759 - Add ``name_only`` as an option to the Django Rest Framework serializer field
760 (thanks Miguel Marques).
761
762 - Add in Python typing.
763
764 - Add Python 3.9, Django 3.1, and Django Rest Framework 3.12 support.
765
766 - Drop Python 3.5 support.
767
768 - Improve IOC code functionality, allowing them to be overridden in
769 ``COUNTRIES_OVERRIDE`` using the complex dictionary format.
770
771
772 6.1.3 (18 August 2020)
773 ======================
774
775 - Update flag of Mauritania.
776
777 - Add flag for Kosovo (under its temporary code of XK).
778
779
780 6.1.2 (26 March 2020)
781 =====================
782
783 - Fix Python 3.5 syntax error (no f-strings just yet...).
784
785
786 6.1.1 (26 March 2020)
787 =====================
788
789 - Change ISO country import so that "Falkland Islands [Malvinas]" => "Falkland Islands (Malvinas)".
790
791
792 6.1 (20 March 2020)
793 ===================
794
795 - Add a GraphQL object type for a django ``Country`` object.
796
797
798 6.0 (28 February 2020)
799 ======================
800
801 - Make DRF CountryField respect ``blank=False``. This is a backwards incompatible change since blank input will now
802 return a validation error (unless ``blank`` is explicitly set to ``True``).
803
804 - Fix ``COUNTRIES_OVERRIDE`` when using the complex dictionary format and a single name.
805
806 - Add bandit to the test suite for basic security analysis.
807
808 - Drop Python 2.7 and Python 3.4 support.
809
810 - Add Rest Framework 3.10 and 3.11 to the test matrix, remove 3.8.
811
812 - Fix a memory leak when using PyUCA. Thanks Meiyer (aka interDist)!
813
814
815 5.5 (11 September 2019)
816 =======================
817
818 - Django 3.0 compatibility.
819
820 - Plugin system for extending the ``Country`` object.
821
822
823 5.4 (11 August 2019)
824 ====================
825
826 - Renamed Macedonia -> North Macedonia.
827
828 - Fix an outlying ``makemigrations`` error.
829
830 - Pulled in new translations which were provided but missing from previous
831 version.
832
833 - Fixed Simplified Chinese translation (needed to be ``locale/zh_Hans``).
834
835 - Introduce an optional complex format for ``COUNTRIES_ONLY`` and
836 ``COUNTRIES_OVERRIDE`` to allow for multiple names for a country, a custom
837 three character code, and a custom numeric country code.
838
839
840 5.3.3 (16 February 2019)
841 ========================
842
843 - Add test coverage for Django Rest Framework 3.9.
844
845
846 5.3.2 (27 August 2018)
847 ======================
848
849 - Tests for Django 2.1 and Django Rest Framework 3.8.
850
851
852 5.3.1 (12 June 2018)
853 ====================
854
855 - Fix ``dumpdata`` and ``loaddata`` for ``CountryField(multiple=True)``.
856
857
858 5.3 (20 April 2018)
859 ===================
860
861 - Iterating a ``Countries`` object now returns named tuples. This makes things
862 nicer when using ``{% get_countries %}`` or using the country list elsewhere
863 in your code.
864
865
866 5.2 (9 March 2018)
867 ==================
868
869 - Ensure Django 2.1 compatibility for ``CountrySelectWidget``.
870
871 - Fix regression introduced into 5.1 when using Django 1.8 and certain queryset
872 lookup types (like ``__in``).
873
874
875 5.1.1 (31 January 2018)
876 =======================
877
878 - Fix some translations that were included in 5.1 but not compiled.
879
880
881 5.1 (30 January 2018)
882 =====================
883
884 * Tests now also cover Django Rest Framework 3.7 and Django 2.0.
885
886 * Allow for creating country fields using (valid) alpha-3 or numeric codes.
887
888 * Fix migration error with blank default (thanks Jens Diemer).
889
890 * Add a ``{% get_countries %}`` template tag (thanks Matija Čvrk).
891
892
893 5.0 (10 October 2017)
894 =====================
895
896 * No longer allow ``multiple=True`` and ``null=True`` together. This causes
897 problems saving the field, and ``null`` shouldn't really be used anyway
898 because the country field is a subclass of ``CharField``.
899
900
901 4.6 (16 June 2017)
902 ==================
903
904 * Add a ``CountryFieldMixin`` Django Rest Framework serializer mixin that
905 automatically picks the right field type for a ``CountryField`` (both single
906 and multi-choice).
907
908 * Validation for Django Rest Framework field (thanks Simon Meers).
909
910 * Allow case-insensitive ``.by_name()`` matching (thanks again, Simon).
911
912 * Ensure a multiple-choice ``CountryField.max_length`` is enough to hold all
913 countries.
914
915 * Fix inefficient pickling of countries (thanks Craig de Stigter for the report
916 and tests).
917
918 * Stop adding a blank choice when dealing with a multi-choice ``CountryField``.
919
920 * Tests now cover multiple Django Rest Framework versions (back to 3.3).
921
922 4.6.1
923 -----
924
925 * Fix invalid reStructuredText in CHANGES.
926
927 4.6.2
928 -----
929
930 * Use transparency layer for flag sprites.
931
932
933 4.5 (18 April 2017)
934 ===================
935
936 * Change rest framework field to be based on ``ChoiceField``.
937
938 * Allow for the rest framework field to deserialize by full country name
939 (specifically the English name for now).
940
941
942 4.4 (6 April 2017)
943 ==================
944
945 * Fix for broken CountryField on certain models in Django 1.11.
946 Thanks aktiur for the test case.
947
948 * Update tests to cover Django 1.11
949
950
951 4.3 (29 March 2017)
952 ===================
953
954 * Handle "Czechia" translations in a nicer way (fall back to "Czech Republic"
955 until new translations are available).
956
957 * Fix for an import error in Django 1.9+ due to use of non-lazy ``ugettext`` in
958 the django-countries custom admin filter.
959
960 * Back to 100% test coverage.
961
962
963 4.2 (10 March 2017)
964 ===================
965
966 * Add sprite flag files (and ``Country.flag_css`` property) to help minimize
967 HTTP requests.
968
969
970 4.1 (22 February 2017)
971 ======================
972
973 * Better default Django admin filter when filtering a country field in a
974 ``ModelAdmin``.
975
976 * Fix settings to support Django 1.11
977
978 * Fix when using a model instance with a deferred country field.
979
980 * Allow ``CountryField`` to handle multiple countries at once!
981
982 * Allow CountryField to still work if Deferred.
983
984 * Fix a field with customized country list. Thanks pilmie!
985
986
987 4.0 (16 August 2016)
988 ====================
989
990 Django supported versions are now 1.8+
991
992 * Drop legacy code
993
994 * Fix tests, 100% coverage
995
996 * IOS / OSX unicode flags function
997
998 * Fix widget choices on Django 1.9+
999
1000 * Add ``COUNTRIES_FIRST_SORT``. Thanks Edraak!
1001
1002 4.0.1
1003 -----
1004
1005 * Fix tests for ``COUNTRIES_FIRST_SORT`` (feature still worked, tests didn't).
1006
1007
1008 3.4 (22 October 2015)
1009 =====================
1010
1011 * Extend test suite to cover Django 1.8
1012
1013 * Fix XSS escaping issue in CountrySelectWidget
1014
1015 * Common name changes: fix typo of Moldova, add United Kingdom
1016
1017 * Add ``{% get_country %}`` template tag.
1018
1019 * New ``CountryField`` Django Rest Framework serializer field.
1020
1021 3.4.1
1022 -----
1023
1024 * Fix minor packaging error.
1025
1026
1027 3.3 (30 Mar 2015)
1028 =================
1029
1030 * Add the attributes to ``Countries`` class that can override the default
1031 settings.
1032
1033 * CountriesField can now be passed a custom countries subclass to use, which
1034 combined with the previous change allows for different country choices for
1035 different fields.
1036
1037 * Allow ``COUNTRIES_ONLY`` to also accept just country codes in its list
1038 (rather than only two-tuples), looking up the translatable country name from
1039 the full country list.
1040
1041 * Fix Montenegro flag size (was 12px high rather than the standard 11px).
1042
1043 * Fix outdated ISO country name formatting for Bolivia, Gambia, Holy See,
1044 Iran, Micronesia, and Venezuela.
1045
1046
1047 3.2 (24 Feb 2015)
1048 =================
1049
1050 * Fixes initial iteration failing for a fresh ``Countries`` object.
1051
1052 * Fix widget's flag URLs (and use ensure widget is HTML encoded safely).
1053
1054 * Add ``countries.by_name(country, language='en')`` method, allowing lookup of
1055 a country code by its full country name. Thanks Josh Schneier.
1056
1057
1058 3.1 (15 Jan 2015)
1059 =================
1060
1061 * Start change log :)
1062
1063 * Add a ``COUNTRIES_FIRST`` setting (and some other related ones) to allow for
1064 specific countries to be shown before the entire alphanumeric list.
1065
1066 * Add a ``blank_label`` argument to ``CountryField`` to allow customization of
1067 the label shown in the initial blank choice shown in the select widget.
1068
1069 3.1.1 (15 Jan 2015)
1070 -------------------
1071
1072 * Packaging fix (``CHANGES.rst`` wasn't in the manifest)
1073
1074
1075 3.0 (22 Oct 2014)
1076 =================
1077
1078 Django supported versions are now 1.4 (LTS) and 1.6+
1079
1080 * Add ``COUNTRIES_ONLY`` setting to restrict to a specific list of countries.
1081
1082 * Optimize country name translations to avoid exessive translation calls that
1083 were causing a notable performance impact.
1084
1085 * PyUCA integration, allowing for more accurate sorting across all locales.
1086 Also, a better sorting method when PyUCA isn't installed.
1087
1088 * Better tests (now at 100% test coverage).
1089
1090 * Add a ``COUNTRIES_FLAG_URL`` setting to allow custom flag urls.
1091
1092 * Support both IOC and numeric country codes, allowing more flexible lookup of
1093 countries and specific code types.
1094
1095 * Field descriptor now returns ``None`` if no country matches (*reverted in
1096 v3.0.1*)
1097
1098 3.0.1 (27 Oct 2014)
1099 -------------------
1100
1101 * Revert descriptor to always return a Country object.
1102
1103 * Fix the ``CountryField`` widget choices appearing empty due to a translation
1104 change in v3.0.
1105
1106 3.0.2 (29 Dec 2014)
1107 -------------------
1108
1109 * Fix ``CountrySelectWidget`` failing when used with a model form that is
1110 passed a model instance.
1111
1112
1113 2.1 (24 Mar 2014)
1114 =================
1115
1116 * Add IOC (3 letter) country codes.
1117
1118 * Fix bug when loading fixtures.
1119
1120 2.1.1 (28 Mar 2014)
1121 -------------------
1122
1123 * Fix issue with translations getting evaluated early.
1124
1125 2.1.2 (28 Mar 2014)
1126 -------------------
1127
1128 * Fix Python 3 compatibility.
1129
1130
1131
1132 2.0 (18 Feb 2014)
1133 =================
1134
1135 This is the first entry to the change log. The previous was 1.5,
1136 released 19 Nov 2012.
1137
1138 * Optimized flag images, adding flags missing from original source.
1139
1140 * Better storage of settings and country list.
1141
1142 * New country list format for fields.
1143
1144 * Better tests.
1145
1146 * Changed ``COUNTRIES_FLAG_STATIC`` setting to ``COUNTRIES_FLAG_URL``.