The response to the first half of your question is: unfortunately, great documentation oriented toward the Python-UNO interface does not currently exist. A Python-LibO interface (in the form of UNO) certainly exists, as you have found, but it is neither robust, nor well-documented. Further, there does not seem to be anyone on the LibO dev list who is actively focused on this particular area. There are scant few functional tests of the Python-UNO interface (that ensure that changes do not unintentionally change user-facing APIs), and there does not appear to be any active development on this front.
However, the Python-UNO interface is basically a veneer over the C++ APIs, as are the other language-level interfaces. Thus, if you can track down another language-level API for UNO, or have the ability read the C++ documentation and/or code, you may have some success translating for your use cases.
Clearly, this is not ideal, and the best workaround I’ve come up with is targeted introspection of the API through use of a drop-in REPL shell. IPython works wonders for this purpose. Consider something like this (or more complete examples ):
ctxt = pyuno.getComponentContext()
smgr = ctxt.ServiceManager
desktop = smgr.createInstanceWithContext('com.sun.star.frame.Desktop', ctxt)
url = 'private:factory/swriter'
doc = desktop.loadComponentFromURL( url, '_blank', 0, () )
from IPython import embed as II
II() # <--- this creates a shell right "here", as if you had typed
# the above commands. For example, try typing 'doc.[tab][tab]'
# to see what IPython can find as possible accessible attributes
# on the doc object.
My choice of “II” is clearly arbitrary, stemming from some measure of lazy. I often put the import statement at the top of a script, and then know that I can type “II()” anywhere I’d like to poke around. 3 letters and typos saved …
Having use of a REPL with the exact context of the program is really helpful. In my opinion, the IPython interface is “better” because it offers many additional “goodies” which many of the Python debugging packages don’t.
Finally, a plug: if you can create functional tests of issues you note with LibO, please do so and submit them. In general, I’d argue that LibO suffers from a weak set of unit and functional tests, and would benefit from folks such as yourself: drive-by coders who happen to notice errant behavior.