Migration from 0.0.x

Version 0.1.0 is an intentional clean break. The legacy package returned nested dictionaries assembled around a different database. The rebuild returns immutable typed objects generated from a source-aware pipeline.

Core lookup

Legacy 0.0.x	Rebuild 0.1.0
`atlas.get_country_profile("Japan")`	`atlas.country("Japan")`
Dictionary keys	Typed properties with autocomplete
`profile["capital"]["name"]`	`country.capital.name`
Directional coordinate fields	Signed WGS84 `Coordinate` values
Mutating returned dictionaries	`country.to_dict()` for a mutable copy

Before

import pyworldatlas as pwa

atlas = pwa.Atlas()
profile = atlas.get_country_profile("Japan")
print(profile["capital"]["name"])

After

>>> from pyworldatlas import Atlas
>>> with Atlas() as atlas:
...     country = atlas.country("Japan")
...     print(country.capital.name)
Tokyo

Compatibility scope

The legacy database schema and query code are not retained. This keeps the new runtime simple and prevents two competing data models from drifting apart.

Moving from 0.7 to 0.8

Version 0.8 is additive. Existing profile, physical-geography, ranking, distance, and border calls keep their 0.7 behavior. New convenience methods make common presentation and classroom tasks shorter:

with Atlas() as atlas:
    print(atlas.country("Brazil").summary())
    print(atlas.coordinates("Tokyo", country="JP").format())
    cities = atlas.search_cities("santo", country="DO")
    questions = atlas.quiz(topic="capitals", count=5, seed=42)

No dataset migration is required. Reproducible quizzes depend on both the seed and bundled dataset version, just like samples and flashcards.

Moving from 0.8 to 0.9

The core API remains additive and dependency-free. Interactive maps are installed only when requested:

python -m pip install --upgrade "pyworldatlas[maps]"

Existing code continues to use the same bundled country database. Map support adds map(); it does not change country models or expose public boundary geometry. See Interactive 3D maps for the smaller Overview edition and the complete viewer API.

Maps after 0.9

Maps no longer need the pyworldatlas-mapview and pyworldatlas-mapdata-* packages or Plotly. The viewer is part of PyWorldAtlas, and map data installs as a checksummed data pack:

python -m pip install --upgrade pyworldatlas
pyworldatlas get maps

atlas.map(...), show(), write_html(), and the generated pages are unchanged. CountryMap now lives in pyworldatlas.maps. figure() still returns a Plotly figure when the separate plotly package is installed, and the new to_dict() returns the same figure as plain data. The maps and maps-overview extras still install, so older commands keep working, and the old companion packages can be uninstalled.