nectar.comment module

class nectar.comment.AccountPosts(sort, account, observer='', limit=20, start_author='', start_permlink='', lazy=False, full=True, raw_data=False, blockchain_instance=None)

Bases: list

Obtain a list of account related posts

Parameters:

  • sort (str) – can be: comments, posts, blog, replies, feed

  • account (str) – Account name

  • observer (str) – Observer name

  • limit (int) – limits the number of returns comments

  • start_author (str) – start author

  • start_permlink (str) – start permlink

  • blockchain_instance (Blockchain) – Blockchain instance to use when accessing the RPC

class nectar.comment.Comment(authorperm: str | Dict[str, Any], api: str = 'bridge', observer: str = '', full: bool = True, lazy: bool = False, blockchain_instance: Any | None = None)

Bases: BlockchainObject

Read data about a Comment/Post in the chain

Parameters:

  • authorperm (str) – identifier to post/comment in the form of @author/permlink

  • tags (str) – defines which api is used. Can be bridge, tags, condenser or database (default = bridge)

  • blockchain_instance (Blockchain) – Blockchain instance to use when accessing the RPC



>>> from nectar.comment import Comment
>>> from nectar.account import Account
>>> # Create a Hive blockchain instance
>>> from nectar import Hive
>>> hv = Hive()
>>> acc = Account("gtg", blockchain_instance=hv)
>>> authorperm = acc.get_blog(limit=1)[0]["authorperm"]
>>> c = Comment(authorperm)
>>> postdate = c["created"]
>>> postdate_str = c.json()["created"]
property author: str
property authorperm: str
property body
property category: str
property community
property community_title

The Community title property.

curation_penalty_compensation_hbd()

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.

delete(account=None, identifier=None)

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.

Note: a post/comment can only be deleted if it has no replies and no positive rshares.

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.

Returns:

dict: Result of the blockchain finalizeOp / transaction broadcast.

Raises:

ValueError: If no account is provided and no default_account is configured.

property depth
downvote(weight: float = 100.0, voter: str | Account | None = None) → Dict[str, Any]

Downvote the post

Parameters:

  • weight (float) – (optional) Weight for posting (-100.0 - +100.0) defaults to -100.0

  • voter (str) – (optional) Voting account

edit(body, meta=None, replace=False)

Edit an existing post

Parameters:

  • body (str) – Body of the reply

  • meta (json) – JSON meta object that can be attached to the post. (optional)

  • replace (bool) – Instead of calculating a diff, replace the post entirely (defaults to False)

estimate_curation_hbd(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.

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.

Returns:

float: Estimated curation reward in HBD for the provided vote value.

get_all_replies(parent=None)

Returns all content replies

get_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.

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_HP”: Amount(…), # HP equivalent (when convertible) “payout_HBD”: Amount(…), # HBD portion (when convertible) “total_payout_HBD”: Amount(…) # Total author share in HBD-equivalent

}

get_beneficiaries_pct()

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).

get_curation_penalty(vote_time=None)

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.

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.

