ci: verify type stubs match PyO3 bindings with mypy.stubtest

[ssmichael1]

What & why

The hand-written .pyi type stubs had never been type-checked and had drifted from the compiled PyO3 bindings. The drift was user-visible: following the stub, quaternion.rotz(theta=0.5) raised TypeError at runtime because PyO3 actually named the argument theta_rad. This adds a mypy.stubtest gate to CI and brings the stubs back into agreement with the runtime.

Not a release — the CHANGELOG heading stays Unreleased; the keyword renames ride the next version bump.

The CI check

• New stubtest step in the python bindings test job; mypy added to the [test] extra.
• Runs with --ignore-positional-only --ignore-disjoint-bases + python/stubtest_allowlist.txt.
• The allowlist is idiom-only (PyO3 constructors, pickle dunders, native submodules, final classes, stub-only type aliases, __all__). No real drift is suppressed; stubtest errors on unused entries so the list stays honest.

Stub build fixes (stubs now parse/type-check)

• Removed 22 illegal overload-implementation blocks across 5 .pyi files.
• Reunited the time.__add__ overload group that was split by other methods.
• Added a _Time alias to dodge time-property annotation shadowing in satstate/propresult.

Drift fixes — stub-only, no runtime change

rotx/y/z theta→theta_rad, from_gps_week_and_second sec→seconds, sgp4 tm→time, satstate.propagate time→timedur, from_rotation_matrix mat→dcm; removed phantom as_gregorian(scale=); fixed sgp4_opsmode.improved; added itrfcoord.height, time.add_utc_days, weekday.Invalid.

Keyword renames — public API (positional calls unaffected)

Function	Old kw	New kw
duration.from_hours/from_minutes/from_seconds	d	hours/minutes/seconds
time.from_string	s	string
time.from_unixtime	t	unixtime
time.from_rfc3339	s	rfc3339
time.from_datetime	tm	dt
time.strftime	fmt	format
time.strptime	s, fmt	date_string, format
kepler.from_pv	r, v	pos, vel

Verification

• stubtest: Success: no issues found in 10 modules (exit 0, no unused allowlist entries)
• cargo clippy --workspace --all-targets -- -D warnings: clean
• cargo fmt --all: applied
• No callers of the old keyword names in python/ or examples/

🤖 Generated with Claude Code