Django Local Flavor

5.0 · active · verified Sun Apr 12

django-localflavor is a collection of country-specific Django helpers, including form fields, form widgets, and model fields, useful for particular countries or cultures. It provides localized components for postal codes, government IDs, and regional selections. Originally part of Django's `contrib` apps, it was extracted into a separate package starting with Django 1.5 for easier maintenance. The current version is 5.0, and new releases generally follow Django's major version number, with a compatible version released within one month of each Django release.

Warnings

breaking The `django.contrib.localflavor` package was deprecated in Django 1.5 and removed in Django 1.6. All imports must be updated to `localflavor.<country_code>`.
Fix: Change all `from django.contrib.localflavor...` imports to `from localflavor...`. Install the standalone `django-localflavor` package.
breaking Version 3.0 removed all previously deprecated code. Ensure you have addressed all `DeprecationWarning` messages if upgrading from versions prior to 3.0.
Fix: Run your project's tests with `python -Wd` to display deprecation warnings and update code accordingly before upgrading to 3.0 or later.
breaking Specific local flavors (e.g., LV, NP, NO in 5.0; MX, IN in 3.1) have had breaking data changes due to updates in official governmental policies or data structures.
Fix: Consult the changelog for `django-localflavor` for the specific version you are upgrading to, particularly if using affected country flavors, and update your data or expectations accordingly.
deprecated django-localflavor no longer accepts contributions for country-specific phone number fields and has removed its own. For robust phone number validation, the `django-phonenumber-field` package is recommended.
Fix: Migrate any existing phone number fields to use `django-phonenumber-field` for better and more comprehensive support.
gotcha For localflavor's text (e.g., form field error messages) to be translated, `localflavor` must be included in your Django project's `INSTALLED_APPS` setting.
Fix: Add `'localflavor'` to your `INSTALLED_APPS` list in `settings.py`.
gotcha Backwards-incompatible changes can occur due to updates reflecting officially gazetted policies of local government authorities (e.g., removal or renaming of a province). These changes will raise a runtime warning when the affected localflavor is imported.
Fix: Monitor for runtime warnings related to localflavor imports and review the changelog for details on specific country flavor updates that might require code or data adjustments.

Install

pip install django-localflavor Install latest version

Imports

SomeField
```
from localflavor.<country_code>.forms import SomeField
```
The 'localflavor' package was moved out of Django's `contrib` in Django 1.5. Imports from `django.contrib.localflavor` ceased to work in Django 1.6.
localflavor
```
INSTALLED_APPS = ['localflavor', ...]
```
For translations of form field error messages, 'localflavor' must be included in `INSTALLED_APPS`. The old `django.contrib.localflavor` is deprecated and will raise warnings.

Quickstart

This example demonstrates creating a simple Django form using `USStateField` from `django-localflavor`. It includes minimal Django settings configuration to make the snippet runnable for demonstration purposes. Users would typically integrate this into an existing Django project's forms.py and views.py.

import os
from django import forms
from localflavor.us.forms import USStateField # Example: using a US-specific field
from django.conf import settings

# Minimal Django settings for standalone execution or in a Django project context
if not settings.configured:
    settings.configure(
        INSTALLED_APPS=[
            'localflavor', # Required for translations and some internal workings
        ],
        DEBUG=True,
        SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-testing-only'),
        # Add other necessary settings like TEMPLATES, DATABASES for a full Django app
    )

class MyUSForm(forms.Form):
    state = USStateField()
    city = forms.CharField(max_length=100)

# Example usage (e.g., in a Django view or a test)
def process_form_data():
    # Simulate form submission
    form_data = {'state': 'NY', 'city': 'New York'}
    form = MyUSForm(form_data)

    if form.is_valid():
        print(f"Form is valid. State: {form.cleaned_data['state']}, City: {form.cleaned_data['city']}")
        return form.cleaned_data
    else:
        print("Form is not valid. Errors:", form.errors)
        return None

if __name__ == '__main__':
    print("Processing valid form data:")
    process_form_data()

    print("\nProcessing invalid form data:")
    invalid_form_data = {'state': 'XX', 'city': 'Invalid City'}
    invalid_form = MyUSForm(invalid_form_data)
    if not invalid_form.is_valid():
        print("Form is not valid. Errors:", invalid_form.errors)

view raw JSON →