hiero-ledger / hiero-ledger/hiero-sdk-python
feat: generate ResponseCode member list from proto in generate_proto.py
- Dominant language
- Python
- Stars
- 63
- Forks
- 298
- Avg merge
- 3d 18h
- Merged PRs (30d)
- 38
Description
### 🧑🔬 Advanced Issue
Welcome! This is an **[Advanced Issue](https://github.com/issues?q=is%3Aopen%20is%3Aissue%20org%3Ahiero-ledger%20archived%3Afalse%20no%3Aassignee%20(label%3A%22advanced%22%20OR%20label%3A%22skill%3A%20advanced%22)%20(repo%3Ahiero-ledger%2Fhiero-sdk-cpp%20OR%20repo%3Ahiero-ledger%2Fhiero-sdk-swift%20OR%20repo%3Ahiero-ledger%2Fhiero-sdk-python%20OR%20repo%3Ahiero-ledger%2Fhiero-sdk-js%20OR%20repo%3Ahiero-ledger%2Fhiero-website))** touching core SDK tooling.
It is designed for expert contributors who have demonstrated deep architectural understanding and a proven track record of high-quality contributions.
### 🐞 Problem Description
`src/hiero_sdk_python/response_code.py` is a hand-maintained duplicate of an enum the repo already generates from protobufs (`src/hiero_sdk_python/hapi/services/response_code_pb2.py`). Hand-maintenance caused the drift fixed in #2608: swapped numbers, misspelled names, and missing codes that produced actively misleading error messages for users.
#2609 adds a CI test that *detects* drift. This issue goes further: make drift structurally impossible by generating the member list of `response_code.py` as part of the existing proto-generation step (`generate_proto.py` at the repo root), so that updating the vendored protobufs automatically updates `ResponseCode`.
### 🛠️ Implementation Notes
The hand-written shell of `response_code.py` must be preserved: module docstring, imports, the `_missing_` hook, `is_unknown`, and the deprecated `get_name`. Only the enum member list should be generated. Plausible approaches to evaluate:
- A marked begin/end region inside `response_code.py` that the generator rewrites in place, or
- A template file the generator renders, with the shell kept in the template.
Design points to settle (post your proposed approach as a comment and get maintainer approval **before writing code**):
- **Source of member data:** parse `.protos/services/response_code.proto` directly, or import the freshly generated `response_code_pb2` and iterate `ResponseCodeEnum.items()`. Consider which is more robust inside `generate_proto.py`'s execution environment.
- **Deprecated aliases:** #2608 introduces deprecated aliases for three renamed codes (`INVALID_GOSSIP_CAE_CERTIFICATE`, `MAX_PENDING_AIRDROP_ID_EXCEEDED`, `INVALID_TOKEN_ID_PENDING_AIRDROP`). These must survive regeneration — e.g. keep them in the hand-written region, or generate them from a small explicit alias map with a documented removal plan.
- **Proto deprecations:** carry `[deprecated = true]` annotations from the proto into comments on the generated members.
- **Static output only:** the generated file must remain a plain, readable, statically-defined `IntEnum` — no dynamic enum construction at import time. IDE autocompletion, `.pyi` type visibility, and mypy must keep working exactly as today.
- **Determinism:** regenerating with unchanged protos must produce a byte-identical file (stable ordering, no timestamps), so CI can verify the checked-in file is up to date.
**Key risks:** silently changing public enum members via generation (mitigated by #2609's parity test and review of the first generated diff); breaking the proto-generation pipeline for all other generated modules; losing the shell methods or docstrings on regeneration.
### 🧠 Advanced Contributors — Prerequisites & Expectations
> [!CAUTION]
> **Advanced issues are the highest-risk work in this project. We will reject PRs that do not meet these standards.**
### 🏁 Concrete Prerequisites
- **Advanced Language:** Proficient with Python.
- **Expertise:** Solid understanding of the proto-generation pipeline (`generate_proto.py`, `.protos/`, `hapi/`) and Python `enum` internals.
- **Proven History:** Successfully completed **≥ 10 intermediate issues** in this repo.
- **Consistency:** **≥ 3–4 months** of active, human-led contributions to this SDK.
### ⚠️ AI Usage Policy
- Using AI to generate code for Advanced issues is **strictly discouraged**
- AI may be used to help explain file relationships, but cannot be the main source of research.
- Submitting AI-generated or unvalidated code is grounds for **immediate closure**
### ⏱️ Timeline & Workflow
- **Typical time:** ~1 month / ~50 hours.
- 🔴 Completing an advanced issue in 1–3 days is a **red flag** and will likely be rejected.
- **Required:** Post your proposed architectural approach as a comment and wait for explicit maintainer approval **before writing any code.**
### 🔬 Technical Domains
- [x] **Protobuf Alignment** (reading `.proto` files, generated `_pb2` modules, `EnumTypeWrapper`)
- [x] **Backward Compatibility** (preserving public enum members, aliases, and the hand-written shell)
- [x] **Code Generation / Tooling** (`generate_proto.py`, deterministic output, template or region rewriting)
- [x] **Testing** (parity test from #2609 as the CI guard; a check that regeneration is idempotent)
- [ ] **API Client Architecture**
- [ ] **Execution Boundaries**
### 🛡️ Quality & Review Standards
Advanced PRs must be **"safe, maintainable, architecturally sound, and production-ready."**
1. **Architectural Fit:** The generator must fit naturally into `generate_proto.py`'s existing structure and conventions.
2. **Correctness:** The first generated `response_code.py` must be diff-reviewed member by member against the previous hand-written file.
3. **Maintainability:** Any maintainer must be able to rerun generation and understand the template/region mechanism without your assistance.
4. **Backward Compatibility:** Public API surface of `ResponseCode` (members, aliases, shell methods) must be byte-for-byte preserved except where the proto itself changes.
5. **Comprehensive Testing:** The #2609 parity test passes on generated output; add a check (test or CI step) that the checked-in file matches freshly generated output.
### ✅ PR Quality Checklist
Before opening your PR, the contributor must confirm:
- [ ] I posted my design as a comment and received maintainer approval before coding.
- [ ] I understand the system-wide impact of these changes on the proto-generation pipeline.
- [ ] Regeneration with unchanged protos is byte-identical (idempotent).
- [ ] I have verified the generated member list against the pinned protobufs.
- [ ] The hand-written shell (`_missing_`, `is_unknown`, `get_name`, docstrings) survives regeneration.
- [ ] Every line of code is personally understood and explainable.
### 📚 Resources & Support
**References:**
- `generate_proto.py` (repo root) — the generation entry point to extend
- `.protos/services/response_code.proto` — the input, including `[deprecated = true]` annotations and doc comments
- `src/hiero_sdk_python/response_code.py` — the shell to preserve
- [Python enum HOWTO](https://docs.python.org/3/howto/enum.html)
**Python SDK References:**
- [SDK Project Structure](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/setup/project_structure.md)
- [Browse closed advanced PRs](https://github.com/hiero-ledger/hiero-sdk-python/pulls?q=is%3Apr+is%3Amerged+label%3A%22skill%3A+advanced%22)
**🆘 Stuck?**
- [Community Calls](https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week)
- [Discord](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/discord.md)
Contributor guide
Research direction
Start with generate_proto.py at the repository root, then inspect .protos/services/response_code.proto and the hand-written shell in src/hiero_sdk_python/response_code.py. Review the parity test from #2609 and the generated response_code_pb2.py before proposing an approach for maintainer approval. Done means deterministic regeneration preserves the shell, aliases, public members, and deprecation information, with the parity and idempotence checks passing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100