Skip to main content

Country information database. Including names, capitals, currencies, etc.

Project description

python-countries

Run tests codecov

Country Database in Python

  • name
  • currency
  • flag
  • official_languages
  • ...

See ggicci/countries for the full list of the properties.

Install

pip install country-database

Usage

Load all countries

from country_database import load_countries

CountryIndex = load_countries()
print(CountryIndex.CAN.alpha2_code) # "CA"
print(CountryIndex.CAN.name) # "Canada"
print(CountryIndex.CAN.name.to_locale("zh")) # "加拿大"


CountryIndexZh = load_countries(locale="zh")
print(CountryIndexZh.CAN.name) # "加拿大"
print(CountryIndexZh.CAN.name.to_locale("en")) # "Canada"

Load one country

from country_database import load_country

ca = load_country("CA") # or "CAN"
print(ca.name) # "Canada"

Load a custom list of countries

from dataclasses import dataclass
from country_database import CountryProperties, load_countries_generic

@dataclass(frozen=True)
class MyCountryIndex:
    CAN: CountryProperties
    USA: CountryProperties
    CHN: CountryProperties

CountryIndex = load_countries_generic(MyCountryIndex)

Add custom properties to a country

The default database is ggicci/countries. You can add your own data and load them easily by instantiate a DataLoader and pass it to the load_countries*, load_country* or just merge your database to the default_dataloader.

from pathlib import Path
from dataclasses import dataclass
from country_database import (
    CountryProperties,
    DataLoader,
    FullCountryIndex,
    Property,
)

CUSTOM_DATA_DIR = Path("/path/to/your/custom/data/dir")

# NOTE: if you don't need the fields from the default database,
# you can just inherit CountryPropertiesBase instead of CountryProperties
@dataclass(frozen=True)
class MyCountry(CountryProperties):
    custom_field_1: Property
    custom_field_2: Property


# WAY 1: create a new dataloader.
loader = DataLoader() # will load the default database
loader.merge_database(CUSTOM_DATA_DIR)

# NOTE: If you don't want to load the default database, use the following statement:
# It will create a loader which only loads
# 1. the country codes from the default database;
# 2. data from CUSTOM_DATA_DIR;
# but data from the default database won't be loaded.
#
# loader = DataLoader(CUSTOM_DATA_DIR)

CountryIndex = load_countries_generic(FullCountryIndex[MyCountry], loader=loader)

# WAY 2: merge your database to the default_dataloader.
from country_database import default_dataloader
default_dataloader.merge_database(CUSTOM_DATA_DIR)
CountryIndex = load_countries_generic(FullCountryIndex[MyCountry])

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

country-database-0.1.0.tar.gz (17.0 kB view hashes)

Uploaded Source

Built Distribution

country_database-0.1.0-py3-none-any.whl (17.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page