TXT file extraction

TXT import with regex phone detection, multi-separator splits, and optional name extraction when name and number share a line.

The TXT extraction functionality is implemented in two primary locations:

• A Flask-based API service that handles file uploads and contact extraction
• Standalone Python utilities for direct command-line usage

graph TB
subgraph "Python Backend"
API["Flask API<br/>app.py"]
EXTRACT["Contact Extraction<br/>extract_contacts.py"]
MANUAL["Manual Numbers Parser<br/>parse_manual_numbers.py"]
VALIDATE["Phone Validator<br/>validate_number.py"]
end
subgraph "External Dependencies"
PANDAS["pandas"]
OPENPYXL["openpyxl"]
XLRD["xlrd"]
FLASK["flask"]
CORS["flask-cors"]
end
API --> EXTRACT
API --> MANUAL
API --> VALIDATE
EXTRACT --> PANDAS
API --> PANDAS
API --> OPENPYXL
API --> XLRD
API --> FLASK
API --> CORS

The TXT extraction system consists of several key components working together:

Phone number cleaning algorithm#

The core phone number cleaning function performs systematic normalization:

• Removes common separators (hyphens, spaces, parentheses, periods)
• Strips non-digit characters except plus signs
• Handles country code detection and normalization
• Validates length constraints (7-15 digits)

TXT file processing pipeline#

The TXT extraction follows a multi-stage approach:

1. Line-by-line processing with UTF-8 encoding
2. Multi-separator splitting using comma, semicolon, tab, and pipe delimiters
3. Pattern-based phone number detection using regex
4. Fallback extraction when separators are absent
5. Name extraction from remaining parts

Fallback parsing strategies#

When initial parsing fails, the system employs progressive fallback mechanisms:

• Separator-based splitting with multiple delimiter support
• Whole-line regex matching for phone numbers
• Name extraction from remaining text segments
• Graceful error handling and empty line skipping

The TXT extraction architecture implements a layered approach with reliable error handling and fallback mechanisms.

sequenceDiagram
participant Client as "Client Application"
participant API as "Flask API"
participant TXT as "TXT Processor"
participant CLEAN as "Phone Cleaner"
participant FS as "File System"
Client->>API : POST /upload (TXT file)
API->>FS : Save uploaded file
API->>TXT : extract_contacts_from_txt(file_path)
TXT->>FS : Read file lines
loop For each line
TXT->>TXT : Split by separators
TXT->>TXT : Detect phone number candidate
TXT->>TXT : Extract name candidate
TXT->>CLEAN : Clean phone number
CLEAN-->>TXT : Normalized number
TXT->>TXT : Validate length constraints
end
TXT-->>API : List of contacts
API-->>Client : JSON response with contacts
Note over TXT,CLEAN : Fallback processing when initial parsing fails

TXT extraction algorithm#

The TXT extraction algorithm implements careful pattern matching and parsing logic.

flowchart TD
Start([Start TXT Processing]) --> ReadFile["Read file lines"]
ReadFile --> ProcessLine["Process each line"]
ProcessLine --> CheckEmpty{"Is line empty?"}
CheckEmpty --> |Yes| NextLine["Skip to next line"]
CheckEmpty --> |No| SplitParts["Split by separators:<br/>[, ; \\t |]"]
SplitParts --> FindPhone["Find phone candidates<br/>using regex pattern"]
FindPhone --> HasPhone{"Phone candidate found?"}
HasPhone --> |Yes| ExtractName["Extract name from remaining parts"]
HasPhone --> |No| FallbackRegex["Apply fallback regex<br/>on entire line"]
FallbackRegex --> FallbackFound{"Fallback match found?"}
FallbackFound --> |Yes| ExtractFromLine["Extract from whole line"]
FallbackFound --> |No| NextLine
ExtractFromLine --> CleanNumber["Clean phone number"]
ExtractName --> CleanNumber
CleanNumber --> ValidateLength{"Validate length<br/>(7-15 digits)"}
ValidateLength --> |Valid| AddContact["Add to contacts list"]
ValidateLength --> |Invalid| NextLine
AddContact --> NextLine
NextLine --> End([End])

Phone number detection patterns#

The system uses careful regex patterns for phone number identification:

Primary detection pattern#

The main pattern [\d+\-\(\)\s]{7,} identifies phone numbers by:

• Matching digits (\d+)
• Including plus signs (+)
• Allowing hyphens (\-)
• Permitting parentheses (\(\))
• Supporting spaces (\s)
• Requiring minimum 7 characters for validation

Fallback detection pattern#

The fallback pattern [\+]?[\d\-\(\)\s]{7,} handles:

• Optional leading plus sign
• Flexible digit and separator combinations
• Whole-line matching when separators are absent

Multi-Separator splitting logic#

The system supports four primary separators with equal precedence:

graph LR
Input["Input Line"] --> Split["re.split(r'[,;\\t|]', line)"]
Split --> Part1["Part 1"]
Split --> Part2["Part 2"]
Split --> Part3["Part 3"]
Split --> PartN["Part N"]
Part1 --> Check1{"Looks like phone?<br/>regex test"}
Part2 --> Check2{"Looks like phone?"}
Part3 --> Check3{"Looks like phone?"}
PartN --> CheckN{"Looks like phone?"}
Check1 --> |Yes| Phone1["Select as phone candidate"]
Check2 --> |Yes| Phone2["Select as phone candidate"]
Check3 --> |Yes| Phone3["Select as phone candidate"]
CheckN --> |Yes| PhoneN["Select as phone candidate"]
Check1 --> |No| Name1["Select as name candidate"]
Check2 --> |No| Name2["Select as name candidate"]
Check3 --> |No| Name3["Select as name candidate"]
CheckN --> |No| NameN["Select as name candidate"]

