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

Overview

Django Countries

PyPI version Build status Coverage status

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

Installation

  1. pip install django-countries
  2. Add django_countries to INSTALLED_APPS

For more accurate sorting of translated country names, install the optional pyuca package.

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:

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:

>>> 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:

country = CountryField(blank_label='(select country)')

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:

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

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:

<link rel="stylesheet" href="{% static 'flags/sprite.css' %}">
<i class="{{ country.flag_css }}"></i>

For multiple flag resolutions, use sprite-hq.css instead and add the flag2x, flag3x, or flag4x class. For example:

<link rel="stylesheet" href="{% static 'flags/sprite-hq.css' %}">
Normal: <i class="{{ country.flag_css }}"></i>
Bigger: <i class="flag2x {{ country.flag_css }}"></i>

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

<i class="{{ country.flag_css }}"
    aria-label="{% blocktrans with country_code=country.code %}
        {{ country_code }} flag
    {% endblocktrans %}"></i>
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:

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:

'{widget}<img class="country-select-flag" id="{flag_id}" style="margin: 6px 4px 0" src="{country.flag}">'

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:

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:

>>> 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)

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/projects/p/django-countries/

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:

{% load countries %}
{% get_country 'BR' as country %}
{{ country.name }}

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

{% load countries %}
{% get_countries as countries %}
<select>
{% for country in countries %}
    <option value="{{ country.code }}">{{ country.name }}</option>
{% endfor %}
</select>

Customization

Customize the country list

Country names are taken from the official ISO 3166-1 list. If your project requires the use of alternative names, the inclusion or exclusion of specific countries then use the COUNTRIES_OVERRIDE setting.

A dictionary of names to 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:

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:

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):

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:

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:

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:

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.

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

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:

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:

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.

REST output format

By default, the field will output just the country code. To output the full country name instead, instanciate 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": "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:

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"
      }
    ]
  }
}

GraphQL

A Country graphene object type is included that can be used when generating your schema.

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
How to use COG's (Cloud optimized GeoTIFFs) with Rasterio

How to use COG's (Cloud optimized GeoTIFFs) with Rasterio According to Cogeo.org: A Cloud Opdtimized GeoTIFF (COG) is a regular GeoTIFF file, aimed at

Marvin Gabler 8 Jul 29, 2022
When traveling in the backcountry during winter time, updating yourself on current and recent weather data is important to understand likely avalanche danger.

Weather Data When traveling in the backcountry during winter time, updating yourself on current and recent weather data is important to understand lik

Trevor Allen 0 Jan 02, 2022
Read images to numpy arrays

mahotas-imread: Read Image Files IO with images and numpy arrays. Mahotas-imread is a simple module with a small number of functions: imread Reads an

Luis Pedro Coelho 67 Jan 07, 2023
Centroids as a Service

Centroids! This application reads a valid geojson FeatureCollection and returns a valid geojson FeatureColleciton of centroids. In the output: All pro

Lyzi Diamond 20 Aug 29, 2021
glTF to 3d Tiles Converter. Convert glTF model to Glb, b3dm or 3d tiles format.

gltf-to-3d-tiles glTF to 3d Tiles Converter. Convert glTF model to Glb, b3dm or 3d tiles format. Usage λ python main.py --help Usage: main.py [OPTION

58 Dec 27, 2022
h3-js provides a JavaScript version of H3, a hexagon-based geospatial indexing system.

h3-js The h3-js library provides a pure-JavaScript version of the H3 Core Library, a hexagon-based geographic grid system. It can be used either in No

Uber Open Source 648 Jan 07, 2023
Histogram matching plugin for rasterio

rio-hist Histogram matching plugin for rasterio. Provides a CLI and python module for adjusting colors based on histogram matching in a variety of col

Mapbox 75 Sep 23, 2022
Deal with Bing Maps Tiles and Pixels / WGS 84 coordinates conversions, and generate grid Shapefiles

PyBingTiles This is a small toolkit in order to deal with Bing Tiles, used i.e. by Facebook for their Data for Good datasets. Install Clone this repos

Shoichi 1 Dec 08, 2021
r.cfdtools 7 Dec 28, 2022
:earth_asia: Python Geocoder

Python Geocoder Simple and consistent geocoding library written in Python. Table of content Overview A glimpse at the API Forward Multiple results Rev

Denis 1.5k Jan 02, 2023
Imports VZD (Latvian State Land Service) open data into postgis enabled database

Python script main.py downloads and imports Latvian addresses into PostgreSQL database. Data contains parishes, counties, cities, towns, and streets.

Kaspars Foigts 7 Oct 26, 2022
Processing and interpolating spatial data with a twist of machine learning

Documentation | Documentation (dev version) | Contact | Part of the Fatiando a Terra project About Verde is a Python library for processing spatial da

Fatiando a Terra 468 Dec 20, 2022
Interactive Maps with Geopandas

Create Interactive maps 🗺️ with your geodataframe Geopatra extends geopandas for interactive mapping and attempts to wrap the goodness of amazing map

sangarshanan 46 Aug 16, 2022
A GUI widget for Linux to show current time in different timezones.

A GUI widget to show current time in different timezones (under development). To use this widget: Run scripts/startup.py Select a country. A list of t

B.Jothin kumar 11 Nov 10, 2022
Zora is a python program that searches for GeoLocation info for given CIDR networks , with options to search with API or without API

Zora Zora is a python program that searches for GeoLocation info for given CIDR networks , with options to search with API or without API Installing a

z3r0day 1 Oct 26, 2021
A service to auto provision devices in Aruba Central based on the Geo-IP location

Location Based Provisioning Service for Aruba Central A service to auto provision devices in Aruba Central based on the Geo-IP location Geo-IP auto pr

Will Smith 3 Mar 22, 2022
PyTorch implementation of ''Background Activation Suppression for Weakly Supervised Object Localization''.

Background Activation Suppression for Weakly Supervised Object Localization PyTorch implementation of ''Background Activation Suppression for Weakly S

34 Dec 27, 2022
Using Global fishing watch's data to build a machine learning model that can identify illegal fishing and poaching activities through satellite and geo-location data.

Using Global fishing watch's data to build a machine learning model that can identify illegal fishing and poaching activities through satellite and geo-location data.

Ayush Mishra 3 May 06, 2022
Pure python WMS

Ogcserver Python WMS implementation using Mapnik. Depends Mapnik = 0.7.0 (and python bindings) Pillow PasteScript WebOb You will need to install Map

Mapnik 130 Dec 28, 2022
This app displays interesting statistical weather records and trends which can be used in climate related research including study of global warming.

This app displays interesting statistical weather records and trends which can be used in climate related research including study of global warming.

0 Dec 27, 2021