Phone numbers, holidays and time zones
Connect works with businesses and customers in many countries, so it relies on maintained community sources rather than its own tables. phonenumbers formats and checks numbers, holidays supplies public holidays, and tzdata provides the time-zone database. Babel and pycountry are used offline to build Connect's country file, not at runtime.
What it is#
phonenumbers is the Python port of Google's libphonenumber: E.164, national and international formats, and whether a number is mobile or fixed, for every country.
holidays generates official public holidays per country and subdivision. tzdata packages the IANA time-zone database for Python's zoneinfo (PEP 615) where the system has none. Babel exposes the Unicode CLDR locale tables, and pycountry exposes the ISO country and currency lists.
- Category
- Locale, calendar and reference libraries
- Versions in Connect
phonenumbers>=9.0.41,holidays>=0.106,tzdata>=2024.1- Build-time only
- Babel and pycountry, in
backend/app/global_data/build_countries.py - Official sources
- libphonenumber, IANA tz, CLDR
Where Connect uses it#
| Place in Connect | What it does there |
|---|---|
identity.py, global_registry.py | Normalising phone numbers so one person is one person across calls, WhatsApp and SMS |
crm_calendar.py, crm_global_api.py | Public holidays in the CRM calendar for the regions a business chooses |
| Business hours and schedules | zoneinfo with tzdata for zones such as Asia/Kolkata |
global_data/build_countries.py | An offline builder that writes the country file from Babel and pycountry |
How it connects#
- A number arrives in any format
phonenumbersparses it with the business's country as the default- It is stored in E.164
- Display uses national or international format for the viewer
- Holidays and hours resolve in the business's own time zone
Benefits and limits#
What it gives Connect:
- Maintained by communities that track numbering plans, holiday law and zone changes.
- Pure Python, so nothing to compile on the host.
- Keeping Babel and pycountry offline keeps them out of the runtime's dependency set.
Where it stops, and what Connect does about it:
- Each list is only as current as the installed version. A numbering-plan change or a newly declared holiday needs a package upgrade.
- A valid format is not proof that a number is in service, or that its owner consented.
- Regional and optional holidays vary. The business chooses which regions apply.
Security and privacy#
- Numbers are personal data. Normalising them is what lets opt-outs apply across channels (personal data).
- No library here calls the network. Lookups are local.
- The country file is generated and checked in, so the runtime has a reviewable artefact.
Licence, cost and versions#
| Question | Answer |
|---|---|
| Licences | phonenumbers: Apache-2.0. holidays: MIT. tzdata: Apache-2.0. Babel: BSD-3-Clause. pycountry: LGPL-2.1 |
| Cost | None |
| Versions | Floors in requirements.txt. Babel and pycountry are not runtime requirements |
| Compatibility | Python 3.12, and Windows for development (hence tzdata) |
Troubleshooting#
ZoneInfoNotFoundErrortzdatais missing on a system without its own zone files.- A number shows as invalid
- Check the default country. A local number without a prefix is read against the business's country.
- A holiday is missing
- The region is not selected for the business, or the installed
holidayspredates the declaration.
Official references#
Questions#
Why store numbers in E.164?
One canonical form means a person who calls, then messages on WhatsApp, is recognised as the same person, and a STOP on one channel can be honoured on the others.
Does Connect download holiday data from the internet?
No. It comes from the installed holidays package and is computed locally.