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

nectar/message.py

@@ -50,11 +50,17 @@ timestamp={meta[timestamp]}
 {MESSAGE_SPLIT[3]}"""
 
     def __init__(self, message, blockchain_instance=None, *args, **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"]
+        """
+        Initialize the message handler, normalize line endings, and set up signing context.
+
+        Parameters:
+            message (str): The raw message text to be signed or verified. Line endings are normalized to LF.
+
+        Description:
+            - Assigns self.blockchain to the provided blockchain_instance or to shared_blockchain_instance() when none is given.
+            - Normalizes CRLF ("\r\n") to LF ("\n") and stores the result in self.message.
+            - Initializes signing/verification context attributes: signed_by_account, signed_by_name, meta, and plain_message to None.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         self.message = message.replace("\r\n", "\n")
         self.signed_by_account = None
@@ -183,11 +189,18 @@ class MessageV2(object):
     """Allow to sign and verify Messages that are sigend with a private key"""
 
     def __init__(self, message, blockchain_instance=None, *args, **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"]
+        """
+        Initialize the message handler and set up default signing context.
+
+        Parameters:
+            message (str): The raw message text to be signed or verified.
+
+        Description:
+            Stores the provided message and sets up the signing context attributes
+            (signed_by_account, signed_by_name, meta, plain_message) to None.
+            If no blockchain instance is supplied, assigns a shared blockchain instance
+            via shared_blockchain_instance().
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
 
         self.message = message

nectar/nodelist.py

@@ -10,12 +10,24 @@ log = logging.getLogger(__name__)
 
 
 def node_answer_time(node):
+    """
+    Measure the RPC/network response time to a Hive node.
+
+    Parameters:
+        node (str): Node endpoint (URL or host) to ping.
+
+    Returns:
+        float: Elapsed time in seconds for a single `get_network` call. Returns float('inf') if an error occurred while contacting the node.
+
+    Raises:
+        KeyboardInterrupt: Re-raised if the operation is interrupted by the user.
+    """
     try:
         from nectar.blockchaininstance import BlockChainInstance
 
-        stm_local = BlockChainInstance(node=node, num_retries=2, num_retries_call=2, timeout=10)
+        hv_local = BlockChainInstance(node=node, num_retries=2, num_retries_call=2, timeout=10)
         start = timer()
-        stm_local.get_network(use_stored_data=False)
+        hv_local.get_network(use_stored_data=False)
         stop = timer()
         rpc_answer_time = stop - start
     except KeyboardInterrupt:
@@ -27,7 +39,7 @@ def node_answer_time(node):
 
 
 class NodeList(list):
-    """Returns HIVE/STEEM nodes as list
+    """Returns Hive nodes as list
 
     .. code-block:: python
 
@@ -38,15 +50,14 @@ class NodeList(list):
     """
 
     def __init__(self):
+        """
+        Initialize the NodeList with a built-in default set of Hive node metadata.
+
+        Creates the list with prepopulated node dictionaries (url, version, type, owner, hive, score)
+        and passes them to the parent list constructor. The default entries are Hive-focused
+        (appbase and testnet types) and intended as the initial internal node registry.
+        """
         nodes = [
-            {
-                "url": "https://api.steemit.com",
-                "version": "0.20.2",
-                "type": "appbase",
-                "owner": "steemit",
-                "hive": False,
-                "score": 50,
-            },
             {
                 "url": "https://api.hive.blog",
                 "version": "1.27.8",
@@ -177,14 +188,24 @@ class NodeList(list):
         super(NodeList, self).__init__(new_nodes)
 
     def get_node_answer_time(self, node_list=None, verbose=False):
-        """Pings all nodes and measure the answer time
-
-        .. code-block:: python
-
-            from nectar.nodelist import NodeList
-            nl = NodeList()
-            nl.update_nodes()
-            nl.ping_nodes()
+        """
+        Return a list of reachable node endpoints sorted by measured RPC latency.
+
+        Pings each URL in node_list (or every URL known to this NodeList if node_list is None)
+        using node_answer_time and returns a list of dicts sorted by increasing latency.
+        Each dict contains:
+            - "url": the node endpoint string
+            - "delay_ms": measured round-trip delay in milliseconds
+
+        Parameters:
+            node_list (iterable[str] | None): Specific node URLs to test. If None, all URLs
+                from this NodeList are tested.
+            verbose (bool): If True, logs each node's measured delay.
+
+        Behavior notes:
+            - URLs not present in this NodeList are treated as unreachable and omitted from the result.
+            - Nodes that fail measurement are treated as infinite latency and are excluded from the returned list.
+            - A KeyboardInterrupt during measurements stops further pinging; the interrupted entry is treated as unreachable.
         """
         ping_times = []
         if node_list is None:
@@ -214,27 +235,39 @@ class NodeList(list):
                 sorted_nodes.append({"url": node_list[i], "delay_ms": ping_times[i] * 1000})
         return sorted_nodes
 
-    def update_nodes(self, weights=None, blockchain_instance=None, **kwargs):
-        """Reads metadata from nectarflower and recalculates the nodes score
-
-        :param list/dict weight: can be used to weight the different benchmarks
-        :type weight: list, dict
-
-        .. code-block:: python
-
-            from nectar.nodelist import NodeList
-            nl = NodeList()
-            weights = [0, 0.1, 0.2, 1]
-            nl.update_nodes(weights)
-            weights = {'block': 0.1, 'history': 0.1, 'apicall': 1, 'config': 1}
-            nl.update_nodes(weights)
+    def update_nodes(self, weights=None, 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"]
-        steem = blockchain_instance or shared_blockchain_instance()
+        Update the internal node list and recalculated scores using nectarflower metadata.
+
+        Fetches the "nectarflower" account's json_metadata (up to 5 attempts) and uses its
+        "report", "failing_nodes", and "parameter" sections to recalculate each node's
+        score and metadata (version, hive). If metadata cannot be retrieved after
+        retries, the method logs a warning and returns without modifying the list.
+
+        Weights:
+        - weights may be None, a list, or a dict.
+          - None: benchmarks are weighted uniformly.
+          - list: values are assigned in order to discovered benchmark names and normalized by their sum.
+          - dict: keys are benchmark names; values are normalized by their sum. Any benchmark not present in the provided dict receives weight 0.
+        The code derives benchmark names from metadata.parameters.benchmarks when available,
+        otherwise from keys present in report entries (excluding obvious non-benchmark fields).
+
+        Scoring rules:
+        - For each report entry, per-benchmark ranks are converted to scores (0–100),
+          multiplied by the benchmark weights, and summed to produce a node score.
+        - If a report entry contains a numeric "weighted_score", that value takes precedence.
+        - Nodes listed in failing_nodes receive a score of -1.
+        - Nodes present in the internal list but missing from the report receive score 0.
+        - Nodes present in the report but missing from the internal list are appended to the final list (with fields populated from the report).
+        - Nodes listed in failing_nodes but absent elsewhere are appended with score -1.
+
+        Side effects:
+        - Replaces the NodeList contents (in-place) with the newly computed list of nodes.
+        - Uses the provided blockchain_instance or a shared blockchain instance to fetch metadata and advance RPC state on transient errors.
+
+        No return value.
+        """
+        bc = blockchain_instance or shared_blockchain_instance()
 
         metadata = None
         account = None
@@ -242,7 +275,7 @@ class NodeList(list):
         while metadata is None and cnt < 5:
             cnt += 1
             try:
-                account = Account("nectarflower", blockchain_instance=steem)
+                account = Account("nectarflower", blockchain_instance=bc)
                 # Metadata is stored in the account's json_metadata field (not posting_json_metadata)
                 raw_meta = account.get("json_metadata") or ""
                 try:
@@ -251,7 +284,7 @@ class NodeList(list):
                     metadata = None
             except Exception as e:
                 log.warning(f"Error fetching metadata (attempt {cnt}): {str(e)}")
-                steem.rpc.next()
+                bc.rpc.next()
                 account = None
                 metadata = None
 
@@ -412,7 +445,7 @@ class NodeList(list):
 
     def get_nodes(
         self,
-        hive=False,
+        hive=True,
         exclude_limited=False,
         dev=False,
         testnet=False,
@@ -423,17 +456,25 @@ class NodeList(list):
         normal=True,
         appbase=True,
     ):
-        """Returns nodes as list
-
-        :param bool hive: When True, only HIVE nodes will be returned
-        :param bool exclude_limited: When True, limited nodes are excluded
-        :param bool dev: when True, dev nodes with version 0.19.11 are included
-        :param bool testnet: when True, testnet nodes are included
-        :param bool testnetdev: When True, testnet-dev nodes are included
-        :param bool not_working: When True, all nodes including not working ones will be returned
-        :param bool normal: deprecated
-        :param bool appbase: deprecated
-
+        """
+        Return a list of node URLs filtered and sorted by score (descending).
+
+        Filters nodes by type (normal, appbase, appbase-dev, testnet, testnet-dev, appbase-limited), by whether they are Hive nodes, by protocol (https/wss), and by working status. Nodes with score < 0 are excluded unless not_working=True. The resulting list is sorted by each node's "score" in descending order.
+
+        Parameters that add non-obvious behavior:
+            hive (bool): If True (default) return only nodes marked as Hive; set to False to include non-Hive entries (note: the bundled node data is Hive-focused).
+            exclude_limited (bool): If True, exclude nodes of type "appbase-limited".
+            dev (bool): If True, include "appbase-dev" nodes (legacy/dev nodes, historically version 0.19.11).
+            testnet (bool): If True, include "testnet" nodes.
+            testnetdev (bool): If True, include "testnet-dev" nodes.
+            wss (bool): If False, exclude URLs that start with "wss".
+            https (bool): If False, exclude URLs that start with "https".
+            not_working (bool): If True, include nodes with negative scores (not working).
+            normal (bool): Include "normal" nodes when True. (Deprecated)
+            appbase (bool): Include "appbase" nodes when True. (Deprecated)
+
+        Returns:
+            list[str]: Filtered node URLs sorted by node["score"] descending.
         """
         node_list = []
         node_type_list = []
@@ -451,6 +492,7 @@ class NodeList(list):
             node_type_list.append("appbase-limited")
         for node in self:
             if node["type"] in node_type_list and (node["score"] >= 0 or not_working):
+                # Hive-only by default; legacy callers can still pass hive=False but list is Hive-only
                 if hive != node["hive"]:
                     continue
                 if not https and node["url"][:5] == "https":
@@ -464,11 +506,19 @@ class NodeList(list):
         ]
 
     def get_hive_nodes(self, testnet=False, not_working=False, wss=True, https=True):
-        """Returns hive only nodes as list
+        """
+        Return a list of Hive node URLs filtered and ordered by score.
 
-        :param bool testnet: when True, testnet nodes are included
-        :param bool not_working: When True, all nodes including not working ones will be returned
+        Filters internal nodes to Hive-only entries and returns their URLs sorted by score (highest first).
 
+        Parameters:
+            testnet (bool): If True, include only nodes whose type is "testnet". If False, include only non-testnet nodes.
+            not_working (bool): If True, include nodes with negative scores (typically non-working). If False, exclude them.
+            wss (bool): If True, include nodes with WSS (wss://) URLs; if False, exclude WSS endpoints.
+            https (bool): If True, include nodes with HTTPS (https://) URLs; if False, exclude HTTPS endpoints.
+
+        Returns:
+            list[str]: Sorted list of node URLs (strings) matching the filters.
         """
         node_list = []
 
@@ -490,33 +540,17 @@ class NodeList(list):
             node["url"] for node in sorted(node_list, key=lambda self: self["score"], reverse=True)
         ]
 
-    def get_steem_nodes(self, testnet=False, not_working=False, wss=True, https=True):
-        """Returns steem only nodes as list
-
-        :param bool testnet: when True, testnet nodes are included
-        :param bool not_working: When True, all nodes including not working ones will be returned
-
+    def get_testnet(self, testnet=True, testnetdev=False):
         """
-        node_list = []
+        Return a list of testnet node URLs.
 
-        for node in self:
-            if node["hive"]:
-                continue
-            if node["score"] < 0 and not not_working:
-                continue
-            if (testnet and node["type"] == "testnet") or (
-                not testnet and node["type"] != "testnet"
-            ):
-                if not https and node["url"][:5] == "https":
-                    continue
-                if not wss and node["url"][:3] == "wss":
-                    continue
-                node_list.append(node)
+        Calls get_nodes with normal and appbase disabled to return nodes belonging to the testnet(s).
 
-        return [
-            node["url"] for node in sorted(node_list, key=lambda self: self["score"], reverse=True)
-        ]
+        Parameters:
+            testnet (bool): If True include nodes marked as `testnet`. If False, include non-testnet nodes.
+            testnetdev (bool): If True include nodes marked as `testnet-dev` (development testnet).
 
-    def get_testnet(self, testnet=True, testnetdev=False):
-        """Returns testnet nodes"""
+        Returns:
+            list: Sorted list of node URL strings matching the requested testnet filters.
+        """
         return self.get_nodes(normal=False, appbase=False, testnet=testnet, testnetdev=testnetdev)

nectar/price.py

@@ -4,23 +4,12 @@ from fractions import Fraction
 
 from nectar.instance import shared_blockchain_instance
 
-from .amount import Amount
+from .amount import Amount, check_asset
 from .asset import Asset
 from .exceptions import InvalidAssetException
 from .utils import assets_from_string, formatTimeString
 
 
-def check_asset(other, self, stm):
-    if isinstance(other, dict) and "asset" in other and isinstance(self, dict) and "asset" in self:
-        if not Asset(other["asset"], blockchain_instance=stm) == Asset(
-            self["asset"], blockchain_instance=stm
-        ):
-            raise AssertionError()
-    else:
-        if not other == self:
-            raise AssertionError()
-
-
 class Price(dict):
     """This class deals with all sorts of prices of any pair of assets to
     simplify dealing with the tuple::
@@ -37,7 +26,7 @@ class Price(dict):
     :param list args: Allows to deal with different representations of a price
     :param Asset base: Base asset
     :param Asset quote: Quote asset
-    :param Steem blockchain_instance: Steem instance
+    :param Hive blockchain_instance: Hive instance
     :returns: All data required to represent a price
     :rtype: dictionary
 
@@ -53,16 +42,16 @@ class Price(dict):
         * ``args`` being a list of ``[quote, base]`` both being instances of ``str`` (``amount symbol``)
         * ``base`` and ``quote`` being instances of :class:`nectar.asset.Amount`
 
-    This allows instanciations like:
+    This allows instantiations like:
 
-    * ``Price("0.315 SBD/STEEM")``
-    * ``Price(0.315, base="SBD", quote="STEEM")``
-    * ``Price(0.315, base=Asset("SBD"), quote=Asset("STEEM"))``
-    * ``Price({"base": {"amount": 1, "asset_id": "SBD"}, "quote": {"amount": 10, "asset_id": "SBD"}})``
-    * ``Price(quote="10 STEEM", base="1 SBD")``
-    * ``Price("10 STEEM", "1 SBD")``
-    * ``Price(Amount("10 STEEM"), Amount("1 SBD"))``
-    * ``Price(1.0, "SBD/STEEM")``
+    * ``Price("0.315 HBD/HIVE")``
+    * ``Price(0.315, base="HBD", quote="HIVE")``
+    * ``Price(0.315, base=Asset("HBD"), quote=Asset("HIVE"))``
+    * ``Price({"base": {"amount": 1, "asset_id": "HBD"}, "quote": {"amount": 10, "asset_id": "HBD"}})``
+    * ``Price(quote="10 HIVE", base="1 HBD")``
+    * ``Price("10 HIVE", "1 HBD")``
+    * ``Price(Amount("10 HIVE"), Amount("1 HBD"))``
+    * ``Price(1.0, "HBD/HIVE")``
 
     Instances of this class can be used in regular mathematical expressions
     (``+-*/%``) such as:
@@ -70,12 +59,12 @@ class Price(dict):
     .. code-block:: python
 
         >>> from nectar.price import Price
-        >>> from nectar import Steem
-        >>> stm = Steem("https://api.steemit.com")
-        >>> Price("0.3314 SBD/STEEM", blockchain_instance=stm) * 2
-        0.662804 SBD/STEEM
-        >>> Price(0.3314, "SBD", "STEEM", blockchain_instance=stm)
-        0.331402 SBD/STEEM
+        >>> from nectar import Hive
+        >>> hv = Hive("https://api.hive.blog")
+        >>> Price("0.3314 HBD/HIVE", blockchain_instance=hv) * 2
+        0.662804 HBD/HIVE
+        >>> Price(0.3314, "HBD", "HIVE", blockchain_instance=hv)
+        0.331402 HBD/HIVE
 
     """
 
@@ -86,13 +75,38 @@ class Price(dict):
         quote=None,
         base_asset=None,  # to identify sell/buy
         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"]
+        """
+        Initialize a Price object representing a ratio between a base and quote asset.
+
+        This constructor accepts multiple input forms and normalizes them into internal
+        "base" and "quote" Amount entries. Supported usages:
+        - price: str like "X BASE/QUOTE" with no base/quote: parses symbols and creates
+          Amounts from the fractional representation of X.
+        - price: dict with "base" and "quote": loads Amounts directly (raises AssertionError
+          if a top-level "price" key is present).
+        - price: numeric (float/int/Decimal) with base and quote provided as Asset or
+          symbol strings: converts the numeric value to a Fraction and builds Amounts.
+        - price: str representing an Amount and base: when price is a string and base is
+          a symbol string, price and base are used to build quote/base Amounts.
+        - price and base as Amount instances: accepts Amount objects directly.
+        - price is None with base and quote as symbol strings or Amounts: loads assets
+          or Amounts respectively.
+
+        Parameters (not exhaustive):
+        - price: numeric, str, dict, or Amount — the price or a representation used to
+          derive base/quote Amounts.
+        - base: Asset, Amount, or str — identifies the base side (or a symbol string
+          used to parse both symbols when combined with a numeric price).
+        - quote: Asset, Amount, or str — identifies the quote side.
+        - base_asset: optional; used only as an identifier flag for buy/sell contexts.
+        - blockchain_instance: blockchain context used to construct Asset/Amount (omitted
+          from param listing as a shared service).
+
+        Raises:
+        - AssertionError: if a dict `price` includes a top-level "price" key.
+        - ValueError: if the combination of inputs cannot be parsed into base and quote.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         if price == "":
             price = None
@@ -112,7 +126,7 @@ class Price(dict):
         elif price is not None and isinstance(price, dict) and "base" in price and "quote" in price:
             if "price" in price:
                 raise AssertionError("You cannot provide a 'price' this way")
-            # Regular 'price' objects according to steem-core
+            # Regular 'price' objects according to hive-core
             # base_id = price["base"]["asset_id"]
             # if price["base"]["asset_id"] == base_id:
             self["base"] = Amount(price["base"], blockchain_instance=self.blockchain)
@@ -201,18 +215,18 @@ class Price(dict):
         return self["base"]["symbol"], self["quote"]["symbol"]
 
     def as_base(self, base):
-        """Returns the price instance so that the base asset is ``base``.
-
-        .. note:: This makes a copy of the object!
+        """
+        Return a copy of this Price expressed with the given asset as the base.
 
-        .. code-block:: python
+        If `base` matches the current base symbol this returns a shallow copy.
+        If `base` matches the current quote symbol this returns a copy with base and quote inverted.
+        Raises InvalidAssetException if `base` is neither the base nor the quote of this price.
 
-            >>> from nectar.price import Price
-            >>> from nectar import Steem
-            >>> stm = Steem("https://api.steemit.com")
-            >>> Price("0.3314 SBD/STEEM", blockchain_instance=stm).as_base("STEEM")
-            3.017483 STEEM/SBD
+        Parameters:
+            base (str): Asset symbol to use as the base (e.g., "HIVE" or "HBD").
 
+        Returns:
+            Price: A new Price instance whose base asset is `base`.
         """
         if base == self["base"]["symbol"]:
             return self.copy()
@@ -222,18 +236,21 @@ class Price(dict):
             raise InvalidAssetException
 
     def as_quote(self, quote):
-        """Returns the price instance so that the quote asset is ``quote``.
+        """
+        Return a Price instance expressed with the given quote asset symbol.
 
-        .. note:: This makes a copy of the object!
+        If `quote` matches the current quote symbol, returns a copy of this Price.
+        If `quote` matches the current base symbol, returns a copied, inverted Price.
+        A new object is always returned (the original is not modified).
 
-        .. code-block:: python
+        Parameters:
+            quote (str): Asset symbol to use as the quote (e.g., "HBD" or "HIVE").
 
-            >>> from nectar.price import Price
-            >>> from nectar import Steem
-            >>> stm = Steem("https://api.steemit.com")
-            >>> Price("0.3314 SBD/STEEM", blockchain_instance=stm).as_quote("SBD")
-            3.017483 STEEM/SBD
+        Returns:
+            Price: A Price object with `quote` as the quote asset.
 
+        Raises:
+            InvalidAssetException: If `quote` does not match either the current base or quote symbol.
         """
         if quote == self["quote"]["symbol"]:
             return self.copy()
@@ -243,16 +260,18 @@ class Price(dict):
             raise InvalidAssetException
 
     def invert(self):
-        """Invert the price (e.g. go from ``SBD/STEEM`` into ``STEEM/SBD``)
+        """
+        Invert the price in place, swapping base and quote assets (e.g., HBD/HIVE -> HIVE/HBD).
 
-        .. code-block:: python
+        Returns:
+            self: The same Price instance after inversion.
 
+        Example:
             >>> from nectar.price import Price
-            >>> from nectar import Steem
-            >>> stm = Steem("https://api.steemit.com")
-            >>> Price("0.3314 SBD/STEEM", blockchain_instance=stm).invert()
-            3.017483 STEEM/SBD
-
+            >>> from nectar import Hive
+            >>> hv = Hive("https://api.hive.blog")
+            >>> Price("0.3314 HBD/HIVE", blockchain_instance=hv).invert()
+            3.017483 HIVE/HBD
         """
         tmp = self["quote"]
         self["quote"] = self["base"]
@@ -451,7 +470,7 @@ class Order(Price):
     ratio of base and quote) but instead has those amounts represent the
     amounts of an actual order!
 
-    :param Steem blockchain_instance: Steem instance
+    :param Hive blockchain_instance: Hive instance
 
     .. note::
 
@@ -504,7 +523,7 @@ class FilledOrder(Price):
     ratio of base and quote) but instead has those amounts represent the
     amounts of an actually filled order!
 
-    :param Steem blockchain_instance: Steem instance
+    :param Hive blockchain_instance: Hive instance
 
     .. note:: Instances of this class come with an additional ``date`` key
               that shows when the order has been filled!

nectar/profile.py

@@ -39,12 +39,15 @@ class DotDict(dict):
 
 class Profile(DotDict):
     """This class is a template to model a user's on-chain
-    profile according to
-
-        * https://github.com/adcpm/steemscript
+    profile according to Hive profile metadata conventions.
     """
 
     def __init__(self, *args, **kwargs):
+        """
+        Initialize a Profile by delegating to the DotDict initializer.
+
+        This constructor accepts the same arguments as DotDict (e.g., dot-separated key/value pairs, a dict, or a JSON string) and performs no additional processing.
+        """
         super(Profile, self).__init__(*args, **kwargs)
 
     def __str__(self):