| 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``. |