pyds-stubs 1.0.2

Typing stubs for NVIDIA DeepStream Python Bindings

Typing stubs for NVIDIA DeepStream Python Bindings

This project provides type stubs for pyds to improve the support of these important bindings in IDEs.

These are generated by pybind11-stubgen and further post-processed. For the post-processing steps, check out the Post-Processing Chapter

With the usage of this project, you agree to the license terms, found in the License chapter. This project is not affiliated with NVIDIA or the authors and maintainer of the pyds repository. It is the result of the need for type hints for a simpler and more stable implementation of DeepStream pipelines in Python.

Index

• Installation
• Usage
• Versioning
• Development
  • Installation of Prerequisites
  • Build wheel
  • Generation
  • Post-Processing
• License
• Appendix
  • Python venv
  • Links
  • Notice for NVIDIA

Installation

This library can be easily installed with pip:

pip install pyds-stubs

Usage

There is no magic, just only import pyds as you would normally do. This package is intended to be used during the development and can be omitted in runtime environments.

Versioning

The stub versions matches the versions of pyds. For example, stub version 1.0.2 fits to pyds version 1.0.2. If any fix has to be applied, the fourth position would be incremented. So the first fix of 1.0.2 results in 1.0.2.1.

Please pin your version directly or limit it upper-wise like:

pyds-stubs>=1.0.2,<1.0.3

Development

Installation of Prerequisites

