[1.5.x] Fixed #20774 -- Mention the new django-localflavor app as a...

import warnings

warnings.warn("django.contrib.localflavor is deprecated. Use the separate django-localflavor-* packages instead.", DeprecationWarning)

warnings.warn("django.contrib.localflavor is deprecated. "

              "Use the separate django-localflavor package instead.",

              DeprecationWarning)

Historically, Django has shipped with ``django.contrib.localflavor`` --

assorted pieces of code that are useful for particular countries or cultures.

Starting with Django 1.5, we've started the process of moving the code to

outside packages (i.e., packages distributed separately from Django), for

Starting with Django 1.5, we've started the process of moving the code to an

external package (i.e., a package distributed separately from Django), for

easier maintenance and to trim the size of Django's codebase.

The localflavor packages are named ``django-localflavor-*``, where the asterisk

is an `ISO 3166 country code`_. For example: ``django-localflavor-us`` is the

The new localflavor package is named ``django-localflavor``, with a main

module called ``localflavor`` and many subpackages using an

`ISO 3166 country code`_. For example: ``localflavor.us`` is the

localflavor package for the U.S.A.

Most of these ``localflavor`` add-ons are country-specific fields for the

French telephone number::

    from django import forms

    from django_localflavor_fr.forms import FRPhoneNumberField

    from localflavor.fr.forms import FRPhoneNumberField

    class MyForm(forms.Form):

        my_french_phone_no = FRPhoneNumberField()

How to migrate

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

If you've used the old ``django.contrib.localflavor`` package, follow these two

easy steps to update your code:

If you've used the old ``django.contrib.localflavor`` package or one of the

temporary ``django-localflavor-*`` releases, follow these two easy steps to

update your code:

1. Install the appropriate third-party ``django-localflavor-*`` package(s).

   Go to https://github.com/django/ and find the package for your country.

1. Install the third-party ``django-localflavor`` package from PyPI.

2. Change your app's import statements to reference the new packages.

2. Change your app's import statements to reference the new package.

   For example, change this::

   ...to this::

       from django_localflavor_fr.forms import FRPhoneNumberField

       from localflavor.fr.forms import FRPhoneNumberField

The code in the new packages is the same (it was copied directly from Django),

The code in the new package is the same (it was copied directly from Django),

so you don't have to worry about backwards compatibility in terms of

functionality. Only the imports have changed.

Supported countries

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

The following countries have django-localflavor- packages.

* Argentina: https://github.com/django/django-localflavor-ar

* Australia: https://github.com/django/django-localflavor-au

* Austria: https://github.com/django/django-localflavor-at

* Belgium: https://github.com/django/django-localflavor-be

* Brazil: https://github.com/django/django-localflavor-br

* Canada: https://github.com/django/django-localflavor-ca

* Chile: https://github.com/django/django-localflavor-cl

* China: https://github.com/django/django-localflavor-cn

* Colombia: https://github.com/django/django-localflavor-co

* Croatia: https://github.com/django/django-localflavor-hr

* Czech Republic: https://github.com/django/django-localflavor-cz

* Ecuador: https://github.com/django/django-localflavor-ec

* Finland: https://github.com/django/django-localflavor-fi

* France: https://github.com/django/django-localflavor-fr

* Germany: https://github.com/django/django-localflavor-de

* Greece: https://github.com/spapas/django-localflavor-gr

* Hong Kong: https://github.com/django/django-localflavor-hk

* Iceland: https://github.com/django/django-localflavor-is

* India: https://github.com/django/django-localflavor-in

* Indonesia: https://github.com/django/django-localflavor-id

* Ireland: https://github.com/django/django-localflavor-ie

* Israel: https://github.com/django/django-localflavor-il

* Italy: https://github.com/django/django-localflavor-it

* Japan: https://github.com/django/django-localflavor-jp

* Kuwait: https://github.com/django/django-localflavor-kw

* Lithuania: https://github.com/simukis/django-localflavor-lt

* Macedonia: https://github.com/django/django-localflavor-mk

* Mexico: https://github.com/django/django-localflavor-mx

* The Netherlands: https://github.com/django/django-localflavor-nl

* Norway: https://github.com/django/django-localflavor-no

* Peru: https://github.com/django/django-localflavor-pe

* Poland: https://github.com/django/django-localflavor-pl

* Portugal: https://github.com/django/django-localflavor-pt

* Paraguay: https://github.com/django/django-localflavor-py

* Romania: https://github.com/django/django-localflavor-ro

* Russia: https://github.com/django/django-localflavor-ru

* Slovakia: https://github.com/django/django-localflavor-sk

* Slovenia: https://github.com/django/django-localflavor-si

* South Africa: https://github.com/django/django-localflavor-za

* Spain: https://github.com/django/django-localflavor-es

* Sweden: https://github.com/django/django-localflavor-se

* Switzerland: https://github.com/django/django-localflavor-ch

* Turkey: https://github.com/django/django-localflavor-tr

* United Kingdom: https://github.com/django/django-localflavor-gb

* United States of America: https://github.com/django/django-localflavor-us

* Uruguay: https://github.com/django/django-localflavor-uy

See the official documentation for more information:

    https://django-localflavor.readthedocs.org/

django.contrib.localflavor.generic

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

The ``django.contrib.localflavor.generic`` package, which hasn't been removed from

Django yet, contains useful code that is not specific to one particular country

Django 1.5 yet, contains useful code that is not specific to one particular country

or culture. Currently, it defines date, datetime and split datetime input

fields based on those from :doc:`forms </topics/forms/index>`, but with non-US

default formats. Here's an example of how to use them::

    class MyForm(forms.Form):

        my_date_field = generic.forms.DateField()

Of course the same package can also be found in the ``django-localflavor``

packages and it's recommended to use that instead.

Internationalization of localflavors

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

To activate translations for a newly-created ``localflavor`` application, you

must include the application's name (e.g. ``django_localflavor_jp``) in the

:setting:`INSTALLED_APPS` setting, so the internationalization system can find

the catalog, as explained in :ref:`how-django-discovers-translations`.

To activate translations for the ``localflavor`` application, you must include

the application's name in the :setting:`INSTALLED_APPS` setting, so the

internationalization system can find the catalog, as explained in

:ref:`how-django-discovers-translations`.

If you're still using the legacy ``localflavor`` application, you must include

:mod:`django.contrib.localflavor` in :setting:`INSTALLED_APPS` (that will