Online Python documentation incomplete
It seems that the online documentation of the Python interface is incomplete. I did not go through everything, but I found the following inconsistencies and problems.
Would it be possible to expose more documentation on the homepage? I am not sure if some documentation is simply missing or not generated on purpose. In all cases that I have checked the classes and methods have a documentation accessible via Python's help(...)
function.
Observations
VolumeDataLayoutDescriptor
I do not find anything about the constructors of class VolumeDataLayoutDescriptor
in the online documentation. When I query the documentation via Python I get much more information including the constructor.
That means if I do the following in a Python session
import openvds
help(openvds.VolumeDataLayoutDescriptor)
gives the following (shortened) output
Help on class VolumeDataLayoutDescriptor in module openvds.core:
class VolumeDataLayoutDescriptor(pybind11_builtins.pybind11_object)
| Method resolution order:
| VolumeDataLayoutDescriptor
| pybind11_builtins.pybind11_object
| builtins.object
|
| Methods defined here:
|
| __init__(...)
| __init__(*args, **kwargs)
| Overloaded function.
|
| 1. __init__(self: openvds.core.VolumeDataLayoutDescriptor) -> None
|
| 2. __init__(self: openvds.core.VolumeDataLayoutDescriptor, brickSize: OpenVDS::VolumeDataLayoutDescriptor::BrickSize, negativeMargin: int, positiveMargin: int, brickSize2DMultiplier: int, lodLevels: OpenVDS::VolumeDataLayoutDescriptor::LODLevels, options: OpenVDS::VolumeDataLayoutDescriptor::Options, fullResolutionDimension: int = 0) -> None
|
...
As you can see there is some information on the constructor.
VolumeDataRequest
There are (at least?) two types of VolumeDataRequest
, but only one is documented in the online documentation.
The documentation explains the usage of an object of type openvds.core.VolumeDataRequest
, see
>>> import openvds
>>> data_request = openvds.VolumeDataRequest
>>> print(data_request)
<class 'openvds.core.VolumeDataRequest'>
>>> buffer = data_request.buffer
>>> data = data_request.data
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: type object 'openvds.core.VolumeDataRequest' has no attribute 'data'
This class does not have any attribute called data
so the error is correct.
However, a function call to the function requestVolumeSubset
of a VolumeDataAccessManager
will return an object of type openvds.volumedataaccess.VolumeDataRequest
with different interface which has a property called data
instead of buffer
.
>>> import openvds
>>> data_request = openvds.volumedataaccess.VolumeDataRequest
>>> print(data_request)
<class 'openvds.volumedataaccess.VolumeDataRequest'>
>>> buffer = data_request.buffer
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: type object 'VolumeDataRequest' has no attribute 'buffer'
>>> data = data_request.data
This class does not have a buffer
attribute so the error message is fine. It is not clear from the documentation of VolumeDataAccessManager
that the return type is not a openvds.core.VolumeDataRequest
.
openvds.IJKCoordinateTransformer
There is no documentation on the IJKCoordinateTransformer
for Python even though it is accessible from Python
>>> transformer = openvds.IJKCoordinateTransformer
>>> print(transformer)
<class 'openvds.core.IJKCoordinateTransformer'>
VolumeDataAccessManager
The type annotation for the constructor of the handle
seems to be off as it is int
, but should be openvds.core.VDS
.
>>> vdam = openvds.VolumeDataAccessManager
>>> print(vdam)
<class 'openvds.volumedataaccess.VolumeDataAccessManager'>
>>> vdam = openvds.VolumeDataAccessManager(1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/Users/aej/software/openvds-3.0.3-install-python/python/openvds/volumedataaccess.py", line 184, in __init__
self._manager = openvds.core.getAccessManager(handle)
TypeError: getAccessManager(): incompatible function arguments. The following argument types are supported:
1. (handle: openvds.core.VDS) -> OpenVDS::VolumeDataAccessManager
Invoked with: 1
Update: In the last case, supplying an object of type openvds.core.VDS
also fails so I assume the documentation might be off here or I misunderstand something.