I recently discovered that using regex to extract phone numbers from text is significantly hard than I initially thought.

What started as a mild curiosity quickly morphed into a descent into a regex rabbit hole, culminating in the magnificent beast you see below:

import re

pattern = re.compile(
    r"""
        (?<![\w$])                     # start word boundary, exclude $ prefix
        (?!\d{1,2}[-/]\d{1,2}[-/]\d{2,4}\b)  # negative lookahead for date patterns
        (
            # Pattern 1: International numbers starting with +
            (?:\+\d{1,3}(?:[\s.-]*\(?\d{1,4}\)?)?(?:[\s.-]*\d+)+)
            |
            # Pattern 2: Numbers with area codes in parentheses
            (?:\(\d{1,4}\)(?:[\s.-]*\d+)+)
            |
            # Pattern 3: Long sequences of digits (8+ digits, without separators)
            (?:\d{8,})
            |
            # Pattern 4: Numbers with separators (dots, spaces, or dashes)
            (?:\d{1,4}[\s.-]+\d+(?:[\s.-]+\d+)+)
        )
        (?![\w])                      # end word boundary
    """,
    re.VERBOSE | re.IGNORECASE,
)

text = """
...
"""

result = []
for match in pattern.finditer(text):
    start_idx, end_idx = match.span()
    result.append(text[start_idx:end_idx])

Why is this so hard? At first glance, a phone number is just a sequence of digits. But I discovered there’s a lot of subtle nuances when trying to capture phone numbers across a range of dialects:

1. (?<![\w$])

(?<!...): This is the syntax for a negative lookbehind.

• It asserts that whatever is inside the (...) does not immediately precede the current position in the string.
• Crucially, the matched characters within the lookbehind are not included in the overall match. They are just a condition.

[\w$]: This is a character class for “word” characters and the literal $ character

Here, this prevents matching numbers embedded within words (e.g., product123-4567), or numbers corresponding to prices like ($123.50)

2. (?!\d{1,4}[-/]\d{1,2}[-/]\d{2,4}\b)

?!: This is the syntax for a negative lookahead. It asserts that the pattern inside the lookahead must not appear immediately after the current position in the string. If the pattern inside does appear, the entire lookahead assertion fails, and thus the match fails at that position.

\d{1,4}: matches any digit one to four times

[-/]: Matches a literal - or /

\b: This is a word boundary. It asserts that the current position is a boundary between a word character (like a letter, number, or underscore) and a non-word character (like a space, punctuation, or the beginning/end of the string). In this context, it’s crucial for ensuring that the date pattern isn’t a part of a larger number or string, but rather a distinct “word” or unit.

This is crucial for excluding common date patterns, which were a major source of false positives

3. (?:...) | (?:...) | (?:...) | (?:...)

This is where I split out the different forms of phone number patterns. Each components is a non-capturing group (?:...), which group parts of your pattern together without “capturing” their matched content into a separate back-reference. That is, unlike a capturing group (...), you can’t refer to the group later in the regex with \1, \2, … or extract it as a separate group in your code.

They’re also used for

1. Grouping for Applying Quantifiers: This is their primary use. If you want to apply a quantifier (like *, +, ?, {n,m}) to multiple characters as a unit, but you don’t care about extracting that unit’s match later, a non-capturing group is perfect.

   • Example: (?:abc)+ will match “abc”, “abcabc”, “abcabcabc”, etc. without each “abc” being stored.

2. Applying Alternation (|) to a Specific Segment: They allow you to define a set of alternatives for a specific part of your pattern without creating a new capture group.

   • Example: foo(?:bar|baz) will match “foobar” or “foobaz”. If it were foo(bar|baz), bar or baz would be captured.

3a. \+\d{1,3}(?:[\s.-]*\(?\d{1,4}\)?)?(?:[\s.-]*\d+)+

Targets international numbers.

\+\d{1,3}: Starts with a + followed by 1 to 3 digits (country code).

(?:[\s.-]*\(?\d{1,4}\)?)?: Optionally allows for separators (space, dot, dash), an optional opening bracket, 1-4 digits (area code/city code), and an optional closing bracket.

• The ? at the end makes this whole section optional, catering to numbers like +44 20... or +1(555)....

(?:[\s.-]*\d+)+: Continues with one or more groups of separators followed by one or more digits. This repeatedly matches the remaining parts of the number.

3b. \(\d{1,4}\)(?:[\s.-]*\d+)+

Specifically handles numbers where the area code (1-4 digits) is contained in brackets, like (555) 123-4567.

\(\d{1,4}\): Matches the parenthesized area code.

(?:[\s.-]*\d+)+: Matches the remaining digits, allowing for separators.

3c. \d{8,}

This is our catch-all for long, uninterrupted sequences of digits of at least 8 digits.

3d. \d{1,4}[\s.-]+\d+(?:[\s.-]+\d+)+

Captures classic XXX-XXX-XXXX or XXX.XXX.XXXX or XXX XXX XXXX styles.

\d{1,4}[\s.-]+: Starts with 1 to 4 digits followed by one or more spaces, dots, or dashes.

\d+: Then one or more digits.

(?:[\s.-]+\d+)+: And then one or more repetitions of separators followed by digits. This ensures we’re dealing with at least two separated parts

4. (?!\w):

Another negative lookahead to ensure that the match isn’t followed by a word character. Prevents matching 123-4567abc.