Metadata-Version: 2.4
Name: worlddatax
Version: 1.0.0
Summary: Comprehensive offline datasets for global country, currency, and geography metadata.
Home-page: https://github.com/example/worlddatax
Author: WorldDataX Maintainers
Author-email: WorldDataX Maintainers <maintainers@worlddatax.dev>
License: MIT
Project-URL: Homepage, https://github.com/example/worlddatax
Project-URL: Documentation, https://github.com/example/worlddatax#readme
Project-URL: Source, https://github.com/example/worlddatax
Project-URL: Tracker, https://github.com/example/worlddatax/issues
Keywords: countries,geography,iso,world,dataset
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# worlddatax

worlddatax is a production-ready Python package that ships an up-to-date, structured snapshot of worldwide geographic and country metadata. It exposes a simple, beginner-friendly API that reads from packaged JSON datasets covering every UN-recognised sovereign state.

## Features

- 195 countries with ISO codes, capitals, continents, currencies, and international dialling prefixes
- Deep-dives for key markets with state, province, and city coverage
- Clean Python functions that never print or raise on missing records—receiving `None` or empty collections instead
- Zero runtime network access; all data is bundled in JSON and loaded on demand with caching

## Installation

Install the library directly from a source checkout or from PyPI (when published):

```bash
pip install worlddatax
```

For local development use:

```bash
pip install -e .
```

## Quick start

```python
from worlddatax import (
		get_all_countries,
		get_country_by_iso,
		get_countries_by_continent,
		get_states,
		get_cities,
		get_currency,
		get_phone_code,
)

india = get_country_by_iso("IND")
asia = get_countries_by_continent("Asia")
states = get_states("United States")
california_cities = get_cities("United States", "California")
yen = get_currency("Japan")
usa_codes = get_phone_code("United States")

print(india["capital"])          # New Delhi
print(len(asia))                  # 46
print(states[:3])                 # ['Alabama', 'Alaska', 'Arizona']
print(california_cities)          # ['Los Angeles', 'San Francisco']
print(yen)                        # {'code': 'JPY', 'name': 'Japanese yen', 'symbol': '¥'}
print(usa_codes)                  # ['+1']
```

## Packaged data

- Countries: names, ISO-2, ISO-3, capitals, continents, currency metadata, international calling prefixes
- States and provinces: complete lists for Australia, Brazil, Canada, China, France, Germany, India, and the United States
- Cities: curated coverage for major regions within the above countries
- Currencies: code, display name, and symbol for every currency referenced by the dataset
- Continents: continent-to-country mappings for simplified grouping

Datasets are fetched from the public [REST Countries](https://restcountries.com) service during packaging and bundled into JSON files inside the distribution. All files are UTF-8 encoded and ship with the wheel, ensuring offline availability.

## Project layout

```
worlddatax/
	worlddatax/           # Package modules
	data/                 # JSON datasets bundled with the wheel
	tests/                # Automated contract checks
```

## Testing

Run the included test suite with `pytest`:

```bash
pytest
```

## License

worlddatax is released under the MIT License. See [LICENSE](LICENSE) for details.
