django-countries 7.6.1

安装

1. pip install django-countries

   为了更准确地排序翻译后的国家名称，请使用可选的 pyuca 包进行安装

   pip install django-countries[pyuca]

2. 将 django_countries 添加到 INSTALLED_APPS

CountryField

Django 模型中用于选择所有 ISO 3166-1 国家字段的字段。

CountryField 基于 Django 的 CharField，提供与官方 ISO 3166-1 国家列表相对应的选择（默认 max_length 为 2）。

考虑以下使用 CountryField 的模型

from django.db import models
from django_countries.fields import CountryField

class Person(models.Model):
    name = models.CharField(max_length=100)
    country = CountryField()

任何 Person 实例都将有一个 country 属性，您可以使用它来获取该人国家的详细信息

>>> person = Person(name="Chris", country="NZ")
>>> person.country
Country(code='NZ')
>>> person.country.name
'New Zealand'
>>> person.country.flag
'/static/flags/nz.gif'

此对象（例如示例中的 person.country）是一个 Country 实例，下面将对其进行描述。

使用 blank_label 设置在表单中显示的初始空白选项的标签

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

除了国家代码外，还可以使用全英文名称进行筛选，尽管数据库中只存储国家代码。使用查询集查找 contains、startswith、endswith、regex 或它们的非大小写版本进行筛选。使用 __name 或 __iname 进行精确/非精确匹配

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

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

from django_countries.widgets import CountrySelectWidget

class PersonForm(forms.ModelForm):
    class Meta:
        model = models.Person
        fields = ("name", "country")
        widgets = {"country": CountrySelectWidget()}

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

自定义表单

如果您想以自定义表单的形式使用国家，请使用模型字段的自定义表单字段以确保国家选择的可翻译字符串在渲染小部件之前保持懒加载

from django_countries.fields import CountryField

class CustomForm(forms.Form):
    country = CountryField().formfield()

对于非必填表单字段，请使用CountryField(blank=True)，并使用CountryField(blank_label="(Select country)")来自定义初始空白选项的标签。

如果您希望在下拉框后显示国旗图像，也可以使用CountrySelectWidget作为此字段的控件。

从Python获取国家

使用django_countries.countries对象实例作为ISO 3166-1国家代码和名称（按名称排序）的迭代器。

例如

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

模板标签

如果您将国家代码存储在不同于CountryField的地方，可以使用模板标签获取Country对象并访问其所有属性

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

如果您需要一个国家列表，也有一个简单的标签可供使用

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

自定义

from django.utils.translation import gettext_lazy as _

COUNTRIES_OVERRIDE = {
    "NZ": _("Middle Earth"),
    "AU": None,
    "US": {
        "names": [
            _("United States of America"),
            _("America"),
        ],
    },
}

COUNTRIES_ONLY = ["NZ", "AU"]

COUNTRIES_ONLY = [
    "US",
    "GB",
    ("NZ", _("Middle Earth")),
    ("AU", _("Desert")),
]

COUNTRIES_FLAG_URL = "flags/{code}.gif"

class Person(models.Model):
    name = models.CharField(max_length=100)
    country = CountryField(
        countries_flag_url="//flags.example.com/{code}.png")

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

setup(
    ...
    entry_points={
        "django_countries.Country": "phone = django_countries_phone.get_phone"
    },
    ...
)

Django Rest Framework

Django Countries附带了一个CountryField模型字段混入，使它与DRF序列化器兼容。使用以下混入与您的模型序列化器一起使用。

from django_countries.serializers import CountryFieldMixin

class CountrySerializer(CountryFieldMixin, serializers.ModelSerializer):

    class Meta:
        model = models.Person
        fields = ("name", "email", "country")

此混入处理标准和多选国家字段。

from django_countries.serializer_fields import CountryField

class CountrySerializer(serializers.Serializer):
    country = CountryField()

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

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

包括了一个Country图形对象类型，可以在生成架构时使用。

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

该对象类型具有以下可用的字段：

• name - 完整的国家名称

• code - ISO 3166-1的两个字符国家代码

• alpha3 - ISO 3166-1的三个字符国家代码

• numeric - ISO 3166-1的数字国家代码

• iocCode - 国际奥委会国家代码

7.6.1（2024年4月2日）

• 修复了在没有选择国家时引入的Django 5修复中的TypeError。

7.6（2024年3月27日）

• 用 importlib_metadata 替换已废弃的 pkg_resources.iter_entry_points。

• 支持Django 5.0。

7.5.1（2023年2月1日）

• 使 CountryField 查询集过滤器除了名称外还能与国家代码一起工作。

• 切换到 pyproject.toml 而不是 setup.py 以修复pip 23.0+的安装问题。

7.5（2022年12月12日）

• 将土耳其重命名为 Türkiye。

• 7.4版本中的变化引入了多选国家被排序并去重存储。这将成为默认行为，但现在可以通过 CountryField 的参数来覆盖。

• 改进了翻译回退处理，修复了可能导致奇怪翻译问题的线程竞争条件。感谢Jan Wróblewski和Antoine Fontaine在解决此问题上的帮助。这还解决了较老Python 3.6/3.7版本中的翻译问题。

