Discovery tools

PyWorldAtlas can turn its sourced country profiles into readable summaries, reproducible samples, compact discovery cards, flashcards, and multiple-choice questions. These tools are offline, dependency-free, and deterministic. They do not maintain scores or user state.

Readable country summaries

summary() assembles a friendly introduction while keeping the typed profile available underneath it:

from pyworldatlas import Atlas

with Atlas() as atlas:
    print(atlas.country("Brazil").summary())

Unavailable values are omitted. Pass local_language="ja" or another covered code to request a particular local identity. The result is display text; use Country.to_dict() for stable field names.

Flag emoji

Japan · Brazil · Switzerland · China · France · United Arab Emirates

Country.flag and Country.flag_emoji expose the same regional-indicator Unicode sequence derived from the profile’s alpha-2 code:

>>> from pyworldatlas import Atlas
>>> atlas = Atlas()
>>> japan = atlas.country("Japan")
>>> japan.flag
'🇯🇵'
>>> japan.flag_emoji
'🇯🇵'

The value itself remains ordinary Unicode. Flag artwork in Python output depends on the operating system, font, terminal, browser, or application, so some environments display a pair of regional-indicator letters. Showcase rows on this documentation site use a small, locally hosted Twemoji fallback for consistent presentation. The installed Python package does not bundle or download flag artwork.

The documentation fallback uses Twemoji graphics, licensed under CC BY 4.0.

Derived profile facts

Convenience properties keep common profile work explicit:

>>> japan.language_codes
('ja',)
>>> japan.currency_code
'JPY'
>>> japan.major_city_count == len(japan.major_cities)
True
>>> round(japan.population_density, 2)
334.81

population_density is calculated from the captured population and area values. It is not a separate official statistic and returns None when the ratio cannot be calculated.

Discovery cards

Country.discovery_card returns a compact immutable view suitable for teaching examples, JSON APIs, notebooks, and static-site generation:

>>> card = japan.discovery_card()
>>> card.country.alpha3
'JPN'
>>> card.capital
'Tokyo'
>>> card.flag_emoji
'🇯🇵'
>>> card.formal_name
'Japan'
>>> card.language_codes
('ja',)
>>> card.anthem_title
'Kimigayo'
>>> card.demonym
'Japanese (singular and plural)'
>>> card.timezone_ids
('Asia/Tokyo',)
>>> card.coastline_km
29751.0
>>> (card.highest_point.name, card.highest_point.elevation_m)
('Mount Fuji', 3776.0)
>>> card.climate_zone_codes
('Cfa', 'Dfb', 'Dfa', 'Af', 'Dfc')
>>> card.to_dict()["country"]["numeric"]
'392'

The card is built from the materialized Country object. It performs no database query and remains usable after its atlas is closed.

Reproducible country samples

Atlas.sample_countries uses a versioned SHA-256 ranking over stable M49 identifiers. It does not use global random state or depend on SQLite row order:

>>> sample = atlas.sample_countries(count=5, seed=42)
>>> [country.name for country in sample]
['Kuwait', 'Bahamas', 'Burundi', 'United Arab Emirates', 'Tunisia']
>>> africa = atlas.sample_countries(count=4, continent="Africa", seed="class")
>>> [country.alpha2 for country in africa]
['BJ', 'MW', 'CV', 'DZ']

The same package version, dataset version, filters, count, and seed produce the same ordered sample on every supported Python version. count must be a positive integer and cannot exceed the filtered population.

Structured flashcards

Atlas.flashcards uses the same stable sampling primitive and returns immutable Flashcard objects:

>>> cards = atlas.flashcards(topic="capitals", count=3, seed=42)
>>> [(card.country.alpha2, card.answer) for card in cards]
[('KW', 'Kuwait City'), ('BS', 'Nassau'), ('BI', 'Gitega')]
>>> cards[0].prompt
'What is the capital of Kuwait?'
>>> cards[0].to_dict()["country"]["numeric"]
'414'

Multiple-choice questions

quiz() uses the same topics and stable sampling while adding deterministic distractors and answer positions:

>>> questions = atlas.quiz(topic="capitals", count=2, seed="classroom")
>>> len(questions[0].choices)
4
>>> questions[0].answer in questions[0].choices
True
>>> questions[0].is_correct(questions[0].answer_number)
True
>>> questions == atlas.quiz(topic="capitals", count=2, seed="classroom")
True

Use learning_topics() to populate a topic menu. choices may be 2 through 6; filters that leave too few distinct answers raise ValueError instead of manufacturing or repeating choices.

Supported topics

Flashcard and quiz topics

Topic	Answer
capitals	Primary capital name
countries_from_capitals	Country or area name
flags	Country or area represented by a flag emoji
alpha_2_codes / alpha_3_codes / m49_codes	Standard country identifier
currencies	Captured currency name and code
calling_codes	Captured international calling codes
top_level_domains	Country-code top-level domain
language_codes	Captured language codes
continents / regions	Bundled geographic classification
local_names	Selected sourced local-language name
neighbors	Alphabetized names from the reviewed land-border graph
border_counts	Number of accepted land-border relationships
populations / areas / population_density	Captured snapshot value or transparent calculated ratio
coastlines	Source-reported coastline length
highest_points	Named highest point and elevation
climate_zones	Largest represented Köppen-Geiger class
rivers / lakes	One source-listed major feature from the profile

Countries missing the answer required by a topic are removed before sampling. If the requested count is impossible, the method raises ValueError rather than returning an incomplete lesson. Local-name flashcards cover all 248 country and area records using their selected local identity. Neighbor cards exclude borderless entities, while border-count cards include them with an answer of 0.

Physical flashcards retain the limits of the underlying data. River and lake answers come from source-listed major features rather than exhaustive inventories. Climate answers use the largest represented class after the documented extraction threshold; they are not a site-level forecast.

>>> atlas.flashcards(topic="local_names", count=2, seed=42)[0].answer
'الكويت'
>>> atlas.close()

Data and interpretation

Discovery features introduce no unsourced country values. Flags come from alpha-2 codes; density is a documented ratio; cards copy profile fields; and sampling, flashcards, and quizzes rearrange existing values. Population and area answers remain snapshots, observed timezones remain limited to bundled places, and language answers are source codes, while local-name cards use the selected CLDR or UNGEGN identity record. Border flashcards are derived from the reviewed graph; they introduce no additional adjacency claims. Physical prompts reuse the sourced or directly derived fields described in Physical geography.

Executable example

"""Build reproducible country-learning material from the offline atlas."""

from pyworldatlas import Atlas


with Atlas() as atlas:
    japan = atlas.country("Japan")
    card = japan.discovery_card()
    print(card.flag_emoji, card.country.name, card.capital)
    print(f"Population density: {card.population_density:.2f} people/km²")

    sample = atlas.sample_countries(count=3, continent="Africa", seed=42)
    print("Sample:", ", ".join(country.name for country in sample))

    for flashcard in atlas.flashcards(topic="capitals", count=2, seed=42):
        print(f"Q: {flashcard.prompt}")
        print(f"A: {flashcard.answer}")

For a complete 0.8 classroom tour, continue to Learning activities.