vcard-graph

A Python tool to visualize vCard contacts as an interactive graph, showing relationships between people and organizations.

Features

• Parse vCard files (.vcf and .vcard formats) using the vobject library
• Extract standard vCard fields including names, emails, organizations, and relationships
• Build a network graph showing connections between contacts
• Visualize relationships with different colors for different relationship types (spouse, child, parent, friend, colleague, etc.)
• Group contacts by organization
• Generate interactive HTML visualizations using Plotly

Installation

pip install vcard-graph

For development:

pip install -e ".[dev]"

Usage

Command Line

Visualize vCard files:

# Single file
vcard-graph contacts.vcf

# Multiple files
vcard-graph contact1.vcf contact2.vcf contact3.vcf

# From a directory
vcard-graph ~/contacts/ --directory

# Specify output file
vcard-graph contacts.vcf -o my_graph.html

Python API

from pathlib import Path
from vcard_graph import VCardParser, VCardGraph

# Parse vCard files
parser = VCardParser()
parser.parse_file(Path("contacts.vcf"))

# Or parse a directory
parser.parse_directory(Path("~/contacts"))

# Build and visualize the graph
graph = VCardGraph()
graph.build_from_parser(parser)
graph.visualize("output.html")

# Get statistics
stats = graph.get_stats()
print(f"People: {stats['people']}")
print(f"Organizations: {stats['organizations']}")
print(f"Relationships: {stats['relationships']}")

vCard Relationship Support

The tool supports both standard vCard relationships and Apple-specific relationship fields.

Standard RELATED Field (RFC 6350)

The standard RELATED field from vCard 4.0 with TYPE parameter:

RELATED;TYPE=spouse:bob@example.com
RELATED;TYPE=child:alice@example.com
RELATED;TYPE=parent:carol@example.com
RELATED;TYPE=friend:dave@example.com
RELATED;TYPE=colleague:eve@example.com

Apple X-ABRELATEDNAMES

Apple Contacts uses X-ABRELATEDNAMES with item grouping and X-ABLabel:

item1.X-ABRELATEDNAMES:Bob Smith
item1.X-ABLabel:_$!<Friend>!$_
item2.X-ABRELATEDNAMES:Carol Johnson
item2.X-ABLabel:_$!<Mother>!$_
item3.X-ABRELATEDNAMES:Dave Wilson
item3.X-ABLabel:Custom Relation

Apple uses the format _$!<Type>!$_ for standard relationship types and plain text for custom labels.

Supported Relationship Types

All relationship types are visualized with different colors in the graph:

• Family: spouse, partner, child, parent, mother, father, sibling, brother, sister
• Social: friend
• Professional: colleague, assistant, manager
• Other: related (default), custom labels

Each relationship type is visualized with a different color in the graph.

Graph Visualization

The interactive graph shows:

• People as colored circles (color varies by category)
• Organizations as red squares
• Relationships as colored lines (color varies by relationship type)
• Hover over nodes to see details (name, email, organization, categories)
• Legend showing relationship types and categories

Category Colors

Contacts are automatically grouped and color-coded by their vCard CATEGORIES field. Each unique category is assigned a distinct color from a diverse color palette. The visualization:

• Groups contacts spatially by their primary category
• Colors each category distinctly for easy visual identification
• Shows "Uncategorized" in gray for contacts without categories
• Displays all categories in the legend

System categories like "Starred" and "MyContacts" are automatically filtered out.

To assign categories to contacts, add the CATEGORIES field to your vCard:

CATEGORIES:Family,VIP

Any category name you use will automatically get a color assigned!

Development

Run tests:

pytest

Format code:

ruff format .

Check code style:

ruff check .

Type checking:

mypy src

License

Apache License 2.0