country-engine 0.1.0
Fast and efficient country code conversion library
Requires Python: >=3.10
Keywords: country, codes, iso, conversion, countries

# Country Engine

A fast and efficient Python library for converting between various country code formats and names.

## Features

- 🚀 **Fast**: Built on Polars for high-performance data operations
- 🔄 **Comprehensive**: Supports 50+ country code formats including ISO codes, regional classifications, and localized names
- 🎯 **Smart**: Automatic format detection and fuzzy name matching
- 💾 **Efficient**: LRU caching for optimal performance
- 📦 **Easy to use**: Simple API with just one main function

## Installation

```bash
pip install country-engine
```

## Quick Start

```python
from country_engine import convert, Formats

# Convert country codes
convert("USA", to=Formats.ISO2C)  # Returns: "US"
convert("US", to=Formats.ISO3C)   # Returns: "USA"
convert("840", to=Formats.ISO3C)  # Returns: "USA"

# Convert country names
convert("United States", to=Formats.ISO2C)  # Returns: "US"
convert("France", to=Formats.ISO3N)         # Returns: "250"

# Explicit source format (faster)
convert("US", to=Formats.ISO3C, from_format=Formats.ISO2C)  # Returns: "USA"

# Multiple language support
convert("Deutschland", to=Formats.ISO2C)  # Returns: "DE"
convert("Japon", to=Formats.ISO3C)        # Returns: "JPN"
```

## Supported Formats

The library supports a wide range of country code formats:

### ISO Standards
- `Formats.ISO2C` - ISO 3166-1 alpha-2 (e.g., "US")
- `Formats.ISO3C` - ISO 3166-1 alpha-3 (e.g., "USA")
- `Formats.ISO3N` - ISO 3166-1 numeric (e.g., "840")

### Country Names
- `Formats.Country.Name.EN` - English names
- `Formats.Country.Name.FR` - French names
- `Formats.Country.Name.DE` - German names
- `Formats.Country.Name.IT` - Italian names

### Regional Classifications
- `Formats.CONTINENT` - Continent names
- `Formats.REGION` - UN regions
- `Formats.EU28` - EU28 membership

### International Organizations
- `Formats.UN` - United Nations codes
- `Formats.WB` - World Bank codes
- `Formats.IMF` - International Monetary Fund codes
- `Formats.FAO` - Food and Agriculture Organization codes

### And many more...
- CLDR localized names in 200+ languages/locales
- Currency codes (ISO 4217)
- Top-level domains
- IOC Olympic codes
- FIPS codes
- And 40+ additional formats

## API Reference

### `convert(value, to, from_format=None)`

Convert a country code or name to a specific target format.

**Parameters:**
- `value` (str | int): The input country code or name
- `to` (str): The target format identifier (from `Formats` class)
- `from_format` (str, optional): Explicit format of the input. If None, the function attempts to infer it.

**Returns:**
- `str | None`: The converted value as a string, or None if conversion failed

**Example:**
```python
# Auto-detect input format
result = convert("USA", to=Formats.ISO2C)

# Specify input format for better performance
result = convert("USA", to=Formats.ISO2C, from_format=Formats.ISO3C)
```

## Performance

Country Engine is designed for high performance:

- **Lazy loading**: Data files are only loaded when needed
- **Caching**: LRU caching for frequently used conversions
- **Efficient data structures**: Polars DataFrames for fast lookups
- **Pre-built search index**: Fast format inference

## Development

### Install for development

```bash
git clone https://github.com/EledoneAi/country-engine.git
cd country-engine
pip install -e .
```

## Data Sources

The library uses data compiled from multiple authoritative sources:
- ISO 3166-1 standard
- Unicode CLDR project
- United Nations statistics
- World Bank data
- And other international organizations

The country data is sourced from [pycountrycode](https://github.com/vincentarelbundock/pycountrycode) by Vincent Arel-Bundock, which provides a comprehensive compilation of country codes and classifications.

## License

MIT License - see LICENSE file for details

## Acknowledgments

- Built with [Polars](https://www.pola.rs/) for high-performance data operations
- Country data sourced from [pycountrycode](https://github.com/vincentarelbundock/pycountrycode) by Vincent Arel-Bundock
- Country data compiled from various international standards and organizations