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

nectar/comment.py

@@ -5,9 +5,10 @@ import math
 from datetime import date, datetime, timezone
 
 from nectar.constants import (
-    STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF6,
-    STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF20,
-    STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF21,
+    HIVE_100_PERCENT,
+    HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF6,
+    HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF20,
+    HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF21,
 )
 from nectarbase import operations
 
@@ -34,16 +35,17 @@ class Comment(BlockchainObject):
     :param str authorperm: identifier to post/comment in the form of
         ``@author/permlink``
     :param str tags: defines which api is used. Can be bridge, tags, condenser or database (default = bridge)
-    :param Hive blockchain_instance: :class:`nectar.hive.Steem` instance to use when accessing a RPC
+    :param Blockchain blockchain_instance: Blockchain instance to use when accessing the RPC
 
 
     .. code-block:: python
 
     >>> from nectar.comment import Comment
     >>> from nectar.account import Account
-    >>> from nectar import Steem
-    >>> stm = Steem()
-    >>> acc = Account("gtg", blockchain_instance=stm)
+    >>> # Create a Hive blockchain instance
+    >>> from nectar.blockchain import Blockchain as Hive
+    >>> hv = Hive()
+    >>> acc = Account("gtg", blockchain_instance=hv)
     >>> authorperm = acc.get_blog(limit=1)[0]["authorperm"]
     >>> c = Comment(authorperm)
     >>> postdate = c["created"]
@@ -61,17 +63,25 @@ class Comment(BlockchainObject):
         full=True,
         lazy=False,
         blockchain_instance=None,
-        **kwargs,
     ):
+        """
+        Create a Comment object representing a Hive post or comment.
+
+        Supports initializing from either an author/permlink string ("author/permlink") or a dict containing at least "author" and "permlink". For a string input the constructor resolves and stores author, permlink, and authorperm. For a dict input the constructor normalizes the dict via _parse_json_data (timestamps, amounts, metadata) and sets the canonical "authorperm" before delegating to the BlockchainObject constructor.
+
+        Parameters:
+            authorperm: Either an "author/permlink" string or a dict with "author" and "permlink".
+            api: RPC bridge to use (defaults to "bridge"); stored on the instance.
+            observer: Optional observer identifier stored on the instance.
+            full: If True, load all fields immediately; if False, allow partial/lazy loading.
+            lazy: If True, delay full object loading until needed.
+
+        Note: The blockchain instance is taken from blockchain_instance (if provided) or the module's shared_blockchain_instance(). The constructor sets instance attributes and then calls the parent initializer with id_item="authorperm".
+        """
         self.full = full
         self.lazy = lazy
         self.api = api
         self.observer = observer
-        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(authorperm, str) and authorperm != "":
             [author, permlink] = resolve_authorperm(authorperm)
@@ -89,10 +99,26 @@ class Comment(BlockchainObject):
             id_item="authorperm",
             lazy=lazy,
             full=full,
-            blockchain_instance=blockchain_instance,
+            blockchain_instance=self.blockchain,
         )
 
     def _parse_json_data(self, comment):
