Connect by JBRH Open Connect

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.

Status
Reference What this means
Audience
both, developer
Last verified
Product version
6.3.2

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 ConnectWhat it does there
identity.py, global_registry.pyNormalising phone numbers so one person is one person across calls, WhatsApp and SMS
crm_calendar.py, crm_global_api.pyPublic holidays in the CRM calendar for the regions a business chooses
Business hours and scheduleszoneinfo with tzdata for zones such as Asia/Kolkata
global_data/build_countries.pyAn offline builder that writes the country file from Babel and pycountry

How it connects#

  1. A number arrives in any format
  2. phonenumbers parses it with the business's country as the default
  3. It is stored in E.164
  4. Display uses national or international format for the viewer
  5. 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#

QuestionAnswer
Licencesphonenumbers: Apache-2.0. holidays: MIT. tzdata: Apache-2.0. Babel: BSD-3-Clause. pycountry: LGPL-2.1
CostNone
VersionsFloors in requirements.txt. Babel and pycountry are not runtime requirements
CompatibilityPython 3.12, and Windows for development (hence tzdata)

Troubleshooting#

ZoneInfoNotFoundError
tzdata is 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 holidays predates 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.