feat: Add Client factory methods (from_env) and simplify examples (#1274)

Signed-off-by: Adityarya11 <[email protected]>

Author: Adityarya11

CHANGELOG.md

@@ -76,6 +76,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Added convenient factory methods to `Hbar` class for easier instantiation: `from_microbars()`, `from_millibars()`, `from_hbars()`, `from_kilobars()`, `from_megabars()`, and `from_gigabars()`. [#1272](https://github.com/hiero-ledger/hiero-sdk-python/issues/1272)
 - Added merge conflict bot workflow (`.github/workflows/bot-merge-conflict.yml`) and helper script (`.github/scripts/bot-merge-conflict.js`) to detect and notify about PR merge conflicts, with retry logic for unknown mergeable states, idempotent commenting, and push-to-main recheck logic (#1247)
 - Added workflow to prevent assigning intermediate issues to contributors without prior Good First Issue completion (#1143).
+- Added `Client.from_env()` and network-specific factory methods (e.g., `Client.for_testnet()`) to simplify client initialization and reduce boilerplate. [[#1251](https://github.com/hiero-ledger/hiero-sdk-python/issues/1251)]
 
 ### Changed
 

examples/account/account_create_transaction.py

@@ -21,102 +21,66 @@
     - Environment variables OPERATOR_ID and OPERATOR_KEY must be set
     - A .env file with the operator credentials (recommended)
     - Sufficient HBAR balance in the operator account to pay for account creation
+
+Environment Variables:
+    OPERATOR_ID (str): The account ID of the operator (format: "0.0.xxxxx")
+    OPERATOR_KEY (str): The private key of the operator account
+    NETWORK (str, optional): Network to use (default: "testnet")
 """
-import os
 import sys
-from typing import Tuple
-from dotenv import load_dotenv
-
 from hiero_sdk_python import (
     Client,
-    Network,
-    AccountId,
     PrivateKey,
     AccountCreateTransaction,
     ResponseCode,
 )
 
-load_dotenv()
-network_name = os.getenv('NETWORK', 'testnet').lower()
-
-def setup_client() -> Tuple[Client, PrivateKey]:
-    """
-    Set up and configure a Hedera client for testnet operations.
-    
-    Creates a client instance connected to the Hedera testnet and configures it
-    with operator credentials from environment variables. The operator account
-    is used to pay for transactions and sign them.
-    
-    Returns:
-        tuple: A tuple containing:
-            - Client: Configured Hedera client instance
-            - PrivateKey: The operator's private key for signing transactions
-    
-    Raises:
-        ValueError: If OPERATOR_ID or OPERATOR_KEY environment variables are not set
-        Exception: If there's an error parsing the operator credentials
-    
-    Environment Variables:
-        OPERATOR_ID (str): The account ID of the operator (format: "0.0.xxxxx")
-        OPERATOR_KEY (str): The private key of the 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)
-
-    return client, operator_key
-
-def create_new_account(client: Client, operator_key: PrivateKey) -> None:
+def create_new_account(client: Client) -> None:
     """
     Create a new Hedera account with generated keys and initial balance.
-    
+
     This function generates a new Ed25519 key pair, creates an account creation
-    transaction, signs it with the operator key, and executes it on the network.
+    transaction, signs it with the operator key, and executes it on the network. 
     The new account is created with an initial balance and a custom memo.
-    
+
     Args:
-        client (Client): Configured Hedera client instance for network communication
-        operator_key (PrivateKey): The operator's private key for signing the transaction
-    
+        client (Client): Configured Hedera client instance with operator set
+
     Returns:
-        None: This function doesn't return a value but prints the results
-    
+        None:  This function doesn't return a value but prints the results
+
     Raises:
         Exception: If the transaction fails or the account ID is not found in the receipt
-        SystemExit: Calls sys.exit(1) if account creation fails
-    
+        SystemExit:  Calls sys.exit(1) if account creation fails
+
     Side Effects:
         - Prints transaction status and account details to stdout
         - Creates a new account on the Hedera network
         - Deducts transaction fees from the operator account
         - Exits the program with code 1 if creation fails
-    
+
     Example Output:
         Transaction status: ResponseCode.SUCCESS
         Account creation successful. New Account ID: 0.0.123456
-        New Account Private Key: 302e020100300506032b657004220420...
+        New Account Private Key:  302e020100300506032b657004220420... 
         New Account Public Key: 302a300506032b6570032100...
     """
     new_account_private_key = PrivateKey.generate("ed25519")
     new_account_public_key = new_account_private_key.public_key()
 
+    # Get the operator key from the client for signing
+    operator_key = client.operator_private_key
+
     transaction = (
         AccountCreateTransaction()
         .set_key(new_account_public_key)
         .set_initial_balance(100000000)  # 1 HBAR in tinybars
         .set_account_memo("My new account")
-        .freeze_with(client)
     )
 
-    transaction.sign(operator_key)
-
     try:
-        receipt = transaction.execute(client)
+        # Explicit signing with key retrieved from client
+        receipt = transaction.freeze_with(client).sign(operator_key).execute(client)
         print(f"Transaction status: {receipt.status}")
 
         if receipt.status != ResponseCode.SUCCESS:
@@ -125,16 +89,18 @@ def create_new_account(client: Client, operator_key: PrivateKey) -> None:
 
         new_account_id = receipt.account_id
         if new_account_id is not None:
-            print(f"Account creation successful. New Account ID: {new_account_id}")
-            print(f"New Account Private Key: {new_account_private_key.to_string()}")
-            print(f"New Account Public Key: {new_account_public_key.to_string()}")
+            print(f"✅ Account creation successful. New Account ID: {new_account_id}")
+            print(f"   New Account Private Key: {new_account_private_key.to_string()}")
+            print(f"   New Account Public Key: {new_account_public_key.to_string()}")
         else:
-            raise Exception("AccountID not found in receipt. Account may not have been created.")
+            raise Exception("AccountID not found in receipt.  Account may not have been created.")
 
     except Exception as e:
-        print(f"Account creation failed: {str(e)}")
+        print(f"❌ Account creation failed: {str(e)}")
         sys.exit(1)
 
-if __name__ == "__main__":
-    client, operator_key = setup_client()
-    create_new_account(client, operator_key)
+if __name__ == "__main__": 
+    client = Client.from_env()
+    print(f"Operator: {client.operator_account_id}")
+    create_new_account(client)
+    client.close()

examples/account/account_delete_transaction.py

@@ -5,32 +5,15 @@
 python examples/account/account_delete_transaction.py
 
 """
-import os
 import sys
-
-from dotenv import load_dotenv
-
-from hiero_sdk_python import AccountId, Client, Hbar, Network, PrivateKey
-from hiero_sdk_python.account.account_create_transaction import AccountCreateTransaction
-from hiero_sdk_python.account.account_delete_transaction import AccountDeleteTransaction
-from hiero_sdk_python.response_code import ResponseCode
-
-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
+from hiero_sdk_python import (
+    Client, 
+    Hbar, 
+    PrivateKey,
+    AccountCreateTransaction,
+    AccountDeleteTransaction,
+    ResponseCode
+)
 
 def create_account(client):
     """Create a test account"""
@@ -66,7 +49,7 @@ def account_delete():
     2. Creating an account
     3. Deleting the account
     """
-    client = setup_client()
+    client = Client.from_env()
 
     # Create an account first
     account_id, account_private_key = create_account(client)

examples/client/client.py

@@ -1,76 +1,113 @@
 """
 Complete network and client setup example with detailed logging.
 
-uv run examples/client/client.py
-python examples/client/client.py
+This example demonstrates the internal steps of setting up a client
+(Network -> Client -> Operator) which is useful for understanding
+the architecture. It also demonstrates the quick `from_env()` method.
+
+Usage:
+    uv run examples/client/client.py
+    python examples/client/client.py
 """
 import os
 from dotenv import load_dotenv
 
-from hiero_sdk_python.client.network import Network
-from hiero_sdk_python.client.client import Client
-from hiero_sdk_python.account.account_id import AccountId
-from hiero_sdk_python.crypto.private_key import PrivateKey
+from hiero_sdk_python import Client, Network, AccountId, PrivateKey
 
 load_dotenv()
 
-
 def setup_network():
     """Create and configure the network with logging."""
     network_name = os.getenv('NETWORK', 'testnet').lower()
+    
     print("Step 1: Create the network configuration")
     network = Network(network_name)
-    print(f"Connected to: {network.network}")
-    print(f"Nodes available: {len(network.nodes)}")
+    
+    print(f"  - Connected to: {network.network}")
+    print(f"  - Nodes available: {len(network.nodes)}")
+    
     return network
 
 
 def setup_client(network):
     """Create and initialize the client with the network."""
     print("\nStep 2: Create the client with the network")
     client = Client(network)
-    print(f"Client initialized with network: {client.network.network}")
+    
+    print(f"  - Client initialized with network: {client.network.network}")
     return client
 
-
 def setup_operator(client):
     """Configure operator credentials for the client."""
     print("\nStep 3: Configure operator credentials")
-    operator_id = AccountId.from_string(os.getenv("OPERATOR_ID", "0.0.0"))
-    operator_key = PrivateKey.from_string(os.getenv("OPERATOR_KEY", ""))
-    client.set_operator(operator_id, operator_key)
-    print(f"Operator set: {client.operator_account_id}")
+    
+    operator_id_str = os.getenv("OPERATOR_ID")
+    operator_key_str = os.getenv("OPERATOR_KEY")
+
+    if not operator_id_str or not operator_key_str:
+        print("  - ⚠️ OPERATOR_ID or OPERATOR_KEY missing in environment.")
+        return
 
+    operator_id = AccountId.from_string(operator_id_str)
+    operator_key = PrivateKey.from_string(operator_key_str)
+    
+    client.set_operator(operator_id, operator_key)
+    print(f"  - Operator set: {client.operator_account_id}")
 
 def display_client_configuration(client):
     """Display client configuration details."""
     print("\n=== Client Configuration ===")
     print(f"Client is ready to use!")
-    print(f"Current node: {client.network.current_node._account_id}")
-    print(f"Mirror address: {client.network.get_mirror_address()}")
     print(f"Max retry attempts: {client.max_attempts}")
+    
+
+    nodes = client.get_node_account_ids()
+    print(f"Total Nodes: {len(nodes)}")
 
 
 def display_available_nodes(client):
-    """Display all available nodes in the network."""
-    print("\n=== Available Nodes ===")
-    for node_id in client.get_node_account_ids():
+    """Display a sample of available nodes in the network."""
+    print("\n=== Available Nodes (Sample) ===")
+    nodes = client.get_node_account_ids()
+    
+    # showing first 5 Nodes
+    for i, node_id in enumerate(nodes[:5]):
         print(f"  - Node: {node_id}")
+    
+    if len(nodes) > 5:
+        print(f"  ... and {len(nodes) - 5} more.")
 
 
-def main():
-    """Complete setup of network and client with full configuration details."""
-    print("=== Network and Client Setup ===\n")
-    
+def demonstrate_manual_setup():
+    """Run the detailed, step-by-step setup."""
+    print("\n--- [ Method 1: Manual Setup] ---")
     network = setup_network()
     client = setup_client(network)
     setup_operator(client)
     display_client_configuration(client)
     display_available_nodes(client)
-    
-    print("\nClient is ready for transactions!")
     client.close()
 
 
+def demonstrate_fast_setup():
+    """Run the quick setup used in production."""
+    print("\n--- [ Method 2: Fast Setup (from_env) ] ---")
+    print("Initializing client from environment variables...")
+    try:
+        client = Client.from_env()
+        print(f"✅ Success! Connected as operator: {client.operator_account_id}")
+        client.close()
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+
+
+def main():
+    # 1. Run the verbose example
+    demonstrate_manual_setup()
+
+    # 2. Run the concise example (Best Practice) 
+    demonstrate_fast_setup()
+
+
 if __name__ == "__main__":
-    main()
+    main()