+        """
+        Normalize and convert raw comment JSON fields into Python-native types.
+
+        This parses and mutates the given comment dict in-place and returns it. Normalizations:
+        - Converts known timestamp strings (e.g., "created", "last_update", "cashout_time") to datetime using formatTimeString.
+        - Converts monetary fields backed by the chain's backed token (HBD) into Amount objects using the instance's backed_token_symbol.
+        - Ensures a "community" key exists and parses `json_metadata` (string/bytes) into a dict; extracts `tags` and `community` from that metadata when present.
+        - Converts numeric string fields like `author_reputation` and `net_rshares` to ints.
+        - Normalizes each entry in `active_votes`: converts vote `time` to datetime and numeric strings (`rshares`, `reputation`) to ints (falling back to 0 on parse errors).
+
+        Parameters:
+            comment (dict): Raw comment/post data as returned by the node RPC.
+
+        Returns:
+            dict: The same comment dict with normalized fields (timestamps as datetimes, amounts as Amount objects, json_metadata as dict, numeric fields as ints).
+        """
         parse_times = [
             "active",
             "cashout_time",
@@ -106,7 +132,7 @@ class Comment(BlockchainObject):
             if p in comment and isinstance(comment.get(p), str):
                 comment[p] = formatTimeString(comment.get(p, "1970-01-01T00:00:00"))
         # Parse Amounts
-        sbd_amounts = [
+        hbd_amounts = [
             "total_payout_value",
             "max_accepted_payout",
             "pending_payout_value",
@@ -114,7 +140,7 @@ class Comment(BlockchainObject):
             "total_pending_payout_value",
             "promoted",
         ]
-        for p in sbd_amounts:
+        for p in hbd_amounts:
             if p in comment and isinstance(comment.get(p), (str, list, dict)):
                 value = comment.get(p, "0.000 %s" % (self.blockchain.backed_token_symbol))
                 if (
@@ -124,6 +150,9 @@ class Comment(BlockchainObject):
                     value = value.split(" ")[0] + " " + self.blockchain.backed_token_symbol
                 comment[p] = Amount(value, blockchain_instance=self.blockchain)
 
+        if "community" not in comment:
+            comment["community"] = ""
+
         # turn json_metadata into python dict
         meta_str = comment.get("json_metadata", "{}")
         if meta_str == "{}":
@@ -138,7 +167,7 @@ class Comment(BlockchainObject):
         if isinstance(comment["json_metadata"], dict):
             if "tags" in comment["json_metadata"]:
                 comment["tags"] = comment["json_metadata"]["tags"]
-            if "community" in comment["json_metadata"] and not comment["community"]:
+            if "community" in comment["json_metadata"]:
                 comment["community"] = comment["json_metadata"]["community"]
 
         parse_int = [
@@ -223,6 +252,19 @@ class Comment(BlockchainObject):
         )
 
     def json(self):
+        """
+        Return a JSON-serializable dict representation of the Comment.
+
+        Removes internal-only keys (e.g., "authorperm", "tags"), ensures json-compatible types, and normalizes several fields so the result can be safely serialized to JSON and consumed by external callers or APIs. Normalizations performed:
+        - Serializes `json_metadata` to a compact JSON string.
+        - Converts datetime/date values in fields like "created", "updated", "last_payout", "cashout_time", "active", and "max_cashout_time" to formatted time strings.
+        - Converts Amount instances in HBD-related fields (e.g., "total_payout_value", "pending_payout_value", "curator_payout_value", "promoted", etc.) to their JSON representation via Amount.json().
+        - Converts selected integer fields ("author_reputation", "net_rshares") and vote numeric fields ("rshares", "reputation") to strings to preserve precision across transports.
+        - Normalizes times and numeric fields inside each entry of "active_votes".
+
+        Returns:
+            dict: A JSON-safe copy of the comment data suitable for json.dumps or returning from an API.
+        """
         output = self.copy()
         if "authorperm" in output:
             output.pop("authorperm")
@@ -246,7 +288,7 @@ class Comment(BlockchainObject):
                     output[p] = formatTimeString(p_date)
                 else:
                     output[p] = p_date
-        sbd_amounts = [
+        hbd_amounts = [
             "total_payout_value",
             "max_accepted_payout",
             "pending_payout_value",
@@ -254,7 +296,7 @@ class Comment(BlockchainObject):
             "total_pending_payout_value",
             "promoted",
         ]
-        for p in sbd_amounts:
+        for p in hbd_amounts:
             if p in output and isinstance(output[p], Amount):
                 output[p] = output[p].json()
         parse_int = [
@@ -377,7 +419,16 @@ class Comment(BlockchainObject):
 
     @property
     def reward(self):
-        """Return the estimated total SBD reward."""
+        """
+        Return the post's total estimated reward as an Amount.
+
+        This is the sum of `total_payout_value`, `curator_payout_value`, and `pending_payout_value`
+        (from the comment data). Each component is converted to an Amount using the comment's
+        blockchain-backed token symbol before summing.
+
+        Returns:
+            Amount: Total estimated reward (in the blockchain's backed token, e.g., HBD).
+        """
         a_zero = Amount(0, self.blockchain.backed_token_symbol, blockchain_instance=self.blockchain)
         author = Amount(self.get("total_payout_value", a_zero), blockchain_instance=self.blockchain)
         curator = Amount(
@@ -398,52 +449,74 @@ class Comment(BlockchainObject):
         return post_age_days < 7.0 and float(total) == 0
 
     def time_elapsed(self):
-        """Returns a timedelta on how old the post is."""
+        """
+        Return the time elapsed since the post was created as a timedelta.
+
+        The difference is computed as now (UTC) minus the post's `created` timestamp (a timezone-aware datetime).
+        A positive timedelta indicates the post is in the past; a negative value can occur if `created` is in the future.
+        """
         return datetime.now(timezone.utc) - self["created"]
 
-    def curation_penalty_compensation_SBD(self):
-        """Returns The required post payout amount after 15 minutes
-        which will compentsate the curation penalty, if voting earlier than 15 minutes
+    def curation_penalty_compensation_hbd(self):
+        """
+        Calculate the HBD payout a post would need (after 15 minutes) to fully compensate the curation penalty for voting earlier than 15 minutes.
+
+        This refreshes the comment data, selects the reverse-auction window based on the blockchain hardfork (HF6/HF20/HF21), and computes the required payout using the post's current reward and age.
+
+        Returns:
+            Amount: Estimated HBD payout required to offset the early-vote curation penalty.
         """
         self.refresh()
-        if self.blockchain.hardfork >= 21:
-            reverse_auction_window_seconds = STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF21
-        elif self.blockchain.hardfork >= 20:
-            reverse_auction_window_seconds = STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF20
+        if self.blockchain.hardfork() >= 21:
+            reverse_auction_window_seconds = HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF21
+        elif self.blockchain.hardfork() >= 20:
+            reverse_auction_window_seconds = HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF20
         else:
-            reverse_auction_window_seconds = STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF6
-        return (
-            self.reward
-            * reverse_auction_window_seconds
-            / ((self.time_elapsed()).total_seconds() / 60) ** 2
-        )
+            reverse_auction_window_seconds = HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF6
+        elapsed_minutes = max((self.time_elapsed()).total_seconds() / 60, 1e-6)
+        return self.reward * reverse_auction_window_seconds / (elapsed_minutes**2)
+
+    def estimate_curation_hbd(self, vote_value_hbd, estimated_value_hbd=None):
+        """
+        Estimate the curation reward (in HBD) for a given vote on this post.
+
+        Refreshes the post data from the chain before computing. If `estimated_value_hbd` is not provided, the current post reward is used as the estimated total post value. The returned value is an estimate of the curator's HBD payout for a vote of size `vote_value_hbd`, accounting for the current curation penalty.
 
-    def estimate_curation_SBD(self, vote_value_SBD, estimated_value_SBD=None):
-        """Estimates curation reward
+        Parameters:
+            vote_value_hbd (float): Vote value in HBD used to compute the curation share.
+            estimated_value_hbd (float, optional): Estimated total post value in HBD to scale the curation; defaults to the post's current reward.
 
-        :param float vote_value_SBD: The vote value in SBD for which the curation
-            should be calculated
-        :param float estimated_value_SBD: When set, this value is used for calculate
-            the curation. When not set, the current post value is used.
+        Returns:
+            float: Estimated curation reward in HBD for the provided vote value.
         """
         self.refresh()
-        if estimated_value_SBD is None:
-            estimated_value_SBD = float(self.reward)
+        if estimated_value_hbd is None:
+            estimated_value_hbd = float(self.reward)
         t = 1.0 - self.get_curation_penalty()
-        k = vote_value_SBD / (vote_value_SBD + float(self.reward))
+        k = vote_value_hbd / (vote_value_hbd + float(self.reward))
         K = (1 - math.sqrt(1 - k)) / 4 / k
-        return K * vote_value_SBD * t * math.sqrt(estimated_value_SBD)
+        return K * vote_value_hbd * t * math.sqrt(estimated_value_hbd)
 
     def get_curation_penalty(self, vote_time=None):
-        """If post is less than 5 minutes old, it will incur a curation
-        reward penalty.
+        """
+        Return the curation penalty factor for a vote at a given time.
+
+        Calculates a value in [0.0, 1.0] representing the fraction of curation rewards
+        that will be removed due to early voting (0.0 = no penalty, 1.0 = full penalty).
+        The penalty is based on the elapsed time between the post's creation and
+        the vote time, scaled by the Hive reverse-auction window for the node's
+        current hardfork (HF21, HF20, or HF6).
+
+        Parameters:
+            vote_time (datetime | date | str | None): Time of the vote. If None,
+                the current time is used. If a string is given it will be parsed
+                with the module's time formatter.
 
-        :param datetime vote_time: A vote time can be given and the curation
-            penalty is calculated regarding the given time (default is None)
-            When set to None, the current date is used.
-        :returns: Float number between 0 and 1 (0.0 -> no penalty, 1.0 -> 100 % curation penalty)
-        :rtype: float
+        Returns:
+            float: Penalty fraction in the range [0.0, 1.0].
 
+        Raises:
+            ValueError: If vote_time is not None and not a datetime, date, or parseable string.
         """
         if vote_time is None:
             elapsed_seconds = self.time_elapsed().total_seconds()
@@ -453,25 +526,33 @@ class Comment(BlockchainObject):
             elapsed_seconds = (vote_time - self["created"]).total_seconds()
         else:
             raise ValueError("vote_time must be a string or a datetime")
-        if self.blockchain.hardfork >= 21:
-            reward = elapsed_seconds / STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF21
-        elif self.blockchain.hardfork >= 20:
-            reward = elapsed_seconds / STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF20
+        if self.blockchain.hardfork() >= 21:
+            reward = elapsed_seconds / HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF21
+        elif self.blockchain.hardfork() >= 20:
+            reward = elapsed_seconds / HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF20
         else:
-            reward = elapsed_seconds / STEEM_REVERSE_AUCTION_WINDOW_SECONDS_HF6
+            reward = elapsed_seconds / HIVE_REVERSE_AUCTION_WINDOW_SECONDS_HF6
         if reward > 1:
             reward = 1.0
         return 1.0 - reward
 
     def get_vote_with_curation(self, voter=None, raw_data=False, pending_payout_value=None):
-        """Returns vote for voter. Returns None, if the voter cannot be found in `active_votes`.
+        """
+        Return the specified voter's vote for this comment, optionally augmented with curation data.
+
+        If `voter` is not found in the comment's votes returns None. When a vote is found:
+        - If `raw_data` is True or the post is not pending payout, returns the raw vote dict.
+        - If the post is pending and `raw_data` is False, returns the vote dict augmented with:
+          - `curation_reward`: the vote's curation reward (in HBD)
+          - `ROI`: percent return on the voter's effective voting value
 
-        :param str voter: Voter for which the vote should be returned
-        :param bool raw_data: If True, the raw data are returned
-        :param pending_payout_SBD: When not None this value instead of the current
-            value is used for calculating the rewards
-        :type pending_payout_SBD: float, str
+        Parameters:
+            voter (str or Account, optional): Voter name or Account. If omitted, defaults to the post author as an Account.
+            raw_data (bool, optional): If True, return the found vote without adding curation/ROI fields.
+            pending_payout_value (float or str, optional): If provided, use this HBD value instead of the current pending payout when computing curation rewards.
 
+        Returns:
+            dict or None: The vote dictionary (possibly augmented with `curation_reward` and `ROI`) or None if the voter has not voted.
         """
         specific_vote = None
         if voter is None:
@@ -491,12 +572,16 @@ class Comment(BlockchainObject):
             return specific_vote
         elif specific_vote is not None:
             curation_reward = self.get_curation_rewards(
-                pending_payout_SBD=True, pending_payout_value=pending_payout_value
+                pending_payout_hbd=True, pending_payout_value=pending_payout_value
             )
             specific_vote["curation_reward"] = curation_reward["active_votes"][voter["name"]]
             specific_vote["ROI"] = (
                 float(curation_reward["active_votes"][voter["name"]])
-                / float(voter.get_voting_value_SBD(voting_weight=specific_vote["percent"] / 100))
+                / float(
+                    voter.get_voting_value(
+                        voting_power=None, voting_weight=specific_vote["percent"] / 100
+                    )
+                )
                 * 100
             )
             return specific_vote
@@ -504,32 +589,35 @@ class Comment(BlockchainObject):
             return None
 
     def get_beneficiaries_pct(self):
-        """Returns the sum of all post beneficiaries in percentage"""
+        """
+        Return the sum of beneficiary weights as a fraction of the full payout.
+
+        If the post has a `beneficiaries` list of dicts with integer `weight` fields (0–10000 representing 0%–100%), this returns the total weight divided by 100.0 (i.e., a float in 0.0–100.0/100 range; typical values are 0.0–1.0).
+        """
         beneficiaries = self["beneficiaries"]
         weight = 0
         for b in beneficiaries:
             weight += b["weight"]
-        return weight / 100.0
+        return weight / HIVE_100_PERCENT
 
     def get_rewards(self):
-        """Returns the total_payout, author_payout and the curator payout in SBD.
-        When the payout is still pending, the estimated payout is given out.
+        """
+        Return the post's total, author, and curator payouts as Amount objects (HBD).
 
-        .. note:: Potential beneficiary rewards were already deducted from the
-                  `author_payout` and the `total_payout`
+        If the post is pending, returns an estimated total based on pending_payout_value and derives the author's share via get_author_rewards(); curator_payout is computed as the difference. For finalized posts, uses total_payout_value and curator_payout_value.
 
-        Example:::
+        Note: beneficiary rewards (if any) are already deducted from the returned author_payout and total_payout.
 
-            {
-                'total_payout': 9.956 SBD,
-                'author_payout': 7.166 SBD,
-                'curator_payout': 2.790 SBD
+        Returns:
+            dict: {
+                "total_payout": Amount,
+                "author_payout": Amount,
+                "curator_payout": Amount,
             }
-
         """
         if self.is_pending():
             total_payout = Amount(self["pending_payout_value"], blockchain_instance=self.blockchain)
-            author_payout = self.get_author_rewards()["total_payout_SBD"]
+            author_payout = self.get_author_rewards()["total_payout_HBD"]
             curator_payout = total_payout - author_payout
         else:
             author_payout = Amount(self["total_payout_value"], blockchain_instance=self.blockchain)
@@ -544,30 +632,38 @@ class Comment(BlockchainObject):
         }
 
     def get_author_rewards(self):
-        """Returns the author rewards.
-
+        """
+        Return the computed author-side rewards for this post.
 
+        If the post payout is not pending, returns zero HP/HBD payouts and the concrete total payout as `total_payout_HBD`. If the payout is pending, computes the author’s share after curation and beneficiaries, and—when price history and percent_hbd are available—splits that share into HBD and HP equivalents.
 
-        Example::
+        Returns:
+            dict: A dictionary with the following keys:
+                - pending_rewards (bool): True when the post payout is still pending.
+                - payout_HP (Amount or None): Estimated Hive Power payout (Amount) when pending and convertible; otherwise 0 Amount (when not pending) or None.
+                - payout_HBD (Amount or None): Estimated HBD payout (Amount) when pending and convertible; otherwise 0 Amount (when not pending) or None.
+                - total_payout_HBD (Amount): Total author-side payout expressed in HBD-equivalent units when pending, or the concrete total payout when not pending.
+                - total_payout (Amount, optional): Present only for pending payouts in the non-convertible branch; the author-side token amount before HBD/HP splitting.
+                - Note: When price/percent data is not available, `payout_HP` and `payout_HBD` will be None and only `total_payout_HBD`/`total_payout` convey the author share.
 
+        Example:
             {
-                'pending_rewards': True,
-                'payout_SP': 0.912 STEEM,
-                'payout_SBD': 3.583 SBD,
-                'total_payout_SBD': 7.166 SBD
+                "pending_rewards": True,
+                "payout_HP": Amount(...),         # HP equivalent (when convertible)
+                "payout_HBD": Amount(...),        # HBD portion (when convertible)
+                "total_payout_HBD": Amount(...)   # Total author share in HBD-equivalent
             }
-
         """
         if not self.is_pending():
             return {
                 "pending_rewards": False,
-                "payout_SP": Amount(
+                "payout_HP": Amount(
                     0, self.blockchain.token_symbol, blockchain_instance=self.blockchain
                 ),
-                "payout_SBD": Amount(
+                "payout_HBD": Amount(
                     0, self.blockchain.backed_token_symbol, blockchain_instance=self.blockchain
                 ),
-                "total_payout_SBD": Amount(
+                "total_payout_HBD": Amount(
                     self["total_payout_value"], blockchain_instance=self.blockchain
                 ),
             }
@@ -579,70 +675,52 @@ class Comment(BlockchainObject):
         curation_tokens = self.reward * author_reward_factor
         author_tokens = self.reward - curation_tokens
         curation_rewards = self.get_curation_rewards()
-        if self.blockchain.hardfork >= 20 and median_hist is not None:
+        if self.blockchain.hardfork() >= 20 and median_hist is not None:
             author_tokens += median_price * curation_rewards["unclaimed_rewards"]
-
-        benefactor_tokens = author_tokens * beneficiaries_pct / 100.0
+        benefactor_tokens = author_tokens * beneficiaries_pct / HIVE_100_PERCENT
         author_tokens -= benefactor_tokens
 
-        if median_hist is not None and "percent_steem_dollars" in self:
-            sbd_steem = author_tokens * self["percent_steem_dollars"] / 20000.0
-            vesting_steem = median_price.as_base(self.blockchain.token_symbol) * (
-                author_tokens - sbd_steem
+        if median_hist is not None and "percent_hbd" in self:
+            hbd_payout = author_tokens * self["percent_hbd"] / 20000.0
+            hp_payout = median_price.as_base(self.blockchain.token_symbol) * (
+                author_tokens - hbd_payout
             )
             return {
                 "pending_rewards": True,
-                "payout_SP": vesting_steem,
-                "payout_SBD": sbd_steem,
-                "total_payout_SBD": author_tokens,
-            }
-        elif median_hist is not None and "percent_hbd" in self:
-            sbd_steem = author_tokens * self["percent_hbd"] / 20000.0
-            vesting_steem = median_price.as_base(self.blockchain.token_symbol) * (
-                author_tokens - sbd_steem
-            )
-            return {
-                "pending_rewards": True,
-                "payout_SP": vesting_steem,
-                "payout_SBD": sbd_steem,
-                "total_payout_SBD": author_tokens,
+                "payout_HP": hp_payout,
+                "payout_HBD": hbd_payout,
+                "total_payout_HBD": author_tokens,
             }
         else:
             return {
                 "pending_rewards": True,
                 "total_payout": author_tokens,
-                "payout_SBD": None,
-                "total_payout_SBD": None,
+                # HBD/HP primary fields
+                "total_payout_HBD": author_tokens,
+                "payout_HBD": None,
+                "payout_HP": None,
             }
 
-    def get_curation_rewards(self, pending_payout_SBD=False, pending_payout_value=None):
-        """Returns the curation rewards. The split between creator/curator is currently 50%/50%.
-
-        :param bool pending_payout_SBD: If True, the rewards are returned in SBD and not in STEEM (default is False)
-        :param pending_payout_value: When not None this value instead of the current
-            value is used for calculating the rewards
-        :type pending_payout_value: float, str
-
-        `pending_rewards` is True when
-        the post is younger than 7 days. `unclaimed_rewards` is the
-        amount of curation_rewards that goes to the author (self-vote or votes within
-        the first 30 minutes). `active_votes` contains all voter with their curation reward.
-
-        Example::
-
-            {
-                'pending_rewards': True, 'unclaimed_rewards': 0.245 STEEM,
-                'active_votes': {
-                    'leprechaun': 0.006 STEEM, 'timcliff': 0.186 STEEM,
-                    'st3llar': 0.000 STEEM, 'crokkon': 0.015 STEEM, 'feedyourminnows': 0.003 STEEM,
-                    'isnochys': 0.003 STEEM, 'loshcat': 0.001 STEEM, 'greenorange': 0.000 STEEM,
-                    'qustodian': 0.123 STEEM, 'jpphotography': 0.002 STEEM, 'thinkingmind': 0.001 STEEM,
-                    'oups': 0.006 STEEM, 'mattockfs': 0.001 STEEM, 'thecrazygm': 0.003 STEEM, 'michaelizer': 0.004 STEEM,
-                    'flugschwein': 0.010 STEEM, 'ulisessabeque': 0.000 STEEM, 'hakancelik': 0.002 STEEM, 'sbi2': 0.008 STEEM,
-                    'zcool': 0.000 STEEM, 'steemhq': 0.002 STEEM, 'rowdiya': 0.000 STEEM, 'qurator-tier-1-2': 0.012 STEEM
-                }
+    def get_curation_rewards(self, pending_payout_hbd=False, pending_payout_value=None):
+        """
+        Calculate curation rewards for this post and distribute them across active voters.
+
+        Parameters:
+            pending_payout_hbd (bool): If True, compute and return rewards in HBD (do not convert to HIVE/HP). Default False.
+            pending_payout_value (float | str | Amount | None): Optional override for the post's pending payout value used when the post is still pending.
+                - If None and the post is pending, the function uses the post's stored pending_payout_value.
+                - Accepted types: numeric, string amount, or an Amount instance.
+
+        Returns:
+            dict: {
+                "pending_rewards": bool,        # True if the post is still within the payout window (uses pending_payout_value)
+                "unclaimed_rewards": Amount,    # Amount reserved for unclaimed curation (e.g., self-votes or early votes)
+                "active_votes": dict            # Mapping voter_name -> Amount of curation reward allocated to that voter
             }
 
+        Notes:
+            - The function splits the curation pool using the protocol's curator share (50% by default) and prorates per-voter claims by vote weight.
+            - When a current median price history is available, rewards may be converted between HBD and the chain's token (HP) according to pending_payout_hbd.
         """
         median_hist = self.blockchain.get_current_median_history()
         if median_hist is not None:
@@ -666,7 +744,7 @@ class Comment(BlockchainObject):
             total_vote_weight += vote["weight"]
 
         if not self.is_pending():
-            if pending_payout_SBD or median_hist is None:
+            if pending_payout_hbd or median_hist is None:
                 max_rewards = Amount(
                     self["curator_payout_value"], blockchain_instance=self.blockchain
                 )
@@ -694,7 +772,7 @@ class Comment(BlockchainObject):
                 pending_payout_value = Amount(
                     pending_payout_value, blockchain_instance=self.blockchain
                 )
-            if pending_payout_SBD or median_hist is None:
+            if pending_payout_hbd or median_hist is None:
                 max_rewards = pending_payout_value * curator_reward_factor
             else:
                 max_rewards = median_price.as_base(self.blockchain.token_symbol) * (
@@ -921,19 +999,22 @@ class Comment(BlockchainObject):
         )
 
     def delete(self, account=None, identifier=None):
-        """Delete an existing post/comment
+        """
+        Delete this post or comment from the blockchain.
+
+        If `identifier` is provided it must be an author/permlink string (e.g. "@author/permlink"); otherwise the current Comment's author and permlink are used. If `account` is not provided the method will use `blockchain.config["default_account"]` when present; otherwise a ValueError is raised.
 
-        :param str account: (optional) Account to use for deletion. If
-            ``account`` is not defined, the ``default_account`` will be
-            taken or a ValueError will be raised.
+        Note: a post/comment can only be deleted if it has no replies and no positive rshares.
 
-        :param str identifier: (optional) Identifier for the post to delete.
-            Takes the form ``@author/permlink``. By default the current post
-            will be used.
+        Parameters:
+            account (str, optional): Account name to perform the deletion. If omitted, the configured default_account is used.
+            identifier (str, optional): Author/permlink of the post to delete (format "@author/permlink"). Defaults to the current Comment.
 
-        .. note:: A post/comment can only be deleted as long as it has no
-                  replies and no positive rshares on it.
+        Returns:
+            dict: Result of the blockchain finalizeOp / transaction broadcast.
 
+        Raises:
+            ValueError: If no account is provided and no default_account is configured.
         """
         if not account:
             if "default_account" in self.blockchain.config:
@@ -949,13 +1030,19 @@ class Comment(BlockchainObject):
         op = operations.Delete_comment(**{"author": post_author, "permlink": post_permlink})
         return self.blockchain.finalizeOp(op, account, "posting")
 
-    def resteem(self, identifier=None, account=None):
-        """Resteem a post
+    def reblog(self, identifier=None, account=None):
+        """
+        Create a reblog (resteem) for the specified post.
+
+        Parameters:
+            identifier (str, optional): Post identifier in the form "@author/permlink". If omitted, uses this Comment's identifier.
+            account (str, optional): Name of the posting account to perform the reblog. If omitted, the configured `default_account` is used.
 
-        :param str identifier: post identifier (@<account>/<permlink>)
-        :param str account: (optional) the account to allow access
-            to (defaults to ``default_account``)
+        Returns:
+            dict: Result from the blockchain custom_json operation.
 
+        Raises:
+            ValueError: If no account is provided and no `default_account` is configured.
         """
         if not account:
             account = self.blockchain.configStorage.get("default_account")
@@ -977,7 +1064,7 @@ class RecentReplies(list):
     :param str author: author
     :param bool skip_own: (optional) Skip replies of the author to him/herself.
         Default: True
-    :param Steem blockchain_instance: Steem() instance to use when accesing a RPC
+    :param Blockchain blockchain_instance: Blockchain instance to use when accessing the RPC
     """
 
     def __init__(
@@ -989,13 +1076,24 @@ class RecentReplies(list):
         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"]
+        """
+        Create a list of recent replies to a given account.
+
+        Initializes the instance as a list of Comment objects built from the account's recent "replies" feed. By default replies authored by the same account are omitted when skip_own is True. If no blockchain connection is available during construction, initialization is aborted (the constructor returns early).
+
+        Parameters:
+            author (str): Account name whose replies to collect.
+            skip_own (bool): If True, omit replies authored by `author`. Default True.
+            start_permlink (str): Legacy/paging parameter; currently ignored by this implementation.
+            limit (int): Maximum number of replies to collect; currently ignored (the underlying API call controls results).
+            lazy (bool): If True, create Comment objects in lazy mode.
+            full (bool): If True, create Comment objects with full data populated.
+
+        Notes:
+            - The blockchain_instance parameter is used to resolve RPC access and is intentionally undocumented here as a shared service.
+            - The underlying account.get_account_posts(sort="replies", raw_data=True) call provides the source data; when it returns None or the instance is not connected, construction exits early.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         if not self.blockchain.is_connected():
             return None
@@ -1020,7 +1118,7 @@ class RecentByPath(list):
     :param str path: path
     :param str tag: tag
     :param str observer: observer
-    :param Steem blockchain_instance: Steem() instance to use when accesing a RPC
+    :param Blockchain blockchain_instance: Blockchain instance to use when accessing the RPC
     """
 
     def __init__(
@@ -1032,13 +1130,18 @@ class RecentByPath(list):
         full=True,
         limit=20,
         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"]
+        """
+        Create a RecentByPath list by fetching ranked posts for a given path/tag and initializing the list with those posts.
+
+        Parameters:
+            path (str): Ranking category to fetch (e.g., "trending", "hot").
+            tag (str): Optional tag to filter posts.
+            observer (str): Observer account used for context-aware fetches (affects reward/curation visibility).
+            lazy (bool): If True, create Comment objects lazily (defer full data loading).
+            full (bool): If True, initialize Comment objects with full data when available.
+            limit (int): Maximum number of posts to fetch.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
 
         # Create RankedPosts with proper parameters
@@ -1050,7 +1153,6 @@ class RecentByPath(list):
             lazy=lazy,
             full=full,
             blockchain_instance=self.blockchain,
-            **kwargs,
         )
 
         super(RecentByPath, self).__init__(ranked_posts)
@@ -1065,7 +1167,7 @@ class RankedPosts(list):
     :param int limit: limits the number of returns comments
     :param str start_author: start author
     :param str start_permlink: start permlink
-    :param Steem blockchain_instance: Steem() instance to use when accesing a RPC
+    :param Blockchain blockchain_instance: Blockchain instance to use when accessing the RPC
     """
 
     def __init__(
@@ -1080,13 +1182,29 @@ class RankedPosts(list):
         full=True,
         raw_data=False,
         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 RankedPosts list by fetching paginated ranked posts from the blockchain.
+
+        Fetches up to `limit` posts for the given `sort` and `tag` using the bridge `get_ranked_posts`
+        RPC, paging with `start_author` / `start_permlink`. Results are appended to the list as raw
+        post dicts when `raw_data` is True, or as Comment objects otherwise. The constructor:
+        - uses `blockchain_instance` (or the shared instance) and returns early (None) if not connected;
+        - pages through results with an API page size up to 100, updating `start_author`/`start_permlink`;
+        - avoids repeating the last item returned by the API; and
+        - on an RPC error, returns partial results if any posts were already collected, otherwise re-raises.
+
+        Parameters:
+            sort (str): Ranking to query (e.g., "trending", "hot", "created").
+            tag (str): Optional tag/category to filter by.
+            observer (str): Optional observer account used by the bridge API (affects personalized results).
+            limit (int): Maximum number of posts to return.
+            start_author (str): Author to start paging from (inclusive/exclusive depends on the API).
+            start_permlink (str): Permlink to start paging from.
+            lazy (bool): If False, wrap results in Comment objects fully; if True, create Comment objects in lazy mode.
+            full (bool): If True, request full Comment initialization when wrapping results.
+            raw_data (bool): If True, return raw post dictionaries instead of Comment objects.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         if not self.blockchain.is_connected():
             return None
@@ -1151,7 +1269,7 @@ class AccountPosts(list):
     :param int limit: limits the number of returns comments
     :param str start_author: start author
     :param str start_permlink: start permlink
-    :param Hive blockchain_instance: Hive() instance to use when accesing a RPC
+    :param Blockchain blockchain_instance: Blockchain instance to use when accessing the RPC
     """
 
     def __init__(
@@ -1166,13 +1284,30 @@ class AccountPosts(list):
         full=True,
         raw_data=False,
         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 an AccountPosts list by fetching posts for a given account (paginated).
+
+        This constructor populates the list with posts returned by the bridge.get_account_posts RPC call,
+        respecting paging (start_author/start_permlink) and the requested limit. Each item is either the
+        raw post dict (when raw_data=True) or a Comment object constructed with the same blockchain instance.
+
+        Parameters:
+            sort (str): The post list type to fetch (e.g., "blog", "comments", "replies", "feed").
+            account (str): Account name whose posts are requested.
+            observer (str): Optional observer account name used by the API (affects visibility/context).
+            limit (int): Maximum number of posts to collect.
+            start_author (str): Author to start paging from (inclusive/exclusive depends on API).
+            start_permlink (str): Permlink to start paging from.
+            lazy (bool): If False, Comment objects are fully loaded; if True, they are initialized lazily.
+            full (bool): If True, Comment objects include full data; otherwise minimal fields.
+            raw_data (bool): If True, return raw post dicts instead of Comment objects.
+
+        Behavior notes:
+            - If the blockchain instance is not connected, initialization returns early (no posts are fetched).
+            - On an RPC error, if some posts have already been collected, the constructor returns those partial results;
+              if no posts were collected, the exception is propagated.
+        """
         self.blockchain = blockchain_instance or shared_blockchain_instance()
         if not self.blockchain.is_connected():
             return None