Skip to content

docs(tcp): MPTCP join and option makers lack Raises, Quick-Start rate lacks unit and versionchanged #2235

Closed

Description

@JarryShaw

Is your feature request related to a problem? Please describe.
Some docstrings leave out facts the code depends on:

  • TCP._make_mptcp_join raises ProtocolError when the segment's flags are neither SYN, SYN/ACK nor ACK. On origin/main, TCP(options=[(Option.Multipath_TCP, {'subtype': MPTCPOption.MP_JOIN})], syn=False, ack=False) raises ProtocolError: TCP: [OptNo 30] 1: invalid flags combination. It is the only maker in the module that raises and has no Raises: section; the _make_mptcp_capable, _make_mptcp_dss, _make_mptcp_addaddr and _make_mode_timeout makers all have one.
  • TCP._make_tcp_options raises whatever its option makers raise (the _make_mptcp_* and _make_mode_timeout ones), but it has no Raises: section either. _read_tcp_options does have one.
  • Data_QuickStartResponse.req_rate holds an int since fix(tcp): Quick-Start rate parses as float and a Fast Open cookie request as None, against their annotations #2167 (fix(tcp): keep Quick-Start rate an int and a Fast Open cookie request bytes (#2167) #2185) where it held a float such as 80.0, but it has no versionchanged and its comment (Rate request.) gives no unit. FastOpenCookie got a versionchanged in the same PR. The IPv4, HOPOPT and IPv6-Opts Quick-Start data models (rate, Rate request/report.) changed in the same way and have the same gap.

Describe the solution you'd like
Add Raises: ProtocolError: If the flags are none of SYN, SYN/ACK and ACK. to _make_mptcp_join. Add Raises: ProtocolError: If an option maker rejects its option. to _make_tcp_options. Change each Quick-Start rate comment to say it is in kbps (40 * 2 ** N, 0 for N = 0), and add a .. versionchanged:: 1.5.0 to each model saying the rate is an int where it was a float (#2167).

Additional context
The unit is stated only in the makers' rate (in kbps) argument docs, not on the data models that users read.

Activity

  1. added
    docsPull requests that change documentation only (docs: subject prefix)
    pendingAccepted and unstarted - nobody is on it and nothing blocks it
    wipWork in flight - a covering PR is open or an agent is actively on it
    and removed
    pendingAccepted and unstarted - nobody is on it and nothing blocks it
    on Oct 26, 2026
  2. added this to the PyPCAPKit v1.5 milestone on Oct 26, 2026
  3. removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsPull requests that change documentation only (docs: subject prefix)

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions