pyPhoneApi

Async Python library for phone number lookup, validation and formatting.

Built on top of asyncio, aiohttp and phonenumbers. No manually maintained country/calling-code tables, no blocking calls on the event loop, no synchronous public API.

Installation

pip install pyPhoneApi

Requirements

• Python >= 3.11
• aiohttp
• phonenumbers

Features

• Fully async public API (await phone.lookup(...))
• Reuses a single aiohttp.ClientSession across calls, never creates one per request
• Country detection, ISO 3166-1 alpha-2 code, calling code, national and international formatting powered by phonenumbers
• Validity and possibility checks (is_valid, is_possible)
• Number type detection (MOBILE, FIXED_LINE, VOIP, ...)
• Localized country names (language="en", language="ru", ...)
• Typed exceptions instead of generic errors
• Safe under concurrent load with asyncio.gather
• No emoji anywhere in output, logs, or exceptions
• Fully typed, ships with py.typed

Quick example

import asyncio

from pyPhoneApi import PhoneApi


async def main() -> None:
    async with PhoneApi() as phone:
        result = await phone.lookup("+380643732627")

        print(f"Country: {result.country}")
        print(f"Country code: {result.country_code}")
        print(f"Calling code: {result.calling_code}")
        print(f"Number: {result.number}")
        print(f"National: {result.national}")
        print(f"Valid: {result.is_valid}")
        print(f"Possible: {result.is_possible}")


asyncio.run(main())

Output:

Country: Ukraine
Country code: UA
Calling code: +380
Number: +380643732627
National: 0643732627
Valid: True
Possible: True

Using async with

from pyPhoneApi import PhoneApi

async with PhoneApi() as phone:
    result = await phone.lookup("+380643732627")

Manual session lifecycle

from pyPhoneApi import PhoneApi

phone = PhoneApi()

await phone.start()

result = await phone.lookup("+380643732627")

await phone.close()

Repeated calls to lookup() reuse the same aiohttp.ClientSession. Calling lookup() or start() after close() raises ClientClosedError.

Shortcut function

from pyPhoneApi import lookup

result = await lookup("+380643732627")

Error handling

from pyPhoneApi import PhoneApi
from pyPhoneApi import InvalidPhoneNumberError

async with PhoneApi() as phone:
    try:
        result = await phone.lookup("invalid-number")
    except InvalidPhoneNumberError as e:
        print(e)

Output:

Invalid phone number

Concurrent requests

import asyncio

from pyPhoneApi import PhoneApi


async def main() -> None:
    async with PhoneApi() as phone:
        results = await asyncio.gather(
            phone.lookup("+380643732627"),
            phone.lookup("+37255555555"),
            phone.lookup("+491234567890"),
        )

        for result in results:
            print(result.country, result.number)


asyncio.run(main())

Only one aiohttp.ClientSession is created and shared across all of these lookups, and the event loop is never blocked.

Localized country names

result = await phone.lookup("+380643732627", language="ru")
print(result.country)

Украина

result = await phone.lookup("+380643732627", language="en")
print(result.country)

Ukraine

PhoneResult

@dataclass(frozen=True, slots=True)
class PhoneResult:
    number: str
    international: str
    national: str
    country: str
    country_code: str
    calling_code: str
    is_valid: bool
    is_possible: bool
    number_type: str

to_dict():

{
    "number": "+380643732627",
    "international": "+380643732627",
    "national": "0643732627",
    "country": "Ukraine",
    "country_code": "UA",
    "calling_code": "+380",
    "is_valid": True,
    "is_possible": True,
    "number_type": "MOBILE"
}

Exceptions

API reference

class PhoneApi(*, language: str = "en")

• await phone.start() -> None — creates the underlying aiohttp.ClientSession if one does not already exist.
• await phone.close() -> None — closes the session and marks the client as closed.
• await phone.lookup(number: str, *, language: str | None = None) -> PhoneResult — parses and analyzes a phone number.
• async with PhoneApi() as phone: — starts the session on enter, closes it on exit.
• phone.is_closed -> bool — whether the client has been closed.

async def lookup(number: str, *, language: str = "en") -> PhoneResult

Shortcut that creates a PhoneApi, performs a single lookup, and closes the session automatically.

Running tests

pip install -e ".[test]"
pytest

License

MIT