Phone numbers
Prefix data lives in src/cedikit/data/prefixes.yaml. Verify it against the NCA numbering plan before relying on network guesses.
cedikit.phone
Normalise, validate, format and mask Ghanaian mobile phone numbers.
Example
from cedikit import phone phone.normalise("024 412 3456") '+233244123456' phone.format("+233244123456", "pretty") '024 412 3456'
NetworkGuess
dataclass
The network a number was originally assigned to.
certainty is never stronger than "likely" because subscribers can
keep their number when they move networks (mobile number portability).
CleanResult
dataclass
The outcome of cleaning one value in :func:clean_column.
CleanReport
dataclass
Summary of a bulk clean. cleaned lines up with the input (None for invalid).
normalise(value)
Convert a Ghanaian mobile number in any common format to E.164.
Accepts forms such as 0244123456, +233 24 412 3456,
233244123456, 00233244123456 and 24 412 3456.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
str | int
|
The phone number as typed by a user. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The number in E.164 format, e.g. |
Raises:
| Type | Description |
|---|---|
InvalidPhoneNumber
|
If the number cannot be normalised. The exception's
|
Example
normalise("(024) 412-3456") '+233244123456'
is_valid(value)
Return True if value is a valid Ghanaian mobile number in any common format.
Example
is_valid("0244123456") True is_valid("02441234") False
format(value, style='e164')
Format a Ghanaian mobile number.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
str | int
|
The phone number in any common format. |
required |
style
|
PhoneStyle
|
One of |
'e164'
|
Raises:
| Type | Description |
|---|---|
InvalidPhoneNumber
|
If the number is invalid. |
ValueError
|
If |
Example
format("233244123456", "international") '+233 24 412 3456'
likely_network(value)
Guess the mobile network from the number's prefix.
The result is only ever likely: numbers can be ported between networks.
Invalid numbers return NetworkGuess(network=None, certainty="unknown")
rather than raising.
Example
likely_network("0244123456").network 'MTN'
mask(value, *, visible_start=3, visible_end=3, char='*')
Mask a phone number for logs and reports, e.g. 024****456.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
str | int
|
A valid phone number in any common format. |
required |
visible_start
|
int
|
Digits to keep at the start of the local form. |
3
|
visible_end
|
int
|
Digits to keep at the end. |
3
|
char
|
str
|
The masking character. |
'*'
|
Raises:
| Type | Description |
|---|---|
InvalidPhoneNumber
|
If the number is invalid (so real data is never echoed back unmasked). |
Example
mask("+233244123456") '024****456'
clean_column(values)
Normalise many numbers at once, e.g. a list or a pandas Series.
Each value is classified as "valid" (already E.164), "fixed"
(normalised from another format) or "invalid" (with a reason).
Missing values (None, NaN, empty strings) are reported as invalid.
Example
report = clean_column(["0244123456", "+233244123456", "12345"]) report.cleaned ['+233244123456', '+233244123456', None] str(report) '3 numbers: 1 valid, 1 fixed, 1 invalid'