"""Foreign country mappings for ISTAT XML export.

Keys are ISO-2 country codes as stored by guest check-in. Values are the
client-required ISTAT XML/geonomenclature country codes, stored as strings so
leading zeros are preserved.

Fallback mappings
-----------------
``FALLBACK_COUNTRY_MAPPING`` handles ISO-2 codes that are valid but absent from
the primary ``COUNTRY_MAPPINGS`` table — typically territories, special
administrative regions, or codes introduced after the ISTAT table was last
updated.

Each entry maps an unsupported ISO-2 code to a *canonical* ISO-2 code that IS
present in ``COUNTRY_MAPPINGS``.  Resolution is then performed against the
canonical code, so the ISTAT output is deterministic and auditable.

Rules:
- Do NOT add codes here that already exist in ``COUNTRY_MAPPINGS``.
- The target (value) MUST exist in ``COUNTRY_MAPPINGS``.
- Each entry must have a comment explaining the mapping rationale.
"""

from __future__ import annotations

from typing import Final


# ---------------------------------------------------------------------------
# Fallback: unsupported ISO-2 → canonical ISO-2 present in COUNTRY_MAPPINGS
# ---------------------------------------------------------------------------
FALLBACK_COUNTRY_MAPPING: Final[dict[str, str]] = {
    "AX": "FI",  # Åland Islands → Finland
    "XK": "RS",  # Kosovo → Serbia (ISTAT baseline)
    "BQ": "AN",  # Bonaire → Netherlands Antilles (2010 split)
    "CW": "AN",  # Curaçao → Netherlands Antilles
    "SX": "AN",  # Sint Maarten → Netherlands Antilles
    "SS": "SD",  # South Sudan → Sudan (2011 independence)
}

