feat: Add convenient factory methods for Hbar units

CHANGELOG.md

@@ -71,6 +71,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Added support for include duplicates in get transaction receipt query (#1166)
 - Added `.github/workflows/cron-check-broken-links.yml` workflow to perform scheduled monthly Markdown link validation across the entire repository with automatic issue creation for broken links ([#1210](https://github.com/hiero-ledger/hiero-sdk-python/issues/1210))
 - 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)
 
 ### Changed
 - Moved `docs/sdk_developers/how_to_link_issues.md` to `docs/sdk_developers/training/workflow/how_to_link_issues.md` and updated all references (#1222)

examples/hbar.py

@@ -6,6 +6,22 @@
 from hiero_sdk_python.hbar import Hbar
 from hiero_sdk_python.hbar_unit import HbarUnit
 
+def create_hbar_using_helpers():
+    """
+    Demonstrates creating Hbar values using the convenient factory methods.
+    """
+    print("\n=== Creating Hbar Using Helper Methods ===")
+
+    h_giga = Hbar.from_gigabars(1)
+
+    h_milli = Hbar.from_millibars(500)
+
+    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 +160,7 @@ def run_example():
     demonstrate_conversion_methods()
     demonstrate_negation()
     demonstrate_constants()
-
+    create_hbar_using_helpers()
 
 if __name__ == "__main__":
     run_example()

src/hiero_sdk_python/hbar.py

@@ -107,6 +107,48 @@ 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 instance from the given amount in microbars.
+        """
+        return cls(amount, unit=HbarUnit.MICROBAR)
+
+    @classmethod
+    def from_millibars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar instance from the given amount in millibars.
+        """
+        return cls(amount, unit=HbarUnit.MILLIBAR)
+
+    @classmethod
+    def from_hbars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar instance from the given amount in hbars.
+        """
+        return cls(amount, unit=HbarUnit.HBAR)
+
+    @classmethod
+    def from_kilobars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar instance from the given amount in kilobars.
+        """
+        return cls(amount, unit=HbarUnit.KILOBAR)
+
+    @classmethod
+    def from_megabars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar instance from the given amount in megabars.
+        """
+        return cls(amount, unit=HbarUnit.MEGABAR)
+
+    @classmethod
+    def from_gigabars(cls, amount: Union[int, float, Decimal]) -> "Hbar":
+        """
+        Create an Hbar instance from the given amount in gigabars.
+        """
+        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,33 @@ 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
+    assert Hbar.from_microbars(1).to_tinybars() == 100
+    assert Hbar.from_microbars(1.5).to_tinybars() == 150
+
+    # from_millibars
+    # 1 millibar = 100,000 tinybars
+    assert Hbar.from_millibars(1).to_tinybars() == 100_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
+
+    # from_kilobars
+    # 1 kilobar = 1,000 hbars
+    assert Hbar.from_kilobars(1).to_hbars() == 1_000
+
+    # from_megabars
+    # 1 megabar = 1,000,000 hbars
+    assert Hbar.from_megabars(1).to_hbars() == 1_000_000
+
+    # from_gigabars
+    # 1 gigabar = 1,000,000,000 hbars
+    assert Hbar.from_gigabars(1).to_hbars() == 1_000_000_000