[Advanced]: Prompt code rabbit on how to review src/hiero_sdk_python/tokens

[exploreriii]

🧠 Advanced Contributors

This issue is intended for contributors who are already very familiar with the
Hiero Python SDK codebase and its architectural patterns.

You should feel comfortable:

• navigating multiple modules across src/
• understanding and modifying core SDK abstractions
• reasoning about API design and backwards compatibility
• updating or extending tests, examples, and documentation as needed
• making changes that may affect public-facing behavior

New developers should start with
Good First Issues or Intermediate Issues first.

🐞 Problem Description

Additions or changes to token transactions should be reviewed in a slightly different way to other src files, like queries, because they use the Transaction base class

💡 Proposed / Expected Solution

Prompt code rabbit on how to review token transactions or classes

class example:
src/hiero_sdk_python/tokens/token_info.py
src/hiero_sdk_python/tokens/token_kyc_status.py (base class enum)

transaction example:
src/hiero_sdk_python/tokens/token_reject_transaction.py
base class: transaction

we should ensure:

• technically functional
• use methods that are safe, and can grow with project needs without much breaking changes
• strictly validate all import paths (don't look at examples, look at other src/token imports or knowledge of code base, flag hallucinations
• no breaking changes, or, if there is, appropriate deprecation warnings and testing
• google style docstrings in functions with args and returns and module level
• type hinted e.g. return types
• comments
• should have setters to allow method chaining
• distinction between internal and external API methods
• errors should be deterministic, user-readable, raised at appropriate places
• if possible should follow documentation of protobufs at https://github.com/hashgraph/hedera-protobufs/tree/8c27786cec93abab974309074feaef9b48a695b7/services
• Changes must not break existing APIs
• If a breaking change is unavoidable:
  Require explicit deprecation warnings for future releases
  Require corresponding tests
• Meaningful inline comments where behavior is non-obvious

classes

• often will have convenience methods e.g. str, repr

transactions

• inherits from transaction
• super init
• _build_proto_body, build_transaction_body, build_scheduled_body (less strict), _get_method- get method needs to call correct service
• often will have from proto method
• will often have a corresponding/example and tests/unit and tests/integration

🧠 Implementation & Design Notes

The implementation requires innovation and creativity to create a solution that achieves a code rabbit reviewer that is better than human reviewers for the python sdk in many ways

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem and design goals described above
• Maintain backwards compatibility unless explicitly approved otherwise
• Follow existing architectural and coding conventions
• Include comprehensive tests covering new and existing behavior
• Update relevant examples and documentation
• Pass all CI checks
• Include a valid changelog entry
• Use DCO and GPG-signed commits

📚 Additional Context, Links, or Prior Art

Optional.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• Create docs/sdk_developers/training/coding_token_transactions.md #863

Related Issues

• Create examples/tokens/token_update_nfts_transaction.py #881
• [Advanced]: Prompt Coderabbit on how to review /examples #1180
• Refactor examples/token_delete, token_dissociate, token_freeze, token_unfreeze, token_mint_fungible, token_mint_non_fungible, topic_create for readability #370
• [Good First Issue]: black examples/tokens #1119
• [Advanced]: Prompt Coderabbit on how to review /docs #1181
• chore: Add comprehensive docstrings to TransactionRecord in transaction_record.py #683
• Deprecate Snake Case Variables and Deprecated Aliases #428

🔗 Related PRs

#1051 - fix: support public for batch_key in Transaction [merged]
#1131 - chore: rename file test_token_fee_schedule_update_transaction_e2e.py to amke it end with _test.py #1117 [merged]
#1148 - feat: Transform custom_fee_fixed example to end-to-end test [merged]
#1176 - chore: refactor custom_royalty_fee.py into modular functions [merged]
#1189 - feat: Add custom CodeRabbit instructions for examples [closed]

👤 Suggested Assignees

• exploreriii
• Adityarya11
• Rishabh1925
• AubreyDDD
• Bhavanahegde-23

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Add CodeRabbit automated review instructions to .coderabbit.yaml for the tokens directory (src/hiero_sdk_python/tokens/), ensuring thorough validation of token transactions, data classes, and enums against established SDK patterns, API compatibility requirements, and protobuf specifications.

Observations

Codebase Summary

The Hiero Python SDK uses a Transaction base class that requires subclasses to implement specific methods (build_transaction_body(), build_scheduled_body(), _get_method()). Token classes are implemented as frozen dataclasses with bidirectional proto conversion (_from_proto(), _to_proto()), while enums extend Python's Enum class with optional proto conversion support. The project already has a .coderabbit.yaml configuration file with a path_instructions section that provides review guidance for the examples/**/* directory, which serves as a template for adding token-specific instructions.

Assumptions

Assumption 1: Single vs Multiple Path Instructions

Options Considered:

• Single comprehensive path instruction for src/hiero_sdk_python/tokens/**/*
• Multiple targeted entries
• Hierarchical approach

Chosen Option: Single comprehensive path instruction for src/hiero_sdk_python/tokens/**/*

Rationale: This aligns with the existing pattern in .coderabbit.yaml where examples use a single comprehensive entry, provides a single source of truth that's easier to maintain, and creates a clearer developer experience. The prompt will be organized into logical sections (Common Requirements, Transaction-Specific, Class-Specific, Enum-Specific) to maintain clarity despite the comprehensive nature.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Add CodeRabbit Review Instructions for Tokens Directory

This phase adds a new path_instructions entry to .coderabbit.yaml that provides comprehensive automated review guidance for all token-related files, organized into sections covering common requirements and type-specific validations.

Task 1: Define Common Review Requirements Section

Create the foundational review requirements that apply to all token files (transactions, classes, enums).

• Add new path_instructions entry in .coderabbit.yaml under the reviews.path_instructions array for path src/hiero_sdk_python/tokens/**/*
• Include validation for import paths: verify all imports reference actual SDK modules (use exploration knowledge of src/hiero_sdk_python/ structure), flag any hallucinated import paths that don't match established patterns
• Require Google-style docstrings with module-level documentation and function/method docstrings that include Args and Returns sections
• Validate type hints are present for all function/method parameters and return types
• Check for meaningful inline comments where behavior is non-obvious or complex
• Verify alignment with Hedera protobuf documentation at https://github.com/hashgraph/hedera-protobufs/tree/8c27786cec93abab974309074feaef9b48a695b7/services
• Validate no breaking changes to existing APIs; if unavoidable, require explicit deprecation warnings using Python's warnings.warn() with DeprecationWarning and corresponding tests
• Check that errors are deterministic, user-readable, and raised at appropriate places in the code

Task 2: Define Transaction-Specific Review Requirements

Add requirements specific to transaction classes that extend the Transaction base class.

• Verify inheritance from Transaction base class and call to super().__init__() in constructor
• Require implementation of all abstract methods: build_transaction_body(), build_scheduled_body(), and _get_method(channel)
• Validate _get_method() returns correct gRPC service method (cross-reference with protobuf service definitions)
• Check for _build_proto_body() method that constructs the transaction-specific protobuf message
• Verify all setter methods return self (or "ClassName" type hint) to enable method chaining
• Ensure proper use of _require_not_frozen() in setters to enforce immutability after freezing
• Check for _from_proto() class method for proto-to-object conversion if the transaction supports deserialization
• Verify proto building uses .CopyFrom() pattern and calls ._to_proto() on nested SDK objects (TokenId, AccountId, etc.)
• Require corresponding example file in examples/tokens/ directory
• Require unit tests in tests/unit/ covering proto building, method chaining, and from_proto conversion
• Require integration test in tests/integration/ covering end-to-end transaction execution with client

Task 3: Define Class-Specific Review Requirements

Add requirements for token data model classes (non-transaction classes like TokenInfo, TokenAllowance).

• Verify use of @dataclass(frozen=True) decorator for immutable data models
• Require _from_proto() class method that converts protobuf message to SDK object
• Require _to_proto() method that converts SDK object to protobuf message
• Check for proper handling of camelCase (proto) to snake_case (Python) field name conversions
• Validate nested message conversions call _from_proto() on complex types (TokenId, AccountId, PublicKey, etc.)
• Require convenience methods like __str__() for comprehensive string representation
• Check that optional fields use Optional[Type] type hints and handle None values appropriately
• Verify proto field mapping includes all fields from the corresponding protobuf message definition
• Validate enum conversions use proper enum constructors or _from_proto() methods

Task 4: Define Enum-Specific Review Requirements

Add requirements for token enum classes that represent protobuf enum types.

• Verify inheritance from Python's Enum base class
• Check enum values match corresponding protobuf enum integer values
• Require _from_proto() static method for enums that need proto conversion, mapping protobuf enum values to Python enum instances
• Validate _from_proto() raises ValueError for unknown proto enum values
• Check for custom __eq__() method if the enum needs to support comparison with integer values
• Verify enum value names match protobuf enum constant names (converted to Python naming convention)
• Ensure import of corresponding protobuf enum type from hiero_sdk_python.hapi.services if proto conversion is implemented

Task 5: Add Testing and Documentation Validation

Add cross-file validation requirements to ensure comprehensive coverage.

• For each new transaction class, verify existence of corresponding example file with consistent naming pattern
• Verify unit test file exists and includes tests for: proto building (test_build_transaction_body_populates_proto), method chaining, from_proto round-trip conversion, and error cases
• Verify integration test file exists and includes at least one end-to-end execution test with response validation
• Check that examples follow established pattern: environment setup, helper functions, main() orchestration, proper error handling with ResponseCode validation
• Validate that test fixtures from tests/unit/conftest.py are reused where appropriate (mock_account_ids, token_id, nft_id, transaction_id, private_key)
• Ensure integration tests use IntegrationTestEnv for client setup and proper cleanup in try/finally blocks
• Verify test assertions check both success status (ResponseCode.SUCCESS) and relevant transaction-specific fields in receipts/records

🤖 Prompt for AI agents

Add comprehensive CodeRabbit review instructions to `.coderabbit.yaml` for the
tokens directory to validate SDK patterns, API compatibility, and protobuf
alignment.

Add new path_instructions entry for `src/hiero_sdk_python/tokens/**/*` with
organized sections:

**Common Requirements:**
- Validate import paths reference actual SDK modules
- Require Google-style docstrings with Args/Returns sections
- Validate type hints on all parameters and return types
- Verify alignment with Hedera protobuf documentation
- Check for breaking changes and require deprecation warnings if needed
- Validate errors are deterministic and user-readable

**Transaction-Specific:**
- Verify Transaction base class inheritance and super().__init__() call
- Require abstract method implementations: build_transaction_body(),
build_scheduled_body(), _get_method()
- Validate _get_method() returns correct gRPC service method
- Check setter methods return self for chaining and use _require_not_frozen()
- Verify proto building uses .CopyFrom() pattern
- Require corresponding example, unit tests, and integration tests

**Class-Specific:**
- Verify @dataclass(frozen=True) decorator usage
- Require _from_proto() and _to_proto() methods
- Check camelCase to snake_case conversions
- Validate nested conversions call _from_proto() on complex types
- Check Optional[Type] hints for optional fields

**Enum-Specific:**
- Verify Enum base class inheritance
- Check enum values match protobuf enum integers
- Require _from_proto() static method with ValueError handling
- Validate enum names match protobuf conventions

**Testing/Documentation:**
- Verify example files exist with consistent naming
- Check unit tests cover proto building, chaining, conversions, and errors
- Verify integration tests include end-to-end execution with response validation
- Validate test fixture reuse and IntegrationTestEnv usage

---

🚀 Next Steps

🤖 All AI agent prompts combined

Add comprehensive CodeRabbit review instructions to `.coderabbit.yaml` for the
tokens directory to validate SDK patterns, API compatibility, and protobuf
alignment.

Add new path_instructions entry for `src/hiero_sdk_python/tokens/**/*` with
organized sections:

**Common Requirements:**
- Validate import paths reference actual SDK modules
- Require Google-style docstrings with Args/Returns sections
- Validate type hints on all parameters and return types
- Verify alignment with Hedera protobuf documentation
- Check for breaking changes and require deprecation warnings if needed
- Validate errors are deterministic and user-readable

**Transaction-Specific:**
- Verify Transaction base class inheritance and super().__init__() call
- Require abstract method implementations: build_transaction_body(),
build_scheduled_body(), _get_method()
- Validate _get_method() returns correct gRPC service method
- Check setter methods return self for chaining and use _require_not_frozen()
- Verify proto building uses .CopyFrom() pattern
- Require corresponding example, unit tests, and integration tests

**Class-Specific:**
- Verify @dataclass(frozen=True) decorator usage
- Require _from_proto() and _to_proto() methods
- Check camelCase to snake_case conversions
- Validate nested conversions call _from_proto() on complex types
- Check Optional[Type] hints for optional fields

**Enum-Specific:**
- Verify Enum base class inheritance
- Check enum values match protobuf enum integers
- Require _from_proto() static method with ValueError handling
- Validate enum names match protobuf conventions

**Testing/Documentation:**
- Verify example files exist with consistent naming
- Check unit tests cover proto building, chaining, conversions, and errors
- Verify integration tests include end-to-end execution with response validation
- Validate test fixture reuse and IntegrationTestEnv usage

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!