docs: add Query class training documentation for SDK contributors #1313
Conversation
undefinedIsMyLife
force-pushed
the
docs-query-explanation
branch
from
8759fa5 to
239f934
Compare
|
[commit-verification-bot] To achieve verified status, please read: Remember, you require a GPG key and each commit must be signed with: Thank you for contributing! From the Hiero Python SDK Team |
📝 WalkthroughWalkthroughAdded a new SDK developer training document Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Pre-merge checks✅ Passed checks (5 passed)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
CHANGELOG.mddocs/sdk_developers/query.md
🧰 Additional context used
📓 Path-based instructions (2)
docs/**
⚙️ CodeRabbit configuration file
docs/**: You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers.Priority 1 - Correctness (code, commands, links)
- Verify code snippets conceptually run and match the current SDK API.
- Check shell commands and workflow steps against actual project tooling.
- Validate URLs and cross-references; flag broken or misleading links.
Priority 2 - Clarity and completeness
- Ensure each page states its purpose and expected outcome early.
- Prefer concrete, step-wise explanations over vague descriptions.
- Highlight missing prerequisites that would block a reader.
- For larger gaps, suggest filing a follow-up issue instead of blocking.
Priority 3 - Consistency and navigation
- Encourage consistent terminology with the SDK and examples.
- Check headings form a logical reading path.
- Confirm each page makes clear which audience it serves.
PHILOSOPHY
- Treat docs as work-in-progress: optimize for correctness and clarity over perfection.
- Keep feedback concise, action-oriented, and focused on reader success.
- Do not request large-scale restructures unless current structure blocks understanding.
AVOID
- Avoid lint-style feedback on Markdown formatting or minor wording.
- Avoid proposing new conventions without clear benefit.
- Avoid turning every high-level gap into a blocker.
Files:
docs/sdk_developers/query.md
docs/sdk_developers/**
⚙️ CodeRabbit configuration file
docs/sdk_developers/**: These documents are for SDK developers and contributors, includingdocs/sdk_developers/training/**.Priority 1 - Workflow accuracy
- Ensure contribution, branching, rebasing, signing (DCO, GPG), CI, linting, and testing instructions match the repo.
- Verify
gitand GitHub flows agree with CONTRIBUTING.md and current practice.- Flag outdated references to scripts, directories, or configuration files.
Priority 2 - Training flow
- For training docs, ensure logical progression and clear prerequisites.
- Check that cross-links between training files are coherent.
PHILOSOPHY
- Treat these docs as a training ground for future maintainers and regular contributors.
- Help readers move from "I cloned the repo" to "I can safely extend and debug the SDK".
- Balance approachability for beginners with enough depth for experts.
Files:
docs/sdk_developers/query.md
🪛 markdownlint-cli2 (0.18.1)
docs/sdk_developers/query.md
23-23: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
49-49: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
136-136: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
139-139: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
148-148: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
151-151: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
199-199: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
200-200: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
211-211: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
212-212: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
219-219: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
222-222: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
223-223: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
226-226: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
293-293: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
296-296: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
309-309: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
310-310: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
368-368: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
369-369: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (4)
CHANGELOG.md (1)
10-10: LGTM!The changelog entry accurately summarizes the PR content and follows the established format. Issue reference is correct.
docs/sdk_developers/query.md (3)
15-51: Clear, well-structured overview and inheritance diagram.The Overview and Relationship sections effectively explain how
Queryextends_Executableand the separation of concerns between execution mechanics and query-specific logic. The Mermaid diagram (lines 43–49) visually reinforces the inheritance hierarchy. This section successfully orients readers before diving into implementation details.
320-376: Retry and Cost Queries explanation is solid; needs formatting corrections.The section clearly explains automatic retry behavior, retryable statuses, and the COST_ANSWER workflow. However:
- Line 369 uses bold text instead of a proper
###heading for "Notes for Contributors".- Code block (lines 361–368) needs blank lines above and below it (markdownlint MD031).
- Line 368 needs a blank line above the notes section (markdownlint MD022).
🔎 Proposed fix
# Execute the query with automatically attached payment balance = query.execute(client) + -**Notes for Contributors** +### Notes for ContributorsLikely an incorrect or invalid review comment.
377-390: Verify example file paths in Reference Implementations section.The section appropriately guides contributors to examine production-ready examples. However, the example file paths (lines 381–389) need verification against the current repository structure to ensure they match the actual locations after any examples reorganization:
examples/query/account_balance_query.pyexamples/query/account_info_query.pyexamples/query/token_info_query.pyexamples/query/token_nft_info_query.pyexamples/query/topic_info_query.pyexamples/query/topic_message_query.pyexamples/query/transaction_receipt_query.pyexamples/query/transaction_record_query.pyConfirm all files exist at these paths and update if the directory structure has changed.
There was a problem hiding this comment.
Actionable comments posted: 5
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
CHANGELOG.mddocs/sdk_developers/query.md
🧰 Additional context used
📓 Path-based instructions (2)
docs/**
⚙️ CodeRabbit configuration file
docs/**: You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers.Priority 1 - Correctness (code, commands, links)
- Verify code snippets conceptually run and match the current SDK API.
- Check shell commands and workflow steps against actual project tooling.
- Validate URLs and cross-references; flag broken or misleading links.
Priority 2 - Clarity and completeness
- Ensure each page states its purpose and expected outcome early.
- Prefer concrete, step-wise explanations over vague descriptions.
- Highlight missing prerequisites that would block a reader.
- For larger gaps, suggest filing a follow-up issue instead of blocking.
Priority 3 - Consistency and navigation
- Encourage consistent terminology with the SDK and examples.
- Check headings form a logical reading path.
- Confirm each page makes clear which audience it serves.
PHILOSOPHY
- Treat docs as work-in-progress: optimize for correctness and clarity over perfection.
- Keep feedback concise, action-oriented, and focused on reader success.
- Do not request large-scale restructures unless current structure blocks understanding.
AVOID
- Avoid lint-style feedback on Markdown formatting or minor wording.
- Avoid proposing new conventions without clear benefit.
- Avoid turning every high-level gap into a blocker.
Files:
docs/sdk_developers/query.md
docs/sdk_developers/**
⚙️ CodeRabbit configuration file
docs/sdk_developers/**: These documents are for SDK developers and contributors, includingdocs/sdk_developers/training/**.Priority 1 - Workflow accuracy
- Ensure contribution, branching, rebasing, signing (DCO, GPG), CI, linting, and testing instructions match the repo.
- Verify
gitand GitHub flows agree with CONTRIBUTING.md and current practice.- Flag outdated references to scripts, directories, or configuration files.
Priority 2 - Training flow
- For training docs, ensure logical progression and clear prerequisites.
- Check that cross-links between training files are coherent.
PHILOSOPHY
- Treat these docs as a training ground for future maintainers and regular contributors.
- Help readers move from "I cloned the repo" to "I can safely extend and debug the SDK".
- Balance approachability for beginners with enough depth for experts.
Files:
docs/sdk_developers/query.md
🪛 markdownlint-cli2 (0.18.1)
docs/sdk_developers/query.md
23-23: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
49-49: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
136-136: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
139-139: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
148-148: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
151-151: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
199-199: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
200-200: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
211-211: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
212-212: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
219-219: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
222-222: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
223-223: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
226-226: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
293-293: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
296-296: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
309-309: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
310-310: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
368-368: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
369-369: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (2)
CHANGELOG.md (1)
10-10: ✓ LGTMThe changelog entry is well-formatted, references the correct issue (#1238), and accurately summarizes the new training documentation.
docs/sdk_developers/query.md (1)
6-6: Verify anchor link rendering for underscore character.The Table of Contents includes an anchor link
#relationship-to-_executable(line 6) with an underscore character. Some Markdown processors may not handle this correctly. Verify that this anchor link works in the actual rendered documentation.This is a minor issue, but worth confirming. You can test by:
- Building the documentation locally and checking if the link resolves
- Checking if your documentation tool (e.g., GitHub Pages, Jekyll, MkDocs) properly handles underscores in headings
If there are rendering issues, consider changing the heading to avoid the underscore or verifying the link works as expected.
undefinedIsMyLife
force-pushed
the
docs-query-explanation
branch
from
239f934 to
27b7301
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/sdk_developers/query.md (1)
304-305: Add blank line before heading (MD022 violation).Line 304 should have a blank line above it to comply with markdown standards.
Usage Example
This pattern may recur in other sections of the document (e.g., lines 200, 212, 223, 310). Please review and apply the same fix throughout. </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: ASSERTIVE **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 239f934649a2ca7ce99ce1f4f2dc60e2475046ad and 27b7301e552ea26d5c27eec87da26dc2eb210940. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `CHANGELOG.md` * `docs/sdk_developers/query.md` </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>📓 Path-based instructions (2)</summary> <details> <summary>docs/**</summary> **⚙️ CodeRabbit configuration file** > `docs/**`: You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers. > > Priority 1 - Correctness (code, commands, links) > 1. Verify code snippets conceptually run and match the current SDK API. > 2. Check shell commands and workflow steps against actual project tooling. > 3. Validate URLs and cross-references; flag broken or misleading links. > > Priority 2 - Clarity and completeness > 1. Ensure each page states its purpose and expected outcome early. > 2. Prefer concrete, step-wise explanations over vague descriptions. > 3. Highlight missing prerequisites that would block a reader. > 4. For larger gaps, suggest filing a follow-up issue instead of blocking. > > Priority 3 - Consistency and navigation > 1. Encourage consistent terminology with the SDK and examples. > 2. Check headings form a logical reading path. > 3. Confirm each page makes clear which audience it serves. > > PHILOSOPHY > - Treat docs as work-in-progress: optimize for correctness and clarity over perfection. > - Keep feedback concise, action-oriented, and focused on reader success. > - Do not request large-scale restructures unless current structure blocks understanding. > > AVOID > - Avoid lint-style feedback on Markdown formatting or minor wording. > - Avoid proposing new conventions without clear benefit. > - Avoid turning every high-level gap into a blocker. > Files: - `docs/sdk_developers/query.md` </details> <details> <summary>docs/sdk_developers/**</summary> **⚙️ CodeRabbit configuration file** > `docs/sdk_developers/**`: These documents are for SDK developers and contributors, including `docs/sdk_developers/training/**`. > > Priority 1 - Workflow accuracy > 1. Ensure contribution, branching, rebasing, signing (DCO, GPG), CI, linting, and testing instructions match the repo. > 2. Verify `git` and GitHub flows agree with CONTRIBUTING.md and current practice. > 3. Flag outdated references to scripts, directories, or configuration files. > > Priority 2 - Training flow > 1. For training docs, ensure logical progression and clear prerequisites. > 2. Check that cross-links between training files are coherent. > > PHILOSOPHY > - Treat these docs as a training ground for future maintainers and regular contributors. > - Help readers move from "I cloned the repo" to "I can safely extend and debug the SDK". > - Balance approachability for beginners with enough depth for experts. > Files: - `docs/sdk_developers/query.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>docs/sdk_developers/query.md</summary> 304-304: Headings should be surrounded by blank lines Expected: 1; Actual: 0; Below (MD022, blanks-around-headings) </details> </details> </details> <details> <summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)</summary> * GitHub Check: Codacy Static Code Analysis </details> <details> <summary>🔇 Additional comments (1)</summary><blockquote> <details> <summary>CHANGELOG.md (1)</summary><blockquote> `10-10`: **CHANGELOG entry is well-formatted and appropriately positioned.** The new documentation entry is correctly placed in the `[Unreleased]` → `### Added` section, follows the established format (description with issue reference), and accurately summarizes the contribution (Query class training documentation with execution flow, payments, retries, and building child queries). </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
undefinedIsMyLife
force-pushed
the
docs-query-explanation
branch
from
27b7301 to
b8b02f9
Compare
|
hey as a general rule don't worry if the code rabbit suggestions are unreasonable ... we are still working on fine tuning it. general principles:
|
|
Thanks for taking a look! |
exploreriii
left a comment
exploreriii
left a comment
There was a problem hiding this comment.
Hi @undefinedIsMyLife
I think this is extremely good!
I will hesitate to approve this just yet because the examples you are using do not 100% line up with the sdk, but i think that's fine as they are high level - sort of
Please do make sure to make it clear they are high level simplfiications
and do link to the real /examples and make sure to point users ther.
Thank you!
|
Hi, this is MergeConflictBot. Please resolve these conflicts locally and push the changes. To assist you, please read: Thank you for contributing! |
|
@exploreriii I’ve added a global note clarifying that the embedded examples are intentionally simplified and linked to the production-ready implementations in /examples. |
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
CHANGELOG.mddocs/sdk_developers/query.md
🧰 Additional context used
📓 Path-based instructions (2)
docs/**
⚙️ CodeRabbit configuration file
docs/**: You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers.Priority 1 - Correctness (code, commands, links)
- Verify code snippets conceptually run and match the current SDK API.
- Check shell commands and workflow steps against actual project tooling.
- Validate URLs and cross-references; flag broken or misleading links.
Priority 2 - Clarity and completeness
- Ensure each page states its purpose and expected outcome early.
- Prefer concrete, step-wise explanations over vague descriptions.
- Highlight missing prerequisites that would block a reader.
- For larger gaps, suggest filing a follow-up issue instead of blocking.
Priority 3 - Consistency and navigation
- Encourage consistent terminology with the SDK and examples.
- Check headings form a logical reading path.
- Confirm each page makes clear which audience it serves.
PHILOSOPHY
- Treat docs as work-in-progress: optimize for correctness and clarity over perfection.
- Keep feedback concise, action-oriented, and focused on reader success.
- Do not request large-scale restructures unless current structure blocks understanding.
AVOID
- Avoid lint-style feedback on Markdown formatting or minor wording.
- Avoid proposing new conventions without clear benefit.
- Avoid turning every high-level gap into a blocker.
Files:
docs/sdk_developers/query.md
docs/sdk_developers/**
⚙️ CodeRabbit configuration file
docs/sdk_developers/**: These documents are for SDK developers and contributors, includingdocs/sdk_developers/training/**.Priority 1 - Workflow accuracy
- Ensure contribution, branching, rebasing, signing (DCO, GPG), CI, linting, and testing instructions match the repo.
- Verify
gitand GitHub flows agree with CONTRIBUTING.md and current practice.- Flag outdated references to scripts, directories, or configuration files.
Priority 2 - Training flow
- For training docs, ensure logical progression and clear prerequisites.
- Check that cross-links between training files are coherent.
PHILOSOPHY
- Treat these docs as a training ground for future maintainers and regular contributors.
- Help readers move from "I cloned the repo" to "I can safely extend and debug the SDK".
- Balance approachability for beginners with enough depth for experts.
Files:
docs/sdk_developers/query.md
🪛 markdownlint-cli2 (0.18.1)
docs/sdk_developers/query.md
318-318: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
406-406: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (4)
CHANGELOG.md (1)
10-10: ✓ Changelog entry is well-formatted and accurate.The entry properly describes the new documentation and references the linked issue.
docs/sdk_developers/query.md (3)
15-52: ✓ Overview and inheritance model explanation is clear and well-structured.The Mermaid diagram and separation of concerns between
_ExecutableandQueryeffectively establish the conceptual foundation for readers.
54-258: ✓ Core documentation sections are comprehensive and logically structured.The execution flow, payment mechanisms, and abstract method definitions effectively bridge high-level concepts with implementation guidance.
404-421: ✓ Reference Implementations section provides excellent guidance with proper disclaimers.The note at lines 406-409 appropriately caveat-emptor the high-level examples and directs readers to production-ready implementations. The linked examples are accurate references.
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## main #1313 +/- ##
=======================================
Coverage 92.29% 92.29%
=======================================
Files 139 139
Lines 8515 8515
=======================================
Hits 7859 7859
Misses 656 656 🚀 New features to boost your workflow:
|
exploreriii
left a comment
exploreriii
left a comment
There was a problem hiding this comment.
Great! Please rebase and ready to go
undefinedIsMyLife
force-pushed
the
docs-query-explanation
branch
from
89ddad8 to
5d19efa
Compare
Signed-off-by: undefinedIsMyLife <[email protected]> docs: fix markdown heading and spacing issues in Query training Signed-off-by: undefinedIsMyLife <[email protected]>
Signed-off-by: undefinedIsMyLife <[email protected]>
undefinedIsMyLife
force-pushed
the
docs-query-explanation
branch
from
5d19efa to
cee7d2b
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/sdk_developers/query.md (1)
316-333: Critical: Usage example contradicts implementation and documented API.Two API inconsistencies will cause runtime failures if copied:
- Line 323: Uses
AccountBalanceQuerybut the implementation (line 282) definesCryptoGetAccountBalanceQuery- Line 326: Uses
set_custom_payment()but the documented and inherited Query method isset_query_payment()Additionally, Line 316: Missing blank line after heading (markdown linting violation).
🔎 Proposed fixes
Usage Example
Once implemented, the query can be executed simply:
from hiero_sdk_python.client import Client client = Client.for_testnet() -query = AccountBalanceQuery(my_account_id) +query = CryptoGetAccountBalanceQuery(my_account_id) # Optional: set custom payment -query.set_custom_payment(Hbar(1)) +query.set_query_payment(Hbar(1)) # Execute query; all retries and payment handled automatically balance = query.execute(client) print(f"Account balance: {balance.balance} Hbar")</details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: ASSERTIVE **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 5d19efa43e9c53d1e2f4914d25f893307a83b853 and cee7d2bf70f5b30a9950b2cfcca95f68f097ed72. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `CHANGELOG.md` * `docs/sdk_developers/query.md` </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>📓 Path-based instructions (2)</summary> <details> <summary>docs/**</summary> **⚙️ CodeRabbit configuration file** > `docs/**`: You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers. > > Priority 1 - Correctness (code, commands, links) > 1. Verify code snippets conceptually run and match the current SDK API. > 2. Check shell commands and workflow steps against actual project tooling. > 3. Validate URLs and cross-references; flag broken or misleading links. > > Priority 2 - Clarity and completeness > 1. Ensure each page states its purpose and expected outcome early. > 2. Prefer concrete, step-wise explanations over vague descriptions. > 3. Highlight missing prerequisites that would block a reader. > 4. For larger gaps, suggest filing a follow-up issue instead of blocking. > > Priority 3 - Consistency and navigation > 1. Encourage consistent terminology with the SDK and examples. > 2. Check headings form a logical reading path. > 3. Confirm each page makes clear which audience it serves. > > PHILOSOPHY > - Treat docs as work-in-progress: optimize for correctness and clarity over perfection. > - Keep feedback concise, action-oriented, and focused on reader success. > - Do not request large-scale restructures unless current structure blocks understanding. > > AVOID > - Avoid lint-style feedback on Markdown formatting or minor wording. > - Avoid proposing new conventions without clear benefit. > - Avoid turning every high-level gap into a blocker. > Files: - `docs/sdk_developers/query.md` </details> <details> <summary>docs/sdk_developers/**</summary> **⚙️ CodeRabbit configuration file** > `docs/sdk_developers/**`: These documents are for SDK developers and contributors, including `docs/sdk_developers/training/**`. > > Priority 1 - Workflow accuracy > 1. Ensure contribution, branching, rebasing, signing (DCO, GPG), CI, linting, and testing instructions match the repo. > 2. Verify `git` and GitHub flows agree with CONTRIBUTING.md and current practice. > 3. Flag outdated references to scripts, directories, or configuration files. > > Priority 2 - Training flow > 1. For training docs, ensure logical progression and clear prerequisites. > 2. Check that cross-links between training files are coherent. > > PHILOSOPHY > - Treat these docs as a training ground for future maintainers and regular contributors. > - Help readers move from "I cloned the repo" to "I can safely extend and debug the SDK". > - Balance approachability for beginners with enough depth for experts. > Files: - `docs/sdk_developers/query.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>docs/sdk_developers/query.md</summary> 316-316: Headings should be surrounded by blank lines Expected: 1; Actual: 0; Below (MD022, blanks-around-headings) </details> </details> </details> <details> <summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)</summary> * GitHub Check: Codacy Static Code Analysis </details> <details> <summary>🔇 Additional comments (7)</summary><blockquote> <details> <summary>docs/sdk_developers/query.md (6)</summary><blockquote> `15-52`: **Clear foundation with effective visualization.** The Overview and Relationship sections provide a solid conceptual foundation, clearly explaining Query's role and inheritance from _Executable. The Mermaid diagram enhances scannability. --- `54-113`: **Comprehensive and well-structured execution lifecycle.** The execution flow section effectively breaks down the query lifecycle into digestible stages with clear explanations of each phase's role. --- `114-168`: **Payment handling thoroughly and accurately documented.** Explains zero-cost queries, custom payment setting, automatic cost calculation, and payment transaction construction with correct API method names and clear examples. --- `169-256`: **Clear method documentation with practical override guidance.** Required and optional abstract methods are well-documented with table summaries and scenarios for overriding. Effectively supports contributors implementing new queries. --- `272-314`: **Example implementation accurately reflects SDK patterns.** The CryptoGetAccountBalanceQuery example correctly demonstrates _make_request(), _get_query_response(), and _get_method() implementations with proper Protobuf usage patterns and _Method construction. --- `344-401`: **Retry and cost-query mechanics clearly explained.** Accurately describes retryable statuses, automatic retry behavior, and COST_ANSWER mechanism with appropriate examples and notes for contributors. </blockquote></details> <details> <summary>CHANGELOG.md (1)</summary><blockquote> `10-10`: **Changelog entry is well-formatted and accurately summarizes the PR contribution.** The entry concisely captures the key documentation additions (execution flow, payments, retries, building child queries) and properly references issue #1238. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Signed-off-by: undefinedIsMyLife <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
docs/sdk_developers/query.md (2)
318-334: Critical: Usage Example has API inconsistencies that contradict the implementation.The Usage Example uses an incorrect class name and method that will cause runtime errors:
- Line 325: The example instantiates
AccountBalanceQuery, but the implementation above (line 284) definesCryptoGetAccountBalanceQuery. These must match.- Line 328: The example calls
set_custom_payment(), but the documented pattern (line 131) andQuerybase class provideset_query_payment().These inconsistencies will break code if users copy this example directly.
🔎 Proposed fix for the Usage Example
client = Client.for_testnet() -query = AccountBalanceQuery(my_account_id) +query = CryptoGetAccountBalanceQuery(my_account_id) # Optional: set custom payment -query.set_custom_payment(Hbar(1)) +query.set_query_payment(Hbar(1)) # Execute query; all retries and payment handled automatically
318-319: Fix markdown heading spacing.The heading
### Usage Example(line 318) is missing a blank line after it before the paragraph text (line 319). This violates markdown linting standard MD022.🔎 Proposed fix for heading spacing
Usage Example
Once implemented, the query can be executed simply:
</details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: ASSERTIVE **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between cee7d2bf70f5b30a9950b2cfcca95f68f097ed72 and c81b1cdd21f90639c7fc9c067be4492b2caa939d. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `docs/sdk_developers/query.md` </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>📓 Path-based instructions (2)</summary> <details> <summary>docs/**</summary> **⚙️ CodeRabbit configuration file** > `docs/**`: You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers. > > Priority 1 - Correctness (code, commands, links) > 1. Verify code snippets conceptually run and match the current SDK API. > 2. Check shell commands and workflow steps against actual project tooling. > 3. Validate URLs and cross-references; flag broken or misleading links. > > Priority 2 - Clarity and completeness > 1. Ensure each page states its purpose and expected outcome early. > 2. Prefer concrete, step-wise explanations over vague descriptions. > 3. Highlight missing prerequisites that would block a reader. > 4. For larger gaps, suggest filing a follow-up issue instead of blocking. > > Priority 3 - Consistency and navigation > 1. Encourage consistent terminology with the SDK and examples. > 2. Check headings form a logical reading path. > 3. Confirm each page makes clear which audience it serves. > > PHILOSOPHY > - Treat docs as work-in-progress: optimize for correctness and clarity over perfection. > - Keep feedback concise, action-oriented, and focused on reader success. > - Do not request large-scale restructures unless current structure blocks understanding. > > AVOID > - Avoid lint-style feedback on Markdown formatting or minor wording. > - Avoid proposing new conventions without clear benefit. > - Avoid turning every high-level gap into a blocker. > Files: - `docs/sdk_developers/query.md` </details> <details> <summary>docs/sdk_developers/**</summary> **⚙️ CodeRabbit configuration file** > `docs/sdk_developers/**`: These documents are for SDK developers and contributors, including `docs/sdk_developers/training/**`. > > Priority 1 - Workflow accuracy > 1. Ensure contribution, branching, rebasing, signing (DCO, GPG), CI, linting, and testing instructions match the repo. > 2. Verify `git` and GitHub flows agree with CONTRIBUTING.md and current practice. > 3. Flag outdated references to scripts, directories, or configuration files. > > Priority 2 - Training flow > 1. For training docs, ensure logical progression and clear prerequisites. > 2. Check that cross-links between training files are coherent. > > PHILOSOPHY > - Treat these docs as a training ground for future maintainers and regular contributors. > - Help readers move from "I cloned the repo" to "I can safely extend and debug the SDK". > - Balance approachability for beginners with enough depth for experts. > Files: - `docs/sdk_developers/query.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>docs/sdk_developers/query.md</summary> 318-318: Headings should be surrounded by blank lines Expected: 1; Actual: 0; Below (MD022, blanks-around-headings) --- 406-406: Headings should be surrounded by blank lines Expected: 1; Actual: 0; Below (MD022, blanks-around-headings) </details> </details> </details> <details> <summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)</summary> * GitHub Check: Codacy Static Code Analysis </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
|
Thanks for the approval this push just restores the intended query.md changes after rebase |
|
Thank you! |
3 participants
Description:
This PR adds comprehensive training documentation for the
Queryclass in the Hiero Python SDK. The doc is intended for intermediate contributors who want to implement new queries or understand query execution patterns.Queryclass and its relationship with_ExecutableAccountBalanceQuery)Related issue(s):
Fixes #1238
Notes for reviewer:
Checklist