Add typestubs and change names

Author: WyattBlue

av/packet.pxd

@@ -21,6 +21,4 @@ cdef class Packet(Buffer):
     cdef size_t _buffer_size(self)
     cdef void* _buffer_ptr(self)
 
-cdef PacketSideData _packet_side_data_from_packet(
-    lib.AVPacket* packet, lib.AVPacketSideDataType data_type
-)
+cdef PacketSideData _packet_sidedata_from_packet(lib.AVPacket* packet, lib.AVPacketSideDataType data_type)

av/packet.py

@@ -8,10 +8,10 @@
 from cython.cimports.av.utils import avrational_to_fraction, to_avrational
 from cython.cimports.libc.string import memcpy
 
-# check https://github.com/FFmpeg/FFmpeg/blob/master/libavcodec/packet.h#L41 for
-# new additions in the future FFmpeg releases
-# note: the order must follow that of the AVPacketSideDataType enum def
-PacketSideDataTypeLiteral = Literal[
+# Check https://github.com/FFmpeg/FFmpeg/blob/master/libavcodec/packet.h#L41
+# for new additions in the future ffmpeg releases
+# Note: the order must follow that of the AVPacketSideDataType enum def
+PktSideDataT = Literal[
     "palette",
     "new_extradata",
     "param_change",
@@ -55,33 +55,26 @@
 ]
 
 
-def _packet_side_data_type_to_literal(
-    data_type: lib.AVPacketSideDataType,
-) -> PacketSideDataTypeLiteral:
-    return get_args(PacketSideDataTypeLiteral)[cython.cast(int, data_type)]
+def packet_sidedata_type_to_literal(dtype: lib.AVPacketSideDataType) -> PktSideDataT:
+    return get_args(PktSideDataT)[cython.cast(int, dtype)]
 
 
-def _packet_side_data_type_from_literal(
-    data_type: PacketSideDataTypeLiteral,
-) -> lib.AVPacketSideDataType:
-    i = cython.declare(cython.int, get_args(PacketSideDataTypeLiteral).index(data_type))
+def packet_sidedata_type_from_literal(dtype: PktSideDataT) -> lib.AVPacketSideDataType:
+    return get_args(PktSideDataT).index(dtype)
 
-    return cython.cast(lib.AVPacketSideDataType, i)
 
-
-def packet_side_data_type_desc(data_type: PacketSideDataTypeLiteral) -> str | None:
+@cython.ccall
+def sidedata_typedesc(dtype: PktSideDataT) -> str | None:
     """FFmpeg description of packet side data type"""
-    dtype = _packet_side_data_type_from_literal(data_type)
-    res = lib.av_packet_side_data_name(dtype)
+    dtype2: lib.AVPacketSideDataType = packet_sidedata_type_from_literal(dtype)
+    res: cython.pointer[cython.char] = lib.av_packet_side_data_name(dtype2)
     return res if res != cython.NULL else None
 
 
 @cython.cclass
 class PacketSideData:
     @staticmethod
-    def from_packet(
-        packet: "Packet", data_type: PacketSideDataTypeLiteral
-    ) -> "PacketSideData":
+    def from_packet(packet: Packet, data_type: PktSideDataT) -> PacketSideData:
         """create new PacketSideData by copying an existing packet's side data
 
         :param packet: Source packet
@@ -92,8 +85,8 @@ def from_packet(
         :rtype: :class:`~av.packet.PacketSideData`
         """
 
-        dtype = _packet_side_data_type_from_literal(data_type)
-        return _packet_side_data_from_packet(packet.ptr, dtype)
+        dtype = packet_sidedata_type_from_literal(data_type)
+        return _packet_sidedata_from_packet(packet.ptr, dtype)
 
     def __cinit__(self, dtype: lib.AVPacketSideDataType, size: cython.size_t):
         self.dtype = dtype
@@ -110,7 +103,7 @@ def __dealloc__(self):
         with cython.nogil:
             lib.av_freep(cython.address(self.data))
 
-    def to_packet(self, packet: "Packet", move: cython.bint = False):
+    def to_packet(self, packet: Packet, move: cython.bint = False):
         """copy or move side data to the specified packet
 
         :param packet: Target packet
@@ -146,7 +139,7 @@ def data_type(self) -> str:
 
         :type: str
         """
-        return _packet_side_data_type_to_literal(self.dtype)
+        return packet_sidedata_type_to_literal(self.dtype)
 
     @property
     def data_desc(self) -> str:
@@ -177,17 +170,16 @@ def __bool__(self) -> bool:
 
 
 @cython.cfunc
-def _packet_side_data_from_packet(
-    packet: cython.pointer[lib.AVPacket], data_type: lib.AVPacketSideDataType
+def _packet_sidedata_from_packet(
+    packet: cython.pointer[lib.AVPacket], dtype: lib.AVPacketSideDataType
 ) -> PacketSideData:
     with cython.nogil:
         c_ptr = lib.av_packet_side_data_get(
-            packet.side_data, packet.side_data_elems, data_type
+            packet.side_data, packet.side_data_elems, dtype
         )
+        found: cython.bint = c_ptr != cython.NULL
 
-        found = cython.declare(cython.bint, c_ptr != cython.NULL)
-
-    sdata = PacketSideData(data_type, c_ptr.size if found else 0)
+    sdata = PacketSideData(dtype, c_ptr.size if found else 0)
 
     with cython.nogil:
         if found:
@@ -426,48 +418,47 @@ def opaque(self, v):
             return
         self.ptr.opaque_ref = opaque_container.add(v)
 
-    def has_side_data(self, data_type: str) -> bool:
+    def has_sidedata(self, dtype: str) -> bool:
         """True if this packet has the specified side data
 
-        :param data_type: side data type
-        :type data_type: str
+        :param dtype: side data type
+        :type dtype: str
         """
 
-        dtype = _packet_side_data_type_from_literal(data_type)
+        dtype2 = packet_sidedata_type_from_literal(dtype)
         return (
             lib.av_packet_side_data_get(
-                self.ptr.side_data, self.ptr.side_data_elems, dtype
+                self.ptr.side_data, self.ptr.side_data_elems, dtype2
             )
             != cython.NULL
         )
 
-    def get_side_data(self, data_type: str) -> PacketSideData:
+    def get_sidedata(self, dtype: str) -> PacketSideData:
         """get a copy of the side data
 
-        :param data_type: side data type (:method:`~av.packet.PacketSideData.side_data_types` for the full list of options)
-        :type data_type: str
+        :param dtype: side data type (:method:`~av.packet.PacketSideData.sidedata_types` for the full list of options)
+        :type dtype: str
         :return: newly created copy of the side data if the side data of the
                  requested type is found in the packet, else an empty object
         :rtype: :class:`~av.packet.PacketSideData`
         """
-        return PacketSideData.from_packet(self, data_type)
+        return PacketSideData.from_packet(self, dtype)
 
-    def set_side_data(self, side_data: PacketSideData, move: bool = False):
+    def set_sidedata(self, sidedata: PacketSideData, move: cython.bint = False):
         """copy or move side data to this packet
 
-        :param side_data: Source packet side data
-        :type side_data: :class:`~av.packet.PacketSideData`
-        :param move: True to move the data from `side_data` object,
-                     defaults to False.
+        :param sidedata: Source packet side data
+        :type sidedata: :class:`~av.packet.PacketSideData`
+        :param move: If True, move the data from `sidedata` object, defaults to False
         :type move: bool
         """
-        side_data.to_packet(self, move)
+        sidedata.to_packet(self, move)
 
-    def iter_side_data(self) -> Iterator[PacketSideData]:
+    def iter_sidedata(self) -> Iterator[PacketSideData]:
         """iterate over side data of this packet.
 
         :yield: :class:`~av.packet.PacketSideData` object
         """
 
         for i in range(self.ptr.side_data_elems):
-            yield _packet_side_data_from_packet(self.ptr, self.ptr.side_data[i].type)
+            yield _packet_sidedata_from_packet(self.ptr, self.ptr.side_data[i].type)

av/packet.pyi

@@ -1,10 +1,71 @@
 from fractions import Fraction
+from typing import Iterator, Literal
 
 from av.subtitles.subtitle import SubtitleSet
 
 from .buffer import Buffer
 from .stream import Stream
 
+# Sync with definition in 'packet.py'
+PktSideDataT = Literal[
+    "palette",
+    "new_extradata",
+    "param_change",
+    "h263_mb_info",
+    "replay_gain",
+    "display_matrix",
+    "stereo_3d",
+    "audio_service_type",
+    "quality_stats",
+    "fallback_track",
+    "cpb_properties",
+    "skip_samples",
+    "jp_dual_mono",
+    "strings_metadata",
+    "subtitle_position",
+    "matroska_block_additional",
+    "webvtt_identifier",
+    "webvtt_settings",
+    "metadata_update",
+    "mpegts_stream_id",
+    "mastering_display_metadata",
+    "spherical",
+    "content_light_level",
+    "a53_cc",
+    "encryption_init_info",
+    "encryption_info",
+    "afd",
+    "prft",
+    "icc_profile",
+    "dovi_conf",
+    "s12m_timecode",
+    "dynamic_hdr10_plus",
+    "iamf_mix_gain_param",
+    "iamf_info_param",
+    "iamf_recon_gain_info_param",
+    "ambient_viewing_environment",
+    "frame_cropping",
+    "lcevc",
+    "3d_reference_displays",
+    "rtcp_sr",
+]
+
+class PacketSideData:
+    @staticmethod
+    def from_packet(packet: Packet, dtype: PktSideDataT) -> PacketSideData: ...
+    def to_packet(self, packet: Packet, move: bool = False): ...
+    @property
+    def data_type(self) -> str: ...
+    @property
+    def data_desc(self) -> str: ...
+    @property
+    def data_size(self) -> int: ...
+    def __bool__(self) -> bool: ...
+
+def packet_sidedata_type_to_literal(dtype: int) -> PktSideDataT: ...
+def packet_sidedata_type_from_literal(dtype: PktSideDataT) -> int: ...
+def sidedata_typedesc(dtype: PktSideDataT) -> str | None: ...
+
 class Packet(Buffer):
     stream: Stream
     stream_index: int
@@ -23,3 +84,7 @@ class Packet(Buffer):
 
     def __init__(self, input: int | bytes | None = None) -> None: ...
     def decode(self) -> list[SubtitleSet]: ...
+    def has_sidedata(self, dtype: PktSideDataT) -> bool: ...
+    def get_sidedata(self, dtype: PktSideDataT) -> PacketSideData: ...
+    def set_sidedata(self, sidedata: PacketSideData, move: bool = False) -> None: ...
+    def iter_sidedata(self) -> Iterator[PacketSideData]: ...

tests/test_packet.py

@@ -53,44 +53,44 @@ def test_set_duration(self) -> None:
 
 
 class TestPacketSideData:
-    def test_data_types(self):
-        dtypes = get_args(av.packet.PacketSideDataTypeLiteral)
+    def test_data_types(self) -> None:
+        dtypes = get_args(av.packet.PktSideDataT)
         ffmpeg_ver = [int(v) for v in av.ffmpeg_version_info.split(".", 2)[:2]]
         for dtype in dtypes:
-            av_enum = av.packet._packet_side_data_type_from_literal(dtype)
-            assert dtype == av.packet._packet_side_data_type_to_literal(av_enum)
-            assert av.packet.packet_side_data_type_desc(dtype) is not None
+            av_enum = av.packet.packet_sidedata_type_from_literal(dtype)
+            assert dtype == av.packet.packet_sidedata_type_to_literal(av_enum)
+            assert av.packet.sidedata_typedesc(dtype) is not None
 
             if (ffmpeg_ver[0] < 8 and dtype == "lcevc") or (
                 ffmpeg_ver[0] < 9 and dtype == "rtcp_sr"
             ):
                 break
 
-    def test_iter(self):
+    def test_iter(self) -> None:
         with av.open(fate_suite("h264/extradata-reload-multi-stsd.mov")) as container:
             for pkt in container.demux():
-                for sdata in pkt.iter_side_data():
+                for sdata in pkt.iter_sidedata():
                     assert pkt.dts == 2 and sdata.data_type == "new_extradata"
 
-    def test_palette(self):
+    def test_palette(self) -> None:
         with av.open(fate_suite("h264/extradata-reload-multi-stsd.mov")) as container:
             iterpackets = container.demux()
-            pkt = next(pkt for pkt in iterpackets if pkt.has_side_data("new_extradata"))
+            pkt = next(pkt for pkt in iterpackets if pkt.has_sidedata("new_extradata"))
 
-            sdata = pkt.get_side_data("new_extradata")
+            sdata = pkt.get_sidedata("new_extradata")
             assert sdata.data_type == "new_extradata"
             assert bool(sdata)
             assert sdata.data_size > 0
             assert sdata.data_desc == "New Extradata"
 
             nxt = next(iterpackets)  # has no palette
 
-            assert not nxt.has_side_data("new_extradata")
+            assert not nxt.has_sidedata("new_extradata")
 
-            sdata1 = nxt.get_side_data("new_extradata")
+            sdata1 = nxt.get_sidedata("new_extradata")
             assert sdata1.data_type == "new_extradata"
             assert not bool(sdata1)
             assert sdata1.data_size == 0
 
-            nxt.set_side_data(sdata, move=True)
+            nxt.set_sidedata(sdata, move=True)
             assert not bool(sdata)