From 6ddcd028bf3507bf44cfc47c9a5d999a967b1135 Mon Sep 17 00:00:00 2001 From: relikd Date: Sun, 18 Jan 2026 14:45:24 +0100 Subject: [PATCH] ref: update readme --- CHANGELOG.md | 6 +++ README.md | 80 ++++++++++++++++++++++++++++++---------- abcddb2vcard/__init__.py | 2 +- 3 files changed, 68 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index afa4b87..3de29a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project does adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.2.2] – 2026-01-18 +### Changed +- Update readme + + ## [1.2.1] – 2025-12-03 ### Fixed - Soft-fail on unknown social service types. (continue export even if a service field fails) @@ -45,6 +50,7 @@ and this project does adhere to [Semantic Versioning](https://semver.org/spec/v2 +[1.2.2]: https://github.com/relikd/abcddb2vcard/compare/v1.2.1...v1.2.2 [1.2.1]: https://github.com/relikd/abcddb2vcard/compare/v1.2.0...v1.2.1 [1.2.0]: https://github.com/relikd/abcddb2vcard/compare/v1.1.1...v1.2.0 [1.1.1]: https://github.com/relikd/abcddb2vcard/compare/v1.1.0...v1.1.1 diff --git a/README.md b/README.md index 05560ca..4590b7d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ This python script reads an AddressBook database file (`AddressBook-v22.abcddb`) and export its content to a vCard file (`.vcf`). -I created this script to automate my contacts backup procedure. The output of this script should be exactly the same as dragging and dropping the "All Contacts" card. +I created this script to automate my contacts backup procedure. +The output of this script should be exactly the same as dragging and dropping the "All Contacts" card. + ## Installation @@ -12,12 +14,6 @@ To install `abcddb2vcard` from [PyPi](https://pypi.org/project/abcddb2vcard/), u pip install abcddb2vcard ``` -Or - -```sh -pip3 install abcddb2vcard -``` - `abcddb2vcard` can then be used from any working directory in the Terminal. To uninstall: @@ -26,32 +22,71 @@ To uninstall: pip uninstall abcddb2vcard ``` -Or - -```sh -pip3 uninstall abcddb2vcard -``` ## Usage +Export all contacts + ```sh abcddb2vcard backup/contacts_$(date +"%Y-%m-%d").vcf ``` -> assuming db is located at "~/Library/Application Support/AddressBook/AddressBook-v22.abcddb" - -### Export into individual files +Export into individual files ```sh abcddb2vcard outdir -s 'path/%{fullname}.vcf' ``` -### Extract contact images +Extract contact images ```sh vcard2img AllContacts.vcf ./profile_pics/ ``` + +### Usage help + +#### abcddb2vcard + +``` +usage: abcddb2vcard [-h] [-f] [--dry-run] [-i AddressBook.abcddb] [-s FORMAT] + outfile.vcf + +Extract data from AddressBook database (.abcddb) to Contacts VCards file +(.vcf) + +positional arguments: + outfile.vcf VCard output file. + +optional arguments: + -h, --help show this help message and exit + -f, --force Overwrite existing output file. + --dry-run Do not write file(s), just print filenames. + -i AddressBook.abcddb, --input AddressBook.abcddb + Specify another abcddb input file. Default: + ~/Library/Application Support/AddressBook/AddressBook-v22.abcddb + -s FORMAT, --split FORMAT + Output into several vcf files instead of a single + file. File format can use any field of type Record. + E.g. "%{id}_%{fullname}.vcf". +``` + +#### vcard2img + +``` +usage: vcard2img [-h] infile.vcf outdir + +Extract all profile pictures from a Contacts VCards file (.vcf) + +positional arguments: + infile.vcf VCard input file. + outdir Output directory. + +optional arguments: + -h, --help show this help message and exit +``` + + ## Supported data fields - `firstname` @@ -79,12 +114,19 @@ vcard2img AllContacts.vcf ./profile_pics/ - `image` - `iscompany` + ## Limitations -The `image` field currently only supports JPG images. But as far as I see, Apple converts PNG to JPG before storing the image. If you encounter a db which includes other image types, please let me know. +Currently, the `image` field only supports JPG images. +But as far as I see, Apple converts PNG to JPG before storing the image. +If you encounter a db which includes other image types, please let me know. + ## Disclaimer -You should check the output for yourself before using it in a production environment. I have tested the script with many arbitrary fields, however there may be some edge cases missing. Feel free to create an issue for missing or wrong field values. +You should check the output for yourself before using it in a production environment. +I have tested the script with many arbitrary fields, however there may be some edge cases missing. +Feel free to create an issue for missing or wrong field values. -> **Note:** The output of `diff` or `FileMerge.app` can be different to this output. Apple does some weird transformations on vcf export that are not only unnecessary but in many cases break the re-import of the file. +> **Note:** The output of `diff` or `FileMerge.app` can be different to this output. +Apple uses some data transformations (on vcf export) which are not only unnecessary but may break the re-import of the file. diff --git a/abcddb2vcard/__init__.py b/abcddb2vcard/__init__.py index 587fcd9..382754d 100644 --- a/abcddb2vcard/__init__.py +++ b/abcddb2vcard/__init__.py @@ -2,6 +2,6 @@ ''' Convert AddressBook database (.abcddb) to Contacts VCards file (.vcf) ''' -__version__ = '1.2.1' +__version__ = '1.2.2' from .ABCDDB import ABCDDB