feat: Add convenient factory methods for Hbar units (#1277)

Signed-off-by: Adityarya11 <arya050411@gmail.com>
Signed-off-by: notsogod <149138960+Adityarya11@users.noreply.github.com>

Author: Adityarya11

CHANGELOG.md

@@ -72,6 +72,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Added `transfer_transaction_tinybar.py` example demonstrating tinybar transfers with both integer and Hbar object approaches. ([#1249](https://github.com/hiero-ledger/hiero-sdk-python/issues/1249))
 - Added `transfer_transaction_gigabar.py` example demonstrating `GIGABAR` unit usage for large-value transfers. ([#1249](https://github.com/hiero-ledger/hiero-sdk-python/issues/1249))
 - Coderabbit prompt for .github
+- 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).
 

examples/hbar.py

@@ -6,6 +6,25 @@
 from hiero_sdk_python.hbar import Hbar
 from hiero_sdk_python.hbar_unit import HbarUnit
 
+def demonstrate_factory_methods():
+    """
+    Demonstrates creating Hbar values using the convenient factory methods.
+    """
+    print("\n=== Creating Hbar Using Factory Methods ===")
+
+    # Creates an Hbar object representing 1 Gigabar (1,000,000,000 ℏ)
+    h_giga = Hbar.from_gigabars(1)
+    
+    # Creates an Hbar object representing 500 Millibars (0.5 ℏ)
+    h_milli = Hbar.from_millibars(500)
+
+    # Creates an Hbar object representing 10.5 Hbars (10.5 ℏ)
+    h_standard = Hbar.from_hbars(10.5)
+
+    print(f"Hbar.from_gigabars(1): {h_giga}")
+    print(f"Hbar.from_millibars(500): {h_milli}")
+    print(f"Hbar.from_hbars(10.5): {h_standard}")
+
 def create_hbar_using_constructor():
     """
     Demonstrates creating Hbar values using the constructor.
@@ -144,7 +163,7 @@ def run_example():
     demonstrate_conversion_methods()
     demonstrate_negation()
     demonstrate_constants()
-
+    demonstrate_factory_methods()
 
 if __name__ == "__main__":
     run_example()

src/hiero_sdk_python/hbar.py

@@ -107,6 +107,54 @@ def from_tinybars(cls, tinybars: int) -> "Hbar":
         if not isinstance(tinybars, int):
             raise TypeError("tinybars must be an int.")
         return cls(tinybars, unit=HbarUnit.TINYBAR)
+    
+    @classmethod
+    def from_microbars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar object representing the specified amount of microbars.
+        Example: Hbar.from_microbars(100) -> 100 μℏ
+        """
+        return cls(amount, unit=HbarUnit.MICROBAR)
+
+    @classmethod
+    def from_millibars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar object representing the specified amount of millibars.
+        Example: Hbar.from_millibars(500) -> 500 mℏ
+        """
+        return cls(amount, unit=HbarUnit.MILLIBAR)
+
+    @classmethod
+    def from_hbars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar object representing the specified amount of hbars.
+        Example: Hbar.from_hbars(10) -> 10 ℏ
+        """
+        return cls(amount, unit=HbarUnit.HBAR)
+
+    @classmethod
+    def from_kilobars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar object representing the specified amount of kilobars.
+        Example: Hbar.from_kilobars(1) -> 1 kℏ
+        """
+        return cls(amount, unit=HbarUnit.KILOBAR)
+
+    @classmethod
+    def from_megabars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar object representing the specified amount of megabars.
+        Example: Hbar.from_megabars(1) -> 1 Mℏ
+        """
+        return cls(amount, unit=HbarUnit.MEGABAR)
+
+    @classmethod
+    def from_gigabars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar object representing the specified amount of gigabars.
+        Example: Hbar.from_gigabars(1) -> 1 Gℏ
+        """
+        return cls(amount, unit=HbarUnit.GIGABAR)
 
     @classmethod
     def from_string(cls, amount: str, unit: HbarUnit = HbarUnit.HBAR) -> "Hbar":

tests/unit/hbar_test.py

@@ -149,4 +149,55 @@ def test_comparison():
     # Comparison without Hbar returns NotImplemented
     assert (h1 == 5) is False
     with pytest.raises(TypeError):
-        _ = h1 < 5
+        _ = h1 < 5
+        
+def test_factory_methods():
+    """Test the convenient from_X factory methods."""
+    
+    # from_microbars
+    # 1 microbar = 100 tinybars
+    result = Hbar.from_microbars(1)
+    assert isinstance(result, Hbar)
+    assert result.to_tinybars() == 100
+    assert Hbar.from_microbars(1.5).to_tinybars() == 150
+    assert Hbar.from_microbars(Decimal("2.5")).to_tinybars() == 250
+    assert Hbar.from_microbars(0).to_tinybars() == 0
+    assert Hbar.from_microbars(-10).to_tinybars() == -1_000
+    # Verify equivalence with constructor
+    assert Hbar.from_microbars(5) == Hbar(5, unit=HbarUnit.MICROBAR)
+
+    # from_millibars
+    # 1 millibar = 100,000 tinybars
+    assert Hbar.from_millibars(1).to_tinybars() == 100_000
+    assert Hbar.from_millibars(0).to_tinybars() == 0
+    assert Hbar.from_millibars(-5).to_tinybars() == -500_000
+    assert Hbar.from_millibars(Decimal("1.5")).to_tinybars() == 150_000
+
+    # from_hbars
+    # 1 hbar = 100,000,000 tinybars
+    assert Hbar.from_hbars(1).to_tinybars() == 100_000_000
+    assert Hbar.from_hbars(0.00000001).to_tinybars() == 1
+    assert Hbar.from_hbars(0).to_tinybars() == 0
+    assert Hbar.from_hbars(-10).to_tinybars() == -1_000_000_000
+    assert Hbar.from_hbars(Decimal("5.5")).to_tinybars() == 550_000_000
+
+    # from_kilobars
+    # 1 kilobar = 1,000 hbars
+    assert Hbar.from_kilobars(1).to_hbars() == 1_000
+    assert Hbar.from_kilobars(0).to_hbars() == 0
+    assert Hbar.from_kilobars(-2).to_hbars() == -2_000
+    assert Hbar.from_kilobars(1).to_tinybars() == 100_000_000_000
+
+    # from_megabars
+    # 1 megabar = 1,000,000 hbars
+    assert Hbar.from_megabars(1).to_hbars() == 1_000_000
+    assert Hbar.from_megabars(0).to_hbars() == 0
+    assert Hbar.from_megabars(-1).to_hbars() == -1_000_000
+    assert Hbar.from_megabars(1).to_tinybars() == 100_000_000_000_000
+
+    # from_gigabars
+    # 1 gigabar = 1,000,000,000 hbars
+    assert Hbar.from_gigabars(1).to_hbars() == 1_000_000_000
+    assert Hbar.from_gigabars(0).to_hbars() == 0
+    assert Hbar.from_gigabars(-1).to_hbars() == -1_000_000_000
+    assert Hbar.from_gigabars(1).to_tinybars() == 100_000_000_000_000_000