pyds-stubs 1.1.5

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.

[!NOTE] The stubs are distributed as a third-party stub-only library according to PEP 561 because this project is not related to NVIDIA and if they ship stubs, this project can easily be deprecated and publicly archived.

Index

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

Installation

This library can be easily installed with pip.

Versioning

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

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

pyds-stubs>=1.1.5,<1.1.6

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.

Development

Installation of Prerequisites

• Python 3.8
• uv and pre-commit (both preferred via pipx)
• Python venv (optional, recommended)

pipx install pre-commit uv
pre-commit install

Build wheel

uv build

Generation

The stubs are generated by pybind11-stubgen (2.5.5). Install pyds from nvidia official sources. To generate the stubs execute the following script in the environment, where pyds is installed.

pybind11-stubgen pyds

Post-Processing

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

• 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
• Datatype of batch_meta of NvDsBaseMeta: NvDsBatchMeta instead of _NvDsBatchMeta
• Datatype of uContext of NvDsBaseMeta: typing.Any instead of capsule
• Datatype of batch_user_meta_list of NvDsBatchMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Datatype of frame_meta_list of NvDsBatchMeta: typing.Optional[GList[NvDsFrameMeta]] instead of GList
• Datatype of meta_mutexof NvDsBatchMeta: GLib.RecMutex instead of _GRecMutex with from gi.repository import GLib
• Datatype of label_info_list of NvDsClassifierMeta: typing.Optional[GList[NvDsLabelInfo]] instead of GList
• Datatype of extMsg of NvDsEventMsgMeta: typing.Any instead of capsule
• Datatype of mask of NvDsFaceObjectWithExt: typing.Optional[GList[typing.Any]] instead of GList
• Datatype of display_meta_list of NvDsFrameMeta: typing.Optional[GList[NvDsDisplayMeta]] instead of GList
• Datatype of frame_user_meta_list of NvDsFrameMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Datatype of obj_meta_list 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
• Datatype of meta of NvDsMeta: Gst.Meta instead of _GstMeta with from gi.repository import Gst
• Datatype of meta_data of NvDsMeta: typing.Any instead of capsule
• Datatype of user_data of NvDsMeta: typing.Any instead of capsule
• Add NvDsMetaList as an alias of typing.Optional[GList[NvDsMeta]]
• Datatype of empty_list of NvDsMetaPool: NvDsMetaList instead of GList
• Datatype of full_list of NvDsMetaPool: NvDsMetaList instead of GList
• Datatype of classifier_meta_list of NvDsObjectMeta: typing.Optional[GList[NvDsClassifierMeta]] instead of GList
• Datatype of obj_user_meta_list of NvDsObjectMeta: typing.Optional[GList[NvDsUserMeta]] instead of GList
• Datatype of data of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Datatype of priv of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Datatype of reserved of NvDsOpticalFlowMeta: typing.Any instead of capsule
• Datatype of mask of NvDsPersonObjectExt: typing.Optional[GList[typing.Any]] instead of GList
• Datatype of payload of NvDsPayload: typing.Any instead of capsule
• Datatype of user_meta_data of NvDsUserMeta: typing.Any instead of capsule
• Datatype of mask of NvDsVehicleObjectExt: typing.Optional[GList[typing.Any]] instead of GList
• Datatype of text of RectDim: typing.Any instead of capsule
• Rename dmabuf to dmabuf_fd of NvBufSurfaceFromFd
• Datatype of buffer of NvBufSurfaceFromFd: capsule[NvBufSurface] instead of capsule
• Datatype of buffer 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
• Datatype of data of get_optical_flow_vectors: capsule[NvDsOpticalFlowMeta] instead of capsule
• Rename data to of_meta of get_optical_flow_vectors
• Datatype of ptr of get_ptr: typing.Any instead of capsule
• Datatype of data of get_segmentation_masks: capsule[NvDsInferSegmentationMeta] instead of capsule
• 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 buffer of gst_buffer_add_nvds_meta: Gst.Buffer instead of _GstBuffer
• Datatype of meta_data of gst_buffer_add_nvds_meta: typing.Any instead of capsule
• Datatype of user_data of gst_buffer_add_nvds_meta: typing.Any instead of capsule
• Returntype of gst_buffer_add_nvds_meta: NvDsMeta instead of _NvDsMeta
• Rename arg0 to gst_element of gst_element_send_nvevent_new_stream_reset
• Rename arg1 to source_id of gst_element_send_nvevent_new_stream_reset
• Datatype of data of nvds_batch_meta_copy_func: capsule[NvDsBatchMeta] instead of capsule
• Datatype of user_meta of nvds_batch_meta_copy_func: typing.Any instead of capsule
• Rename user_meta to user_data of nvds_batch_meta_copy_func
• Returntype of nvds_batch_meta_copy_func: capsule[NvDsBatchMeta] instead of capsule
• Datatype of data of nvds_batch_meta_release_func: capsule[NvDsBatchMeta] instead of capsule
• Datatype of user_data of nvds_batch_meta_release_func: typing.Any instead of capsule
• Add NvDsUserMetaList as an alias of typing.Optional[GList[NvDsUserMeta]]
• Datatype of meta_list of nvds_clear_batch_user_meta_list: NvDsUserMetaList instead of GList
• Add NvDisplayMetaList as an alias of typing.Optional[GList[NvDsDisplayMeta]]
• Datatype of meta_list of nvds_clear_display_meta_list: NvDisplayMetaList instead of GList
• Add NvDsFrameMetaList as an alias of typing.Optional[GList[NvDsFrameMeta]]
• Datatype of meta_list of nvds_clear_frame_meta_list: NvDsFrameMetaList instead of GList
• Datatype of meta_list of nvds_clear_frame_user_meta_list: NvDsUserMetaList instead of GList
• Datatype of meta_list of nvds_clear_meta_list: NvDsMetaList instead of GList
• Returntype of nvds_clear_meta_list: NvDsMetaList instead of GList
• Add NvDsObjectMetaList as an alias of typing.Optional[GList[NvDsObjectMeta]]
• Datatype of meta_list of nvds_clear_obj_meta_list: NvDsObjectMetaList instead of GList
• Datatype of meta_list of nvds_clear_obj_user_meta_list: NvDsObjectMetaList instead of GList
• Datatype of src_user_meta_list of nvds_copy_batch_user_meta_list: NvDsObjectMetaList instead of GList
• Datatype of src_display_meta of nvds_copy_display_meta_list: NvDisplayMetaList instead of GList
• Rename src_display_meta to src_display_meta_list of nvds_copy_display_meta_list
• Datatype of src_frame_meta_list of nvds_copy_frame_meta_list: NvDsFrameMetaList instead of GList
• Datatype of src_user_meta_list of nvds_copy_frame_user_meta_list: NvDsUserMetaList instead of GList
• Datatype of src_obj_meta_list of nvds_copy_obj_meta_list: NvDsObjectMetaList instead of GList
• Rename dst_object_meta to dst_frame_meta of nvds_copy_obj_meta_list
• Datatype of frame_meta_list of nvds_get_nth_frame_meta: GList[NvDsFrameMeta] instead of GList
• 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 func of user_copyfunc: typing.Callable[[typing.Any, typing.Any], typing.Any] instead of typing.Callable[[capsule, capsule], capsule]
• Datatype of func 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

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 ;)