• Python 3 (latest) (https://www.python.org/downloads)
• Python venv (optional, recommended) _{GoTo Installation}
• Installation of development requirements:

pip install -r requirements/dev/requirements.txt

• Installation of requirements:

pip install -r requirements/library/requirements.txt

Build wheel

python3 -m build

Generation

The stubs are generated by pybind11-stubgen (2.5.5). It is contained in the development requirements. To generate the stubs execute the following script. It adds the shared object path of pyds to the python search path and executes pybind11-stubgen after that.

export PYTHONPATH=/opt/nvidia/deepstream/deepstream/lib
pybind11-stubgen pyds

Post-Processing

For correct usage, the generated stubs are post-processed. Following steps are applied:

• Format with ruff
• add generic class for capsule with information about the class of the object.
• remove class GList and add generic GList class with information about the class of the data.
• cast functions with capsule datatype: capsule is replaced by capsule[class] where class is the target class.
• array datatype: Replace with numpy.ndarray
• numpy.ndarray[float32]: Replace with NDArray[numpy.float32] with from numpy.typing import NDArray
• Returntype of eglImage property of NvBufSurfaceMappedAddr: typing.Any instead of capsule
• Returntype of dataPtr property of NvBufSurfaceParams: typing.Any instead of capsule
• Returntype of batch_meta property of NvDsBaseMeta: NvDsBatchMeta instead of _NvDsBatchMeta
• Datatype of arg0 of batch_meta property setter of NvDsBaseMeta: NvDsBatchMeta instead of _NvDsBatchMeta
• Returntype of uContext property of NvDsBaseMeta: typing.Any instead of capsule
• Datatype of arg0 of uContext property setter of NvDsBaseMeta: typing.Any instead of capsule
• Returntype of batch_user_meta_list property of NvDsBatchMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Datatype of arg0 of batch_user_meta_list property setter of NvDsBatchMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Returntype of frame_meta_list property of NvDsBatchMeta: typing.Optional[GList[NvDsFrameMeta]] instead of GList
• Datatype of arg0 of frame_meta_list property setter of NvDsBatchMeta: typing.Optional[GList[NvDsFrameMeta]] instead of GList
• Returntype of meta_mutex property of NvDsBatchMeta: GLib.RecMutex instead of _GRecMutex with from gi.repository import GLib
• Datatype of arg0 of meta_mutex property setter of NvDsBatchMeta: GLib.RecMutex instead of _GRecMutex with from gi.repository import GLib
• Returntype of label_info_list property of NvDsClassifierMeta: typing.Optional[GList[NvDsLabelInfo]] instead of GList
• Datatype of arg0 of label_info_list property setter of NvDsClassifierMeta: typing.Optional[GList[NvDsLabelInfo]] instead of GList
• Returntype of extMsg property of NvDsEventMsgMeta: typing.Any instead of capsule
• Datatype of arg0 of extMsg property setter of NvDsEventMsgMeta: typing.Any instead of capsule
• Returntype of mask property of NvDsFaceObjectWithExt: typing.Optional[GList[typing.Any]] instead of GList
• Datatype of arg0 of mask property setter of NvDsFaceObjectWithExt: typing.Optional[GList[typing.Any]] instead of GList
• Returntype of display_meta_list property of NvDsFrameMeta: typing.Optional[GList[NvDsDisplayMeta]] instead of GList
• Datatype of arg0 of display_meta_list property setter of NvDsFrameMeta: typing.Optional[GList[NvDsDisplayMeta]] instead of GList
• Returntype of frame_user_meta_list property of NvDsFrameMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Datatype of arg0 of frame_user_meta_list property setter of NvDsFrameMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Returntype of obj_meta_list property of NvDsFrameMeta: typing.Optional[GList[NvDsObjectMeta]] instead of GList
• Datatype of arg0 of obj_meta_list property setter of NvDsFrameMeta: typing.Optional[GList[NvDsObjectMeta]] instead of GList
• Returntype of buffer property of NvDsInferLayerInfo: typing.Any instead of capsule
• Returntype of priv_data property of NvDsInferSegmentationMeta: typing.Any instead of capsule
• Returntype of out_buf_ptrs_dev property of NvDsInferTensorMeta: typing.Any instead of capsule
• Returntype of out_buf_ptrs_host property of NvDsInferTensorMeta: typing.Any instead of capsule
• Returntype of priv_data property of NvDsInferTensorMeta: typing.Any instead of capsule
• Returntype of meta property of NvDsMeta: Gst.Meta instead of _GstMeta with from gi.repository import Gst
• Datatype of arg0 of meta property setter of NvDsMeta: Gst.Meta instead of _GstMeta with from gi.repository import Gst
• Returntype of meta_data property of NvDsMeta: typing.Any instead of capsule
• Datatype of arg0 of meta_data property setter of NvDsMeta: typing.Any instead of capsule
• Returntype of user_data property of NvDsMeta: typing.Any instead of capsule
• Datatype of arg0 of of user_data property setter of NvDsMeta: typing.Any instead of capsule
• Add NvDsMetaList as an alias of typing.Optional[GList[NvDsMeta]]
• Returntype of empty_list property of NvDsMetaPool: NvDsMetaList instead of GList
• Datatype of arg0 of empty_list property setter of NvDsMetaPool: NvDsMetaList instead of GList
• Returntype of full_list property of NvDsMetaPool: NvDsMetaList instead of GList
• Datatype of arg0 of full_list property setter of NvDsMetaPool: NvDsMetaList instead of GList
• Returntype of classifier_meta_list property of NvDsObjectMeta: typing.Optional[GList[NvDsClassifierMeta]] instead of GList
• Datatype of args0 of classifier_meta_list property setter of NvDsObjectMeta: typing.Optional[GList[NvDsClassifierMeta]] instead of GList
• Returntype of mask_params property of NvDsObjectMeta: typing.Any instead of _NvOSD_MaskParams
• Datatype of args0 of mask_params property setter of NvDsObjectMeta: typing.Any instead of _NvOSD_MaskParams
• Returntype of obj_user_meta_list property of NvDsObjectMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Datatype of arg0 of obj_user_meta_list property setter of NvDsObjectMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Returntype of data property of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Datatype of arg0 of data property setter of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Returntype of priv property of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Datatype of arg0 of priv property setter of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Returntype of reserved property of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Datatype of arg0 of reserved property setter of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Returntype of mask property of NvDsPersonObjectExt: typing.Optional[GList[typing.Any]] instead of GList
• Datatype of arg0 of mask property setter of NvDsPersonObjectExt: typing.Optional[GList[typing.Any]] instead of GList
• Returntype of payload property of NvDsPayload: typing.Any instead of capsule
• Datatype of arg0 of payload property setter of NvDsPayload: typing.Any instead of capsule
• Returntype of user_meta_data property of NvDsUserMeta: typing.Any instead of capsule
• Datatype of arg0 of user_meta_data property setter of NvDsUserMeta: typing.Any instead of capsule
• Returntype of mask property of NvDsVehicleObjectExt: typing.Optional[GList[typing.Any]] instead of GList
• Datatype of arg0 of mask property setter of NvDsVehicleObjectExt: typing.Optional[GList[typing.Any]] instead of GList
• Returntype of text property of RectDim: typing.Any instead of capsule
• Datatype of arg0 of text property setter of RectDim: typing.Any instead of capsule
• Rename arg0 to srcSurf of NvBufSurfaceCopy
• Rename arg1 to dstSurf of NvBufSurfaceCopy
• Rename arg0 to surf of NvBufSurfaceCreate
• Rename arg1 to batchSize of NvBufSurfaceCreate
• Rename arg2 to params of NvBufSurfaceCreate
• Rename arg0 to surf of NvBufSurfaceDestroy
• Rename arg0 to dmabuf_fd of NvBufSurfaceFromFd
• Datatype of arg1 of NvBufSurfaceFromFd: capsule[NvBufSurface] instead of capsule
• Rename arg1 to surf of NvBufSurfaceFromFd
• Rename arg0 to index of NvBufSurfaceMap
• Rename arg1 to buffer of NvBufSurfaceMap
• Rename arg2 to plane of NvBufSurfaceMap
• Rename arg3 to type of NvBufSurfaceMap
• Rename arg0 to surf of NvBufSurfaceMapEglImage
• Rename arg1 to index of NvBufSurfaceMapEglImage
• Rename arg0 to surf of NvBufSurfaceMemSet
• Rename arg1 to index of NvBufSurfaceMemSet
• Rename arg2 to plane of NvBufSurfaceMemSet
• Rename arg3 to value of NvBufSurfaceMemSet
• Rename arg0 to surf of NvBufSurfaceSyncForCpu
• Rename arg1 to index of NvBufSurfaceSyncForCpu
• Rename arg2 to plane of NvBufSurfaceSyncForCpu
• Rename arg0 to surf of NvBufSurfaceSyncForDevice
• Rename arg1 to index of NvBufSurfaceSyncForDevice
• Rename arg2 to plane of NvBufSurfaceSyncForDevice
• Rename arg0 to surf of NvBufSurfaceUnMap
• Rename arg1 to index of NvBufSurfaceUnMap
• Rename arg2 to plane of NvBufSurfaceUnMap
• Datatype of arg0 of free_gbuffer: typing.Any instead of capsule
• Datatype of arg0 of get_detections: typing.Any instead of capsule
• Datatype of arg0 of get_nvds_LayerInfo: typing.Any instead of capsule
• Rename arg0 to input of get_nvds_buf_surface
• Rename arg1 to input1 of get_nvds_buf_surface
• Datatype of arg0 of get_optical_flow_vectors: capsule[NvDsOpticalFlowMeta] instead of capsule
• Rename arg0 to of_meta of get_optical_flow_vectors
• Datatype of arg0 of get_ptr: typing.Any instead of capsule
• Datatype of arg0 of get_segmentation_masks: capsule[NvDsInferSegmentationMeta] instead of capsule
• Rename arg0 to input of get_segmentation_masks
• Datatype of arg0 of glist_get_nvds_Surface_Params: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_batch_meta: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_classifier_meta: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_display_meta: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_event_msg_meta: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_frame_meta: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_label_info: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_object_meta: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_person_object: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_tensor_meta: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_user_meta: typing.Any instead of capsule
• Datatype of arg0 of glist_get_nvds_vehicle_object: typing.Any instead of capsule
• Datatype of arg0 of gst_buffer_add_nvds_meta: Gst.Buffer instead of _GstBuffer
• Rename arg0 to buffer of gst_buffer_add_nvds_meta
• Datatype of arg1 of gst_buffer_add_nvds_meta: typing.Any instead of capsule
• Rename arg1 to meta_data of gst_buffer_add_nvds_meta
• Datatype of arg2 of gst_buffer_add_nvds_meta: typing.Any instead of capsule
• Rename arg2 to user_data of gst_buffer_add_nvds_meta
• Rename arg3 to copy_func of gst_buffer_add_nvds_meta
• Rename arg4 to release_func of gst_buffer_add_nvds_meta
• Rename arg0 to batch_meta of nvds_acquire_classifier_meta_from_pool
• Rename arg0 to batch_meta of nvds_acquire_display_meta_from_pool
• Rename arg0 to batch_meta of nvds_acquire_frame_meta_from_pool
• Rename arg0 to batch_meta of nvds_acquire_label_info_meta_from_pool
• Rename arg0 to input of nvds_acquire_meta_lock
• Rename arg0 to batch_meta of nvds_acquire_obj_meta_from_pool
• Rename arg0 to batch_meta of nvds_acquire_user_meta_from_pool
• Rename arg0 to obj_meta of nvds_add_classifier_meta_to_object
• Rename arg1 to classifier_meta of nvds_add_classifier_meta_to_object
• Rename arg0 to frame_meta of nvds_add_display_meta_to_frame
• Rename arg1 to display_meta of nvds_add_display_meta_to_frame
• Rename arg0 to batch_meta of nvds_add_frame_meta_to_batch
• Rename arg1 to frame_meta of nvds_add_frame_meta_to_batch
• Rename arg0 to classifier_meta of nvds_add_label_info_meta_to_classifier
• Rename arg1 to label_info_meta of nvds_add_label_info_meta_to_classifier
• Rename arg0 to frame_meta of nvds_add_obj_meta_to_frame
• Rename arg1 to obj_meta of nvds_add_obj_meta_to_frame
• Rename arg2 to obj_parent of nvds_add_obj_meta_to_frame
• Rename arg0 to batch_meta of nvds_add_user_meta_to_batch
• Rename arg1 to user_meta of nvds_add_user_meta_to_batch
• Rename arg0 to frame_meta of nvds_add_user_meta_to_frame
• Rename arg1 to user_meta of nvds_add_user_meta_to_frame
• Rename arg0 to obj_meta of nvds_add_user_meta_to_obj
• Rename arg1 to user_meta of nvds_add_user_meta_to_obj
• Datatype of arg0 of nvds_batch_meta_copy_func: capsule[NvDsBatchMeta] instead of capsule
• Rename arg0 to data of nvds_batch_meta_copy_func
• Datatype of arg1 of nvds_batch_meta_copy_func: typing.Any instead of capsule
• Rename arg1 to user_data of nvds_batch_meta_copy_func
• Datatype of arg0 of nvds_batch_meta_release_func: capsule[NvDsBatchMeta] instead of capsule
• Rename arg0 to data of nvds_batch_meta_release_func
• Datatype of arg1 of nvds_batch_meta_release_func: typing.Any instead of capsule
• Rename arg1 to user_data of nvds_batch_meta_release_func
• Rename arg0 to batch_meta of nvds_clear_batch_user_meta_list
• Datatype of arg1 of nvds_clear_batch_user_meta_list: NvDsUserMetaList instead of GList
• Rename arg1 to meta_list of nvds_clear_batch_user_meta_list
• Add NvDisplayMetaList as an alias of typing.Optional[GList[NvDsDisplayMeta]]
• Rename arg0 to frame_meta of nvds_clear_display_meta_list
• Datatype of arg1 of nvds_clear_display_meta_list: NvDisplayMetaList instead of GList
• Rename arg1 to meta_list of nvds_clear_display_meta_list
• Add NvDsFrameMetaList as an alias of typing.Optional[GList[NvDsFrameMeta]]
• Rename arg0 to batch_meta of nvds_clear_frame_meta_list
• Datatype of arg1 of nvds_clear_frame_meta_list: NvDsFrameMetaList instead of GList
• Rename arg1 to meta_list of nvds_clear_frame_meta_list
• Add NvDsUserMetaList as an alias of typing.Optional[GList[NvDsUserMeta]]
• Rename arg0 to frame_meta of nvds_clear_frame_user_meta_list
• Datatype of arg1 of nvds_clear_frame_user_meta_list: NvDsUserMetaList instead of GList
• Rename arg1 to meta_list of nvds_clear_frame_user_meta_list
• Rename arg0 to batch_meta of nvds_clear_meta_list
• Datatype of arg1 of nvds_clear_meta_list: NvDsMetaList instead of GList
• Rename arg1 to meta_list of nvds_clear_meta_list
• Rename arg2 to meta_pool of nvds_clear_meta_list
• Returntype of nvds_clear_meta_list: NvDsMetaList instead of GList
• Add NvDsObjectMetaList as an alias of typing.Optional[GList[NvDsObjectMeta]]
• Rename arg0 to frame_meta of nvds_clear_obj_meta_list
• Datatype of arg1 of nvds_clear_obj_meta_list: NvDsObjectMetaList instead of GList
• Rename arg1 to meta_list of nvds_clear_obj_meta_list
• Rename arg0 to object_meta of nvds_clear_obj_user_meta_list
• Datatype of arg1 of nvds_clear_obj_user_meta_list: NvDsObjectMetaList instead of GList
• Rename arg1 to meta_list of nvds_clear_obj_user_meta_list
• Datatype of arg0 of nvds_copy_batch_user_meta_list: NvDsObjectMetaList instead of GList
• Rename arg0 to src_user_meta_list of nvds_copy_batch_user_meta_list
• Rename arg1 to dst_batch_meta of nvds_copy_batch_user_meta_list
• Datatype of arg0 of nvds_copy_display_meta_list: NvDisplayMetaList instead of GList
• Rename arg0 to src_display_meta_list of nvds_copy_display_meta_list
• Rename arg1 to dst_frame_meta of nvds_copy_display_meta_list
• Datatype of arg0 of nvds_copy_frame_meta_list and its overload: NvDsFrameMetaList instead of GList
• Rename arg0 to src_frame_meta_list of nvds_copy_frame_meta_list
• Rename arg1 to dst_batch_meta of nvds_copy_frame_meta_list
• Datatype of arg0 of nvds_copy_frame_user_meta_list: NvDsUserMetaList instead of GList
• Rename arg0 to src_user_meta_list of nvds_copy_frame_user_meta_list
• Rename arg1 to dst_frame_meta of nvds_copy_frame_user_meta_list
• Datatype of arg0 of nvds_copy_obj_meta_list: NvDsObjectMetaList instead of GList
• Rename arg0 to src_obj_meta_list of nvds_copy_obj_meta_list
• Rename arg1 to dst_frame_meta of nvds_copy_obj_meta_list
• Rename arg0 to max_batch_size of nvds_create_batch_meta
• Rename arg0 to batch_meta of nvds_destroy_batch_meta
• Rename arg0 to batch_meta of nvds_get_current_metadata_info
• Datatype of arg0 of nvds_get_nth_frame_meta: GList[NvDsFrameMeta] instead of GList
• Rename arg0 to frame_meta_list of nvds_get_nth_frame_meta
• Rename arg1 to index of nvds_get_nth_frame_meta
• Rename arg0 to meta_descriptor of nvds_get_user_meta_type
• Rename arg0 to input of nvds_release_meta_lock
• Rename arg0 to obj_meta of nvds_remove_classifier_meta_from_obj
• Rename arg1 to classifier_meta of nvds_remove_classifier_meta_from_obj
• Rename arg0 to frame_meta of nvds_remove_display_meta_from_frame
• Rename arg1 to display_meta of nvds_remove_display_meta_from_frame
• Rename arg0 to batch_meta of nvds_remove_frame_meta_from_batch
• Rename arg1 to frame_meta of nvds_remove_frame_meta_from_batch
• Rename arg0 to classifier_meta of nvds_remove_label_info_meta_from_classifier
• Rename arg1 to label_info_meta of nvds_remove_label_info_meta_from_classifier
• Rename arg0 to frame_meta of nvds_remove_obj_meta_from_frame
• Rename arg1 to obj_meta of nvds_remove_obj_meta_from_frame
• Rename arg0 to batch_meta of nvds_remove_user_meta_from_batch
• Rename arg1 to user_meta of nvds_remove_user_meta_from_batch
• Rename arg0 to frame_meta of nvds_remove_user_meta_from_frame
• Rename arg1 to user_meta of nvds_remove_user_meta_from_frame
• Rename arg0 to obj_meta of nvds_remove_user_meta_from_object
• Rename arg1 to user_meta of nvds_remove_user_meta_from_object
• Datatype of arg0 of register_user_copyfunc: typing.Callable[[typing.Any, typing.Any], typing.Any] instead of typing.Callable[[capsule, capsule], capsule]
• Datatype of arg0 of register_user_releasefunc: typing.Callable[[typing.Any, typing.Any], None] instead of typing.Callable[[capsule, capsule], None]
• Datatype of arg1 of set_user_copyfunc: typing.Callable[[typing.Any, typing.Any], typing.Any] instead of typing.Callable[[capsule, capsule], capsule]
• Datatype of arg1 of set_user_releasefunc: typing.Callable[[typing.Any, typing.Any], None] instead of typing.Callable[[capsule, capsule], None]
• Datatype of arg1 of user_copyfunc: typing.Callable[[typing.Any, typing.Any], typing.Any] instead of typing.Callable[[capsule, capsule], capsule]
• Datatype of arg1 of user_releasefunc: typing.Callable[[typing.Any, typing.Any], None] instead of typing.Callable[[capsule, capsule], None]

License

This project is published under Apache License, Version 2.0 - please comply with it, if you use/modify/distribute it. The license can be found in "LICENSE".

Appendix

Python venv

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools

Links

• Project Home
• pyds - NVIDIA DeepStream Python Bindings
• pybind11-stubgen

Notice for NVIDIA

I recently (Jun, 2025) saw a discussion on your forum. If there is any official stub support by NVIDIA, this project will be deprecated and publicly archived. I hope to hear from you ;)