Skip to content

Fix type stub mismatches and HWConfig.methods - #2463

Merged
WyattBlue merged 1 commit into
masterfrom
stub-fixes-2
Oct 24, 2026
Merged

WyattBlue merged 1 commit into
masterfrom
stub-fixes-2

Conversation

@WyattBlue

@WyattBlue WyattBlue commented Oct 24, 2026 •

Copy link
Copy Markdown
Member

Fixes stub annotations that don't match runtime. I found them by reading every stubbed attribute and property on objects from the test assets and type-checking the real values against the annotations, which catches things stubtest can't see in Cython classes.

Runtime fixes

  • HWConfig.methods raised ValueError whenever a config supported several methods (e.g. VideoToolbox h264 reports 11), because FFmpeg's methods is a bitmask but HWConfigMethod was an IntEnum. It's now an IntFlag. Added test_codec_hardware_config_methods, which fails without the fix.
  • CodecContext.is_encoder, CodecContext.is_decoder, Container.input_was_opened, and VideoFormatComponent.is_chroma returned raw C ints; they now return bool.
  • Frame.time_base returned None when unset; it now returns a falsy AVRational(0, 1), like every other AVRational property. Internal is None checks in AudioResampler and Graph.add_buffer/add_abuffer now test truthiness. Code checking frame.time_base is None should use not frame.time_base.

Stub fixes

  • average_rate, base_rate, and guessed_rate moved from Stream to VideoStream, the only class that defines them.
  • codec, codec_tag, and options moved from Stream to AudioStream, VideoStream, and SubtitleStream, which forward them to their codec context. DataStream and AttachmentStream don't forward and raise AttributeError. options is now dict[str, str] there, matching CodecContext.options: non-str values made open() raise TypeError.
  • Stream.codec_context is CodecContext | None; DataStream and AttachmentStream declare it as None.
  • Now optional: AudioStream.bit_rate, InputContainer.start_time, VideoFrame.time, and FilterPad.context (FilterContextPad.context stays non-optional).
  • Codec.hardware_configs is tuple[HWConfig, ...], not list; CodecContext.delay is int, not bool.
  • Added AudioStream.max_bit_rate.
  • Removed Plane.frame, Plane.index, and Container.buffer_size, which are private cdef fields.

Notes

  • Possible break for type-checked code: container.streams[0].codec (a plain Stream) no longer type-checks, matching runtime for data streams. Narrow first, e.g. container.streams.video[0] or an isinstance check.
  • Several tests were partly unreachable to mypy, because asserts like bit_rate is None contradicted the old stubs. They're now checked, and needed three small edits: two isinstance(..., av.VideoStream) asserts and streams.subtitles[0] in place of streams[0].
  • Not fixed: streams from add_mux_stream() have codec_context is None, and AudioStream.format/VideoStream.format can be None, but the stubs say otherwise. Making these optional would force None checks into most stream-handling code, so they're left for a separate decision.

- Make `HWConfigMethod` an `IntFlag`, so `HWConfig.methods` no longer raises `ValueError` for combined methods
- Return `bool` from `is_encoder`, `is_decoder`, `input_was_opened`, and `is_chroma`
- Move video-only rates to `VideoStream`, and context-forwarded `codec`, `codec_tag`, and `options` to audio, video, and subtitle streams
- Mark attributes that can be `None` as optional, fix `hardware_configs` and `delay` types, and remove stubs for private fields
@WyattBlue
WyattBlue merged commit 74cc113 into master Oct 24, 2026
8 of 9 checks passed
@WyattBlue
WyattBlue deleted the stub-fixes-2 branch October 24, 2026 04:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant