Skip to content

Commit

Permalink
[PyOV] Add doc strings to Python Remote API functions (openvinotoolki…
Browse files Browse the repository at this point in the history 
…t#23030)

### Details:
 - Added documentation to Python Remote API functions and classes.

### Tickets:
 - *129478*
  • Loading branch information
Jan Iwaszkiewicz authored Feb 23, 2024
1 parent 8440051 commit 05b0fca
Show file tree
Hide file tree
Showing 2 changed files with 178 additions and 34 deletions.
109 changes: 98 additions & 11 deletions src/bindings/python/src/pyopenvino/core/remote_context.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,33 @@ namespace py = pybind11;
void regclass_RemoteContext(py::module m) {
py::class_<RemoteContextWrapper, std::shared_ptr<RemoteContextWrapper>> cls(m, "RemoteContext");

cls.def("get_device_name", [](RemoteContextWrapper& self) {
return self.context.get_device_name();
});
cls.def(
"get_device_name",
[](RemoteContextWrapper& self) {
return self.context.get_device_name();
},
R"(
Returns name of a device on which the context is allocated.
:return: A device name string in fully specified format `<device_name>[.<device_id>[.<tile_id>]]`.
:rtype: str
)");

cls.def(
"get_params",
[](RemoteContextWrapper& self) {
return self.context.get_params();
},
R"(
Returns a dict of device-specific parameters required for low-level
operations with the underlying context.
Parameters include device/context handles, access flags, etc.
Content of the returned dict depends on remote execution context that is
currently set on the device (working scenario).
cls.def("get_params", [](RemoteContextWrapper& self) {
return self.context.get_params();
});
:return: A dictionary of device-specific parameters.
:rtype: dict
)");

cls.def(
"create_tensor",
Expand All @@ -35,15 +55,42 @@ void regclass_RemoteContext(py::module m) {
},
py::arg("type"),
py::arg("shape"),
py::arg("properties"));
py::arg("properties"),
R"(
Allocates memory tensor in device memory or wraps user-supplied memory handle
using the specified tensor description and low-level device-specific parameters.
Returns the object that implements the RemoteTensor interface.
:param type: Defines the element type of the tensor.
:type type: openvino.Type
:param shape: Defines the shape of the tensor.
:type shape: openvino.Shape
:param properties: dict of the low-level tensor object parameters.
:type properties: dict
:return: A remote tensor instance.
:rtype: openvino.RemoteTensor
)");

cls.def(
"create_host_tensor",
[](RemoteContextWrapper& self, const ov::element::Type& type, const ov::Shape& shape) {
return self.context.create_host_tensor(type, shape);
},
py::arg("type"),
py::arg("shape"));
py::arg("shape"),
R"(
This method is used to create a host tensor object friendly for the device in
current context. For example, GPU context may allocate USM host memory
(if corresponding extension is available), which could be more efficient
than regular host memory.
:param type: Defines the element type of the tensor.
:type type: openvino.Type
:param shape: Defines the shape of the tensor.
:type shape: openvino.Shape
:return: A tensor instance with device friendly memory.
:rtype: openvino.Tensor
)");
}

void regclass_VAContext(py::module m) {
Expand All @@ -59,7 +106,20 @@ void regclass_VAContext(py::module m) {
}),
py::arg("core"),
py::arg("display"),
py::arg("target_tile_id") = -1);
py::arg("target_tile_id") = -1,
R"(
Constructs remote context object from valid VA display handle.
:param core: OpenVINO Runtime Core object.
:type core: openvino.Core
:param device: A valid `VADisplay` to create remote context from.
:type device: Any
:param target_tile_id: Desired tile id within given context for multi-tile system.
Default value (-1) means that root device should be used.
:type target_tile_id: int
:return: A context instance.
:rtype: openvino.VAContext
)");

cls.def(
"create_tensor_nv12",
Expand All @@ -75,7 +135,20 @@ void regclass_VAContext(py::module m) {
},
py::arg("height"),
py::arg("width"),
py::arg("nv12_surface"));
py::arg("nv12_surface"),
R"(
This function is used to obtain a NV12 tensor from NV12 VA decoder output.
The result contains two remote tensors for Y and UV planes of the surface.
:param height: A height of Y plane.
:type height: int
:param width: A width of Y plane
:type width: int
:param nv12_surface: NV12 `VASurfaceID` to create NV12 from.
:type nv12_surface: int
:return: A pair of remote tensors for each plane.
:rtype: Tuple[openvino.VASurfaceTensor, openvino.VASurfaceTensor]
)");

