hive-nectar 0.0.10__py3-none-any.whl → 0.1.0__py3-none-any.whl

nectar/witness.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import json
+import warnings
 from datetime import date, datetime, timezone
 
 from prettytable import PrettyTable
@@ -21,27 +22,54 @@ class Witness(BlockchainObject):
     :param bool lazy: Use lazy loading
     :param bool full: Get full data about witness
     :param nectar.nectar.nectar blockchain_instance: nectar
-        instance to use when accesing a RPC
+        instance to use when accessing the RPC
     """
 
     type_id = 3
 
     def __init__(self, owner, full=False, lazy=False, blockchain_instance=None, **kwargs):
+        # Warn about any unused kwargs to maintain backward compatibility
+        """
+        Initialize a Witness object representing a blockchain witness.
+
+        Parameters:
+            owner (str | dict): Witness owner account name or a dictionary of witness fields. If a dict is provided, it will be parsed into the internal witness representation.
+            full (bool): If True, load full witness data when available; otherwise keep a lighter representation.
+            lazy (bool): If True, defer network loading until data is accessed.
+
+        Notes:
+            - `blockchain_instance` defaults to the shared blockchain instance when not provided.
+            - Any unexpected keyword arguments are accepted for backward compatibility but will trigger a DeprecationWarning and be ignored.
+        """
+        if kwargs:
+            for key in kwargs:
+                warnings.warn(
+                    f"Unexpected keyword argument '{key}' passed to Witness.__init__. "
+                    "This may be a deprecated parameter and will be ignored.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
         self.full = full
         self.lazy = lazy
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         if isinstance(owner, dict):
             owner = self._parse_json_data(owner)
         super(Witness, self).__init__(
-            owner, lazy=lazy, full=full, id_item="owner", blockchain_instance=blockchain_instance
+            owner, lazy=lazy, full=full, id_item="owner", blockchain_instance=self.blockchain
         )
 
     def refresh(self):
+        """
+        Refresh the witness data from the blockchain and reinitialize this object.
+
+        If the witness identifier is empty or the blockchain is not connected, the method returns early.
+        Fetches witness data via the configured RPC (supports both appbase and legacy RPC paths), parses
+        timestamps and numeric fields via _parse_json_data, and reinitializes the Witness instance with the
+        retrieved data (respecting this object's lazy/full flags and blockchain instance).
+
+        Raises:
+            WitnessDoesNotExistsException: If no witness information is found for the current identifier.
+        """
         if not self.identifier:
             return
         if not self.blockchain.is_connected():
@@ -125,13 +153,25 @@ class Witness(BlockchainObject):
         )
 
     def feed_publish(self, base, quote=None, account=None):
-        """Publish a feed price as a witness.
+        """
+        Publish a witness feed price (exchange rate) to the blockchain.
+
+        Accepts the base and quote as Amount objects, strings, or numeric values and submits a Feed_publish operation using the provided account (defaults to the witness owner).
+
+        Parameters:
+            base: Amount | str | number
+                The base side of the exchange_rate (must use the blockchain's backed token symbol).
+            quote: Amount | str | number, optional
+                The quote side of the exchange_rate. Defaults to "1.000 <TOKEN>" where <TOKEN> is the blockchain token_symbol.
+            account: str | Account, optional
+                Account name or Account object used to sign and publish the feed. If omitted, the witness owner is used.
 
-        :param float base: USD Price of STEEM in SBD (implied price)
-        :param float quote: (optional) Quote Price. Should be 1.000 (default), unless
-            we are adjusting the feed to support the peg.
-        :param str account: (optional) the source account for the transfer
-            if not self["owner"]
+        Returns:
+            The result returned by blockchain.finalizeOp (typically the broadcast/transaction result).
+
+        Raises:
+            ValueError: If no account is provided and the witness has no owner.
+            AssertionError: If the resolved base or quote symbols do not match the blockchain's expected backed_token_symbol and token_symbol, respectively.
         """
         quote = quote if quote is not None else "1.000 %s" % (self.blockchain.token_symbol)
         if not account:
@@ -349,8 +389,8 @@ class GetWitnesses(WitnessesObject):
     :param list name_list: list of witneses to fetch
     :param int batch_limit: (optional) maximum number of witnesses
         to fetch per call, defaults to 100
-    :param Steem steem_instance: Steem() instance to use when
-        accessing a RPCcreator = Witness(creator, steem_instance=self)
+    :param nectar.nectar.nectar blockchain_instance: nectar instance to use when
+        accessing the RPC
 
     .. code-block:: python
 
@@ -362,13 +402,24 @@ class GetWitnesses(WitnessesObject):
     """
 
     def __init__(
-        self, name_list, batch_limit=100, lazy=False, full=True, blockchain_instance=None, **kwargs
+        self,
+        name_list,
+        batch_limit=100,
+        lazy=False,
+        full=True,
+        blockchain_instance=None,
     ):
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
+        """
+        Initialize the GetWitnesses collection by fetching witness objects for the given list of account names.
+
+        If the connected RPC backend uses appbase, names are fetched in batches (size controlled by `batch_limit`); otherwise each name is queried individually. If no blockchain connection is available the initializer returns early and the collection remains empty.
+
+        Parameters:
+            name_list (Iterable[str]): Account names of witnesses to retrieve.
+            batch_limit (int): Maximum number of names to request per batch when using appbase RPC.
+            lazy (bool): If True, create Witness objects in lazy-loading mode.
+            full (bool): If True, create Witness objects with full data loaded.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         if not self.blockchain.is_connected():
             return
@@ -396,8 +447,8 @@ class GetWitnesses(WitnessesObject):
 class Witnesses(WitnessesObject):
     """Obtain a list of **active** witnesses and the current schedule
 
-    :param Steem steem_instance: Steem instance to use when
-        accesing a RPC
+    :param nectar.nectar.nectar blockchain_instance: nectar instance to use when
+        accessing the RPC
 
     .. code-block:: python
 
@@ -407,12 +458,17 @@ class Witnesses(WitnessesObject):
 
     """
 
-    def __init__(self, lazy=False, full=True, blockchain_instance=None, **kwargs):
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
+    def __init__(self, lazy=False, full=True, blockchain_instance=None):
+        """
+        Initialize a Witnesses collection and load active witnesses from the configured blockchain.
+
+        Parameters:
+            lazy (bool): If True, create Witness objects without fetching full data (deferred loading).
+            full (bool): If True, eager-load full witness data when constructing each Witness.
+
+        Notes:
+            Resolves the blockchain instance from `blockchain_instance` or the shared default and immediately calls `refresh()` to populate the list of active witnesses.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         self.lazy = lazy
         self.full = full
@@ -449,8 +505,8 @@ class WitnessesVotedByAccount(WitnessesObject):
     """Obtain a list of witnesses which have been voted by an account
 
     :param str account: Account name
-    :param Steem steem_instance: Steem instance to use when
-        accesing a RPC
+    :param nectar.nectar.nectar blockchain_instance: nectar instance to use when
+        accessing the RPC
 
     .. code-block:: python
 
@@ -460,12 +516,20 @@ class WitnessesVotedByAccount(WitnessesObject):
 
     """
 
-    def __init__(self, account, lazy=False, full=True, blockchain_instance=None, **kwargs):
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
+    def __init__(self, account, lazy=False, full=True, blockchain_instance=None):
+        """
+        Initialize a WitnessesVotedByAccount collection for the given account.
+
+        Resolves the provided account to a full Account object, reads the list of witnesses that the account voted for (using appbase or legacy RPC paths as appropriate), and populates the list with Witness objects created with the specified loading flags. If the account has no witness votes recorded the constructor returns early and the collection remains empty. The instance identifier is set to the account name.
+
+        Parameters:
+            account (str|Account): Account name or Account-like object to inspect for witness votes.
+            lazy (bool): If True, create Witness objects in lazy-loading mode. Defaults to False.
+            full (bool): If True, request full witness data when constructing Witness objects. Defaults to True.
+
+        Note:
+            The blockchain instance is taken from the optional `blockchain_instance` argument or the shared default; it is not documented here as a parameter.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         self.account = Account(account, full=True, blockchain_instance=self.blockchain)
         account_name = self.account["name"]
@@ -500,8 +564,8 @@ class WitnessesRankedByVote(WitnessesObject):
 
     :param str from_account: Witness name from which the lists starts (default = "")
     :param int limit: Limits the number of shown witnesses (default = 100)
-    :param Steem steem_instance: Steem instance to use when
-        accesing a RPC
+    :param nectar.nectar.nectar blockchain_instance: nectar instance to use when
+        accessing the RPC
 
     .. code-block:: python
 
@@ -512,13 +576,34 @@ class WitnessesRankedByVote(WitnessesObject):
     """
 
     def __init__(
-        self, from_account="", limit=100, lazy=False, full=False, blockchain_instance=None, **kwargs
+        self,
+        from_account="",
+        limit=100,
+        lazy=False,
+        full=False,
+        blockchain_instance=None,
     ):
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
+        """
+        Initialize a list of witnesses ranked by vote, with optional pagination.
+
+        Builds a WitnessesRankedByVote list starting at `from_account` and returning up to `limit`
+        entries. The constructor transparently pages RPC calls when the requested `limit`
+        exceeds the per-call query limit, handles appbase vs legacy RPC paths and condenser
+        mode, and wraps returned witness entries as Witness objects.
+
+        Parameters:
+            from_account (str): Account name to start ranking from (inclusive). When empty, ranking starts from the top.
+            limit (int): Maximum number of witnesses to return.
+            lazy (bool): If True, create Witness objects in lazy-loading mode.
+            full (bool): If True, fully load each Witness on creation.
+
+        Notes:
+            - `blockchain_instance` is taken from the shared instance when not provided.
+            - The method uses different RPC endpoints depending on the node configuration
+              (appbase vs non-appbase, and condenser mode) and automatically pages results
+              to satisfy `limit`.
+            - Returns early (no list created) if no witnesses are found.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         witnessList = []
         last_limit = limit
@@ -577,10 +662,10 @@ class WitnessesRankedByVote(WitnessesObject):
 class ListWitnesses(WitnessesObject):
     """List witnesses ranked by name
 
-    :param str from_account: Witness name from which the lists starts (default = "")
+    :param str from_account: Witness name from which the list starts (default = "")
     :param int limit: Limits the number of shown witnesses (default = 100)
-    :param Steem steem_instance: Steem instance to use when
-        accesing a RPC
+    :param nectar.nectar.nectar blockchain_instance: nectar instance to use when
+        accessing the RPC
 
     .. code-block:: python
 
@@ -591,13 +676,27 @@ class ListWitnesses(WitnessesObject):
     """
 
     def __init__(
-        self, from_account="", limit=100, lazy=False, full=False, blockchain_instance=None, **kwargs
+        self,
+        from_account="",
+        limit=100,
+        lazy=False,
+        full=False,
+        blockchain_instance=None,
     ):
-        if blockchain_instance is None:
-            if kwargs.get("steem_instance"):
-                blockchain_instance = kwargs["steem_instance"]
-            elif kwargs.get("hive_instance"):
-                blockchain_instance = kwargs["hive_instance"]
+        """
+        Initialize a ListWitnesses collection starting from a given account name.
+
+        Creates a list of Witness objects beginning at `from_account` (lexicographic start)
+        up to `limit` entries. If no witnesses are found the constructor returns early
+        leaving the instance empty. The object uses the provided blockchain instance
+        (or the shared default) to query the node and sets `identifier` to `from_account`.
+
+        Parameters:
+            from_account (str): Account name to start listing witnesses from (inclusive).
+            limit (int): Maximum number of witness entries to retrieve.
+            lazy (bool): If True, construct Witness objects in lazy mode (defer full data load).
+            full (bool): If True, request full witness data when constructing Witness objects.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         self.identifier = from_account
         self.blockchain.rpc.set_next_node_on_empty_reply(False)