Metadata-Version: 1.1
Name: django-countries
Version: 5.2
Summary: Provides a country field for Django models.
Home-page: https://github.com/SmileyChris/django-countries/
Author: Chris Beaven
Author-email: smileychris@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Description: ================
        Django Countries
        ================
        
        .. image:: https://api.travis-ci.org/SmileyChris/django-countries.svg?branch=master
            :alt: Build Status
            :target: http://travis-ci.org/SmileyChris/django-countries
        
        
        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.
        
        .. _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)')
        
        
        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
        
        
        The ``Country`` object
        ----------------------
        
        An object used to represent a country, instanciated with a two character
        country 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
        
            <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:
        
          .. code:: jinja
        
            <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:
        
          .. code:: jinja
        
            <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.
        
        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.
        
        
        ``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}<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 following custom
        field to ensure the translatable strings for the country choices are left lazy
        until the widget renders:
        
          .. code:: python
        
            from django_countries.fields import LazyTypedChoiceField
        
            class CustomForm(forms.Form):
                country = LazyTypedChoiceField(choices=countries)
        
        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("{name} ({code})".format(name=name, code=code))
            ...
            Afghanistan (AF)
            Åland Islands (AX)
            Albania (AL)
        
        Country names are translated using Django's standard ``ugettext``.
        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:
        
          .. 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 %}
            <select>
            {% for country in countries %}
                <option>{{ 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.
        
        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 ugettext_lazy as _
        
            COUNTRIES_OVERRIDE = {
                'NZ': _('Middle Earth'),
                'AU': None
            }
        
        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::
        
            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()
        
        
        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 ``countries`` with a custom
        Countries_ instance.
        
        .. _Countries: `Single field customization`_
        
        
        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/
        
        
        REST output format
        ------------------
        
        By default, the field will output just the country code. 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.
        
        ==========
        Change Log
        ==========
        
        This log shows interesting changes that happen for each version, latest
        versions first. It can be assumed that translations have been updated each
        release, and any new translations added.
        
        5.2 (9 March 2018)
        ==================
        
        - Ensure Django 2.1 compatibility for ``CountrySelectWidget``.
        
        - Fix regression introduced into 5.1 when using Django 1.8 and certain queryset
          lookup types (like ``__in``).
        
        
        5.1.1 (31 January 2018)
        =======================
        
        - Fix some translations that were included in 5.1 but not compiled.
        
        
        5.1 (30 January 2018)
        =====================
        
        * Tests now also cover Django Rest Framework 3.7 and Django 2.0.
        
        * Allow for creating country fields using (valid) alpha-3 or numeric codes.
        
        * Fix migration error with blank default (thanks Jens Diemer).
        
        * Add a ``{% get_countries %}`` template tag (thanks Matija Čvrk).
        
        
        5.0 (10 October 2017)
        =====================
        
        * No longer allow ``multiple=True`` and ``null=True`` together. This causes
          problems saving the field, and ``null`` shouldn't really be used anyway
          because the country field is a subclass of ``CharField``.
        
        
        4.6 (16 June 2017)
        ==================
        
        * Add a ``CountryFieldMixin`` Django Rest Framework serializer mixin that
          automatically picks the right field type for a ``CountryField`` (both single
          and multi-choice).
        
        * Validation for Django Rest Framework field (thanks Simon Meers).
        
        * Allow case-insensitive ``.by_name()`` matching (thanks again, Simon).
        
        * Ensure a multiple-choice ``CountryField.max_length`` is enough to hold all
          countries.
        
        * Fix inefficient pickling of countries (thanks Craig de Stigter for the report
          and tests).
        
        * Stop adding a blank choice when dealing with a multi-choice ``CountryField``.
        
        * Tests now cover multiple Django Rest Framework versions (back to 3.3).
        
        4.6.1
        -----
        
        * Fix invalid reStructuredText in CHANGES.
        
        4.6.2
        -----
        
        * Use transparency layer for flag sprites.
        
        
        4.5 (18 April 2017)
        ===================
        
        * Change rest framework field to be based on ``ChoiceField``.
        
        * Allow for the rest framework field to deserialize by full country name
          (specifically the English name for now).
        
        
        4.4 (6 April 2017)
        ==================
        
        * Fix for broken CountryField on certain models in Django 1.11.
          Thanks aktiur for the test case.
        
        * Update tests to cover Django 1.11
        
        
        4.3 (29 March 2017)
        ===================
        
        * Handle "Czechia" translations in a nicer way (fall back to "Czech Republic"
          until new translations are available).
        
        * Fix for an import error in Django 1.9+ due to use of non-lazy ``ugettext`` in
          the django-countries custom admin filter.
        
        * Back to 100% test coverage.
        
        
        4.2 (10 March 2017)
        ===================
        
        * Add sprite flag files (and ``Country.flag_css`` property) to help minimize
          HTTP requests.
        
        
        4.1 (22 February 2017)
        ======================
        
        * Better default Django admin filter when filtering a country field in a
          ``ModelAdmin``.
        
        * Fix settings to support Django 1.11
        
        * Fix when using a model instance with a deferred country field.
        
        * Allow ``CountryField`` to handle multiple countries at once!
        
        * Allow CountryField to still work if Deferred.
        
        * Fix a field with customized country list. Thanks pilmie!
        
        
        4.0 (16 August 2016)
        ====================
        
        Django supported versions are now 1.8+
        
        * Drop legacy code
        
        * Fix tests, 100% coverage
        
        * IOS / OSX unicode flags function
        
        * Fix widget choices on Django 1.9+
        
        * Add ``COUNTRIES_FIRST_SORT``. Thanks Edraak!
        
        4.0.1
        -----
        
        * Fix tests for ``COUNTRIES_FIRST_SORT`` (feature still worked, tests didn't).
        
        
        3.4 (22 October 2015)
        =====================
        
        * Extend test suite to cover Django 1.8
        
        * Fix XSS escaping issue in CountrySelectWidget
        
        * Common name changes: fix typo of Moldova, add United Kingdom
        
        * Add ``{% get_country %}`` template tag.
        
        * New ``CountryField`` Django Rest Framework serializer field.
        
        3.4.1
        -----
        
        * Fix minor packaging error.
        
        
        3.3 (30 Mar 2015)
        =================
        
        * Add the attributes to ``Countries`` class that can override the default
          settings.
        
        * CountriesField can now be passed a custom countries subclass to use, which
          combined with the previous change allows for different country choices for
          different fields.
        
        * Allow ``COUNTRIES_ONLY`` to also accept just country codes in its list
          (rather than only two-tuples), looking up the translatable country name from
          the full country list.
        
        * Fix Montenegro flag size (was 12px high rather than the standard 11px).
        
        * Fix outdated ISO country name formatting for Bolivia, Gambia, Holy See,
          Iran, Micronesia, and Venezuela.
        
        
        3.2 (24 Feb 2015)
        =================
        
        * Fixes initial iteration failing for a fresh ``Countries`` object.
        
        * Fix widget's flag URLs (and use ensure widget is HTML encoded safely).
        
        * Add ``countries.by_name(country, language='en')`` method, allowing lookup of
          a country code by its full country name. Thanks Josh Schneier.
        
        
        3.1 (15 Jan 2015)
        =================
        
        * Start change log :)
        
        * Add a ``COUNTRIES_FIRST`` setting (and some other related ones) to allow for
          specific countries to be shown before the entire alphanumeric list.
        
        * Add a ``blank_label`` argument to ``CountryField`` to allow customization of
          the label shown in the initial blank choice shown in the select widget.
        
        3.1.1 (15 Jan 2015)
        -------------------
        
        * Packaging fix (``CHANGES.rst`` wasn't in the manifest)
        
        
        3.0 (22 Oct 2014)
        =================
        
        Django supported versions are now 1.4 (LTS) and 1.6+
        
        * Add ``COUNTRIES_ONLY`` setting to restrict to a specific list of countries.
        
        * Optimize country name translations to avoid exessive translation calls that
          were causing a notable performance impact.
        
        * PyUCA integration, allowing for more accurate sorting across all locales.
          Also, a better sorting method when PyUCA isn't installed.
        
        * Better tests (now at 100% test coverage).
        
        * Add a ``COUNTRIES_FLAG_URL`` setting to allow custom flag urls.
        
        * Support both IOC and numeric country codes, allowing more flexible lookup of
          countries and specific code types.
        
        * Field descriptor now returns ``None`` if no country matches (*reverted in v3.0.1*)
        
        3.0.1 (27 Oct 2014)
        -------------------
        
        * Revert descriptor to always return a Country object.
        
        * Fix the ``CountryField`` widget choices appearing empty due to a translation
          change in v3.0.
        
        3.0.2 (29 Dec 2014)
        -------------------
        
        * Fix ``CountrySelectWidget`` failing when used with a model form that is
          passed a model instance.
        
        
        2.1 (24 Mar 2014)
        =================
        
        * Add IOC (3 letter) country codes.
        
        * Fix bug when loading fixtures.
        
        2.1.1 (28 Mar 2014)
        -------------------
        
        * Fix issue with translations getting evaluated early.
        
        2.1.2 (28 Mar 2014)
        -------------------
        
        * Fix Python 3 compatibility.
        
        
        
        2.0 (18 Feb 2014)
        =================
        
        This is the first entry to the change log. The previous was 1.5,
        released 19 Nov 2012.
        
        * Optimized flag images, adding flags missing from original source.
        
        * Better storage of settings and country list.
        
        * New country list format for fields.
        
        * Better tests.
        
        * Changed ``COUNTRIES_FLAG_STATIC`` setting to ``COUNTRIES_FLAG_URL``.
        
Keywords: django,countries,flags
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Framework :: Django