cls.def(
"create_tensor",
Expand All @@ -92,5 +165,19 @@ void regclass_VAContext(py::module m) {
py::arg("type"),
py::arg("shape"),
py::arg("surface"),
py::arg("plane") = 0);
py::arg("plane") = 0,
R"(
Create remote tensor from VA surface handle.
:param type: Defines the element type of the tensor.
:type type: openvino.Type
:param shape: Defines the shape of the tensor.
:type shape: openvino.Shape
:param surface: `VASurfaceID` to create tensor from.
:type surface: int
:param plane: An index of a plane inside `VASurfaceID` to create tensor from. Default: 0
:type plane: int
:return: A remote tensor instance wrapping `VASurfaceID`.
:rtype: openvino.VASurfaceTensor
)");
}
103 changes: 80 additions & 23 deletions src/bindings/python/src/pyopenvino/core/remote_tensor.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,21 +16,51 @@ void regclass_RemoteTensor(py::module m) {
"RemoteTensor",
py::base<ov::Tensor>());

cls.def("get_device_name", [](RemoteTensorWrapper& self) {
return self.tensor.get_device_name();
});
cls.def(
"get_device_name",
[](RemoteTensorWrapper& self) {
return self.tensor.get_device_name();
},
R"(
Returns name of a device on which the tensor is allocated.
cls.def("get_params", [](RemoteTensorWrapper& self) {
return self.tensor.get_params();
});
:return: A device name string in fully specified format `<device_name>[.<device_id>[.<tile_id>]]`.
:rtype: str
)");

cls.def("copy_to", [](RemoteTensorWrapper& self, py::object& dst) {
Common::utils::raise_not_implemented();
});
cls.def(
"get_params",
[](RemoteTensorWrapper& self) {
return self.tensor.get_params();
},
R"(
Returns a dict of device-specific parameters required for low-level
operations with the underlying tensor.
Parameters include device/context/surface/buffer handles, access flags, etc.
Content of the returned dict depends on remote execution context that is
currently set on the device (working scenario).
:return: A dictionary of device-specific parameters.
:rtype: dict
)");

cls.def(
"copy_to",
[](RemoteTensorWrapper& self, py::object& dst) {
Common::utils::raise_not_implemented();
},
R"(
This method is not implemented.
)");

cls.def_property_readonly("data", [](RemoteTensorWrapper& self) {
Common::utils::raise_not_implemented();
});
cls.def_property_readonly(
"data",
[](RemoteTensorWrapper& self) {
Common::utils::raise_not_implemented();
},
R"(
This property is not implemented.
)");

cls.def_property(
"bytes_data",
Expand All @@ -39,7 +69,10 @@ void regclass_RemoteTensor(py::module m) {
},
[](RemoteTensorWrapper& self, py::object& other) {
Common::utils::raise_not_implemented();
});
},
R"(
This property is not implemented.
)");

cls.def_property(
"str_data",
Expand All @@ -48,7 +81,10 @@ void regclass_RemoteTensor(py::module m) {
},
[](RemoteTensorWrapper& self, py::object& other) {
Common::utils::raise_not_implemented();
});
},
R"(
This property is not implemented.
)");

cls.def("__repr__", [](const RemoteTensorWrapper& self) {
std::stringstream ss;
Expand All @@ -64,17 +100,38 @@ void regclass_VASurfaceTensor(py::module m) {
m,
"VASurfaceTensor");

cls.def_property_readonly("surface_id", [](VASurfaceTensorWrapper& self) {
return self.surface_id();
});
cls.def_property_readonly(
"surface_id",
[](VASurfaceTensorWrapper& self) {
return self.surface_id();
},
R"(
Returns ID of underlying video decoder surface.
cls.def_property_readonly("plane_id", [](VASurfaceTensorWrapper& self) {
return self.plane_id();
});
:return: VASurfaceID of the tensor.
:rtype: int
)");

cls.def_property_readonly("data", [](VASurfaceTensorWrapper& self) {
Common::utils::raise_not_implemented();
});
cls.def_property_readonly(
"plane_id",
[](VASurfaceTensorWrapper& self) {
return self.plane_id();
},
R"(
Returns plane ID of underlying video decoder surface.
:return: Plane ID of underlying video decoder surface.
:rtype: int
)");

cls.def_property_readonly(
"data",
[](VASurfaceTensorWrapper& self) {
Common::utils::raise_not_implemented();
},
R"(
This property is not implemented.
)");

cls.def("__repr__", [](const VASurfaceTensorWrapper& self) {
std::stringstream ss;
Expand Down

0 comments on commit 05b0fca

Please sign in to comment.