chore: enhance exception type safety and context

[Adityarya11]

Description:
Type hints to exception classes (PrecheckError, MaxAttemptsError, ReceiptStatusError) constructors and string methods.

Related issue(s):

Fixes #1504

Notes for reviewer:
Tested the unit test and the example

Checklist

• Documented (Code comments, README, etc.)
• Tested (unit, integration, etc.)

[codecov]

Codecov Report

❌ Patch coverage is 91.66667% with 1 line in your changes missing coverage. Please review.

@@            Coverage Diff             @@
##             main    #1594      +/-   ##
==========================================
+ Coverage   92.89%   92.90%   +0.01%     
==========================================
  Files         140      140              
  Lines        8767     8769       +2     
==========================================
+ Hits         8144     8147       +3     
+ Misses        623      622       -1     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Walkthrough

Adds type annotations and return type hints to three exception classes, adds unit tests for those exceptions, introduces two new error example scripts, refactors an existing example to use Client.from_env() and top-level SDK imports, and updates the changelog. No behavioral changes reported.

Changes

Cohort / File(s)	Summary
Exception Type Hints src/hiero_sdk_python/exceptions.py	Added from __future__ import annotations, TYPE_CHECKING imports, precise type hints to PrecheckError, MaxAttemptsError, and ReceiptStatusError constructors, and added -> str return annotations to __str__() and __repr__().
Exception Unit Tests tests/unit/exceptions_test.py	New unit tests covering PrecheckError, MaxAttemptsError, and ReceiptStatusError, validating default/custom messages, attribute preservation, and str/repr outputs using mocked transaction id/receipt.
Refactored Example examples/errors/receipt_status_error.py	Refactored to use Client.from_env() and top-level hiero_sdk_python imports; main() annotated -> None; operator credentials sourced from the client; receipt handling now explicitly checks for missing status and non-success status.
New Error Examples examples/errors/max_attempts_error.py, examples/errors/precheck_error.py	Added examples demonstrating handling of MaxAttemptsError and PrecheckError; both use Client.from_env(), explicit main() -> None, and show SDK error-handling flows.
Changelog CHANGELOG.md	Added Unreleased entry documenting added type hints to exception constructors and __str__/__repr__ methods.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'chore: enhance exception type safety and context' accurately reflects the main change in the PR, which adds type hints to exception classes.
Description check	✅ Passed	The description is related to the changeset, stating that type hints were added to exception class constructors and string methods, and references the linked issue #1504.
Linked Issues check	✅ Passed	The PR successfully implements all Phase 1 and Phase 2 objectives from issue #1504: adds return type hints (-> str) to str() and repr() methods, adds comprehensive constructor type hints with proper typing to all three exception classes, includes unit tests covering the new typed constructors, and provides example files demonstrating exception handling.
Out of Scope Changes check	✅ Passed	All changes directly support the linked issue objectives. The examples (precheck_error.py, max_attempts_error.py, receipt_status_error.py) demonstrate exception handling per issue requirements, the unit tests validate typed constructors, and exceptions.py adds the required type hints without introducing unrelated functionality.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR improves type safety and developer ergonomics around core exception types and their usage, and adds tests and documentation updates to validate and describe the behavior.

Changes:

• Added precise constructor and string/representation type hints for PrecheckError, MaxAttemptsError, and ReceiptStatusError, including forward-referenced types for transaction context.
• Introduced unit tests exercising these exception types’ initialization, default message generation, and string/repr behavior.
• Modernized the examples/errors/receipt_status_error.py example to use Client.from_env() and the high-level package imports, and documented the change in CHANGELOG.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/hiero_sdk_python/exceptions.py	Adds type hints to exception constructors and __str__/__repr__ methods, and uses TYPE_CHECKING imports to avoid runtime cycles while enabling structured error context types.
tests/unit/exceptions_test.py	New unit tests validate typed construction, default message generation, and string/repr output for the three exception classes.
examples/errors/receipt_status_error.py	Updates the error-handling example to use Client.from_env(), the package-level imports (Client, ResponseCode, TokenAssociateTransaction, TokenId), and to align with the stricter ReceiptStatusError typing.
CHANGELOG.md	Records the addition of type hints for the exception classes’ constructors and string methods.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

[github-actions]

Hi, this is MergeConflictBot.
Your pull request cannot be merged because it contains merge conflicts.

Please resolve these conflicts locally and push the changes.

To assist you, please read:

• Resolving Merge Conflicts
• Rebasing Guide

Thank you for contributing!

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

examples/errors/receipt_status_error.py (1)

52-58: Simplify redundant ResponseCode() wrapping.

Same as in precheck_error.py: e.status is already a ResponseCode enum, so wrapping it again is unnecessary.

♻️ Suggested simplification

     except ReceiptStatusError as e:
         print("\nCaught ReceiptStatusError!")
-        print(f"Status: {e.status} ({ResponseCode(e.status).name})")
+        print(f"Status: {e.status} ({e.status.name})")
         print(f"Transaction ID: {e.transaction_id}")

[coderabbitai]

Actionable comments posted: 1

[github-actions]

Hello, this is the OfficeHourBot.

This is a reminder that the Hiero Python SDK Office Hours are scheduled in approximately 4 hours (14:00 UTC).

This session provides an opportunity to ask questions regarding this Pull Request.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.

From,
The Python SDK Team

[aceppaluni]

@Adityarya11
I looked into _Executable._execute, and at the moment MaxAttemptsError is always constructed with err_persistant, which is a formatted string (including in the grpc.RpcError path).

Given that current usage, I agree that keeping last_error typed as Optional[str] is reasonable for now and accurately reflects how the SDK behaves today.

If we later decide to propagate the underlying grpc.RpcError (or another concrete Exception) instead of a formatted message, we can revisit this and widen the type or refactor the execution path in a follow-up PR. For this change, keeping the scope minimal makes sense.

[Adityarya11]

@Adityarya11 I looked into _Executable._execute, and at the moment MaxAttemptsError is always constructed with err_persistant, which is a formatted string (including in the grpc.RpcError path).

Given that current usage, I agree that keeping last_error typed as Optional[str] is reasonable for now and accurately reflects how the SDK behaves today.

If we later decide to propagate the underlying grpc.RpcError (or another concrete Exception) instead of a formatted message, we can revisit this and widen the type or refactor the execution path in a follow-up PR. For this change, keeping the scope minimal makes sense.

Yeah got it Thanks..👍

may be a GFI would make sense for that :)
We got early GFI even if it is not one XD.

[aceppaluni]

@Adityarya11 This is great work, awesome job!