"""
These descriptors are generic classes that pertain to various aspects of country data. The class names match the
section names of the INI file used to store the data.
"""
# Imports
from django.utils.safestring import mark_safe
# Exports
__all__ = (
"Addressing",
"Codes",
"Country",
"Geography",
"Wiki",
)
# Classes
[docs]class Addressing(object):
"""A descriptor for country address specifications."""
[docs] def __init__(self, code, **kwargs):
"""Initialize and address specification.
:param code: The two-character ISO-3166 country code.
:type code: str
:param city_field_name: The name of the form or database field.
:param city_label: The name equivalent of cities for the country. For example, *locality*.
:param city_required: Indicates that the city field is typically required for an address to be valid.
:param fields: A dictionary of field names and field widgets or field clasess to use for forms.
:param postal_code_field_name: The name of the form or database field.
:param postal_code_label: The name equivalent of postal code for the country. For example, *ZIP code*.
:param postal_code_required: Indicates that the postal code field is required for an address to be valid.
:param regions: A list of regions that may be used as choices. See ``has_regions``.
:param state_field_name: The name of the form or database field.
:param state_label: The name equivalent of states for the country. For example, *province*.
:param state_required: Indicates that the state field is typically required for an address to be valid.
param states: A list of states that may be used as choices. See ``has_states``.
"""
self.city_field_name = kwargs.pop("city_field_name", None)
self.city_label = kwargs.pop("city_label", None)
self.city_required = kwargs.pop("city_required", False)
self.code = code
self.fields = kwargs.pop("fields", dict())
self.postal_code_field_name = kwargs.pop("postal_code_field_name", None)
self.postal_code_label = kwargs.pop("postal_code_label", None)
self.postal_code_required = kwargs.pop("postal_code_required", False)
self.regions = kwargs.pop("regions", None)
self.state_field_name = kwargs.pop("state_field_name", None)
self.state_label = kwargs.pop("state_label", None)
self.state_required = kwargs.pop("state_required", False)
self.states = kwargs.pop("states", None)
@property
def has_regions(self):
"""Indicates the country has administrative divisions apart from states.
:rtype: bool
"""
return len(self.regions) > 0
@property
def has_states(self):
"""Indicates the country has administrative or legal divisions such as states, provinces, etc.
:rtype: bool
"""
return len(self.states) > 0
[docs]class Codes(object):
"""A collection of country codes."""
[docs] def __init__(self, fips=None, iso2=None, iso3=None, ison=None, phone=None, stanag=None, tld=None):
"""Keyword arguments are the various possible codes.
:param fips: The FIPs code.
:param iso2: The two-character ISO-3166 code.
:param iso3: The three-character ISO-3166 code.
:param ison: The ISON code.
:param phone: The country code for phone calls.
:param stanag: The STANAG code.
:param tld: The top-level domain code.
"""
self.fips = fips
self.iso2 = iso2
self.iso3 = iso3
self.ison = ison
self.phone = phone
self.stanag = stanag
self.tld = tld
[docs]class Country(object):
"""A country descriptor. This descriptor incorporates various attributes and sub-objects to represent a country.
Example:
.. code-block:: python
from superdjango.contrib.i18n.countries import country_factory
country = country_factory("UY")
print(country.name)
**Attributes**
Some, but rarely all, of the following properties are available:
- ``capital``: The capital city of the country.
- ``comment``: Any comment regarding the country data.
- ``code``: The two-character ISO 3166 code.
- ``name``: The country name.
**Objects**
More complex objects are used to represent additional data.
- ``address`` is an instance of :py:class:`Address`.
- ``codes`` is an instance of :py:class:`Codes`.
- ``currency`` is an instance of :py:class:`Currency`.
- ``languages`` a list of :py:class:`Language`` instances.
- ``wiki`` is an instance of :py:class:`Wiki`.
**Flags**
The ``flag`` and ``icon`` properties may be used to display the country's flag. For convenience, CSS and images have
been bundled from: https://github.com/lipis/flag-icon-css
"""
[docs] def __init__(self, code, **kwargs):
"""Initialize a country.
:param code: The two-character ISO-3166 code of the country.
:type code: str
"""
self.addressing = kwargs.pop("addressing", None)
self.capital = kwargs.pop("capital", None)
self.code = code
self.codes = kwargs.pop("codes", Codes(iso2=code))
self.comment = kwargs.pop("comment", None)
self.currency = kwargs.pop("currency", None)
self.geography = kwargs.pop("geography", None)
self.languages = kwargs.pop("languages", None)
self.name = kwargs.pop("name", None)
self.regions = kwargs.pop("regions", None)
self.states = kwargs.pop("states", None)
self.wiki = kwargs.pop("wiki", None)
def __repr__(self):
return "<%s %s:%s>" % (self.__class__.__name__, self.code, self.name)
def __str__(self):
return self.name
@property
def flag(self):
"""Get the URL for the country's flag image.
:rtype: str
This is intended for use with the static template tag:
.. code-block:: python
{% static country.flag %}
"""
return "i18n/flags/images/4x3/%s.svg" % self.code.lower()
@property
def icon(self):
"""Get the flag as an HTML icon.
:rtype: str
.. note::
This requires that you include ``i18n/flags/css/flag-icon.css`` (or ``flag-icon.min.css``) in your template.
"""
return mark_safe('<span class="flag-icon flag-icon-%s"></span>' % self.code.lower())
[docs]class Geography(object):
"""A descriptor for regions, sub-regions, or intermediate regions into which countries are organized.
.. tip::
Do not confuse the terminology with regions in address specification.
"""
[docs] def __init__(self, code, name):
self.code = code
self.intermediate = None
self.name = name
self.sub = None
[docs]class Wiki(object):
"""A descriptor for country Wiki URLs.
**Attributes**
A wiki instance may include 2 properties; ``capital`` is URL of the country's capital, while ``country`` is the URL
of the country page.
"""
[docs] def __init__(self, **kwargs):
"""Initialize a Wikipedia descriptor.
:param capital: The capital URL of the country.
:type capital: str
:param country: The country URL.
:type country: str
"""
self.capital = kwargs.pop("capital", None)
self.country = kwargs.pop("country", None)