Countryinfo Python Library

Warnings

• gotcha Initializing `CountryInfo` with a non-existent country name will raise a `CountryNotFoundError`.
  Fix: Wrap the `CountryInfo` constructor in a `try-except CountryNotFoundError` block.
• gotcha Passing `None` or an empty string to the `CountryInfo` constructor will raise a `ValueError`.
  Fix: Ensure the input to `CountryInfo` is a non-empty string or a valid integer (for ISO numeric).
• gotcha Region names (e.g., 'Africa', 'Europe') are not valid inputs for the `CountryInfo` constructor. It expects specific country identifiers.
  Fix: To get countries within a region, use `CountryInfo.all()` to retrieve all country data and then filter the results based on the 'region' key.
• gotcha Users have reported `KeyError` or issues with data loading, sometimes indicating missing data files or corrupted installations.
  Fix: Verify the `countryinfo/data` directory exists within your `site-packages` and contains the necessary JSON files. Reinstalling the package might resolve the issue.
• gotcha Environments with non-UTF-8 default encodings may encounter `UnicodeDecodeError` or `charmap` errors when processing certain country names or data.
  Fix: Ensure your Python environment is configured to use UTF-8 encoding. This can often be set via environment variables (e.g., `PYTHONIOENCODING=UTF-8`) or by running Python with the `-X utf8` flag.

Install

• pip install countryinfo Standard installation
• pip install "countryinfo[fuzzy]" With fuzzy matching for typo tolerance
• pip install "countryinfo[pydantic]" With Pydantic v2 support for typed models
• pip install "countryinfo[all]" All optional extras

Imports

• CountryInfo

  from countryinfo import CountryInfo

• CountryNotFoundError

  from countryinfo import CountryInfo, CountryNotFoundError

  Import CountryNotFoundError for explicit error handling.

Quickstart

Initializes `CountryInfo` with a country name (or ISO code/numeric ID) and demonstrates fetching its capital and ISO code. It also includes error handling for non-existent countries and demonstrates filtering all available countries by region.

from countryinfo import CountryInfo, CountryNotFoundError
import os

try:
    # Use a well-known country for the quickstart
    country = CountryInfo("Singapore")
    print(f"Capital of Singapore: {country.capital()}")

    # Example of retrieving ISO information
    print(f"ISO Alpha-2 code: {country.iso(2)}")

    # Example with a non-existent country to demonstrate error handling
    non_existent_country = "Neverland"
    print(f"\nTrying to get info for '{non_existent_country}':")
    CountryInfo(non_existent_country).name()
except CountryNotFoundError as e:
    print(f"Error: {e}")
except ValueError as e:
    print(f"Error: {e}")

# To demonstrate filtering countries by region
print("\nFetching some countries in Europe:")
europe_countries = [c['name'] for c in CountryInfo.all().values() if c.get('region') == 'Europe']
if europe_countries:
    print(f"Example European countries: {', '.join(europe_countries[:5])}...")