Python reference¶

def countrycode(
    sourcevar: Any,
    origin: str,
    destination: str | Sequence[str],
    custom_dict: Any = None,
    *,
    warn: bool = True,
    nomatch: Any = _DEFAULT_NOMATCH,
    custom_match: Mapping[Any, Any] | None = None,
    origin_regex: bool | None = None,
) -> Any:
    """Convert country codes or names from one format to another.

    Converts long country names into coding schemes, translates between
    schemes, standardizes country names, and identifies continents or regions.
    The built-in conversion dictionary supports ISO, Correlates of War,
    Gleditsch-Ward, World Bank, Unicode flag, and many other fields.

    Multiple destinations are tried from left to right. Each destination fills
    values not covered by an earlier one. Country-name origins use regular
    expressions; other built-in origins use case-insensitive exact matching.

    Args:
        sourcevar: Country codes or names to convert. Accepts a scalar, list,
            tuple, Pandas Series, Polars Series, or another iterable.
        origin: Name of the source coding scheme, such as ``"iso3c"`` or
            ``"country.name"``.
        destination: Destination coding scheme, or a sequence of schemes to
            try in order, such as ``["cowc", "iso3c"]``.
        custom_dict: Optional replacement dictionary. Accepts a mapping of
            column names to equal-length sequences, a Pandas or Polars
            DataFrame, or a path to a ``.csv`` or ``.csv.gz`` file.
        warn: Emit warnings listing unmatched or ambiguous input values.
        nomatch: Replacement for unmatched values. By default they become
            ``None``. Pass ``None`` to preserve the original inputs, a scalar
            to use one replacement, or a sequence matching ``sourcevar``.
        custom_match: Mapping of input values to destination values. These
            overrides supersede normal or ambiguous matches.
        origin_regex: Whether the origin column contains regular expressions.
            The default selects regex matching for built-in country-name
            origins and exact matching otherwise.

    Returns:
        Converted values. A scalar input returns a scalar; lists and tuples
        retain their container kind; Pandas and Polars Series retain their
        respective type and metadata where applicable.

    Raises:
        TypeError: If ``origin``, ``destination``, or ``sourcevar`` has an
            unsupported shape or type.
        ValueError: If a code field is invalid, a numeric origin receives
            non-numeric input, the custom dictionary is malformed, or
            ``nomatch`` has an incompatible length.
        FileNotFoundError: If a custom dictionary path does not exist.
        NotImplementedError: If a custom dictionary type or file format is
            unsupported.

    Examples:
        Convert ISO codes to Correlates of War numeric codes:

        >>> countrycode(["USA", "DZA"], "iso3c", "cown")
        [2, 615]

        Convert an English country name to ISO:

        >>> countrycode("Albania", "country.name", "iso3c")
        'ALB'

        Try a historical code first, then fall back to ISO:

        >>> countrycode("Serbia", "country.name", ["cowc", "iso3c"], warn=False)
        'SRB'

    Note:
        Country-year data require special care because some political units,
        including Vietnam and Serbia, change codes over time. For panel data,
        prefer :func:`countrycode.datasets.load_codelist_panel` and merge on
        the appropriate year instead of relying on the cross-sectional
        dictionary.
    """
    if not isinstance(origin, str):
        raise TypeError("origin must be a string.")
    destinations = [destination] if isinstance(destination, str) else list(destination)
    if not destinations or not all(isinstance(value, str) for value in destinations):
        raise TypeError(
            "destination must be a string or non-empty sequence of strings."
        )

    using_default = custom_dict is None
    if using_default:
        if origin == "country.name":
            origin = "country.name.en.regex"
        elif origin in _NAME_ALIASES:
            origin = f"{origin}.regex"
        destinations = [
            "country.name.en" if value == "country.name" else value
            for value in destinations
        ]
        if origin not in _VALID_DEFAULT_ORIGINS:
            raise ValueError(
                "origin must be one of: " + ", ".join(sorted(_VALID_DEFAULT_ORIGINS))
            )

    dictionary = (
        _BUILTIN_CODELIST
        if using_default
        else _prepare_codelist(custom_dict, origin, destinations)
    )
    if origin_regex is None:
        use_regex = using_default and origin in _REGEX_ORIGINS
    else:
        use_regex = origin_regex

    if not use_regex:
        seen = set()
        duplicates = set()
        for value in dictionary[origin]:
            if _is_missing(value):
                continue
            normalized = (
                value.casefold()
                if using_default
                and isinstance(value, str)
                and "country" not in origin
                and origin != "unicode.symbol"
                else value
            )
            if normalized in seen:
                duplicates.add(value)
            seen.add(normalized)
        if duplicates:
            raise ValueError(
                "Countrycode cannot accept dictionaries with duplicated origin "
                f"codes: {sorted(map(str, duplicates))}"
            )

    source, input_type = _normalize_input(sourcevar)
    if not use_regex:
        dictionary_origin = [
            value for value in dictionary[origin] if not _is_missing(value)
        ]
        if (
            dictionary_origin
            and all(
                isinstance(value, (int, float)) and not isinstance(value, bool)
                for value in dictionary_origin
            )
            and any(isinstance(value, str) for value in source)
        ):
            raise ValueError(
                f"To convert a '{origin}' code, sourcevar must be numeric."
            )

    result = [None] * len(source)
    all_ambiguous: dict[int, list[Any]] = {}
    if use_regex:
        if using_default:
            patterns = _DEFAULT_REGEX_PATTERNS.get(origin)
            if patterns is None:
                patterns = [
                    (re.compile(str(pattern), re.IGNORECASE), row)
                    for row, pattern in enumerate(dictionary[origin])
                    if not _is_missing(pattern)
                ]
                _DEFAULT_REGEX_PATTERNS[origin] = patterns
        else:
            patterns = None
        regex_matches = _regex_match_rows(source, origin, dictionary, patterns)
    else:
        ignore_case = (
            using_default and "country" not in origin and origin != "unicode.symbol"
        )
        cache_key = (origin, ignore_case)
        exact_lookup = _DEFAULT_EXACT_INDEXES.get(cache_key) if using_default else None
        if exact_lookup is None:
            exact_lookup = _exact_index(origin, dictionary, ignore_case=ignore_case)
            if using_default:
                _DEFAULT_EXACT_INDEXES[cache_key] = exact_lookup
    for dest in destinations:
        if use_regex:
            converted, ambiguous = _regex_convert(regex_matches, dest, dictionary)
        else:
            converted, ambiguous = _exact_convert(
                source, dest, dictionary, exact_lookup, ignore_case=ignore_case
            )
        all_ambiguous.update(ambiguous)
        result = [
            new if _is_missing(old) and not _is_missing(new) else old
            for old, new in zip(result, converted)
        ]

    if custom_match:
        result = [
            custom_match[value] if value in custom_match else converted
            for value, converted in zip(source, result)
        ]
        all_ambiguous = {
            index: matches
            for index, matches in all_ambiguous.items()
            if source[index] not in custom_match
        }

    if all_ambiguous and warn:
        values = [source[index] for index in all_ambiguous]
        warnings.warn(
            "Some values matched more than once and were set to None: "
            + ", ".join(map(repr, values)),
            UserWarning,
            stacklevel=2,
        )

    unmatched_indexes = [
        index for index, value in enumerate(result) if _is_missing(value)
    ]
    if unmatched_indexes:
        if nomatch is None:
            replacements = source
        elif nomatch is _DEFAULT_NOMATCH:
            replacements = [None] * len(source)
        elif isinstance(nomatch, Sequence) and not isinstance(nomatch, str):
            replacements = list(nomatch)
            if len(replacements) != len(source):
                raise ValueError(
                    "nomatch must be a scalar or have the same length as sourcevar."
                )
        else:
            replacements = [nomatch] * len(source)
        for index in unmatched_indexes:
            result[index] = replacements[index]
        if warn:
            _warn_unmatched(
                [
                    source[index]
                    for index in unmatched_indexes
                    if index not in all_ambiguous
                ]
            )

    return _restore_type(result, sourcevar, input_type)

