hive-nectar 0.0.11__py3-none-any.whl → 0.1.1__py3-none-any.whl

nectarbase/operations.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 import json
 import re
+import warnings
 from binascii import hexlify
 from collections import OrderedDict
 
@@ -467,11 +468,24 @@ class Update_proposal_votes(GrapheneObject):
 
 class Remove_proposal(GrapheneObject):
     def __init__(self, *args, **kwargs):
+        """
+        Initialize a Remove_proposal operation.
+
+        Creates the internal OrderedDict for a remove_proposal operation with:
+        - proposal_owner: account name (String)
+        - proposal_ids: list of Uint64-wrapped proposal IDs
+        - extensions: empty Array
+
+        If initialized with a single existing GrapheneObject instance, initialization returns early after copying that instance's data (handled by check_for_class).
+
+        Required kwargs:
+        - proposal_owner: str
+        - proposal_ids: iterable of integers (each converted to Uint64)
+        """
         if check_for_class(self, args):
             return
         if len(args) == 1 and len(kwargs) == 0:
             kwargs = args[0]
-        prefix = kwargs.get("prefix", default_prefix)
         extensions = Array([])
         proposal_ids = []
         for e in kwargs["proposal_ids"]:
@@ -490,12 +504,26 @@ class Remove_proposal(GrapheneObject):
 
 class Update_proposal(GrapheneObject):
     def __init__(self, *args, **kwargs):
+        """
+        Initialize an Update_proposal operation.
+
+        Accepts either an existing Update_proposal instance (handled by check_for_class), a single positional dict, or keyword arguments. Required fields: `proposal_id`, `creator`, `daily_pay`, `subject`, and `permlink`. Optional `end_date` will be converted into an `update_proposal_end_date` extension. The `daily_pay` Amount uses the provided `prefix` kwarg if present, otherwise `default_prefix` is used.
+
+        Accepted kwargs:
+        - proposal_id: numeric id of the proposal (converted to Uint64)
+        - creator: account name string (converted to String)
+        - daily_pay: amount specifier (converted to Amount; honors `prefix`)
+        - subject: short subject string (converted to String)
+        - permlink: permlink string (converted to String)
+        - end_date: optional datetime/string; if provided, added as an extension
+        - prefix: optional asset/account prefix for Amount conversion (defaults to module `default_prefix`)
+
+        No return value; constructs the internal OrderedDict representing the operation.
+        """
         if check_for_class(self, args):
             return
         if len(args) == 1 and len(kwargs) == 0:
             kwargs = args[0]
