vcf_to_obsidian

vcf-to-obsidian-vcf-contacts

A Python module that batch-converts VCF files into Markdown files that are compatible with obsidian-vcf-contacts plugin for ObsidianMD.

Author: Ian Dennis Miller License: MIT

Submodules

• vcf_to_obsidian.cli
• vcf_to_obsidian.filename_generator
• vcf_to_obsidian.markdown_writer
• vcf_to_obsidian.vcf_converter
• vcf_to_obsidian.vcf_reader

Classes

VCFReader	Class responsible for reading and parsing VCF files.
MarkdownWriter	Class responsible for generating Markdown content from vCard objects.
FilenameGenerator	Class responsible for generating output filenames from vCard objects.
VCFConverter	Class responsible for converting VCF files to Markdown format.

Package Contents

class vcf_to_obsidian.VCFReader

Class responsible for reading and parsing VCF files.

is_valid_uuid(uid_value)

Check if a UID value is a valid UUID.

Parameters:

uid_value (str) – UID value to validate

Returns:

True if valid UUID, False otherwise

Return type:

bool

read_vcf_file(vcf_path)

Read and parse a VCF file using vobject.

Parameters:

vcf_path (Path) – Path to the VCF file

Returns:

Parsed vCard object

Return type:

vobject.vCard

Raises:

Exception – If file cannot be read or parsed

class vcf_to_obsidian.MarkdownWriter

Class responsible for generating Markdown content from vCard objects.

generate_obsidian_markdown(vcard)

Generate Markdown content compatible with obsidian-vcf-contacts plugin. Works directly with vobject instead of intermediate representation.

Parameters:

vcard – vobject vCard object

Returns:

Markdown content with frontmatter

Return type:

str

class vcf_to_obsidian.FilenameGenerator

Class responsible for generating output filenames from vCard objects.

generate_filename(vcard, vcf_path)

Generate an output filename based on vCard data with priority logic.

Priority: 1. Full Name (FN) field 2. Constructed name from given + family names 3. UID field 4. Original VCF filename

Parameters:

• vcard – vobject vCard object

• vcf_path (Path) – Original VCF file path

Returns:

Safe filename (without extension)

Return type:

str

_clean_filename(filename)

Clean a filename to make it filesystem-safe.

Parameters:

filename (str) – Original filename

Returns:

Cleaned filename safe for filesystem use

Return type:

str

find_existing_files_with_uid(output_dir, uid)

Find existing Markdown files in output directory that have the same UID.

Parameters:

• output_dir (Path) – Output directory to search

• uid (str) – UID to search for

Returns:

List of Path objects for files with matching UID

Return type:

list

class vcf_to_obsidian.VCFConverter

Class responsible for converting VCF files to Markdown format.

reader

writer

filename_gen

_extract_rev_timestamp_from_markdown(markdown_path)

Extract REV timestamp from existing Markdown file.

Parameters:

markdown_path (Path) – Path to the Markdown file

Returns:

REV timestamp as datetime object, or None if not found

Return type:

datetime or None

_should_skip_conversion(vcf_path, markdown_path)

Check if conversion should be skipped based on file modification times.

Parameters:

• vcf_path (Path) – Path to the VCF file

• markdown_path (Path) – Path to the Markdown file

Returns:

True if conversion should be skipped, False otherwise

Return type:

bool

convert_vcf_to_markdown(vcf_path, output_dir)

Convert a single VCF file to Markdown format.

Parameters:

• vcf_path (Path) – Path to the VCF file

• output_dir (Path) – Output directory for Markdown files

Returns:

True if successful, False otherwise

Return type:

bool

convert_vcf_files_from_sources(folder_sources, file_sources, output_dir, ignore_files=None, verbose=False)

Convert VCF files from multiple sources (folders and individual files) to Markdown format.

This method collects VCF files from the specified sources, applies ignore filters, and processes them directly using convert_vcf_to_markdown.

Parameters:

• folder_sources (list) – List of Path objects for directories containing VCF files

• file_sources (list) – List of Path objects for individual VCF files

• output_dir (Path) – Output directory for Markdown files

• ignore_files (list, optional) – List of Path objects for files to ignore

• verbose (bool) – Whether to enable verbose output

Returns:

(successful_count, total_count, all_vcf_files)

Return type:

tuple

process_tasks(folder, obsidian, file, verbose, ignore)

Process VCF conversion tasks from CLI arguments.

This method handles the complete CLI workflow including validation, file collection, processing, and reporting.

Parameters:

• folder – Tuple/list of folder paths containing VCF files

• obsidian – Path to destination directory for Markdown files

• file – Tuple/list of individual VCF file paths to process

• verbose – Boolean flag for verbose output

• ignore – Tuple/list of VCF file paths to ignore