Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/SmileyChris/django-countries

A Django application that provides country choices for use with forms, flag icons static files, and a country field for models.
https://github.com/SmileyChris/django-countries

country-codes django python

Last synced: 6 days ago
JSON representation

A Django application that provides country choices for use with forms, flag icons static files, and a country field for models.

Awesome Lists containing this project

README 

        
================

Django Countries

================



.. image:: https://badge.fury.io/py/django-countries.svg

    :alt: PyPI version

    :target: https://badge.fury.io/py/django-countries



.. image:: https://github.com/SmileyChris/django-countries/actions/workflows/tests.yml/badge.svg

    :alt: Build status

    :target: https://github.com/SmileyChris/django-countries/actions/workflows/tests.yml



A Django application that provides country choices for use with forms, flag

icons static files, and a country field for models.



Country names are translated using Django's standard ``gettext``. If you would

like to help by adding a translation, please visit

https://www.transifex.com/smileychris/django-countries/



.. contents::

    :local:

    :backlinks: none



Installation

============



1. ``pip install django-countries``



   For more accurate sorting of translated country names, install it with the

   optional pyuca_ package:



   ``pip install django-countries[pyuca]``



2. Add ``django_countries`` to ``INSTALLED_APPS``



.. _pyuca: https://pypi.python.org/pypi/pyuca/



CountryField

============



A country field for Django models that provides all ISO 3166-1 countries as

choices.



``CountryField`` is based on Django's ``CharField``, providing choices

corresponding to the official ISO 3166-1 list of countries (with a default

``max_length`` of 2).



Consider the following model using a ``CountryField``:



.. code:: python



    from django.db import models

    from django_countries.fields import CountryField



    class Person(models.Model):

        name = models.CharField(max_length=100)

        country = CountryField()



Any ``Person`` instance will have a ``country`` attribute that you can use to

get details of the person's country:



.. code:: python



    >>> person = Person(name="Chris", country="NZ")

    >>> person.country

    Country(code='NZ')

    >>> person.country.name

    'New Zealand'

    >>> person.country.flag

    '/static/flags/nz.gif'



This object (``person.country`` in the example) is a ``Country`` instance,

which is described below.



Use ``blank_label`` to set the label for the initial blank choice shown in

forms:



.. code:: python



    country = CountryField(blank_label="(select country)")



You can filter using the full English country names in addition to country

codes, even though only the country codes are stored in the database by using

the queryset lookups ``contains``, ``startswith``, ``endswith``, ``regex``, or

their case insensitive versions. Use ``__name`` or ``__iname`` for the

``exact``/``iexact`` equivalent:



.. code:: python



    >>> Person.objects.filter(country__name="New Zealand").count()

    1

    >>> Person.objects.filter(country__icontains="zealand").count()

    1



Multi-choice

------------



This field can also allow multiple selections of countries (saved as a comma

separated string). The field will always output a list of countries in this

mode. For example:



.. code:: python



    class Incident(models.Model):

        title = models.CharField(max_length=100)

        countries = CountryField(multiple=True)



    >>> for country in Incident.objects.get(title="Pavlova dispute").countries:

    ...     print(country.name)

    Australia

    New Zealand



By default, countries are stored sorted for data consistency, and any

duplicates are removed. These behaviours can be overridden by using the field

arguments ``multiple_sort=False`` and ``multiple_unique=False`` respectively.



The ``Country`` object

----------------------



An object used to represent a country, instantiated with a two character

country code, three character code, or numeric code.



It can be compared to other objects as if it was a string containing the

country code and when evaluated as text, returns the country code.



name

  Contains the full country name.



flag

  Contains a URL to the flag. If you page could have lots of different flags

  then consider using ``flag_css`` instead to avoid excessive HTTP requests.



flag_css

  Output the css classes needed to display an HTML element as the correct flag

  from within a single sprite image that contains all flags. For example:



  .. code:: jinja



    

    



  For multiple flag resolutions, use ``sprite-hq.css`` instead and add the

  ``flag2x``, ``flag3x``, or ``flag4x`` class. For example:



  .. code:: jinja



    

    Normal: 

    Bigger: 



  You might also want to consider using ``aria-label`` for better

  accessibility:



  .. code:: jinja



    



unicode_flag

  A unicode glyph for the flag for this country. Currently well-supported in

  iOS and OS X. See https://en.wikipedia.org/wiki/Regional_Indicator_Symbol

  for details.



code

  The two letter country code for this country.



alpha3

  The three letter country code for this country.



numeric

  The numeric country code for this country (as an integer).



numeric_padded

  The numeric country code as a three character 0-padded string.



ioc_code

  The three letter International Olympic Committee country code.



``CountrySelectWidget``

-----------------------



A widget is included that can show the flag image after the select box