Name extraction process#

When names are combined with phone numbers, the system implements intelligent extraction:

Mixed format handling#

The algorithm prioritizes:

1. First phone candidate. Selected when multiple phone-like segments exist
2. First non-empty segment. Used as name when no clear phone candidate exists
3. Fallback extraction. When separators are absent, the system extracts from the entire line

Name candidate selection#

flowchart TD
Parts["Split parts"] --> LoopParts["Iterate through parts"]
LoopParts --> CheckPhone{"Part matches phone pattern?"}
CheckPhone --> |Yes| CheckExistingPhone{"Phone candidate exists?"}
CheckExistingPhone --> |No| SetPhone["Set as phone candidate"]
CheckExistingPhone --> |Yes| NextPart["Next part"]
CheckPhone --> |No| CheckName{"Name candidate exists?"}
CheckName --> |No| SetName["Set as name candidate"]
CheckName --> |Yes| NextPart
SetPhone --> NextPart
SetName --> NextPart
NextPart --> MoreParts{"More parts?"}
MoreParts --> |Yes| LoopParts
MoreParts --> |No| Done["Extraction complete"]

Supported TXT formats and examples#

Standard separated format#

John Doe,123-456-7890
Jane Smith;[email protected]|+1-555-0123
Bob Wilson|+44 20 7946 0958
Alice Brown,555.123.4567

Mixed format handling#

+1-555-0123 John Smith
5551234567 Jane Doe
+442079460958 Bob Wilson

Edge case examples#

John Doe,123-456-7890,,Extra Field

123-456-7890
Jane Smith

Error recovery mechanisms#

The system implements clear error handling:

File processing errors#

• UTF-8 encoding enforcement
• Graceful handling of unreadable files
• Empty file and directory handling

Parsing failures#

• Line-by-line processing with individual error isolation
• Empty line skipping
• Partial parsing continuation on errors

Phone number validation#

• Length validation (7-15 digits)
• Format normalization
• Country code detection and correction

The TXT extraction system relies on several key dependencies:

graph TB
subgraph "Core Dependencies"
RE["re (regex)"]
OS["os"]
SYS["sys"]
JSON["json"]
end
subgraph "Optional Dependencies"
PANDAS["pandas"]
OPENPYXL["openpyxl"]
XLRD["xlrd"]
end
subgraph "External Libraries"
FLASK["flask"]
CORS["flask-cors"]
WERKZEUG["werkzeug"]
end
TXT_EXTRACT["TXT Extraction"] --> RE
TXT_EXTRACT --> OS
TXT_EXTRACT --> SYS
TXT_EXTRACT --> JSON
CSV_EXTRACT["CSV Extraction"] --> PANDAS
EXCEL_EXTRACT["Excel Extraction"] --> PANDAS
EXCEL_EXTRACT --> OPENPYXL
EXCEL_EXTRACT --> XLRD
API["Flask API"] --> FLASK
API --> CORS
API --> WERKZEUG
API --> TXT_EXTRACT
API --> CSV_EXTRACT
API --> EXCEL_EXTRACT

External dependencies impact#

• pandas. Enables structured data processing for CSV/Excel files
• openpyxl/xlrd. Provides Excel file format support
• flask/flask-cors. Powers the web API interface
• werkzeug. Handles file uploads and security

The TXT extraction system is optimized for efficiency and scalability:

Algorithm complexity#

• Time Complexity. O(n × m) where n is number of lines and m is average parts per line
• Space Complexity. O(k) where k is number of valid contacts extracted
• Memory Usage. Linear with respect to file size

Optimization strategies#

• Single-pass line processing
• Early termination on empty lines
• Minimal regex operations per line
• Efficient string operations for phone number cleaning

Scalability factors#

• File size limitations (16MB max upload)
• Memory constraints for large files
• Regex compilation caching
• Streaming file processing

Common issues and solutions#

Phone number not detected#

Symptoms. Phone numbers appear as empty or invalid Causes.

• Numbers shorter than 7 digits or longer than 15 digits
• Unrecognized separators or formatting
• Leading zeros in international numbers

Solutions.

• Ensure numbers meet length requirements
• Use recognized separators (spaces, hyphens, parentheses)
• Include country codes for international numbers

Mixed format problems#

Symptoms. Names incorrectly extracted or phone numbers missed Causes.

• Ambiguous separators causing misinterpretation
• Names containing phone number patterns
• Missing separators in lines

Solutions.

• Use consistent separator usage
• Place phone numbers first when mixing formats
• Include explicit separators between name and number

File encoding issues#

Symptoms. Characters appear corrupted or parsing fails Causes.

• Non-UTF-8 file encoding
• Special characters not properly handled
• BOM (Byte Order Mark) interference

Solutions.

• Save files in UTF-8 encoding
• Remove BOM if present
• Verify character encoding compatibility

Performance issues#

Symptoms. Slow processing for large files Causes.

• Very large file sizes exceeding limits
• Complex regex patterns
• Memory constraints

Solutions.

• Split large files into smaller chunks
• Optimize regex patterns
• Monitor memory usage during processing

Error codes and messages#

The system provides structured error reporting:

• File not found errors
• Unsupported file type errors
• Processing exceptions with detailed messages
• Validation failures with specific reasons

TXT is the messy format. Expect skipped lines; tighten your separators if too many valid numbers are dropped.