feat(python): expose structured IggyError

[mmmmxa]

Which issue does this PR address?

Closes #3618

Rationale

Introduce IggyError class in Python SDK to fully represent Iggy-specific errors from Rust. (See issue for more info)

What changed?

Python was exposing Iggy failures as plain RuntimeError or ValueError with only a message, while no code and snake case error name was provided.

The changes introduce the IggyError Python class that represent IggyError in Rust 1 to 1. Thus, it has code, message and the snake case error name, which gives more transparency in debugging and more information for clean exception handling.

Local Execution

• Passed
• Pre-commit hooks ran

AI Usage

1. Which tools? (e.g., GitHub Copilot, Claude, ChatGPT) - Claude
2. Scope of usage? (e.g., autocomplete, generated functions, entire implementation) - autocomplete, mass updates of some test cases, documentation generation.
3. How did you verify the generated code works correctly? - The generated code is either tested or a part of tests, which all pass. I have also performed multiple self-reviews.
4. Can you explain every line of the code if asked? - Yes.

[mmmmxa]

/ready

[codecov]

Codecov Report

❌ Patch coverage is 86.20690% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.99%. Comparing base (6f1d548) to head (8d2402f).
⚠️ Report is 45 commits behind head on master.

Files with missing lines	Patch %	Lines
foreign/python/src/error.rs	58.82%	7 Missing ⚠️
foreign/python/src/identifier.rs	75.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3696      +/-   ##
============================================
- Coverage     73.99%   73.99%   -0.01%     
  Complexity      937      937              
============================================
  Files          1301     1302       +1     
  Lines        147393   147405      +12     
  Branches     122945   122945              
============================================
+ Hits         109063   109070       +7     
- Misses        34858    34863       +5     
  Partials       3472     3472              

Components	Coverage Δ
Rust Core	74.29% <ø> (ø)
Java SDK	62.44% <ø> (ø)
C# SDK	72.18% <ø> (ø)
Python SDK	91.73% <86.20%> (-0.44%)	⬇️
PHP SDK	84.29% <ø> (ø)
Node SDK	91.26% <ø> (ø)
Go SDK	42.87% <ø> (ø)

Files with missing lines	Coverage Δ
foreign/python/src/client.rs	98.99% <100.00%> (-0.01%)	⬇️
foreign/python/src/consumer.rs	81.15% <100.00%> (+0.61%)	⬆️
foreign/python/src/lib.rs	100.00% <100.00%> (ø)
foreign/python/src/send_message.rs	96.77% <100.00%> (ø)
foreign/python/src/identifier.rs	76.47% <75.00%> (-1.31%)	⬇️
foreign/python/src/error.rs	58.82% <58.82%> (ø)

🚀 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.

[slbotbm]

@mmmmxa Will come back to this once all existing python sdk PRs are merged since they will require aligning the error types to the struct introduced here.

[slbotbm]

/request-review @slbotbm

[mmmmxa]

@slbotbm Could you please let me know when it’s going to happen? Or let me know a way of finding out when should I merge the master and make same changes to the new code as well?

[slbotbm]

sure, when the other prs are merged, i'll review yours and ping you

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs.

If you need a review, please ensure CI is green and the PR is rebased on the latest master. Don't hesitate to ping the maintainers - either @core on Discord or by mentioning them directly here on the PR.

Thank you for your contribution!

[slbotbm]

The docs for the methods are not updated. Please update them to include IggyError in them as well. If the methods are following the old way of documentation with 1-2 lines of docs, could you update them to follow the new way that aligns with normal python lib docs as well please?