|
| 1 | +# Hiero Python SDK Project Structure |
| 2 | + |
| 3 | +Welcome to the Hiero Python SDK! Understanding the repository's structure is the first step to contributing effectively. This guide outlines the main directories and explains where to find the core SDK functionality, helping you locate the classes and methods you need to use and modify. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Top-Level File Structure](#top-level-file-structure) |
| 8 | + - [The `docs` Directory](#the-docs-directory) |
| 9 | + - [The `examples` Directory](#the-examples-directory) |
| 10 | + - [The `src` Directory (Core SDK)](#the-src-directory-core-sdk) |
| 11 | + - [The `tests` Directory](#the-tests-directory) |
| 12 | +- [Implications for Development (How to Import)](#implications-for-development-how-to-import) |
| 13 | +- [Conclusion](#conclusion) |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## Top-Level File Structure |
| 18 | + |
| 19 | +The repository is organized into four main directories: |
| 20 | + |
| 21 | +- `/docs`: All project documentation. |
| 22 | +- `/examples`: Runnable example scripts for SDK users. |
| 23 | +- `/src`: The SDK source code. **This is where you will make code changes.** |
| 24 | +- `/tests`: The unit and integration tests for the SDK. |
| 25 | + |
| 26 | +### The `docs` Directory |
| 27 | + |
| 28 | +This directory contains all documentation for both users and developers of the SDK. |
| 29 | + |
| 30 | +- **`docs/sdk_users/`**: Guides for people *using* the SDK in their applications (e.g., `running_examples.md`). |
| 31 | +- **`docs/sdk_developers/`**: Guides for people *contributing* to the SDK (e.g., `CONTRIBUTING.md`, `signing.md`, `testing.md`). |
| 32 | + |
| 33 | +### The `examples` Directory |
| 34 | + |
| 35 | +This folder contains complete, runnable Python scripts demonstrating how to use the SDK for various operations, such as creating tokens or submitting topic messages. This is the best place to see the SDK in action. |
| 36 | + |
| 37 | +### The `src` Directory (Core SDK) |
| 38 | + |
| 39 | +This is the heart of the SDK. The main source code lives inside `src/hiero_sdk_python/`. As an SDK developer, you will spend most of your time reading and modifying files in this directory. |
| 40 | + |
| 41 | +#### `src/hiero_sdk_python/hapi` |
| 42 | + |
| 43 | +This directory contains the Python classes auto-generated from the Hedera `.proto` (protobuf) files. |
| 44 | + |
| 45 | +- **Do not edit files here!** They are generated automatically by running `uv run python generate_proto.py`. |
| 46 | +- This is an advanced concept, but it can be useful to look at these files (especially in `hapi/services/`) to understand the exact data structures required by the Hedera network APIs. |
| 47 | + |
| 48 | +#### Core SDK Modules |
| 49 | + |
| 50 | +The other directories inside `src/hiero_sdk_python/` contain the actual SDK logic. This is where you will add features, fix bugs, and make your contributions. |
| 51 | + |
| 52 | +Each directory corresponds to a specific area of functionality: |
| 53 | + |
| 54 | +- **`account/`**: Contains transactions and queries related to Hedera accounts (e.g., `AccountCreateTransaction`, `AccountInfoQuery`). |
| 55 | +- **`address_book/`**: Contains logic for node address books. |
| 56 | +- **`client/`**: Contains the main `Client` class that manages network connections and operators. |
| 57 | +- **`consensus/`**: For Hedera Consensus Service (HCS) (e.g., `TopicCreateTransaction`, `TopicMessageSubmitTransaction`). |
| 58 | +- **`contract/`**: For Hedera Smart Contract Service (HSCS) (e.g., `ContractCreateTransaction`, `ContractCallQuery`). |
| 59 | +- **`file/`**: For Hedera File Service (HFS) (e.g., `FileCreateTransaction`, `FileContentsQuery`). |
| 60 | +- **`logger/`**: Internal logging utilities. |
| 61 | +- **`nodes/`**: Transactions for managing network nodes (privileged operations). |
| 62 | +- **`query/`**: Base classes and logic for all network queries. |
| 63 | +- **`schedule/`**: For the Hedera Schedule Service (e.g., `ScheduleCreateTransaction`). |
| 64 | +- **`tokens/`**: For Hedera Token Service (HTS) (e.g., `TokenCreateTransaction`, `CustomFixedFee`). |
| 65 | +- **`transaction/`**: Base classes and logic for all network transactions. |
| 66 | +- **`utils/`**: Helper utilities, like for checksums or entity ID parsing. |
| 67 | + |
| 68 | +There are also individual files (e.g., `Duration.py`, `channels.py`, `exceptions.py`, `hbar.py`) that provide utility classes. |
| 69 | + |
| 70 | +When you work on an issue, you will most likely be modifying a file within one of these directories, such as `src/hiero_sdk_python/tokens/custom_fixed_fee.py`. Each file contains the specific logic for the services we provide for the Hedera network. |
| 71 | + |
| 72 | +### The `tests` Directory |
| 73 | + |
| 74 | +This directory contains all the automated tests for the SDK, separated into two main types: |
| 75 | + |
| 76 | +- **`tests/unit/`**: Unit tests that check individual functions and classes in isolation. They are fast and do not require a network connection. |
| 77 | +- **`tests/integration/`**: Integration tests that run end-to-end workflows against a live Hedera network (or a local `solo` network). These are marked with `@pytest.mark.integration`. |
| 78 | + |
| 79 | +All contributions require new or updated tests to be included. |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +## Implications for Development (How to Import) |
| 84 | + |
| 85 | +When you create a new feature (e.g., an imaginary `src/hiero_sdk_python/fees/step_fee.py`), you will need to import and use classes and functions from other modules. |
| 86 | + |
| 87 | +For example, your new "step fee" logic might need: |
| 88 | +- `AccountId` (from `account/`) to know who pays and who receives the fee. |
| 89 | +- `TokenId` (from `tokens/`) if the fee is paid with a token. |
| 90 | +- The `Client` (from `client/`) to make network calls. |
| 91 | + |
| 92 | +This is why every file begins with an import block. These imports must be correct and point to the exact location of the file within the `src/` directory. |
| 93 | + |
| 94 | +### Finding the Correct Import Path |
| 95 | + |
| 96 | +The import path always starts from the root of the package, `hiero_sdk_python`. |
| 97 | + |
| 98 | +**Example 1: Importing the `TokenId` class** |
| 99 | +- **File Location:** `src/hiero_sdk_python/tokens/token_id.py` |
| 100 | +- **Class Name:** `TokenId` |
| 101 | +- **Correct Import:** `from hiero_sdk_python.tokens.token_id import TokenId` |
| 102 | + |
| 103 | +**Example 2: Importing a Protobuf type** |
| 104 | +- **File Location:** `src/hiero_sdk_python/hapi/services/basic_types_pb2.py` |
| 105 | +- **File to Import:** `basic_types_pb2` |
| 106 | +- **Correct Import:** `from hiero_sdk_python.hapi.services import basic_types_pb2` |
| 107 | + |
| 108 | +A tool like Pylance (in VS Code) can help verify your import paths and flag any that are incorrect. |
| 109 | + |
| 110 | +--- |
| 111 | + |
| 112 | +## Conclusion |
| 113 | + |
| 114 | +This guide outlines the basic file structure of the project. By understanding where different types of code live (`src/`, `tests/`, `examples/`, `docs/`), you can more easily find the classes you need to import and know where to place your new contributions. |
0 commit comments