From 029700359e2c43a84457c62c2e9b93548563fbf7 Mon Sep 17 00:00:00 2001 From: tomballgithub Date: Sat, 29 Nov 2025 19:34:27 -0600 Subject: [PATCH 1/7] Fix vcard decoding errors --- Whatsapp_Chat_Exporter/vcards_contacts.py | 57 ++++++++++++++++------- 1 file changed, 41 insertions(+), 16 deletions(-) diff --git a/Whatsapp_Chat_Exporter/vcards_contacts.py b/Whatsapp_Chat_Exporter/vcards_contacts.py index 9360b2f..d303965 100644 --- a/Whatsapp_Chat_Exporter/vcards_contacts.py +++ b/Whatsapp_Chat_Exporter/vcards_contacts.py @@ -1,4 +1,6 @@ import vobject +import re +import quopri from typing import List, TypedDict from Whatsapp_Chat_Exporter.data_model import ChatStore from Whatsapp_Chat_Exporter.utility import Device @@ -33,24 +35,47 @@ class ContactsFromVCards: chats.add_chat(number + "@s.whatsapp.net", ChatStore(Device.ANDROID, name)) +def decode_vcard_value(value: str) -> str: + """Decode a vCard value that may be quoted-printable UTF-8.""" + try: + value = value.replace("=\n", "") # remove soft line breaks + bytes_val = quopri.decodestring(value) + return bytes_val.decode("utf-8", errors="replace") + except Exception: + return value + def read_vcards_file(vcf_file_path, default_country_code: str): contacts = [] - with open(vcf_file_path, mode="r", encoding="utf-8") as f: - reader = vobject.readComponents(f, ignoreUnreadable=True) - for row in reader: - if hasattr(row, 'fn'): - name = str(row.fn.value) - elif hasattr(row, 'n'): - name = str(row.n.value) - else: - name = None - if not hasattr(row, 'tel') or name is None: - continue - contact: ExportedContactNumbers = { - "full_name": name, - "numbers": list(map(lambda tel: tel.value, row.tel_list)), - } - contacts.append(contact) + with open(vcf_file_path, "r", encoding="utf-8", errors="ignore") as f: + content = f.read() + + # Split into individual vCards + vcards = content.split("BEGIN:VCARD") + for vcard in vcards: + if "END:VCARD" not in vcard: + continue + + # Extract name in priority: FN -> N -> ORG + name = None + for field in ("FN", "N", "ORG"): + match = re.search(rf'^{field}(?:;[^:]*)?:(.*)', vcard, re.IGNORECASE | re.MULTILINE) + if match: + name = decode_vcard_value(match.group(1).strip()) + break + + if not name: + continue + + # Extract phone numbers + numbers = re.findall(r'^\s*TEL(?:;[^:]*)?:(\+?\d+)', vcard, re.IGNORECASE | re.MULTILINE) + if not numbers: + continue + + contact = { + "full_name": name, + "numbers": numbers, + } + contacts.append(contact) return map_number_to_name(contacts, default_country_code) From 8c9c69a53616c1f5b9e19a98af72a898d0cb88e8 Mon Sep 17 00:00:00 2001 From: tomballgithub Date: Sat, 29 Nov 2025 20:28:51 -0600 Subject: [PATCH 2/7] Print the number of imported vcards --- Whatsapp_Chat_Exporter/vcards_contacts.py | 1 + 1 file changed, 1 insertion(+) diff --git a/Whatsapp_Chat_Exporter/vcards_contacts.py b/Whatsapp_Chat_Exporter/vcards_contacts.py index d303965..ba2165d 100644 --- a/Whatsapp_Chat_Exporter/vcards_contacts.py +++ b/Whatsapp_Chat_Exporter/vcards_contacts.py @@ -77,6 +77,7 @@ def read_vcards_file(vcf_file_path, default_country_code: str): } contacts.append(contact) + print(f"Imported {len(contacts)} contacts/vcards") return map_number_to_name(contacts, default_country_code) From 02363af6373a60b7e944934b1eb8d5b48aaf1060 Mon Sep 17 00:00:00 2001 From: tomballgithub Date: Wed, 3 Dec 2025 22:42:31 -0600 Subject: [PATCH 3/7] Updated vcard test to check for failing cases which caused this PR --- tests/data/contacts.vcf | 41 ++++++++++++++++++++++++++++++++++- tests/test_vcards_contacts.py | 25 ++++++++++++++++++++- 2 files changed, 64 insertions(+), 2 deletions(-) diff --git a/tests/data/contacts.vcf b/tests/data/contacts.vcf index 12a026b..1e872be 100644 --- a/tests/data/contacts.vcf +++ b/tests/data/contacts.vcf @@ -2,4 +2,43 @@ BEGIN:VCARD VERSION:3.0 FN:Sample Contact TEL;TYPE=CELL:+85288888888 -END:VCARD \ No newline at end of file +END:VCARD + +BEGIN:VCARD +VERSION:2.1 +N:Lopez;Yard Lawn Guy;Jose;; +FN:Yard Lawn Guy, Jose Lopez +TEL;HOME:5673334444 +END:VCARD + +BEGIN:VCARD +VERSION:2.1 +N;CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE:;=4A=6F=68=6E=20=42=75=74=6C=65=72=20=F0=9F=8C=9F= +=F0=9F=92=AB=F0=9F=8C=9F;;; +FN;CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE:=4A=6F=68=6E=20=42=75=74=6C=65=72=20=F0=9F=8C=9F= +=F0=9F=92=AB=F0=9F=8C=9F +TEL;PREF:5556667777 +END:VCARD + +BEGIN:VCARD +VERSION:2.1 +TEL;WORK;PREF:1234567890 +ORG:Airline Contact #'s +NOTE;ENCODING=QUOTED-PRINTABLE:=53=70=69=72=69=74=20=41=69=72=6C=69= +=6E=65=73=20=38=30=30=2D=37=37=32=2D=37=31=31=37=55=6E=69=74=65=64= +=20=41=69=72=6C=69=6E=65=73=20=38=30=30=2D=32=34=31=2D=36=35=32=32 +END:VCARD + +BEGIN:VCARD +VERSION:2.1 +TEL;WORK;PREF:3451112222 +X-SAMSUNGADR;ENCODING=QUOTED-PRINTABLE:;;=31=31=31=31=32=20=4E=6F=72=74=68=20=45=6C=64=72= +=69=64=67=65=20=50=61=72=6B=77=61=79;=44=61=6C=6C=61=73;=54=58;=32=32=32=32=32 +ORG:James Peacock Elementary +END:VCARD + +BEGIN:VCARD +VERSION:2.1 +TEL;CELL:8889990001 +ORG:AAA Car Service +END:VCARD diff --git a/tests/test_vcards_contacts.py b/tests/test_vcards_contacts.py index 62cf603..e737228 100644 --- a/tests/test_vcards_contacts.py +++ b/tests/test_vcards_contacts.py @@ -6,7 +6,30 @@ from Whatsapp_Chat_Exporter.vcards_contacts import normalize_number, read_vcards def test_readVCardsFile(): data_dir = os.path.join(os.path.dirname(__file__), "data") - assert len(read_vcards_file(os.path.join(data_dir, "contacts.vcf"), "852")) > 0 + data = read_vcards_file(os.path.join(data_dir, "contacts.vcf"), "852") + if data: + print("Found Names") + print("-----------------------") + for count, contact_tuple in enumerate(data, start=1): + # The name is the second element of the tuple (at index 1) + name = contact_tuple[1] + + # Print the count and the name + print(f"{count}. {name}") + print(data) + assert len(data) == 6 + # Test simple contact name + assert data[0][1] == "Sample Contact" + # Test complex name + assert data[1][1] == "Yard Lawn Guy, Jose Lopez" + # Test name with emoji + assert data[2][1] == "John Butler 🌟" + # Test note with multi-line encoding + assert data[3][1] == "Airline Contact #'s" + # Test address with multi-line encoding + assert data[4][1] == "James Peacock Elementary" + # Test business entry using ORG but not F/FN + assert data[5][1] == "AAA Car Service" def test_create_number_to_name_dicts(): From 43658a92c4add62298af62842bc1fd17ba8ee04b Mon Sep 17 00:00:00 2001 From: KnugiHK <24708955+KnugiHK@users.noreply.github.com> Date: Sun, 14 Dec 2025 21:57:17 +0800 Subject: [PATCH 4/7] Replace print with logger in read_vcards_file Changed the contact import message from a print statement to a logger.info call for better logging consistency. --- Whatsapp_Chat_Exporter/vcards_contacts.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Whatsapp_Chat_Exporter/vcards_contacts.py b/Whatsapp_Chat_Exporter/vcards_contacts.py index ba2165d..6baf5ba 100644 --- a/Whatsapp_Chat_Exporter/vcards_contacts.py +++ b/Whatsapp_Chat_Exporter/vcards_contacts.py @@ -1,9 +1,12 @@ -import vobject +import logging import re import quopri from typing import List, TypedDict from Whatsapp_Chat_Exporter.data_model import ChatStore -from Whatsapp_Chat_Exporter.utility import Device +from Whatsapp_Chat_Exporter.utility import CLEAR_LINE, Device + + +logger = logging.getLogger(__name__) class ExportedContactNumbers(TypedDict): @@ -77,7 +80,7 @@ def read_vcards_file(vcf_file_path, default_country_code: str): } contacts.append(contact) - print(f"Imported {len(contacts)} contacts/vcards") + logger.info(f"Imported {len(contacts)} contacts/vcards{CLEAR_LINE}") return map_number_to_name(contacts, default_country_code) From ddd0ac3143e913eb6c748f9844dd6df74773801a Mon Sep 17 00:00:00 2001 From: KnugiHK <24708955+KnugiHK@users.noreply.github.com> Date: Sun, 14 Dec 2025 23:00:48 +0800 Subject: [PATCH 5/7] Refactor vCard parsing to improve decoding and structure Replaces regex-based vCard parsing with dedicated functions for parsing lines, handling quoted-printable encoding, and extracting fields. Adds support for CHARSET and ENCODING parameters, improves handling of multi-line and encoded values, and centralizes vCard entry processing for better maintainability and accuracy. --- Whatsapp_Chat_Exporter/vcards_contacts.py | 147 +++++++++++++++++----- tests/test_vcards_contacts.py | 2 +- 2 files changed, 120 insertions(+), 29 deletions(-) diff --git a/Whatsapp_Chat_Exporter/vcards_contacts.py b/Whatsapp_Chat_Exporter/vcards_contacts.py index 6baf5ba..4cb285d 100644 --- a/Whatsapp_Chat_Exporter/vcards_contacts.py +++ b/Whatsapp_Chat_Exporter/vcards_contacts.py @@ -38,14 +38,124 @@ class ContactsFromVCards: chats.add_chat(number + "@s.whatsapp.net", ChatStore(Device.ANDROID, name)) -def decode_vcard_value(value: str) -> str: +def decode_quoted_printable(value: str, charset: str) -> str: """Decode a vCard value that may be quoted-printable UTF-8.""" - try: - value = value.replace("=\n", "") # remove soft line breaks - bytes_val = quopri.decodestring(value) - return bytes_val.decode("utf-8", errors="replace") - except Exception: - return value + bytes_val = quopri.decodestring(value) + return bytes_val.decode(charset, errors="replace") + +def _parse_vcard_line(line: str) -> tuple[str, dict[str, str], str] | None: + """ + Parses a single vCard property line into its components: + Property Name, Parameters (as a dict), and Value. + + Example: 'FN;CHARSET=UTF-8:John Doe' -> ('FN', {'CHARSET': 'UTF-8'}, 'John Doe') + """ + # Find the first colon, which separates the property/parameters from the value. + colon_index = line.find(':') + if colon_index == -1: + return None # Invalid vCard line format + + prop_and_params = line[:colon_index].strip() + value = line[colon_index + 1:].strip() + + # Split property name from parameters + parts = prop_and_params.split(';') + property_name = parts[0].upper() + + parameters = {} + for part in parts[1:]: + if '=' in part: + key, val = part.split('=', 1) + parameters[key.upper()] = val.strip('"') # Remove potential quotes from value + + return property_name, parameters, value + + +def get_vcard_value(entry: str, field_name: str) -> list[str]: + """ + Scans the vCard entry for lines starting with the specific field_name + and returns a list of its decoded values, handling parameters like + ENCODING and CHARSET. + """ + target_name = field_name.upper() + cached_line = "" + charset = "utf-8" + values = [] + + for line in entry.splitlines(): + line = line.strip() + if cached_line: + if line.endswith('='): + cached_line += line[:-1] + continue # Wait for the next line to complete the value + values.append(decode_quoted_printable(cached_line + line, charset)) + cached_line = "" + else: + # Skip empty lines or lines that don't start with the target field (after stripping) + if not line or not line.upper().startswith(target_name): + continue + + parsed = _parse_vcard_line(line) + if parsed is None: + continue + + prop_name, params, raw_value = parsed + + if prop_name != target_name: + continue + + encoding = params.get('ENCODING') + charset = params.get('CHARSET', 'utf-8') + + # Apply decoding if ENCODING parameter is present + if encoding == 'QUOTED-PRINTABLE': + if raw_value.endswith('='): + # Handle soft line breaks in quoted-printable and cache the line + cached_line += raw_value[:-1] + continue # Wait for the next line to complete the value + values.append(decode_quoted_printable(raw_value, charset)) + elif encoding: + raise NotImplementedError(f"Encoding '{encoding}' not supported yet.") + else: + values.append(raw_value) + return values + + +def process_vcard_entry(entry: str) -> dict | bool: + """ + Process a vCard entry using pure string manipulation + + Args: + entry: A string containing a single vCard block. + + Returns: + A dictionary of the extracted data or False if required fields are missing. + """ + + name = None + + # Extract name in priority: FN -> N -> ORG + for field in ("FN", "N", "ORG"): + if name_values := get_vcard_value(entry, field): + name = name_values[0].replace(';', ' ') # Simple cleanup for structured name + break + + if not name: + return False + + # 2. Extract phone numbers + numbers = get_vcard_value(entry, "TEL") + + # Ensure at least one number was found + if not numbers: + return False + + return { + "full_name": name, + # Remove duplications + "numbers": set(numbers), + } + def read_vcards_file(vcf_file_path, default_country_code: str): contacts = [] @@ -58,27 +168,8 @@ def read_vcards_file(vcf_file_path, default_country_code: str): if "END:VCARD" not in vcard: continue - # Extract name in priority: FN -> N -> ORG - name = None - for field in ("FN", "N", "ORG"): - match = re.search(rf'^{field}(?:;[^:]*)?:(.*)', vcard, re.IGNORECASE | re.MULTILINE) - if match: - name = decode_vcard_value(match.group(1).strip()) - break - - if not name: - continue - - # Extract phone numbers - numbers = re.findall(r'^\s*TEL(?:;[^:]*)?:(\+?\d+)', vcard, re.IGNORECASE | re.MULTILINE) - if not numbers: - continue - - contact = { - "full_name": name, - "numbers": numbers, - } - contacts.append(contact) + if contact := process_vcard_entry(vcard): + contacts.append(contact) logger.info(f"Imported {len(contacts)} contacts/vcards{CLEAR_LINE}") return map_number_to_name(contacts, default_country_code) diff --git a/tests/test_vcards_contacts.py b/tests/test_vcards_contacts.py index e737228..2eac4d9 100644 --- a/tests/test_vcards_contacts.py +++ b/tests/test_vcards_contacts.py @@ -23,7 +23,7 @@ def test_readVCardsFile(): # Test complex name assert data[1][1] == "Yard Lawn Guy, Jose Lopez" # Test name with emoji - assert data[2][1] == "John Butler 🌟" + assert data[2][1] == "John Butler 🌟💫🌟" # Test note with multi-line encoding assert data[3][1] == "Airline Contact #'s" # Test address with multi-line encoding From bb10203b449491bd18b7bd4ff70beb6912a2a332 Mon Sep 17 00:00:00 2001 From: KnugiHK <24708955+KnugiHK@users.noreply.github.com> Date: Sun, 14 Dec 2025 23:47:24 +0800 Subject: [PATCH 6/7] Remove vobject dependency from project and workflow Eliminated the use of the vobject library from the codebase, dependency groups, and GitHub Actions workflow. vobject is no longer a dependency for vCards enrichment. --- .github/workflows/compile-binary.yml | 6 +++--- Whatsapp_Chat_Exporter/__main__.py | 19 ++----------------- pyproject.toml | 5 ++--- 3 files changed, 7 insertions(+), 23 deletions(-) diff --git a/.github/workflows/compile-binary.yml b/.github/workflows/compile-binary.yml index 48e459d..bad45ed 100644 --- a/.github/workflows/compile-binary.yml +++ b/.github/workflows/compile-binary.yml @@ -20,7 +20,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install pycryptodome vobject javaobj-py3 ordered-set zstandard nuitka==2.6.7 + pip install pycryptodome javaobj-py3 ordered-set zstandard nuitka==2.6.7 pip install . - name: Build binary with Nuitka run: | @@ -45,7 +45,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install pycryptodome vobject javaobj-py3 ordered-set zstandard nuitka==2.6.7 + pip install pycryptodome javaobj-py3 ordered-set zstandard nuitka==2.6.7 pip install . - name: Build binary with Nuitka run: | @@ -69,7 +69,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install pycryptodome vobject javaobj-py3 ordered-set zstandard nuitka==2.6.7 + pip install pycryptodome javaobj-py3 ordered-set zstandard nuitka==2.6.7 pip install . - name: Build binary with Nuitka run: | diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py index e20fff4..89c7e97 100644 --- a/Whatsapp_Chat_Exporter/__main__.py +++ b/Whatsapp_Chat_Exporter/__main__.py @@ -20,16 +20,8 @@ from argparse import ArgumentParser, SUPPRESS from datetime import datetime from getpass import getpass from sys import exit -from typing import Tuple, Optional, List, Dict, Any, Union - -# Try to import vobject for contacts processing -try: - import vobject -except ModuleNotFoundError: - vcards_deps_installed = False -else: - from Whatsapp_Chat_Exporter.vcards_contacts import ContactsFromVCards - vcards_deps_installed = True +from typing import Optional, List, Dict +from Whatsapp_Chat_Exporter.vcards_contacts import ContactsFromVCards logger = logging.getLogger(__name__) @@ -432,13 +424,6 @@ def process_single_date_filter(parser: ArgumentParser, args) -> None: def setup_contact_store(args) -> Optional['ContactsFromVCards']: """Set up and return a contact store if needed.""" if args.enrich_from_vcards is not None: - if not vcards_deps_installed: - logger.error( - "You don't have the dependency to enrich contacts with vCard.\n" - "Read more on how to deal with enriching contacts:\n" - "https://github.com/KnugiHK/Whatsapp-Chat-Exporter/blob/main/README.md#usage\n" - ) - exit(1) contact_store = ContactsFromVCards() contact_store.load_vcf_file( args.enrich_from_vcards, args.default_country_code) diff --git a/pyproject.toml b/pyproject.toml index 054bbc3..6bc571f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,10 +44,9 @@ android_backup = ["pycryptodome", "javaobj-py3"] crypt12 = ["pycryptodome"] crypt14 = ["pycryptodome"] crypt15 = ["pycryptodome", "javaobj-py3"] -all = ["pycryptodome", "javaobj-py3", "vobject"] -everything = ["pycryptodome", "javaobj-py3", "vobject"] +all = ["pycryptodome", "javaobj-py3"] +everything = ["pycryptodome", "javaobj-py3"] backup = ["pycryptodome", "javaobj-py3"] -vcards = ["vobject", "pycryptodome", "javaobj-py3"] [project.scripts] wtsexporter = "Whatsapp_Chat_Exporter.__main__:main" From 5a80fe189d9b0e0897317716a9450dfb8c046f59 Mon Sep 17 00:00:00 2001 From: KnugiHK <24708955+KnugiHK@users.noreply.github.com> Date: Sun, 14 Dec 2025 23:49:10 +0800 Subject: [PATCH 7/7] Add error handling to quoted-printable decoding Wrapped the decode_quoted_printable function in a try-except block to handle decoding errors gracefully. If decoding fails, a warning is logged and the original value is returned, improving robustness when processing malformed vCard data. --- Whatsapp_Chat_Exporter/vcards_contacts.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/Whatsapp_Chat_Exporter/vcards_contacts.py b/Whatsapp_Chat_Exporter/vcards_contacts.py index 4cb285d..03d60ce 100644 --- a/Whatsapp_Chat_Exporter/vcards_contacts.py +++ b/Whatsapp_Chat_Exporter/vcards_contacts.py @@ -40,8 +40,16 @@ class ContactsFromVCards: def decode_quoted_printable(value: str, charset: str) -> str: """Decode a vCard value that may be quoted-printable UTF-8.""" - bytes_val = quopri.decodestring(value) - return bytes_val.decode(charset, errors="replace") + try: + bytes_val = quopri.decodestring(value) + return bytes_val.decode(charset, errors="replace") + except Exception: + # Fallback: return the original value if decoding fails + logger.warning( + f"Failed to decode quoted-printable value: {value}, " + f"charset: {charset}. Please report this issue.{CLEAR_LINE}" + ) + return value def _parse_vcard_line(line: str) -> tuple[str, dict[str, str], str] | None: """ @@ -143,10 +151,7 @@ def process_vcard_entry(entry: str) -> dict | bool: if not name: return False - # 2. Extract phone numbers numbers = get_vcard_value(entry, "TEL") - - # Ensure at least one number was found if not numbers: return False