def countryname(
    sourcevar: Any,
    destination: str = "country.name.en",
    *,
    nomatch: Any = _DEFAULT_NOMATCH,
    warn: bool = True,
) -> Any:
    """Convert country names in many languages to another name or code.

    The function makes two passes over the data. First it detects country-name
    variations in many languages extracted from the Unicode Common Locale Data
    Repository. It then applies the English country-name patterns used by
    :func:`countrycode` to unresolved values.

    Because the two-pass approach is permissive, some names can be ambiguous,
    such as Saint Martin versus Saint Martin (French part). Use
    ``countrycode(x, "country.name", "country.name")`` when stricter English
    name matching is preferable.

    Args:
        sourcevar: Country names to convert. Non-ASCII names are supported.
            Accepts the same scalar and container types as :func:`countrycode`.
        destination: Destination country-name or coding field. Defaults to the
            standardized English name, ``"country.name.en"``.
        nomatch: Replacement for unmatched values. By default they become
            ``None``. Pass ``None`` to preserve the original input, or pass a
            scalar or same-length sequence of replacements.
        warn: Emit warnings listing values that could not be matched.

    Returns:
        Converted names or codes, preserving the scalar or container type of
        ``sourcevar`` where supported.

    Examples:
        >>> countryname(["Barbadas", "Sverige", "UK"])
        ['Barbados', 'Sweden', 'United Kingdom']
        >>> countryname(["Barbadas", "Sverige"], destination="iso3c")
        ['BRB', 'SWE']
    """
    source, input_type = _normalize_input(sourcevar)
    global _COUNTRYNAME_DICT
    if _COUNTRYNAME_DICT is None:
        _COUNTRYNAME_DICT = load_countryname_dict()
    alternative_names = _COUNTRYNAME_DICT
    english = countrycode(
        source,
        "country.name.alt",
        "country.name.en",
        custom_dict=alternative_names,
        warn=False,
    )
    unresolved = [
        original if _is_missing(match) else match
        for original, match in zip(source, english)
    ]
    english = countrycode(
        unresolved,
        "country.name.en",
        "country.name.en",
        warn=warn,
        nomatch=nomatch,
    )
    if destination != "country.name.en":
        english = countrycode(
            english,
            "country.name.en",
            destination,
            warn=warn,
            nomatch=nomatch,
        )
    return _restore_type(list(english), sourcevar, input_type)

