How to create multiple components of the same kind

[drzraf]

What the right way to add multiple components like one PREF+WORK phone + one HOME phone number?

j = vobject.vCard()
j.add('fn')
j.fn.value = "Foo"
j.add('tel')
j.tel.value = "+12345"
j.tel.type_param = "WORK"
# Add a HOME phone
# j.add('tel')   # won't work: override the existing tel
# j.tel.value = "+67890"
# j.tel.type_param = "HOME"

I found nothing in the doc or the tests and the code itself didn't make it self-explanatory either.

I also wonder about type_param = ["PREF", "HOME"] which creates entries like TEL;TYPE=CELL,PREF:+123456 (apparently conforming to the standard) meanwhile several tests contains another syntax, like:

vobject/tests/test_vobject.py

Line 30 in 43223ae

assert vobject.base.parseLine("EMAIL;PREF;INTERNET:[email protected]") == ('EMAIL', [['PREF'], ['INTERNET']], '[email protected]', None)

vobject/test_files/radicale-1238-0.ics

Line 8 in 43223ae

TEL;TYPE=WORK;TYPE=pref:+61 2 8056 8588

[da4089]

Let me answer the second part first.

There are three versions of the vCard specification in use: 2.1, 3.0, and 4.0.

In vCard 2.1, the "TEL" element can have type parameters, whose names can be "HOME", "WORK", etc, but also "PREF", indicating a "preferred number". The example from the spec is:

TEL;PREF;WORK;MSG;FAX:+1-800-555-1234

In vCard 3.0, this was changed. To quote the spec,

These type parameter values can be specified as a parameter list (i.e., "TYPE=work;TYPE=voice") or as a value list (i.e., "TYPE=work,voice").

So rather than the old syntax with a list of semi-colon separated values after the TEL, there's now either "TYPE=foo,bar,baz" OR "TYPE=foo;TYPE=bar;TYPE=baz" styles.

The example from the 3.0 spec shows that "PREF" is still a type of number, like "HOME", etc.

TEL;TYPE=work,voice,pref,msg:+1-213-555-1234

In vCard 4.0, this was changed again. A preferred number is now indicated by a separate parameter. The example from the 4.0 spec is (ignore the "VALUE=uri" bit, and the quotes around the TYPE parameter's values -- those are different changes):

 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555

The key thing is that PREF is now an independent parameter, a peer of TYPE, rather than a possible value of TYPE.

The first test case you cited is testing the 2.1-era syntax (for email, but they're the same). The second example is 3.0 syntax, using two TYPE parameters each with a single value, including the one with "pref". We don't yet support vCard 4.0, but it's on the list ...

I hope this helps clarify the context. I appreciate that it's a bit of a nightmare :-)

[drzraf]

Very insightful. Thank you for summarizing this "volatile" aspect of the specs' !

Regarding question 1, do you happen to have the answer regarding library usage when it comes to multiple TEL/EMAIL/... fields? Is there something obvious about the syntax/usage that I overlooked?

[da4089]

Nothing obvious, but once it's explained, hopefully it's easy enough to use. See below.

[da4089]

Firstly, allow me to say that the programmer's API for vObject is, well ... awful. I have plans to improve that, but for now we're stuck with 21 year old decisions that don't seem too good from this end of history (no disrespect to Jeffrey Harris, but Python style in 2025 is a little different!)

Now, the practical:

I suggest a slightly different pattern when adding components to a card, which makes this easier: save the created component as a local variable.

j = vobject.vCard()
fn = j.add('fn')
fn.value = "Foo"

This has no real value over the j.tel.value = "Foo" syntax in simple cases, but it does make access easier when dealing with multiple same-named components.

Step 1, using that syntax, it's easy to create and populate a second TEL component:

j = vobject.vCard()
fn = j.add('fn')
fn.value = "Foo"
work_tel = j.add('tel')
work_tel.value = "+12345"
home_tel = j.add('tel')
home_tel.value = "+67890"

print(j.serialize())
BEGIN:VCARD
FN:Foo
TEL:+12345
TEL:+67890
END:VCARD

Step 2, the syntax for parameters is non-intuitive, but it does (mostly) work. The value of a parameter is actually a list. For example, reflecting "TYPE=WORK,HOME" the internal value is ['WORK', 'HOME'].

foo_param is used to access the parameter named "foo", but hides the fact that it's actually a list: it will only access the first element of the parameter's list of values.

foo_paramlist is used to access the full parameter value list for "foo". With some caveats as discussed below.

With that understanding, your example can become:

j = vobject.vCard()
fn = j.add('fn')
fn.value = "Foo"
work_tel = j.add('tel')
work_tel.value = "+12345"
work_tel.type_paramlist = ['WORK', 'PREF']
home_tel = j.add('tel')
home_tel.value = "+16789"
home_tel.type_param = 'HOME'

The first caveat is that the parameter's value list doesn't exist unless you assign to it. So, for instance,

work_tel = j.add('tel')
work_tel.value = "+12345"
work_tel.type_paramlist.extend(['WORK', 'PREF'])

will throw a KeyError: 'TYPE', because the parameter and its value list haven't been created yet.

The second caveat is that internally, vObject stores the parameters of a component as a standard Python dictionary, with string keys (like, "TYPE") and a list of strings (like ["WORK", "PREF"]) as the value. Because of this, there's no way for vObject to store the vCard 3.0 syntax of TYPE=work;TYPE=pref: it will normalize that to TYPE=work,pref, and when serializing, that's what it will emit.

Sorry for the long-winded response, but I hope this both explains both how to make it work, and why that's needed!

[drzraf]

Wow ! Wonderful hints which helped me so much. (I should have thought about add() return value but got confused by base.py add() returning... obj which wasn't immediately obvious)

I confirm the non-intuitive nature of some parts of the API (and most of all, the magicness of the attributes and the readability of some Python functions). But the library is handy and works well once these aspects are overcome.

I suggest to add the couple of examples from your above posts discussion to the documentation.
Thank you very much David for your detailed and helpful answers, keep up the good work!

[da4089]

Thanks @drzraf !

I think you're right -- the magic getattr/setattr hacks make it very difficult to understand what you should do, and their caveats just make it worse. But, as you say, it does work once you get past that.

I'm working on some new documentation, with more details, and available at https://vobject.readthedocs.io/latest/ I will see if some of this discussion could be edited in there.