(updated with JavaScript when the selection changes).



When you create your form, you can use this custom widget like normal:



.. code:: python



    from django_countries.widgets import CountrySelectWidget



    class PersonForm(forms.ModelForm):

        class Meta:

            model = models.Person

            fields = ("name", "country")

            widgets = {"country": CountrySelectWidget()}



Pass a ``layout`` text argument to the widget to change the positioning of the

flag and widget. The default layout is:



.. code:: python



    '{widget}'



Custom forms

============



If you want to use the countries in a custom form, use the model field's custom

form field to ensure the translatable strings for the country choices are left

lazy until the widget renders:



.. code:: python



    from django_countries.fields import CountryField



    class CustomForm(forms.Form):

        country = CountryField().formfield()



Use ``CountryField(blank=True)`` for non-required form fields, and

``CountryField(blank_label="(Select country)")`` to use a custom label for the

initial blank option.



You can also use the CountrySelectWidget_ as the widget for this field if you

want the flag image after the select box.



Get the countries from Python

=============================



Use the ``django_countries.countries`` object instance as an iterator of ISO

3166-1 country codes and names (sorted by name).



For example:



.. code:: python



    >>> from django_countries import countries

    >>> dict(countries)["NZ"]

    'New Zealand'



    >>> for code, name in list(countries)[:3]:

    ...     print(f"{name} ({code})")

    ...

    Afghanistan (AF)

    Åland Islands (AX)

    Albania (AL)



Template Tags

=============



If you have your country code stored in a different place than a

``CountryField`` you can use the template tag to get a ``Country`` object and

have access to all of its properties:



.. code:: jinja



    {% load countries %}

    {% get_country 'BR' as country %}

    {{ country.name }}



If you need a list of countries, there's also a simple tag for that:



.. code:: jinja



    {% load countries %}

    {% get_countries as countries %}

    

    {% for country in countries %}

        {{ country.name }}

    {% endfor %}

    



Customization

=============



Customize the country list

--------------------------



Country names are taken from the official ISO 3166-1 list, with some country

names being replaced with their more common usage (such as "Bolivia" instead

of "Bolivia, Plurinational State of").



To retain the official ISO 3166-1 naming for all fields, set the

``COUNTRIES_COMMON_NAMES`` setting to ``False``.



If your project requires the use of alternative names, the inclusion or

exclusion of specific countries then set the ``COUNTRIES_OVERRIDE`` setting to

a dictionary of names which override the defaults. The values can also use a

more `complex dictionary format`_.



Note that you will need to handle translation of customised country names.



Setting a country's name to ``None`` will exclude it from the country list.

For example:



.. code:: python



    from django.utils.translation import gettext_lazy as _



    COUNTRIES_OVERRIDE = {

        "NZ": _("Middle Earth"),

        "AU": None,

        "US": {

            "names": [

                _("United States of America"),

                _("America"),

            ],

        },

    }



If you have a specific list of countries that should be used, use

``COUNTRIES_ONLY``:



.. code:: python



    COUNTRIES_ONLY = ["NZ", "AU"]



or to specify your own country names, use a dictionary or two-tuple list

(string items will use the standard country name):



.. code:: python



    COUNTRIES_ONLY = [

        "US",

        "GB",

        ("NZ", _("Middle Earth")),

        ("AU", _("Desert")),

    ]



Show certain countries first

----------------------------



Provide a list of country codes as the ``COUNTRIES_FIRST`` setting and they

will be shown first in the countries list (in the order specified) before all

the alphanumerically sorted countries.



If you want to sort these initial countries too, set the

``COUNTRIES_FIRST_SORT`` setting to ``True``.



By default, these initial countries are not repeated again in the

alphanumerically sorted list. If you would like them to be repeated, set the

``COUNTRIES_FIRST_REPEAT`` setting to ``True``.



Finally, you can optionally separate these "first" countries with an empty

choice by providing the choice label as the ``COUNTRIES_FIRST_BREAK`` setting.



Customize the flag URL

----------------------



The ``COUNTRIES_FLAG_URL`` setting can be used to set the url for the flag

image assets. It defaults to:



.. code:: python



    COUNTRIES_FLAG_URL = "flags/{code}.gif"



The URL can be relative to the STATIC_URL setting, or an absolute URL.



The location is parsed using Python's string formatting and is passed the

following arguments:



* ``code``

* ``code_upper``



For example: ``COUNTRIES_FLAG_URL = "flags/16x10/{code_upper}.png"``



No checking is done to ensure that a static flag actually exists.



Alternatively, you can specify a different URL on a specific ``CountryField``:



.. code:: python



    class Person(models.Model):

        name = models.CharField(max_length=100)

        country = CountryField(

            countries_flag_url="//flags.example.com/{code}.png")



Single field customization

--------------------------