• 添加Python 3.11，移除Python 3.6和Django 2.2支持。

7.4.2（2022年10月10日）

• 修复了当 USE_I18N = False 时出现的错误。

7.4.1（2022年10月7日）

• 修复了由于最后的共同国家名称修复导致的损坏的翻译。

7.4（2022年10月7日）

• 修复了传统中文翻译（需要是 locale/zh_Hant）。

• 更新洪都拉斯国旗。

• 将Django 4.0和4.1添加到测试矩阵中，移除3.0和3.1。

• 添加Django Rest Framework 3.13和3.14，移除3.11。

• 多选国家现在被排序并去除重复项存储。感谢flbraun和Jens Diemer！

• 修复了在非英语翻译中不尊重常用国家名称的问题（仅修复Python 3.8+）。

7.3.2（2022年3月4日）

• 修复了由于v7.3中始终使用国家名称进行字段比较而引入的减速问题。现在将不再匹配 filter(country="New Zealand")，而是添加了新的 __name 和 __iname 过滤器来实现这一点。

7.3.1（2022年3月1日）

• 为Python <3.9修复类型兼容性。

7.3（2022年2月28日）

• 使完整的英语国家名称在数据库查找中正常工作，例如，Person.objects.filter(country__icontains="zealand")。

7.2.1（2021年5月11日）

• 修复了拉丁翻译。

7.2（2021年5月10日）

• 允许字符字段与自定义国家代码一起工作，这些代码不是2个字符（例如，“GB-WLS”）。

• 修复了与 django-migrations-ignore-attrs 库的兼容性。

7.1（2021年3月17日）

• 允许通过新的 countries_str_attr 关键字参数自定义从 CountryField 返回的 Country 对象的 str_attr（感谢C. Quentin）。

• 将 pyuca 添加为额外依赖项，因此它可以像 pip install django-countries[pyuca] 一样安装。

• 添加Django 3.2支持。

7.0（2020年12月5日）

• 将 name_only 作为选项添加到Django Rest Framework序列化器字段（感谢Miguel Marques）。

• 添加Python类型。

• 添加Python 3.9、Django 3.1和Django Rest Framework 3.12支持。

• 移除Python 3.5支持。

• 改进IOC代码功能，允许在COUNTRIES_OVERRIDE中使用复杂字典格式覆盖它们。

6.1.3（2020年8月18日）

• 更新毛里塔尼亚的国旗。

• 添加科索沃（以其临时代码XK）的国旗。

6.1.2（2020年3月26日）

• 修复Python 3.5语法错误（目前还没有f-strings……）。

6.1.1（2020年3月26日）

• 更改ISO国家导入，使“福克兰群岛[马尔维纳斯]”=>“福克兰群岛（马尔维纳斯）”。

6.1（2020年3月20日）

• 为django Country对象添加GraphQL对象类型。

6.0（2020年2月28日）

• 使DRF CountryField尊重blank=False。这是一个不兼容的向后兼容更改，因为现在空白输入将返回验证错误（除非显式将blank设置为True）。

• 修复使用复杂字典格式和单个名称时COUNTRIES_OVERRIDE的问题。

• 将bandit添加到测试套件中进行基本安全分析。

• 停止支持Python 2.7和Python 3.4。

• 将Rest Framework 3.10和3.11添加到测试矩阵中，删除3.8。

• 修复使用PyUCA时的内存泄漏。感谢Meiyer（又名interDist）！

5.5（2019年9月11日）

• Django 3.0兼容性。

• 用于扩展Country对象的插件系统。

5.4（2019年8月11日）

• 将马其顿重命名为北马其顿。

• 修复了makemigrations的一个错误。

• 引入了新翻译，这些翻译在先前版本中已提供但缺失。

• 修复了简体中文翻译（需要是locale/zh_Hans）。

• 为COUNTRIES_ONLY和COUNTRIES_OVERRIDE引入可选的复杂格式，允许国家有多个名称、自定义三位代码和自定义数字国家代码。

5.3.3（2019年2月16日）

• 为Django Rest Framework 3.9添加测试覆盖率。

5.3.2（2018年8月27日）

• 测试Django 2.1和Django Rest Framework 3.8。

5.3.1（2018年6月12日）

• 修复了dumpdata和loaddata的CountryField(multiple=True)错误。

5.3（2018年4月20日）

• 迭代Countries对象现在返回命名元组。这使得使用{% get_countries %}或在代码的其他部分使用国家列表时更加方便。

5.2（2018年3月9日）

• 确保CountrySelectWidget对Django 2.1兼容。

• 修复了在Django 1.8和某些查询集查找类型（如__in）时引入的回归。

5.1.1（2018年1月31日）

• 修复了5.1中包含但未编译的一些翻译。

5.1（2018年1月30日）

• 测试现在还覆盖Django Rest Framework 3.7和Django 2.0。

• 允许使用（有效的）alpha-3或数字代码创建国家字段。

• 修复了带有空白默认值的迁移错误（感谢Jens Diemer）。

• 添加了{% get_countries %}模板标签（感谢Matija Čvrk）。