def guess_field(codes: Any, min_similarity: float = 80) -> list[dict[str, Any]]:
    """Guess which coding scheme or name field contains a collection of values.

    Compares the unique supplied values with every field in the built-in
    ``countrycode`` dictionary and ranks fields by their match percentage.

    Args:
        codes: Country codes or country names. Scalars and iterable inputs
            accepted by :func:`countrycode` are supported.
        min_similarity: Minimum percentage of unique, non-missing values that
            must occur in a field for that field to be returned.

    Returns:
        A list of dictionaries sorted by decreasing match percentage. Each
        dictionary contains ``"code"`` and
        ``"percent_of_unique_matched"``. Returns an empty list when no
        non-missing values are supplied or no field meets the threshold.

    Examples:
        >>> guess_field(["DZA", "CAN", "DEU"])[0]
        {'code': 'genc3c', 'percent_of_unique_matched': 100.0}
    """
    values, _ = _normalize_input(codes)
    unique = list(dict.fromkeys(value for value in values if not _is_missing(value)))
    if not unique:
        return []
    result = []
    for name, column in codelist.items():
        available = set(value for value in column if not _is_missing(value))
        percent = sum(value in available for value in unique) / len(unique) * 100
        if percent >= min_similarity:
            result.append({"code": name, "percent_of_unique_matched": float(percent)})
    return sorted(
        result, key=lambda item: (-item["percent_of_unique_matched"], item["code"])
    )

def get_dictionary(
    dictionary: str | None = None,
) -> dict[str, list[Any]] | tuple[str, ...]:
    """List or download a maintained custom conversion dictionary.

    Downloaded dictionaries can be passed directly to the ``custom_dict``
    argument of :func:`countrycode`.

    Args:
        dictionary: Name of the dictionary to retrieve. If omitted, return the
            names of all available dictionaries.

    Returns:
        A tuple of available names when ``dictionary`` is ``None``; otherwise,
        a mapping of column names to values suitable for ``custom_dict``.

    Raises:
        ValueError: If ``dictionary`` is not one of the available names.
        urllib.error.URLError: If the remote dictionary cannot be downloaded.

    Examples:
        List available dictionaries:

        >>> "us_states" in get_dictionary()
        True

        Download and use a dictionary:

        >>> states = get_dictionary("us_states")  # doctest: +SKIP
        >>> countrycode(  # doctest: +SKIP
        ...     "MO", "state.abb", "state.name", custom_dict=states
        ... )
        'Missouri'
    """
    if dictionary is None:
        return AVAILABLE_DICTIONARIES
    if dictionary not in AVAILABLE_DICTIONARIES:
        raise ValueError(
            "dictionary must be one of: " + ", ".join(AVAILABLE_DICTIONARIES)
        )
    url = (
        "https://raw.githubusercontent.com/vincentarelbundock/countrycode/"
        f"main/custom-dictionaries/data_{dictionary}.csv"
    )
    with urllib.request.urlopen(url) as response:
        text = response.read().decode("utf-8-sig")
    reader = csv.DictReader(io.StringIO(text))
    data = {name: [] for name in (reader.fieldnames or [])}
    for row in reader:
        for name, value in row.items():
            data[name].append(None if value == "" else value)
    return _prepare_codelist(data)

