DynamicListBuilder documentation wrong and init method does not work

[timthelion]

The docs for DynamicListBuilder claim you should pass an undocumented string "phones" to the init method:

        phones = person.init('phones', 2) # This returns a _DynamicListBuilder

https://github.com/capnproto/pycapnp/blame/master/capnp/lib/capnp.pyx#L476

But init takes an int.

    cpdef init(self, index, size):
        """A method for initializing an element in a list
        :type index: int
        :param index: The index of the element in the list
        :type size: int
        :param size: Size of the element to be initialized.
        """
        return to_python_builder(self.thisptr.init(index, size), self._parent)

https://github.com/capnproto/pycapnp/blame/master/capnp/lib/capnp.pyx#L541

I also cannot find any combination of values that can be sent to this method which don't result in a crash.

>>> f=a.userFields.init("foo",3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "capnp/lib/capnp.pyx", line 541, in capnp.lib.capnp._DynamicListBuilder.init
  File "capnp/lib/capnp.pyx", line 550, in capnp.lib.capnp._DynamicListBuilder.init
TypeError: an integer is required
>>> f=a.userFields.init(2,3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "capnp/lib/capnp.pyx", line 541, in capnp.lib.capnp._DynamicListBuilder.init
  File "capnp/lib/capnp.pyx", line 550, in capnp.lib.capnp._DynamicListBuilder.init
capnp.lib.capnp.KjException: capnp/dynamic.c++:1248: failed: expected index < this->size(); List index out-of-bounds.
stack: 7fc70f429ead 7fc70f42a5d2 4d7913 5526a7 54bcc1 54e0a2 630ce1 480b9a 480d1c 631bf2 65432d 65468d 7fc7100ab09a 5e0e89
>>> f=a.userFields.init(2,3000)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "capnp/lib/capnp.pyx", line 541, in capnp.lib.capnp._DynamicListBuilder.init
  File "capnp/lib/capnp.pyx", line 550, in capnp.lib.capnp._DynamicListBuilder.init
capnp.lib.capnp.KjException: capnp/dynamic.c++:1248: failed: expected index < this->size(); List index out-of-bounds.
stack: 7fc70f429ead 7fc70f42a5d2 4d7913 5526a7 54bcc1 54e0a2 630ce1 480b9a 480d1c 631bf2 65432d 65468d 7fc7100ab09a 5e0e89
>>> f=a.userFields.init(2000,0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "capnp/lib/capnp.pyx", line 541, in capnp.lib.capnp._DynamicListBuilder.init
  File "capnp/lib/capnp.pyx", line 550, in capnp.lib.capnp._DynamicListBuilder.init
capnp.lib.capnp.KjException: capnp/dynamic.c++:1248: failed: expected index < this->size(); List index out-of-bounds.
stack: 7fc70f429ead 7fc70f42a5d2 4d7913 5526a7 54bcc1 54e0a2 630ce1 480b9a 480d1c 631bf2 65432d 65468d 7fc7100ab09a 5e0e89
>>> 

This is my version info.

    LIBCAPNP_VERSION = 8000
    LIBCAPNP_VERSION_MAJOR = 0
    LIBCAPNP_VERSION_MICRO = 0
    LIBCAPNP_VERSION_MINOR = 8
    short_version = '1.0.0'
    version = '1.0.0'

[kentonv]

phones = person.init('phones', 2) # This returns a _DynamicListBuilder

In this line, person is not a list -- it is a builder for a struct of type Person as defined here in the address book example. This method is initializing the field of the struct called phones. That field is a list, so the caller also passes the desired size (2), and the method returns a list builder.

[timthelion]

What is the init method on the DynamicListBuilder for?

[kentonv]

When you have a list-of-lists, like List(List(UInt64)), then you need a way to initialize one element of the outer list. Since the element is itself a list, you then need to pass the size of the new inner list.