chore: structure examples to have subfiles and names to match src (#770)

Signed-off-by: exploreriii <133720349+exploreriii@users.noreply.github.com>

Author: exploreriii

.github/workflows/examples.yml

@@ -46,15 +46,16 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          files=$(ls examples/*.py)
+          export PYTHONPATH="$PWD"
 
-          for file in $files;
-          do
+          files=$(find examples -name "*.py" -type f ! -name "__init__.py")
+
+          for file in $files; do
             echo -e "\n************ ${file} ************"
 
-            module="examples.$(basename "$file" .py)"
+            # Convert path to module name
+            module=$(realpath --relative-to="$PWD" "$file" | sed 's|/|.|g' | sed 's|.py$||')
 
-            # Run the example and capture both stdout and stderr
             if ! output=$(uv run -m "$module" 2>&1); then
               echo -e "\n❌ Example failed: ${file}"
               echo "************ Error Output ************"

CHANGELOG.md

@@ -82,7 +82,9 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - docs: Add `docs/sdk_developers/project_structure.md` to explain repository layout and import paths.
 
 ### Changed
-
+- chore: renamed examples to match src where possible
+- Moved examples/ to be inside subfiles to match src structure
+- changed example script workflow to run on new subdirectory structure
 - chore: bumped solo action from 14.0 to 15.0 (#764)
 - chore: replaced hardcoded 'testnet' messages with environment network name
 - chore: validate that token airdrop transactions require an available token service on the channel (#632)
@@ -148,7 +150,6 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Added `docs/discord.md` explaining how to join and navigate the Hiero community Discord (#614).
 
 ### Changed
-
 - Added direct links to Python SDK channel in Linux Foundation Decentralized Trust Discord back in
 - Updated all occurrences of non-functional Discord invite links throughout the documentation with the new, stable Hyperledger and Hedera invite links (#603).
 - Refactored TopicId class to use @dataclass decorator for reducing boilerplate code

examples/account/__init__.py

@@ -0,0 +1,163 @@
+"""
+Example demonstrating hbar allowance approval and usage.
+Run:
+uv run examples/account/account_allowance_approve_transaction_hbar.py
+"""
+
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from hiero_sdk_python import AccountId, Client, Hbar, Network, PrivateKey, TransactionId
+from hiero_sdk_python.account.account_allowance_approve_transaction import (
+    AccountAllowanceApproveTransaction,
+)
+from hiero_sdk_python.account.account_create_transaction import AccountCreateTransaction
+from hiero_sdk_python.response_code import ResponseCode
+from hiero_sdk_python.transaction.transfer_transaction import TransferTransaction
+
+load_dotenv()
+network_name = os.getenv('NETWORK', 'testnet').lower()
+
+def setup_client():
+    """Initialize and set up the client with operator account"""
+    network = Network(network_name)
+    print(f"Connecting to Hedera {network_name} network!")
+    client = Client(network)
+
+    operator_id = AccountId.from_string(os.getenv("OPERATOR_ID",""))
+    operator_key = PrivateKey.from_string(os.getenv("OPERATOR_KEY",""))
+    client.set_operator(operator_id, operator_key)
+    print(f"Client set up with operator id {client.operator_account_id}")
+
+    return client
+
+
+def create_account(client):
+    """Create an account"""
+    account_private_key = PrivateKey.generate_ed25519()
+    account_public_key = account_private_key.public_key()
+
+    account_receipt = (
+        AccountCreateTransaction()
+        .set_key(account_public_key)
+        .set_initial_balance(Hbar(1))
+        .set_account_memo("Account for hbar allowance")
+        .execute(client)
+    )
+
+    if account_receipt.status != ResponseCode.SUCCESS:
+        print(f"Account creation failed with status: {ResponseCode(account_receipt.status).name}")
+        sys.exit(1)
+
+    account_account_id = account_receipt.account_id
+
+    return account_account_id, account_private_key
+
+
+def approve_hbar_allowance(client, owner_account_id, spender_account_id, amount):
+    """Approve Hbar allowance for spender"""
+    receipt = (
+        AccountAllowanceApproveTransaction()
+        .approve_hbar_allowance(owner_account_id, spender_account_id, amount)
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"Hbar allowance approval failed with status: {ResponseCode(receipt.status).name}")
+        sys.exit(1)
+
+    print(f"Hbar allowance of {amount} approved for spender {spender_account_id}")
+    return receipt
+
+
+def delete_hbar_allowance(client, owner_account_id, spender_account_id):
+    """Delete hbar allowance by setting amount to 0"""
+    receipt = (
+        AccountAllowanceApproveTransaction()
+        .approve_hbar_allowance(owner_account_id, spender_account_id, Hbar(0))
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"Hbar allowance deletion failed with status: {ResponseCode(receipt.status).name}")
+        sys.exit(1)
+
+    print(f"Hbar allowance deleted for spender {spender_account_id}")
+    return receipt
+
+
+def transfer_hbar_without_allowance(client, spender_account_id, spender_private_key, amount):
+    """Transfer hbars without allowance"""
+    print("Trying to transfer hbars without allowance...")
+    owner_account_id = client.operator_account_id
+    client.set_operator(spender_account_id, spender_private_key)  # Set operator to spender
+
+    receipt = (
+        TransferTransaction()
+        .add_approved_hbar_transfer(owner_account_id, -amount.to_tinybars())
+        .add_approved_hbar_transfer(spender_account_id, amount.to_tinybars())
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SPENDER_DOES_NOT_HAVE_ALLOWANCE:
+        print(
+            f"Hbar transfer should have failed with SPENDER_DOES_NOT_HAVE_ALLOWANCE "
+            f"status but got: {ResponseCode(receipt.status).name}"
+        )
+
+    print(f"Hbar transfer successfully failed with {ResponseCode(receipt.status).name} status")
+
+
+def hbar_allowance():
+    """
+    Demonstrates hbar allowance functionality by:
+    1. Setting up client with operator account
+    2. Creating spender and receiver accounts
+    3. Approving hbar allowance for spender
+    4. Transferring hbars using the allowance
+    5. Deleting the allowance
+    6. Attempting to transfer hbars without allowance (should fail)
+    """
+    client = setup_client()
+
+    # Create spender and receiver accounts
+    spender_id, spender_private_key = create_account(client)
+    print(f"Spender account created with ID: {spender_id}")
+
+    receiver_id, _ = create_account(client)
+    print(f"Receiver account created with ID: {receiver_id}")
+
+    # Approve hbar allowance for spender
+    allowance_amount = Hbar(2)
+
+    approve_hbar_allowance(client, client.operator_account_id, spender_id, allowance_amount)
+
+    # Transfer hbars using the allowance
+    receipt = (
+        TransferTransaction()
+        .set_transaction_id(TransactionId.generate(spender_id))
+        .add_approved_hbar_transfer(client.operator_account_id, -allowance_amount.to_tinybars())
+        .add_approved_hbar_transfer(receiver_id, allowance_amount.to_tinybars())
+        .freeze_with(client)
+        .sign(spender_private_key)
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"Hbar transfer failed with status: {ResponseCode(receipt.status).name}")
+        sys.exit(1)
+
+    print(f"Successfully transferred {allowance_amount} from", end=" ")
+    print(f"{client.operator_account_id} to {receiver_id} using allowance")
+
+    # Delete allowance
+    delete_hbar_allowance(client, client.operator_account_id, spender_id)
+
+    # Try to transfer hbars without allowance
+    transfer_hbar_without_allowance(client, spender_id, spender_private_key, allowance_amount)
+
+
+if __name__ == "__main__":
+    hbar_allowance()

examples/account/account_allowance_approve_transaction_hbar.py

@@ -9,7 +9,7 @@
 - Spender (as payer) transfers the NFT from the owner to the receiver.
 
 Usage:
-    uv run examples/account_allowance_approve_transaction_nft.py
+    uv run examples/account/account_allowance_approve_transaction_nft.py
 """
 
 import os

examples/account_allowance_approve_transaction_nft.py renamed to examples/account/account_allowance_approve_transaction_nft.py

@@ -8,7 +8,7 @@
 - Verifies the spender can NO LONGER transfer the NFT.
 
 Usage:
-    uv run examples/account_allowance_delete_transaction_nft.py
+    uv run examples/account/account_allowance_delete_transaction_nft.py
 """
 
 import os

examples/account_allowance_delete_transaction_nft.py renamed to examples/account/account_allowance_delete_transaction_nft.py

@@ -12,10 +12,10 @@
 
 Usage:
     Run this script directly:
-        python examples/account_create.py
+        python examples/account/account_create_transaction.py
     
     Or using uv:
-        uv run examples/account_create.py
+        uv run examples/account/account_create_transaction.py
 
 Requirements:
     - Environment variables OPERATOR_ID and OPERATOR_KEY must be set

examples/account_create.py renamed to examples/account/account_create_transaction.py

@@ -1,8 +1,8 @@
 """
 Example demonstrating account delete functionality.
 Run:
-uv run examples/account_delete.py
-python examples/account_delete.py
+uv run examples/account/account_delete_transaction.py
+python examples/account/account_delete_transaction.py
 
 """
 import os

examples/account_delete.py renamed to examples/account/account_delete_transaction.py

@@ -1,6 +1,6 @@
 """
-uv run examples/account_id.py
-python examples/account_id.py
+uv run examples/account/account_id.py
+python examples/account/account_id.py
 
 This example demonstrates various ways to use the AccountId class:
 1. Creating a standard AccountId

examples/account_id.py renamed to examples/account/account_id.py

@@ -1,3 +1,7 @@
+"""
+uv run examples/account/account_info.py
+"""
+
 from hiero_sdk_python.account.account_id import AccountId
 from hiero_sdk_python.crypto.private_key import PrivateKey
 from hiero_sdk_python.crypto.public_key import PublicKey