def load_dataset(
    name: str,
    as_type: Literal["dict", "pandas", "polars"] = "dict",
) -> Any:
    """Load a supplementary dataset distributed with ``countrycode``.

    Args:
        name: Dataset name. Valid values are ``"codelist_panel"``,
            ``"countryname_dict"``, and ``"cldr_examples"``.
        as_type: Output representation: ``"dict"``, ``"pandas"``, or
            ``"polars"``.

    Returns:
        A mapping of column names to lists, a Pandas DataFrame, or a Polars
        DataFrame, depending on ``as_type``.

    Raises:
        ValueError: If ``name`` or ``as_type`` is invalid.
        ImportError: If the requested optional DataFrame library is not
            installed.

    Examples:
        >>> panel = load_dataset("codelist_panel")
        >>> len(panel["year"]) > 1000
        True
    """
    if name not in _DATASETS:
        raise ValueError(f"name must be one of: {', '.join(sorted(_DATASETS))}")
    data = _read_csv(_DATASETS[name])
    if as_type == "dict":
        return data
    if as_type == "pandas":
        pd = _import_optional("pandas")
        if pd is None:
            raise ImportError("Pandas is not installed.")
        return pd.DataFrame(data)
    if as_type == "polars":
        pl = _import_optional("polars")
        if pl is None:
            raise ImportError("Polars is not installed.")
        return pl.DataFrame(data)
    raise ValueError("as_type must be 'dict', 'pandas', or 'polars'.")

def load_codelist_panel(
    as_type: Literal["dict", "pandas", "polars"] = "dict",
) -> Any:
    """Load the reconciled country-year conversion dictionary.

    The panel contains country-year observations with multiple coding schemes.
    It is preferable to the cross-sectional dictionary when political units
    or codes change over time.

    Args:
        as_type: Output representation: ``"dict"``, ``"pandas"``, or
            ``"polars"``.

    Returns:
        The country-year panel in the requested representation.

    Raises:
        ValueError: If ``as_type`` is invalid.
        ImportError: If the requested optional DataFrame library is absent.

    Examples:
        >>> panel = load_codelist_panel()
        >>> {"year", "iso3c"}.issubset(panel)
        True
    """
    return load_dataset("codelist_panel", as_type)

def load_countryname_dict(
    as_type: Literal["dict", "pandas", "polars"] = "dict",
) -> Any:
    """Load alternative country names used by :func:`countryname`.

    The dataset pairs standardized English country names with alternative
    names drawn from many languages and sources.

    Args:
        as_type: Output representation: ``"dict"``, ``"pandas"``, or
            ``"polars"``.

    Returns:
        The alternative-name dictionary in the requested representation.

    Raises:
        ValueError: If ``as_type`` is invalid.
        ImportError: If the requested optional DataFrame library is absent.

    Examples:
        >>> names = load_countryname_dict()
        >>> set(names) == {"country.name.en", "country.name.alt"}
        True
    """
    return load_dataset("countryname_dict", as_type)

def load_cldr_examples(
    as_type: Literal["dict", "pandas", "polars"] = "dict",
) -> Any:
    """Load examples of available Unicode CLDR destination fields.

    The dataset associates CLDR field codes with example country names and is
    useful for choosing among the hundreds of ``cldr.*`` destinations.

    Args:
        as_type: Output representation: ``"dict"``, ``"pandas"``, or
            ``"polars"``.

    Returns:
        The CLDR examples in the requested representation.

    Raises:
        ValueError: If ``as_type`` is invalid.
        ImportError: If the requested optional DataFrame library is absent.

    Examples:
        >>> examples = load_cldr_examples()
        >>> {"Code", "Example"}.issubset(examples)
        True
    """
    return load_dataset("cldr_examples", as_type)