Metadata-Version: 2.4
Name: countrystatecity-phonecodes
Version: 1.0.3
Summary: Type-safe Python package for international phone/dialing codes with 250+ country associations.
Author-email: dr5hn <support@countrystatecity.in>
Maintainer-email: dr5hn <support@countrystatecity.in>
License: Open Database License (ODbL) v1.0
        
        This package uses data from the countries-states-cities-database project,
        which is licensed under the Open Database License (ODbL) v1.0.
        
        For the full text of the ODbL license, please visit:
        https://opendatacommons.org/licenses/odbl/1-0/
        
        Summary:
        You are free to:
        - Share: Copy and redistribute the database
        - Create: Produce works from the database
        - Adapt: Modify, transform and build upon the database
        
        Under the following conditions:
        - Attribute: You must attribute any public use of the database
        - Share-Alike: If you publicly use any adapted version, you must also offer
          that adapted database under the ODbL
        - Keep open: If you redistribute the database, you must keep it open
        
Project-URL: Homepage, https://github.com/dr5hn/countrystatecity-pypi
Project-URL: Documentation, https://github.com/dr5hn/countrystatecity-pypi/tree/master/python/packages/phonecodes
Project-URL: Repository, https://github.com/dr5hn/countrystatecity-pypi
Project-URL: Source, https://github.com/dr5hn/countrystatecity-pypi/tree/master/python/packages/phonecodes
Project-URL: Issues, https://github.com/dr5hn/countrystatecity-pypi/issues
Project-URL: Changelog, https://github.com/dr5hn/countrystatecity-pypi/blob/master/python/packages/phonecodes/CHANGELOG.md
Keywords: phonecodes,dialing-codes,country-codes,international,phone,geography,lazy-loading,type-hints,pydantic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# countrystatecity-phonecodes

[![PyPI](https://img.shields.io/pypi/v/countrystatecity-phonecodes)](https://pypi.org/project/countrystatecity-phonecodes/)
[![Python Version](https://img.shields.io/pypi/pyversions/countrystatecity-phonecodes)](https://pypi.org/project/countrystatecity-phonecodes/)
[![License](https://img.shields.io/badge/License-ODbL--1.0-blue.svg)](LICENSE)
[![Type Checked](https://img.shields.io/badge/type--checked-mypy-blue)](https://mypy.readthedocs.io/)

Official Python package for international phone/dialing codes — 250+ entries with country associations. Part of the [countrystatecity](https://github.com/dr5hn/countrystatecity-pypi) ecosystem.

## Installation

```bash
pip install countrystatecity-phonecodes
```

## Usage

```python
from countrystatecity_phonecodes import (
    get_all_phonecodes,
    get_phonecode_by_country,
    get_countries_by_phonecode,
    search_phonecodes,
)

# Get phone code for a country
us = get_phonecode_by_country("US")
print(f"+{us.phoneCode} — {us.countryName}")  # +1 — United States

# Get all countries sharing a dialing code
plus1 = get_countries_by_phonecode("1")
print(f"{len(plus1)} countries use +1")  # 25 countries use +1

# Works with or without + prefix
plus44 = get_countries_by_phonecode("+44")

# Search by country name, code, or phone code
results = search_phonecodes("united")
results = search_phonecodes("44")

# All phone codes
all_codes = get_all_phonecodes()
print(f"Total entries: {len(all_codes)}")
```

## API Reference

### `get_all_phonecodes() -> List[PhoneCode]`
Returns all phone code entries (one per country).

### `get_phonecode_by_country(country_code: str) -> Optional[PhoneCode]`
Returns the phone code for a country by ISO2 code (e.g., `"US"`).

### `get_countries_by_phonecode(phone_code: str) -> List[PhoneCode]`
Returns all countries sharing a dialing code (e.g., `"1"` or `"+1"`).

### `search_phonecodes(query: str) -> List[PhoneCode]`
Search by country name, ISO2 code, or phone code (case-insensitive).

## PhoneCode Model

```python
class PhoneCode:
    phoneCode: str      # e.g. "1", "44", "91"
    countryCode: str    # ISO2 e.g. "US", "GB", "IN"
    countryName: str    # e.g. "United States"
```

## License

ODbL-1.0 — see [LICENSE](LICENSE).

## Other Packages in this Ecosystem

| Package | Description |
|---|---|
| [countrystatecity-countries](https://pypi.org/project/countrystatecity-countries/) | 250+ countries, 5,000+ states, 150,000+ cities |
| [countrystatecity-timezones](https://pypi.org/project/countrystatecity-timezones/) | 400+ IANA timezones with country associations and time conversion |
| [countrystatecity-currencies](https://pypi.org/project/countrystatecity-currencies/) | Currency codes, names, and symbols for every country |
| [countrystatecity-translations](https://pypi.org/project/countrystatecity-translations/) | Country name translations in 18+ languages |

Data sourced from [countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database).

---

Made with ❤️ by [dr5hn](https://github.com/dr5hn)
