[Telepathy] telepathy-python

[Alexandr Akulich]

On Fri, Aug 21, 2015 at 11:41 AM, Diane Trout <diane at ghic.org> wrote:
> On Thursday, August 20, 2015 17:39:12 Nicolas Dufresne wrote:
>> Le mardi 18 août 2015 à 16:59 -0700, Diane Trout a écrit :
>> > My current progress is at:
>> >
>> > https://github.com/detrout/telepathy-python
>>
>> Hmm, but telepathy-glib is fully instrospectable, you don't need
>> manually written bindings. To start using it, simply do:
>>
>>  from gi.repository import TelepathyGLib
>>
>> Nicolas
>
> I knew there was a gi.repostory implementation, but I wasn't sure how complete
> it was. In my experience many other C apis that are ported to python end up
> with some glue python code added on top of the C api in order to make the API
> look more like python. I wasn't sure how well worked out the class wrappers
> would be in gi.repository.
>
> The existence of the gi.repository bindings is also why I was thinking of
> adapting this version to more closely resemble the TelepathyQt bindings as the
> glib people can just use gi.repository.
>
> Also, although gi.repository is a really neat technology, there's no way to
> avoid the fact that the APIs implemented in gi.repository are still glib APIs.
>
> (As an aside is there any documentation about how to create a typelib?)
>
> Also, there's very little documentation available about the gi.repository
> bindings themselves. Not to mention the glib bindings themselves lack any sort
> of user guide, though API docs for the glib bindings appear to be decent.
>
> However I'm used to well written sphinx docs. E.g. compare the following:
>
> http://telepathy.freedesktop.org/doc/telepathy-glib/index.html
> or
> http://telepathy.freedesktop.org/doc/telepathy-qt/index.html
> to
> http://scikit-learn.org/stable/documentation.html
>
> And as an example drilling down to a particular api call:
>
> we have glib:
> http://telepathy.freedesktop.org/doc/telepathy-glib/telepathy-glib-connection-aliasing.html
> Qt:
> http://telepathy.freedesktop.org/doc/telepathy-qt/a00270.html

You pointed to the Adaptor class, which is a generated class, not
intended to be used by a developer. I'm wonder, why we export it.

Correct link to the Connection Aliasing interface Qt/C++ API is:
http://telepathy.freedesktop.org/doc/telepathy-qt/a00117.html

That said, the documentation is even worse, than you think.

As TpQt developer, I think it's more important to implement all
features, than write documentation, because you always can use the
spec as documentation.
http://telepathy.freedesktop.org/spec/Connection_Interface_Aliasing.html
TpQt API is mostly a mirror of specification. The mentioned Aliasing
interface is fully (for 100%) generated from the XML by
https://github.com/TelepathyQt/telepathy-qt-generator.
It is possible to improve the generator to copy the documentation from
spec, but it doesn't worth it yet.

We have a special case with FileTransfer API, which is different from
the spec, thus we added a documentation for it:
https://github.com/TelepathyQt/telepathy-qt/blob/master/TelepathyQt/base-channel.cpp#L952
> Sphinx:
> http://scikit-learn.org/stable/modules/generated/sklearn.cluster.DBSCAN.html#sklearn.cluster.DBSCAN
>
> Sphinx has cross references, individual calls have paragraph anchor markers,
> there are links to the source
>
> I had been contemplating if it was possible to take the old Telepathy
> Developer's Manual and convert it into a sphinx tree and generate a more up-
> to-date user guide + api docs. (I wasn't sure how free the documentation
> license was)
>
> Also in trying to use the gi.repository bindings I tried the following:
>
> In [1]: from gi.repository import TelepathyGLib as tp
>
> In [2]: tp.ConnectionManager()
>
> (process:22488): tp-glib-CRITICAL **: tp_proxy_constructor: assertion 'self-
>>dbus_connection != NULL' failed
> Segmentation fault
>
> The pure python telepathy bindings have never ever segfaulted on me. I used
> them to repeatedly crash plasmashell, but no matter how poorly I understood
> the telepathy dbus bindings python never crashed.
>
> Further introspecting on the ConnectionManager object:
>
> ConnectionManager(**properties)
> new(dbus:TelepathyGLib.DBusDaemon, name:str, manager_filename:str=None) ->
> TelepathyGLib.ConnectionManager
>
> suggests it might want a dbus and str parameter, however:
>
> In [6]: tp.ConnectionManager(bus, 'foo')
> ---------------------------------------------------------------------------
> TypeError                                 Traceback (most recent call last)
> <ipython-input-6-b863bc8f3613> in <module>()
> ----> 1 tp.ConnectionManager(bus, 'foo')
>
> TypeError: GObject.__init__() takes exactly 0 arguments (2 given)
>
> It's kind of baffling how you might use that class.
>
> If that's a bug and not user error I'm on Debian using:
> Package: gir1.2-telepathyglib-0.12
> Version: 0.24.1-1
>
> Diane
> _______________________________________________
> telepathy mailing list
> telepathy at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/telepathy