-
-        prefix = kwargs.get("prefix", default_prefix)
         extensions = Array([])
         if "end_date" in kwargs and kwargs["end_date"]:
             extension = {
@@ -509,7 +537,10 @@ class Update_proposal(GrapheneObject):
                 [
                     ("proposal_id", Uint64(kwargs["proposal_id"])),
                     ("creator", String(kwargs["creator"])),
-                    ("daily_pay", Amount(kwargs["daily_pay"], prefix=prefix)),
+                    (
+                        "daily_pay",
+                        Amount(kwargs["daily_pay"], prefix=kwargs.get("prefix", default_prefix)),
+                    ),
                     ("subject", String(kwargs["subject"])),
                     ("permlink", String(kwargs["permlink"])),
                     ("extensions", extensions),
@@ -679,6 +710,30 @@ class Custom_json(GrapheneObject):
 
 class Comment_options(GrapheneObject):
     def __init__(self, *args, **kwargs):
+        """
+        Initialize a Comment_options operation.
+
+        This constructor builds the serialized fields for a comment options operation from provided keyword arguments or a single dict positional argument. It converts and validates inputs into the expected Graphene types and handles backward compatibility and extensions.
+
+        Expected kwargs:
+        - author (str): post author.
+        - permlink (str): post permlink.
+        - max_accepted_payout (str|Amount): payout limit; converted to Amount using optional `prefix` and `json_str`.
+        - percent_hbd (int|str): required percent value (primary source) stored as Uint16.
+        - percent_steem_dollars (int|str, optional, deprecated): fallback for `percent_hbd`; using it emits a DeprecationWarning.
+        - allow_votes (bool): whether voting is allowed.
+        - allow_curation_rewards (bool): whether curation rewards are allowed.
+        - beneficiaries (list, optional): if provided, placed into extensions as a beneficiaries extension.
+        - extensions (iterable, optional): explicit extensions; each entry is wrapped with CommentOptionExtensions.
+        - prefix (str, optional): asset/account prefix used when constructing Amount (defaults to module default_prefix).
+        - json_str (bool, optional): if true, construct Amount with json string mode.
+
+        Behavior and side effects:
+        - If initialized from an existing GrapheneObject (via check_for_class), initialization returns early after copying.
+        - If `beneficiaries` is present and non-empty, it is converted into an extensions entry.
+        - If neither `percent_hbd` nor `percent_steem_dollars` is provided, raises ValueError.
+        - If `percent_steem_dollars` is used, emits a DeprecationWarning.
+        """
         if check_for_class(self, args):
             return
         if len(args) == 1 and len(kwargs) == 0:
@@ -691,40 +746,34 @@ class Comment_options(GrapheneObject):
         extensions = Array([])
         if "extensions" in kwargs and kwargs["extensions"]:
             extensions = Array([CommentOptionExtensions(o) for o in kwargs["extensions"]])
-        if "percent_hbd" in kwargs:
-            super(Comment_options, self).__init__(
-                OrderedDict(
-                    [
-                        ("author", String(kwargs["author"])),
-                        ("permlink", String(kwargs["permlink"])),
-                        (
-                            "max_accepted_payout",
-                            Amount(kwargs["max_accepted_payout"], prefix=prefix, json_str=json_str),
-                        ),
-                        ("percent_hbd", Uint16(int(kwargs["percent_hbd"]))),
-                        ("allow_votes", Bool(bool(kwargs["allow_votes"]))),
-                        ("allow_curation_rewards", Bool(bool(kwargs["allow_curation_rewards"]))),
-                        ("extensions", extensions),
-                    ]
-                )
-            )
-        else:
-            super(Comment_options, self).__init__(
-                OrderedDict(
-                    [
-                        ("author", String(kwargs["author"])),
-                        ("permlink", String(kwargs["permlink"])),
-                        (
-                            "max_accepted_payout",
-                            Amount(kwargs["max_accepted_payout"], prefix=prefix),
-                        ),
-                        ("percent_steem_dollars", Uint16(int(kwargs["percent_steem_dollars"]))),
-                        ("allow_votes", Bool(bool(kwargs["allow_votes"]))),
-                        ("allow_curation_rewards", Bool(bool(kwargs["allow_curation_rewards"]))),
-                        ("extensions", extensions),
-                    ]
+        percent_value = kwargs.get("percent_hbd")
+        if percent_value is None:
+            # Backward compatibility: fall back to percent_steem_dollars
+            percent_value = kwargs.get("percent_steem_dollars")
+            if percent_value is not None:
+                warnings.warn(
+                    "Parameter 'percent_steem_dollars' is deprecated. Use 'percent_hbd' instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
                 )
+            else:
+                raise ValueError("Comment_options requires 'percent_hbd'")
+        super(Comment_options, self).__init__(
+            OrderedDict(
+                [
+                    ("author", String(kwargs["author"])),
+                    ("permlink", String(kwargs["permlink"])),
+                    (
+                        "max_accepted_payout",
+                        Amount(kwargs["max_accepted_payout"], prefix=prefix, json_str=json_str),
+                    ),
+                    ("percent_hbd", Uint16(int(percent_value))),
+                    ("allow_votes", Bool(bool(kwargs["allow_votes"]))),
+                    ("allow_curation_rewards", Bool(bool(kwargs["allow_curation_rewards"]))),
+                    ("extensions", extensions),
+                ]
             )
+        )
 
 
 class Delete_comment(GrapheneObject):
@@ -1019,63 +1068,52 @@ class Cancel_transfer_from_savings(GrapheneObject):
 
 class Claim_reward_balance(GrapheneObject):
     def __init__(self, *args, **kwargs):
+        """
+        Initialize a Claim_reward_balance operation.
+
+        Constructs the serialized fields for claiming reward balances. Requires
+        account, reward_hive, reward_hbd, and reward_vests in the canonical order.
+        All reward fields are required asset strings - use "0.000 HIVE" or "0.000 HBD"
+        when nothing to claim for that asset.
+
+        Behavior:
+        - Always serializes ("account", "reward_hive", "reward_hbd", "reward_vests")
+        - Converts provided values to Amount objects, respecting prefix/json_str behavior
+        - Uses zero-asset strings ("0.000 HIVE"/"0.000 HBD") for any missing reward fields
+
+        Recognized kwargs:
+        - account (str): account name claiming rewards.
+        - reward_hive (str|Amount): HIVE amount to claim (required, use "0.000 HIVE" if none).
+        - reward_hbd (str|Amount): HBD amount to claim (required, use "0.000 HBD" if none).
+        - reward_vests (str|Amount): VESTS amount to claim.
+        - prefix (str): asset prefix to use (defaults to module default_prefix).
+        - json_str (bool): if True, pass amounts as JSON-string form to Amount.
+
+        Also supports initialization from an existing instance via the module's check_for_class helper.
+        """
         if check_for_class(self, args):
             return
         if len(args) == 1 and len(kwargs) == 0:
             kwargs = args[0]
         prefix = kwargs.get("prefix", default_prefix)
         json_str = kwargs.get("json_str", False)
-        if "reward_sbd" in kwargs and "reward_steem" in kwargs:
-            super(Claim_reward_balance, self).__init__(
-                OrderedDict(
-                    [
-                        ("account", String(kwargs["account"])),
-                        (
-                            "reward_steem",
-                            Amount(kwargs["reward_steem"], prefix=prefix, json_str=json_str),
-                        ),
-                        (
-                            "reward_sbd",
-                            Amount(kwargs["reward_sbd"], prefix=prefix, json_str=json_str),
-                        ),
-                        ("reward_vests", Amount(kwargs["reward_vests"], prefix=prefix)),
-                    ]
-                )
-            )
-        elif "reward_hbd" in kwargs and "reward_hive" in kwargs:
-            super(Claim_reward_balance, self).__init__(
-                OrderedDict(
-                    [
-                        ("account", String(kwargs["account"])),
-                        ("reward_hive", Amount(kwargs["reward_hive"], prefix=prefix)),
-                        ("reward_hbd", Amount(kwargs["reward_hbd"], prefix=prefix)),
-                        ("reward_vests", Amount(kwargs["reward_vests"], prefix=prefix)),
-                    ]
-                )
-            )
-        elif "reward_hive" in kwargs:
-            super(Claim_reward_balance, self).__init__(
-                OrderedDict(
-                    [
-                        ("account", String(kwargs["account"])),
-                        (
-                            "reward_hive",
-                            Amount(kwargs["reward_hive"], prefix=prefix, json_str=json_str),
-                        ),
-                        ("reward_vests", Amount(kwargs["reward_vests"], prefix=prefix)),
-                    ]
-                )
-            )
-        else:
-            super(Claim_reward_balance, self).__init__(
-                OrderedDict(
-                    [
-                        ("account", String(kwargs["account"])),
-                        ("reward_steem", Amount(kwargs["reward_steem"], prefix=prefix)),
-                        ("reward_vests", Amount(kwargs["reward_vests"], prefix=prefix)),
-                    ]
-                )
+
+        # Ensure all required fields are present, using zero amounts for missing rewards
+        account = kwargs["account"]
+        reward_hive = kwargs.get("reward_hive", "0.000 HIVE")
+        reward_hbd = kwargs.get("reward_hbd", "0.000 HBD")
+        reward_vests = kwargs["reward_vests"]
+
+        super(Claim_reward_balance, self).__init__(
+            OrderedDict(
+                [
+                    ("account", String(account)),
+                    ("reward_hive", Amount(reward_hive, prefix=prefix, json_str=json_str)),
+                    ("reward_hbd", Amount(reward_hbd, prefix=prefix, json_str=json_str)),
+                    ("reward_vests", Amount(reward_vests, prefix=prefix, json_str=json_str)),
+                ]
             )
+        )
 
 
 class Transfer_to_savings(GrapheneObject):
@@ -1143,6 +1181,23 @@ class Recover_account(GrapheneObject):
 
 class Escrow_transfer(GrapheneObject):
     def __init__(self, *args, **kwargs):
+        """
+        Initialize an Escrow_transfer operation object.
+
+        If constructed from an existing GrapheneObject instance (detected via check_for_class), the initializer returns early after copying data.
+
+        Accepts either a single dict positional argument or keyword arguments. Expected fields:
+        - from, to, agent (str): account names involved.
+        - escrow_id (int): escrow identifier.
+        - hbd_amount, hive_amount, fee: amounts; when both `hbd_amount` and `hive_amount` are provided, amounts are wrapped with the `json_str` option; otherwise amounts are wrapped without `json_str`.
+        - ratification_deadline, escrow_expiration: datetime-like values for deadlines.
+        - json_meta: optional metadata — if a dict or list it will be JSON-serialized; otherwise used as-is.
+        Optional kwargs:
+        - prefix (str): asset prefix (default "STM").
+        - json_str (bool): whether to force JSON string representation for Amount fields when the branch requires it.
+
+        No return value; constructs and initializes the underlying ordered field mapping for the operation.
+        """
         if check_for_class(self, args):
             return
         if len(args) == 1 and len(kwargs) == 0:
@@ -1186,8 +1241,8 @@ class Escrow_transfer(GrapheneObject):
                         ("to", String(kwargs["to"])),
                         ("agent", String(kwargs["agent"])),
                         ("escrow_id", Uint32(kwargs["escrow_id"])),
-                        ("sbd_amount", Amount(kwargs["sbd_amount"], prefix=prefix)),
-                        ("steem_amount", Amount(kwargs["steem_amount"], prefix=prefix)),
+                        ("hbd_amount", Amount(kwargs["hbd_amount"], prefix=prefix)),
+                        ("hive_amount", Amount(kwargs["hive_amount"], prefix=prefix)),
                         ("fee", Amount(kwargs["fee"], prefix=prefix)),
                         ("ratification_deadline", PointInTime(kwargs["ratification_deadline"])),
                         ("escrow_expiration", PointInTime(kwargs["escrow_expiration"])),
@@ -1217,6 +1272,21 @@ class Escrow_dispute(GrapheneObject):
 
 class Escrow_release(GrapheneObject):
     def __init__(self, *args, **kwargs):
+        """
+        Initialize an Escrow_release operation.
+
+        Constructs the operation fields required to release escrowed funds: from, to, who, escrow_id, hbd_amount, and hive_amount. Accepts either a single dict positional argument or keyword arguments. If initialized from an existing GrapheneObject instance (detected by check_for_class), initialization returns early after cloning.
+
+        Key kwargs:
+        - from, to, who (str): account names involved in the escrow release.
+        - escrow_id (int): escrow identifier.
+        - hbd_amount, hive_amount (str|Amount): amounts to release; wrapped as Amount objects using the provided prefix.
+        - prefix (str, optional): asset/account prefix passed to Amount (defaults to default_prefix).
+        - json_str (bool, optional): when True and both amount keys are present, amounts are wrapped with json_str enabled.
+
+        Raises:
+        - KeyError if any required field is missing.
+        """
         if check_for_class(self, args):
             return
         if len(args) == 1 and len(kwargs) == 0:
@@ -1250,8 +1320,8 @@ class Escrow_release(GrapheneObject):
                         ("to", String(kwargs["to"])),
                         ("who", String(kwargs["who"])),
                         ("escrow_id", Uint32(kwargs["escrow_id"])),
-                        ("sbd_amount", Amount(kwargs["sbd_amount"], prefix=prefix)),
-                        ("steem_amount", Amount(kwargs["steem_amount"], prefix=prefix)),
+                        ("hbd_amount", Amount(kwargs["hbd_amount"], prefix=prefix)),
+                        ("hive_amount", Amount(kwargs["hive_amount"], prefix=prefix)),
                     ]
                 )
             )

nectarbase/signedtransactions.py

@@ -30,18 +30,54 @@ class Signed_Transaction(GrapheneSigned_Transaction):
         super(Signed_Transaction, self).__init__(*args, **kwargs)
 
     def add_custom_chains(self, custom_chain):
+        """
+        Add entries from custom_chain into this transaction's known chains without overwriting existing entries.
+
+        Accepts a mapping of chain identifiers to chain configuration values and merges any keys not already present into self.known_chains. Existing known chains are left unchanged.
+        Parameters:
+            custom_chain (Mapping): Mapping of chain name -> chain data (e.g., RPC URL or chain parameters); keys present in self.known_chains are not replaced.
+        """
         if len(custom_chain) > 0:
             for c in custom_chain:
                 if c not in self.known_chains:
                     self.known_chains[c] = custom_chain[c]
 
-    def sign(self, wifkeys, chain="STEEM"):
+    def sign(self, wifkeys, chain="HIVE"):
+        """
+        Sign the transaction using one or more WIF-format private keys.
+
+        wifkeys: Single WIF string or iterable of WIF private key strings used to produce signatures.
+        chain: Chain identifier to use for signing (defaults to "HIVE").
+
+        Returns:
+            The value returned by the superclass `sign` implementation.
+        """
         return super(Signed_Transaction, self).sign(wifkeys, chain)
 
-    def verify(self, pubkeys=[], chain="STEEM", recover_parameter=False):
+    def verify(self, pubkeys=None, chain="HIVE", recover_parameter=False):
+        """
+        Verify this transaction's signatures.
+
+        Parameters:
+            pubkeys (list[str] | None): Public keys to verify against. If None, an empty list is used (all signatures will be checked
+                without restricting expected pubkeys).
+            chain (str): Chain identifier to use for verification (defaults to "HIVE").
+            recover_parameter (bool): If True, return signature recovery parameters alongside verification results.
+
+        Returns:
+            Any: The result returned by the superclass verify method (verification outcome as defined by the base implementation).
+        """
+        if pubkeys is None:
+            pubkeys = []
         return super(Signed_Transaction, self).verify(pubkeys, chain, recover_parameter)
 
     def getOperationKlass(self):
+        """
+        Return the Operation class used to construct operations for this transaction.
+
+        Returns:
+            type: The Operation class used by this Signed_Transaction.
+        """
         return Operation
 
     def getKnownChains(self):

nectarbase/version.py

@@ -1,3 +1,3 @@
 """THIS FILE IS GENERATED FROM nectar PYPROJECT.TOML."""
 
-version = "0.0.11"
+version = "0.1.1"