get_curation_rewards(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.

get_parent(children=None)

Returns the parent post with depth == 0

get_reblogged_by(identifier=None)

Shows in which blogs this post appears

get_replies(raw_data=False, identifier=None)

Returns content replies

Parameters:

raw_data (bool) – When set to False, the replies will be returned as Comment class objects

get_rewards()

Return the post’s total, author, and curator payouts as Amount objects (HBD).

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.

Note: beneficiary rewards (if any) are already deducted from the returned author_payout and total_payout.

Returns:
dict: {

“total_payout”: Amount, “author_payout”: Amount, “curator_payout”: Amount,

}

get_vote_with_curation(voter=None, raw_data=False, pending_payout_value=None)

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

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.

get_votes(raw_data=False)

Returns all votes as ActiveVotes object

property id: int
is_archived()

Determine whether the post is archived (cashout window passed).

is_comment()

Returns True if post is a comment

is_main_post()

Returns True if main post, and False if this is a comment (reply).

is_pending()

Returns if the payout is pending (the post/comment is younger than 7 days)

json() → Dict[str, Any]

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.

property json_metadata
property parent_author
reblog(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.

Returns:

dict: Result from the blockchain custom_json operation.

Raises:

ValueError: If no account is provided and no default_account is configured.

refresh() → None

Refresh the object’s data from the API.

This method should be overridden by subclasses to implement specific refresh logic. The base implementation does nothing.

reply(body, title='', author='', meta=None)

Reply to an existing post

Parameters:

  • body (str) – Body of the reply

  • title (str) – Title of the reply post

  • author (str) – Author of reply (optional) if not provided default_user will be used, if present, else a ValueError will be raised.

  • meta (json) – JSON meta object that can be attached to the post. (optional)

property 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).

time_elapsed()

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.

property title
to_token_value(account: str | Account, hbd: bool = False, partial: float = 100.0, nobroadcast: bool = False) → float

Compute the UI upvote percent needed for account so the vote contributes approximately hbd HBD to payout (payout-based math).

  • Returns a positive UI percent (e.g., 75.0 means 75% upvote).

  • Automatically casts the upvote (use the blockchain instance’s no_broadcast flag to suppress broadcasting when needed).

to_zero(account: str | Account, partial: float = 100.0, nobroadcast: bool = False) → float

Compute the UI downvote percent needed for account to reduce this post’s pending payout to approximately zero using payout-based math (reward fund + median price + effective vests) scaled by the account’s current downvoting power.

  • Returns a negative UI percent (e.g., -75.0 means a 75% downvote).

  • Automatically casts the downvote (use the blockchain instance’s no_broadcast flag to suppress broadcasting when needed).

If the account’s current 100% downvote value is insufficient, returns -100.0. If the post has no pending payout, returns 0.0.

type_id = 8
upvote(weight: float = 100.0, voter: str | Account | None = None) → Dict[str, Any]

Upvote the post

Parameters:

  • weight (float) – (optional) Weight for posting (-100.0 - +100.0) defaults to +100.0

  • voter (str) – (optional) Voting account

vote(weight: float, account: str | Account | None = None, identifier: str | None = None, **kwargs: Any) → Dict[str, Any]

Vote for a post

Parameters:

  • weight (float) – Voting weight. Range: -100.0 - +100.0.

  • account (str) – (optional) Account to use for voting. If account is not defined, the default_account will be used or a ValueError will be raised

  • identifier (str) – Identifier for the post to vote. Takes the form @author/permlink.

class nectar.comment.RankedPosts(sort, tag='', observer='', limit=21, start_author='', start_permlink='', lazy=False, full=True, raw_data=False, blockchain_instance=None)

Bases: list

Obtain a list of ranked posts

Parameters:

  • sort (str) – can be: trending, hot, created, promoted, payout, payout_comments, muted

  • tag (str) – tag, when used my, the community posts of the observer are shown

  • observer (str) – Observer name

  • limit (int) – limits the number of returns comments

  • start_author (str) – start author

  • start_permlink (str) – start permlink

  • blockchain_instance (Blockchain) – Blockchain instance to use when accessing the RPC

class nectar.comment.RecentByPath(path='trending', tag='', observer='', lazy=False, full=True, limit=20, blockchain_instance=None)

Bases: list

Obtain a list of posts recent by path, does the same as RankedPosts

Parameters:

  • path (str) – path

  • tag (str) – tag

  • observer (str) – observer

  • blockchain_instance (Blockchain) – Blockchain instance to use when accessing the RPC

class nectar.comment.RecentReplies(author, skip_own=True, start_permlink='', limit=100, lazy=False, full=True, blockchain_instance=None)

Bases: list

Obtain a list of recent replies

Parameters:

  • author (str) – author

  • skip_own (bool) – (optional) Skip replies of the author to him/herself. Default: True

  • blockchain_instance (Blockchain) – Blockchain instance to use when accessing the RPC