feat(python): expose get_stats on IggyClient

[7487]

Which issue does this PR address?

Closes #4016

Rationale

get_stats is the server's headline diagnostic call and is exposed by every other SDK; the Python SDK could not reach it.

What changed?

The Python SDK had no binding for get_stats, so server counts, host/version details and cache metrics were unreachable from Python.

A new foreign/python/src/stats.rs wraps Stats, CacheMetrics and CacheMetricsKey following the user.rs pattern. CacheMetricsKey is frozen with __eq__/__hash__, so Stats.cache_metrics converts to dict[CacheMetricsKey, CacheMetrics]. IggyClient.get_stats returns an awaitable resolving to Stats; byte sizes are exposed as integer bytes and times as microseconds, matching the existing getters. Stubs were regenerated with cargo run --bin stub_gen (purely additive diff after ruff).

tests/test_stats.py creates a stream/topic, sends messages, and asserts the stream/topic/partition/message counts moved, the version string is non-empty, and the cache-metrics dict round-trips through key lookup.

Local Execution

• Passed
• Pre-commit hooks ran

Ran against a locally built iggy-server from this branch: pytest tests/ gives 323 passed (only test_tls errors locally for lack of a Docker daemon, unrelated). cargo fmt, cargo clippy --all-features --all-targets, ruff check/format and pyrefly are clean.

AI Usage

1. Claude Code (Fable 5).
2. Entire implementation and tests, following the pattern proposed in the issue.
3. Built the extension and ran the new and full Python test suites against a locally built server; regenerated and diffed the stubs; ran clippy/fmt/ruff/pyrefly.
4. Yes.

[github-actions]

Thanks for the PR. It is labeled S-waiting-on-review and queued for review.

Slash commands (own line, regular comment) move it around the queue:

• /ready - back to S-waiting-on-review after addressing feedback
• /author - flip to S-waiting-on-author while you finish changes
• /request-review @user-or-team - request a reviewer

See CONTRIBUTING.md for details.

[codecov]

Codecov Report

❌ Patch coverage is 43.75000% with 72 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.97%. Comparing base (328b289) to head (fe8d21d).
⚠️ Report is 29 commits behind head on master.

Files with missing lines	Patch %	Lines
foreign/python/src/stats.rs	37.39%	72 Missing ⚠️

❌ Your patch check has failed because the patch coverage (43.75%) is below the target coverage (50.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #4018      +/-   ##
============================================
- Coverage     85.00%   84.97%   -0.03%     
  Complexity     1402     1402              
============================================
  Files          1225     1226       +1     
  Lines        180283   180411     +128     
  Branches     146587   146587              
============================================
+ Hits         153248   153304      +56     
- Misses        22993    23065      +72     
  Partials       4042     4042              

Components	Coverage Δ
Rust Core	85.90% <ø> (ø)
Java SDK	67.29% <ø> (ø)
C# SDK	75.37% <ø> (ø)
Python SDK	87.63% <43.75%> (-2.44%)	⬇️
PHP SDK	85.65% <ø> (ø)
Node SDK	96.24% <ø> (ø)
Go SDK	69.31% <ø> (ø)

Files with missing lines	Coverage Δ
foreign/python/src/client.rs	99.85% <100.00%> (+<0.01%)	⬆️
foreign/python/src/lib.rs	100.00% <100.00%> (ø)
foreign/python/src/stats.rs	37.39% <37.39%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[justinmclean]

Nice addition, follows the existing user.rs wrapper pattern and the stub is regenerated. Nothing blocking; a few things worth a look.

• src/stats.rs:30 — CacheMetricsKey has no #[new], so Python can't construct one. The dict ends up iterate-only: you can't ask for stream 1 / topic 2 / partition 0 directly. A constructor would fix that cheaply.
• src/stats.rs:264 — cache_metrics is a #[getter], so every access re-collects the whole map. Iterating the property and indexing it in the same loop is quadratic, which is what the test does at tests/test_stats.py:66 and :70. Building it once in From<RustStats> would avoid the surprise.
• tests/test_stats.py:66 — the loop body is the only thing test_get_stats_cache_metrics_dict asserts, and on a server with no cached partitions it never runs. Sending and polling messages first, then asserting the map is non-empty, would make it test the conversion.
• tests/test_stats.py:70-:73 — stats.cache_metrics[key] is not None can't fail (a miss raises KeyError), and >= 0 on u32 / u64 is always true.
• tests/test_stats.py:47-:49 — exact equality on server-global counters. Fine today since the suite runs serially, but pytest-xdist is a declared dev dependency; >= avoids the trap.
• src/stats.rs:255 — 1.2.3 -> 100200300 should be 1002003. Inherited verbatim from core/common/src/types/stats/mod.rs:73, so not yours. Fixing it means the Rust doc comment plus a stub_gen regen, ideally in core/common too.

---

This review was drafted by an AI-assisted tool (Apache Magpie), so it may contain mistakes. If you think one of them is misapplied, please reply on the PR, and a maintainer will weigh in.

[ethanlin01x]

Three small things, mostly about matching the SDK's existing conventions.

[ethanlin01x]

run_time is an IggyDuration, and this SDK already exposes durations as datetime.timedelta. Returning raw microseconds here is inconsistent.

[7487]

Done in 7a28235 — run_time now returns datetime.timedelta via the shared iggy_duration_to_py_delta helper, and the stub is regenerated.

[ethanlin01x]

Nit: the other overrides write builtins.int | None (e.g. config.rs:191). Same meaning here, but this string is copied verbatim into the generated stub, so it stays as the only hand-written bare int across every future regen.

[7487]

Fixed in 7a28235 — the override now reads builtins.int | None, and the regenerated stub carries it.

[ethanlin01x]

CacheMetrics and CacheMetricsKey both define __repr__, but Stats does not. Since get_stats is a diagnostic call, print(stats) showing an object address is not great. A short repr with a few key fields would help.

[7487]

Added in 7a28235 — Stats.__repr__ now prints hostname, server version and the headline counters (streams/topics/partitions/messages/clients).

[slbotbm]

/author

[7487]

Thanks for the thorough pass — all addressed, point by point:

• CacheMetricsKey constructor: added #[new], so CacheMetricsKey(stream_id=1, topic_id=2, partition_id=3) now works, and there is a new test that an independently constructed equal key addresses a dict entry (eq/hash round-trip).
• cache_metrics re-collection: the map is now converted exactly once in From<RustStats> and stored as a Py<PyDict>; the getter hands back the same dict on every access, so iterate-and-index is linear. The test asserts stats.cache_metrics is stats.cache_metrics to pin that down.
• Non-empty assertion: I could not make that work, and traced why — the server currently hardcodes an empty map in the GetStats reply (core/server/src/responses.rs: cache_metrics: Vec::new()), so the map stays empty no matter how much traffic precedes the call. A non-empty assertion would fail unconditionally. I left the per-entry type checks (with a comment explaining they only run once the server starts populating the field) and covered the key/dict semantics in the new server-free test instead.
• Vacuous assertions (is not None, >= 0 on unsigned): dropped.
• Exact equality on server-global counters: switched to >= with a comment naming the pytest-xdist reason.
• Semver docstring: you're right — get_numeric_version formats {major}{minor:03}{patch:03}, so 1.2.3 -> 1002003. Fixed in the binding, in core/common/src/types/stats/mod.rs, and the stub is regenerated.

Also merged master to catch the branch up.

[7487]

/ready