To customize an individual field, rather than rely on project level settings,

create a ``Countries`` subclass which overrides settings.



To override a setting, give the class an attribute matching the lowercased

setting without the ``COUNTRIES_`` prefix.



Then just reference this class in a field. For example, this ``CountryField``

uses a custom country list that only includes the G8 countries:



.. code:: python



    from django_countries import Countries



    class G8Countries(Countries):

        only = [

            "CA", "FR", "DE", "IT", "JP", "RU", "GB",

            ("EU", _("European Union"))

        ]



    class Vote(models.Model):

        country = CountryField(countries=G8Countries)

        approve = models.BooleanField()



Complex dictionary format

-------------------------



For ``COUNTRIES_ONLY`` and ``COUNTRIES_OVERRIDE``, you can also provide a

dictionary rather than just a translatable string for the country name.



The options within the dictionary are:



``name`` or ``names`` (required)

  Either a single translatable name for this country or a list of multiple

  translatable names. If using multiple names, the first name takes preference

  when using ``COUNTRIES_FIRST`` or the ``Country.name``.



``alpha3`` (optional)

  An ISO 3166-1 three character code (or an empty string to nullify an existing

  code for this country.



``numeric`` (optional)

  An ISO 3166-1 numeric country code (or ``None`` to nullify an existing code

  for this country. The numeric codes 900 to 999 are left available by the

  standard for user-assignment.



``ioc_code`` (optional)

  The country's International Olympic Committee code (or an empty string to

  nullify an existing code).

  



``Country`` object external plugins

-----------------------------------



Other Python packages can add attributes to the Country_ object by using entry

points in their setup script.



.. _Country: `The Country object`_



For example, you could create a ``django_countries_phone`` package which had a

with the following entry point in the ``setup.py`` file. The entry point name

(``phone``) will be the new attribute name on the Country object. The attribute

value will be the return value of the ``get_phone`` function (called with the

Country instance as the sole argument).



.. code:: python



  setup(

      ...

      entry_points={

          "django_countries.Country": "phone = django_countries_phone.get_phone"

      },

      ...

  )



Django Rest Framework

=====================



Django Countries ships with a ``CountryFieldMixin`` to make the

`CountryField`_ model field compatible with DRF serializers. Use the following

mixin with your model serializer:



.. code:: python



    from django_countries.serializers import CountryFieldMixin



    class CountrySerializer(CountryFieldMixin, serializers.ModelSerializer):



        class Meta:

            model = models.Person

            fields = ("name", "email", "country")



This mixin handles both standard and `multi-choice`_ country fields.



Django Rest Framework field

---------------------------



For lower level use (or when not dealing with model fields), you can use the

included ``CountryField`` serializer field. For example:



.. code:: python



    from django_countries.serializer_fields import CountryField



    class CountrySerializer(serializers.Serializer):

        country = CountryField()



You can optionally instantiate the field with the ``countries`` argument to

specify a custom Countries_ instance.



.. _Countries: `Single field customization`_



REST output format

^^^^^^^^^^^^^^^^^^



By default, the field will output just the country code. To output the full

country name instead, instantiate the field with ``name_only=True``.



If you would rather have more verbose output, instantiate the field with

``country_dict=True``, which will result in the field having the following

output structure:



.. code:: json



    {"code": "NZ", "name": "New Zealand"}



Either the code or this dict output structure are acceptable as input

irregardless of the ``country_dict`` argument's value.



OPTIONS request

---------------



When you request OPTIONS against a resource (using the DRF `metadata support`_)

the countries will be returned in the response as choices:



.. code:: text



    OPTIONS /api/address/ HTTP/1.1



    HTTP/1.1 200 OK

    Content-Type: application/json

    Allow: GET, POST, HEAD, OPTIONS



    {

    "actions": {

      "POST": {

        "country": {

        "type": "choice",

        "label": "Country",

        "choices": [

          {

            "display_name": "Australia",

            "value": "AU"

          },

          [...]

          {

            "display_name": "United Kingdom",

            "value": "GB"

          }

        ]

      }

    }



.. _metadata support: http://www.django-rest-framework.org/api-guide/metadata/



GraphQL

=======



A ``Country`` graphene object type is included that can be used when generating

your schema.



.. code:: python



    import graphene

    from graphene_django.types import DjangoObjectType

    from django_countries.graphql.types import Country



    class Person(ObjectType):

        country = graphene.Field(Country)



        class Meta:

            model = models.Person

            fields = ["name", "country"]



The object type has the following fields available:



* ``name`` for the full country name

* ``code`` for the ISO 3166-1 two character country code

* ``alpha3`` for the ISO 3166-1 three character country code

* ``numeric`` for the ISO 3166-1 numeric country code

* ``iocCode`` for the International Olympic Committee country code