COUNTRY_MAPPINGS: Final[dict[str, dict[str, str]]] = {
    "AD": {"istat_code": "043", "name": "Andorra"},
    "AE": {"istat_code": "647", "name": "United Arab Emirates"},
    "AF": {"istat_code": "660", "name": "Afghanistan"},
    "AG": {"istat_code": "459", "name": "Antigua and Barbuda"},
    "AI": {"istat_code": "446", "name": "Anguilla"},
    "AL": {"istat_code": "070", "name": "Albania"},
    "AM": {"istat_code": "077", "name": "Armenia"},
    "AN": {"istat_code": "478", "name": "Netherlands Antilles"},
    "AO": {"istat_code": "330", "name": "Angola"},
    "AQ": {"istat_code": "891", "name": "Antarctica"},
    "AR": {"istat_code": "528", "name": "Argentina"},
    "AS": {"istat_code": "830", "name": "American Samoa"},
    "AT": {"istat_code": "038", "name": "Austria"},
    "AU": {"istat_code": "800", "name": "Australia"},
    "AW": {"istat_code": "474", "name": "Aruba"},
    "AZ": {"istat_code": "078", "name": "Azerbaijan"},
    "BA": {"istat_code": "093", "name": "Bosnia and Herzegovina"},
    "BB": {"istat_code": "469", "name": "Barbados"},
    "BD": {"istat_code": "666", "name": "Bangladesh"},
    "BE": {"istat_code": "017", "name": "Belgium"},
    "BF": {"istat_code": "236", "name": "Burkina Faso"},
    "BG": {"istat_code": "068", "name": "Bulgaria"},
    "BH": {"istat_code": "640", "name": "Bahrain"},
    "BI": {"istat_code": "328", "name": "Burundi"},
    "BJ": {"istat_code": "284", "name": "Benin"},
    "BM": {"istat_code": "413", "name": "Bermuda"},
    "BN": {"istat_code": "703", "name": "Brunei"},
    "BO": {"istat_code": "516", "name": "Bolivia"},
    "BR": {"istat_code": "508", "name": "Brazil"},
    "BS": {"istat_code": "453", "name": "Bahamas"},
    "BT": {"istat_code": "675", "name": "Bhutan"},
    "BV": {"istat_code": "892", "name": "Bouvet Island"},
    "BW": {"istat_code": "391", "name": "Botswana"},
    "BY": {"istat_code": "073", "name": "Belarus"},
    "BZ": {"istat_code": "421", "name": "Belize"},
    "CA": {"istat_code": "404", "name": "Canada"},
    "CC": {"istat_code": "833", "name": "Cocos Islands"},
    "CD": {"istat_code": "322", "name": "Democratic Republic of the Congo"},
    "CF": {"istat_code": "306", "name": "Central African Republic"},
    "CG": {"istat_code": "318", "name": "Congo"},
    "CH": {"istat_code": "039", "name": "Switzerland"},
    "CI": {"istat_code": "272", "name": "Cote d'Ivoire"},
    "CK": {"istat_code": "837", "name": "Cook Islands"},
    "CL": {"istat_code": "512", "name": "Chile"},
    "CM": {"istat_code": "302", "name": "Cameroon"},
    "CN": {"istat_code": "720", "name": "China"},
    "CO": {"istat_code": "480", "name": "Colombia"},
    "CR": {"istat_code": "436", "name": "Costa Rica"},
    "CU": {"istat_code": "448", "name": "Cuba"},
    "CV": {"istat_code": "247", "name": "Cape Verde"},
    "CX": {"istat_code": "834", "name": "Christmas Island"},
    "CY": {"istat_code": "600", "name": "Cyprus"},
    "CZ": {"istat_code": "061", "name": "Czech Republic"},
    "DE": {"istat_code": "004", "name": "Germany"},
    "DJ": {"istat_code": "338", "name": "Djibouti"},
    "DK": {"istat_code": "008", "name": "Denmark"},
    "DM": {"istat_code": "460", "name": "Dominica"},
    "DO": {"istat_code": "456", "name": "Dominican Republic"},
    "DZ": {"istat_code": "208", "name": "Algeria"},
    "EC": {"istat_code": "500", "name": "Ecuador"},
    "EE": {"istat_code": "053", "name": "Estonia"},
    "EG": {"istat_code": "220", "name": "Egypt"},
    "ER": {"istat_code": "336", "name": "Eritrea"},
    "ES": {"istat_code": "011", "name": "Spain"},
    "ET": {"istat_code": "334", "name": "Ethiopia"},
    "FI": {"istat_code": "032", "name": "Finland"},
    "FJ": {"istat_code": "815", "name": "Fiji"},
    "FK": {"istat_code": "529", "name": "Falkland Islands"},
    "FM": {"istat_code": "823", "name": "Micronesia"},
    "FO": {"istat_code": "041", "name": "Faroe Islands"},
    "FR": {"istat_code": "001", "name": "France"},
    "GA": {"istat_code": "314", "name": "Gabon"},
    "GB": {"istat_code": "006", "name": "United Kingdom"},
    "GD": {"istat_code": "473", "name": "Grenada"},
    "GE": {"istat_code": "076", "name": "Georgia"},
    "GF": {"istat_code": "001", "name": "French Guiana"},
    "GH": {"istat_code": "276", "name": "Ghana"},
    "GI": {"istat_code": "044", "name": "Gibraltar"},
    "GL": {"istat_code": "406", "name": "Greenland"},
    "GM": {"istat_code": "252", "name": "Gambia"},
    "GN": {"istat_code": "260", "name": "Guinea"},
    "GP": {"istat_code": "001", "name": "Guadeloupe"},
    "GQ": {"istat_code": "310", "name": "Equatorial Guinea"},
    "GR": {"istat_code": "009", "name": "Greece"},
    "GS": {"istat_code": "893", "name": "South Georgia and the South Sandwich Islands"},
    "GT": {"istat_code": "416", "name": "Guatemala"},
    "GU": {"istat_code": "831", "name": "Guam"},
    "GW": {"istat_code": "257", "name": "Guinea-Bissau"},
    "GY": {"istat_code": "488", "name": "Guyana"},
    "HK": {"istat_code": "740", "name": "Hong Kong"},
    "HM": {"istat_code": "835", "name": "Heard Island and McDonald Islands"},
    "HN": {"istat_code": "424", "name": "Honduras"},
    "HR": {"istat_code": "092", "name": "Croatia"},
    "HT": {"istat_code": "452", "name": "Haiti"},
    "HU": {"istat_code": "064", "name": "Hungary"},
    "ID": {"istat_code": "700", "name": "Indonesia"},
    "IE": {"istat_code": "007", "name": "Ireland"},
    "IL": {"istat_code": "624", "name": "Israel"},
    "IN": {"istat_code": "664", "name": "India"},
    "IO": {"istat_code": "357", "name": "British Indian Ocean Territory"},
    "IQ": {"istat_code": "612", "name": "Iraq"},
    "IR": {"istat_code": "616", "name": "Iran"},
    "IS": {"istat_code": "024", "name": "Iceland"},
    "IT": {"istat_code": "005", "name": "Italy"},
    "JM": {"istat_code": "464", "name": "Jamaica"},
    "JO": {"istat_code": "628", "name": "Jordan"},
    "JP": {"istat_code": "732", "name": "Japan"},
    "KE": {"istat_code": "346", "name": "Kenya"},
    "KG": {"istat_code": "083", "name": "Kyrgyzstan"},
    "KH": {"istat_code": "696", "name": "Cambodia"},
    "KI": {"istat_code": "812", "name": "Kiribati"},
    "KM": {"istat_code": "375", "name": "Comoros"},
    "KN": {"istat_code": "449", "name": "Saint Kitts and Nevis"},
    "KP": {"istat_code": "724", "name": "North Korea"},
    "KR": {"istat_code": "728", "name": "South Korea"},
    "KW": {"istat_code": "636", "name": "Kuwait"},
    "KY": {"istat_code": "463", "name": "Cayman Islands"},
    "KZ": {"istat_code": "079", "name": "Kazakhstan"},
    "LA": {"istat_code": "684", "name": "Laos"},
    "LB": {"istat_code": "604", "name": "Lebanon"},
    "LC": {"istat_code": "465", "name": "Saint Lucia"},
    "LI": {"istat_code": "037", "name": "Liechtenstein"},
    "LK": {"istat_code": "669", "name": "Sri Lanka"},
    "LR": {"istat_code": "268", "name": "Liberia"},
    "LS": {"istat_code": "395", "name": "Lesotho"},
    "LT": {"istat_code": "055", "name": "Lithuania"},
    "LU": {"istat_code": "018", "name": "Luxembourg"},
    "LV": {"istat_code": "054", "name": "Latvia"},
    "LY": {"istat_code": "216", "name": "Libya"},
    "MA": {"istat_code": "204", "name": "Morocco"},
    "MC": {"istat_code": "001", "name": "Monaco"},
    "MD": {"istat_code": "074", "name": "Moldova"},
    "ME": {"istat_code": "097", "name": "Montenegro"},
    "MG": {"istat_code": "370", "name": "Madagascar"},
    "MH": {"istat_code": "824", "name": "Marshall Islands"},
    "MK": {"istat_code": "096", "name": "North Macedonia"},
    "ML": {"istat_code": "232", "name": "Mali"},
    "MM": {"istat_code": "676", "name": "Myanmar"},
    "MN": {"istat_code": "716", "name": "Mongolia"},
    "MO": {"istat_code": "743", "name": "Macao"},
    "MP": {"istat_code": "820", "name": "Northern Mariana Islands"},
    "MQ": {"istat_code": "001", "name": "Martinique"},
    "MR": {"istat_code": "228", "name": "Mauritania"},
    "MS": {"istat_code": "470", "name": "Montserrat"},
    "MT": {"istat_code": "046", "name": "Malta"},
    "MU": {"istat_code": "373", "name": "Mauritius"},
    "MV": {"istat_code": "667", "name": "Maldives"},
    "MW": {"istat_code": "386", "name": "Malawi"},
    "MX": {"istat_code": "412", "name": "Mexico"},
    "MY": {"istat_code": "701", "name": "Malaysia"},
    "MZ": {"istat_code": "366", "name": "Mozambique"},
    "NA": {"istat_code": "389", "name": "Namibia"},
    "NC": {"istat_code": "809", "name": "New Caledonia"},
    "NE": {"istat_code": "240", "name": "Niger"},
    "NF": {"istat_code": "836", "name": "Norfolk Island"},
    "NG": {"istat_code": "288", "name": "Nigeria"},
    "NI": {"istat_code": "432", "name": "Nicaragua"},
    "NL": {"istat_code": "003", "name": "Netherlands"},
    "NO": {"istat_code": "028", "name": "Norway"},
    "NP": {"istat_code": "672", "name": "Nepal"},
    "NR": {"istat_code": "803", "name": "Nauru"},
    "NU": {"istat_code": "838", "name": "Niue"},
    "NZ": {"istat_code": "804", "name": "New Zealand"},
    "OM": {"istat_code": "649", "name": "Oman"},
    "PA": {"istat_code": "442", "name": "Panama"},
    "PE": {"istat_code": "504", "name": "Peru"},
    "PF": {"istat_code": "822", "name": "French Polynesia"},
    "PG": {"istat_code": "801", "name": "Papua New Guinea"},
    "PH": {"istat_code": "708", "name": "Philippines"},
    "PK": {"istat_code": "662", "name": "Pakistan"},
    "PL": {"istat_code": "060", "name": "Poland"},
    "PM": {"istat_code": "408", "name": "Saint Pierre and Miquelon"},
    "PN": {"istat_code": "813", "name": "Pitcairn"},
    "PR": {"istat_code": "400", "name": "Puerto Rico"},
    "PS": {"istat_code": "625", "name": "Palestinian Territory"},
    "PT": {"istat_code": "010", "name": "Portugal"},
    "PW": {"istat_code": "825", "name": "Palau"},
    "PY": {"istat_code": "520", "name": "Paraguay"},
    "QA": {"istat_code": "644", "name": "Qatar"},
    "RE": {"istat_code": "001", "name": "Reunion"},
    "RO": {"istat_code": "066", "name": "Romania"},
    "RS": {"istat_code": "098", "name": "Serbia"},
    "RU": {"istat_code": "075", "name": "Russia"},
    "RW": {"istat_code": "324", "name": "Rwanda"},
    "SA": {"istat_code": "632", "name": "Saudi Arabia"},
    "SB": {"istat_code": "806", "name": "Solomon Islands"},
    "SC": {"istat_code": "355", "name": "Seychelles"},
    "SD": {"istat_code": "224", "name": "Sudan"},
    "SE": {"istat_code": "030", "name": "Sweden"},
    "SG": {"istat_code": "706", "name": "Singapore"},
    "SH": {"istat_code": "329", "name": "Saint Helena"},
    "SI": {"istat_code": "091", "name": "Slovenia"},
    "SK": {"istat_code": "063", "name": "Slovakia"},
    "SL": {"istat_code": "264", "name": "Sierra Leone"},
    "SM": {"istat_code": "047", "name": "San Marino"},
    "SN": {"istat_code": "248", "name": "Senegal"},
    "SO": {"istat_code": "342", "name": "Somalia"},
    "SR": {"istat_code": "492", "name": "Suriname"},
    "ST": {"istat_code": "311", "name": "Sao Tome and Principe"},
    "SV": {"istat_code": "428", "name": "El Salvador"},
    "SY": {"istat_code": "608", "name": "Syria"},
    "SZ": {"istat_code": "393", "name": "Eswatini"},
    "TC": {"istat_code": "454", "name": "Turks and Caicos Islands"},
    "TD": {"istat_code": "244", "name": "Chad"},
    "TF": {"istat_code": "894", "name": "French Southern Territories"},
    "TG": {"istat_code": "280", "name": "Togo"},
    "TH": {"istat_code": "680", "name": "Thailand"},
    "TJ": {"istat_code": "082", "name": "Tajikistan"},
    "TK": {"istat_code": "839", "name": "Tokelau"},
    "TL": {"istat_code": "626", "name": "Timor-Leste"},
    "TM": {"istat_code": "080", "name": "Turkmenistan"},
    "TN": {"istat_code": "212", "name": "Tunisia"},
    "TO": {"istat_code": "817", "name": "Tonga"},
    "TP": {"istat_code": "626", "name": "East Timor"},
    "TR": {"istat_code": "052", "name": "Turkey"},
    "TT": {"istat_code": "472", "name": "Trinidad and Tobago"},
    "TV": {"istat_code": "807", "name": "Tuvalu"},
    "TW": {"istat_code": "736", "name": "Taiwan"},
    "TZ": {"istat_code": "352", "name": "Tanzania"},
    "UA": {"istat_code": "072", "name": "Ukraine"},
    "UG": {"istat_code": "350", "name": "Uganda"},
    "UM": {"istat_code": "832", "name": "United States Minor Outlying Islands"},
    "US": {"istat_code": "400", "name": "United States"},
    "UY": {"istat_code": "524", "name": "Uruguay"},
    "UZ": {"istat_code": "081", "name": "Uzbekistan"},
    "VA": {"istat_code": "045", "name": "Vatican City"},
    "VC": {"istat_code": "467", "name": "Saint Vincent and the Grenadines"},
    "VE": {"istat_code": "484", "name": "Venezuela"},
    "VG": {"istat_code": "468", "name": "British Virgin Islands"},
    "VI": {"istat_code": "457", "name": "United States Virgin Islands"},
    "VN": {"istat_code": "690", "name": "Vietnam"},
    "VU": {"istat_code": "816", "name": "Vanuatu"},
    "WF": {"istat_code": "811", "name": "Wallis and Futuna"},
    "WS": {"istat_code": "819", "name": "Samoa"},
    "XC": {"istat_code": "021", "name": "Ceuta"},
    "XL": {"istat_code": "023", "name": "Melilla"},
    "YE": {"istat_code": "653", "name": "Yemen"},
    "YT": {"istat_code": "377", "name": "Mayotte"},
    "YU": {"istat_code": "094", "name": "Yugoslavia"},
    "ZA": {"istat_code": "388", "name": "South Africa"},
    "ZM": {"istat_code": "378", "name": "Zambia"},
    "ZW": {"istat_code": "382", "name": "Zimbabwe"},
}