5.0（2017年10月10日）

• 不再允许同时使用multiple=True和null=True。这会导致字段保存时出现问题，而且实际上不应该使用null，因为国家字段是CharField的子类。

4.6（2017年6月16日）

• 添加了Django Rest Framework序列化器的CountryFieldMixin，它会自动选择合适的字段类型用于CountryField（单选和多选）。

• Django Rest Framework字段的验证（感谢Simon Meers）。

• 允许不区分大小写的.by_name()匹配（再次感谢，Simon）。

• 确保多选CountryField.max_length足够容纳所有国家。

• 修复了国家数据的低效序列化（感谢Craig de Stigter的报告和测试）。

• 在处理多选CountryField时，停止添加空白选项。

• 测试现在覆盖了多个Django Rest Framework版本（回溯到3.3）。

4.5（2017年4月18日）

• 将rest framework字段改为基于ChoiceField。

• 允许rest framework字段通过完整国家名称反序列化（目前特指英文名称）。

4.4（2017年4月6日）

• 修复了Django 1.11中某些模型上断开的CountryField。感谢aktiur提供的测试用例。

• 更新测试以涵盖Django 1.11

4.3（2017年3月29日）

• 以更优雅的方式处理“Czechia”的翻译（在新翻译可用之前回退到“Czech Republic”）。

• 修复了Django 1.9+中由于在django-countries自定义管理过滤器中使用非懒加载ugettext导致的导入错误。

• 回归100%测试覆盖率。

4.2（2017年3月10日）

• 添加精灵国旗文件（以及Country.flag_css属性），以帮助最小化HTTP请求。

4.1（2017年2月22日）

• 改进了在ModelAdmin中筛选国家字段时的默认Django管理过滤器。

• 修复了支持Django 1.11的设置

• 修复了使用具有延迟国家字段的模型实例时的问题。

• 允许CountryField一次处理多个国家！

• 允许CountryField在延迟的情况下仍然工作。

• 修复了自定义国家列表的字段。感谢pilmie！

4.0（2016年8月16日）

Django支持的版本现在是1.8+

• 删除遗留代码

• 修复测试，100%覆盖率

• IOS / OSX Unicode国旗功能

• 修复Django 1.9+上的小部件选择问题

• 添加COUNTRIES_FIRST_SORT设置。感谢Edraak！

3.4（2015年10月22日）

• 扩展测试套件以涵盖Django 1.8

• 修复了CountrySelectWidget中的XSS转义问题

• 常用名称更改：修复Moldova的错别字，添加英国

• 添加{% get_country %}模板标签。

• 新的CountryField Django Rest Framework序列化器字段。

3.3（2015年3月30日）

• 为Countries类添加可以覆盖默认设置的属性。

• CountriesField现在可以传递一个自定义的国家子类来使用，这结合了之前的变化，允许不同字段有不同的国家选择。

• COUNTRIES_ONLY现在也可以接受列表中的国家代码（而不仅仅是两个元组），从完整国家列表中查找可翻译的国家名称。

• 修复了黑山国旗的大小（高度为12px而不是标准的11px）。

• 修复了玻利维亚、冈比亚、梵蒂冈、伊朗、密克罗尼西亚和委内瑞拉过时的ISO国家名称格式。

3.2（2015年2月24日）

• 修复了新创建的Countries对象初始迭代失败的问题。

• 修复了小部件的国旗URL（并确保小部件安全地HTML编码）。

• 添加了countries.by_name(country, language='en')方法，允许通过完整国家名称查找国家代码。感谢Josh Schneier。

3.1（2015年1月15日）

• 开始变更日志 :)

• 添加一个COUNTRIES_FIRST设置（以及一些其他相关设置），允许特定国家显示在整个字母数字列表之前。

• 将 blank_label 参数添加到 CountryField 中，以便在 select 小部件中显示的初始空白选项中自定义标签。

3.0（2014年10月22日）

Django 支持的版本现在是 1.4（LTS）和 1.6+。

• 添加 COUNTRIES_ONLY 设置以限制特定国家的列表。

• 优化国家名称翻译，以避免过多翻译调用，这曾导致明显的性能影响。

• PyUCA 集成，允许跨所有区域设置进行更准确的排序。如果没有安装 PyUCA，还有一个更好的排序方法。

• 更好的测试（现在测试覆盖率达到了100%）。

• 添加 COUNTRIES_FLAG_URL 设置以允许自定义标志 URL。

• 支持 IOC 和数字国家代码，允许更灵活地查找国家和特定代码类型。

• 字段描述符现在在找不到匹配的国家时返回 None（在 v3.0.1 中恢复）

2.1（2014年3月24日）

• 添加 IOC（3字母）国家代码。

• 修复了加载 fixtures 时的错误。

2.0（2014年2月18日）

这是更改日志的第一条记录。上一个版本是 1.5，于 2012年11月19日发布。

• 优化标志图像，添加了原始来源中缺失的标志。

• 改进设置和国家列表的存储。

• 为字段提供新的国家列表格式。

• 更好的测试。

• 将 COUNTRIES_FLAG_STATIC 设置更改为 COUNTRIES_FLAG_URL。