Skip to content

README.md

Latest commit

 

History

History
132 lines (93 loc) · 3.56 KB

README.md

File metadata and controls

132 lines (93 loc) · 3.56 KB

Python Packages for Countries States Cities Database

This directory contains official Python packages for the countries-states-cities-database project.

📦 Available Packages

Priority 1 (Released)

Coming Soon

  • countrystatecity-timezones - IANA timezone data and utilities
  • countrystatecity-currencies - Currency codes, symbols, and formatting
  • countrystatecity-languages - Language codes and metadata
  • countrystatecity-phonecodes - International dialing codes and validation

🚀 Quick Start

Installation

pip install countrystatecity-countries

Usage

from countrystatecity_countries import get_countries, get_country_by_code

# Get all countries
countries = get_countries()

# Get specific country
usa = get_country_by_code("US")
print(f"{usa.emoji} {usa.name}")

🏗️ Repository Structure

python/
├── packages/
│   ├── countries/           # Priority 1: Core package
│   ├── timezones/           # Priority 2 (planned)
│   ├── currencies/          # Priority 3 (planned)
│   ├── languages/           # Priority 4 (planned)
│   └── phone-codes/         # Priority 5 (planned)
├── shared/                  # Shared utilities
├── scripts/                 # Build scripts
└── README.md               # This file

📖 Documentation

For detailed documentation, please refer to the specifications folder:

🛠️ Development

Setup

# Navigate to a package
cd packages/countries

# Install dependencies
pip install -e ".[dev]"

Running Tests

# Run tests
pytest

# Run with coverage
pytest --cov=countrystatecity_countries --cov-report=html

Type Checking

mypy countrystatecity_countries/

Code Formatting

black countrystatecity_countries/ tests/
isort countrystatecity_countries/ tests/
ruff countrystatecity_countries/ tests/

📊 Technology Stack

Component Technology Purpose
Package Manager pip/setuptools Dependency management
Type System Pydantic Data validation, immutable models
Testing pytest Unit and integration tests
Type Checking mypy Static type checking
Formatting black + isort Code formatting
Linting ruff Fast Python linter
Data Format JSON Lazy-loadable data files

🎯 Design Principles

  1. Type Safety - Full type hints with Pydantic models
  2. Performance - Lazy loading with LRU cache
  3. Minimal Dependencies - Only essential dependencies
  4. Python Best Practices - PEP 8 compliant, well-tested
  5. Developer Experience - Clear APIs, comprehensive docs

📝 License

All packages are licensed under the Open Database License (ODbL-1.0).

🤝 Contributing

Contributions are welcome! Please see the Contributing Guidelines.

📞 Support

Made with ❤️ by dr5hn