Package: bguo
File-based contact managementConceptEach contact corresponds to a single file inside of the bguo directory.
Contact information should be edited in this directory and then exported
to various output formats for use by other programs. They can also be
roughly imported to this directory, but you will have to proofread the
results; the importers are intended for one-time imports, not for
regular synchronization with other programs.For our purposes, a contact is a thing with a single name.
People, mailing lists, and organizations can all be
contacts. bguo has no special features for grouping contacts.bguo contact file formatHere is an example of a contact file.name: Thomas Levine
email: sngmscrmrchroh@thomaslevine.com
phone: 8835 1000 990 2082
x-favorite-color: pinkThe contact file format is similar to that of an email
(RFC-5322internet message)
except for the following changes.Header names are different. (See below.)Line breaks do not need to include carriage returns;
it is acceptable to break lines either with CRLF or just LF.Non-ASCII data may be included in headers; MIME encoded-word syntax is
optional.The message body must be empty.A contact file may contain any of the following case-insensitive fields
and any field beginning with “x-” or “X-“.nameName of a person, mailing list, organization, &c.name-latinSame as “name”, but used when “name” isn’t acceptable for the output
format because it is in a different alphabetphoneTelephone numberemail*Email addressfeed*News feed address, like for an RSS or Atom feedwebWebsite addresspostPostal addressbguo will report an error if any other field is present.
Fields marked with “*” may be included multiple times;
other fields may be included only once.UsageInstallpip3 install bguoThe Seltzer importer has a special dependency. If you need the Seltzer
importer, install like this in order to ensure that the dependency is met.pip3 install ‘bguo[seltzer]’Helpbguo -hExamples are distributed with the package, in the “examples” directory.
pip downloads the package, but you can download the packagefrom PyPI, and you can download
the development versionfrom thomaslevine.com.Here is how you can download the development version and run the examples.wget https://thomaslevine.com/scm/bguo/tarball/bguo.tar.gz
tar xzf bguo.tar.gz
cd bguo/examples
make clean
makeSupported formatsbguo supports only the formats that I (Tom) have used.
Let’s separate the formats into two groups. The first group of formats
is for specific integrations with other software.konftelKonftel 300IPphonebook filemhMHaliases filemuttMuttalias_filenewsbeuterNewsbeuter~/.newsbeuter/urlsseltzerSeltzer CRMmember listing (/?q=members)voipmsVoIP.msphonebook exportThe second group is generic exports that could be helpful for making
your own exports.python (the default)Python string representation, as a list of dicts, one dict per contactcustomYour own format, specified as a Pythonformat string,
using the fields that you can check with thebguo formatsubcommandThe format arguments include all of the raw fields from the contact file
format (name, name-latin, &c.) and the following derived fields.phone-numericPhone number from the “phone” field with non-numeric characters removedpost-formattedPostal address from the “post” field formatted for inclusion on a
letter, with the contact’s name or identifier and with slashes
replaced by line breaks.For most of these formats, only the import or the export is supported,
not both. This is summarized in the table below.FormatImportExportKonftelNoYesMHYesYesMuttYesYesNewsbeuterYesYesSeltzerYesNoVoIP.msYesNoPythonNoYesCustomNoYesFor imports, command-line program expects that you are converting from
only one format to bguo. To merge multiple formats during an export,
write a custom merging program with the functions inbguo.parse.
I did this once with email addresses (MH) and phone numbers (VoIP.MS);
seeexamples/merge.py.Export workflowLet us categorize exports into two types.STDOUT is sent to a configuration file.STDOUT is sent directly to another program.An example of the former type is the MH format; I run a command like this,
and my contacts are made available when I am composing emails.bguo export ./my-contacts mh > ~/mh/aliasesAn example of the latter type is connecting the generic phone number
export to a Session Initicialization Protocol (SIP) client; I can call
myself with the following command.pjsua "$(bguo export ./thomas.levine custom 'sip:{phone-numeric}@paris.voip.ms')"