nectar.community module

class nectar.community.Communities(sort: str = 'rank', observer: str | None = None, last: str | None = None, limit: int = 100, lazy: bool = False, full: bool = True, blockchain_instance=None)

Bases: CommunityObject

A list of communities with additional querying capabilities.

This class extends CommunityObject to provide methods for fetching and searching communities from the blockchain.

Args:

sort: Sort order for communities (default: “rank”) observer: Observer account for personalized results (optional) last: Last community name for pagination (optional) limit: Maximum number of communities to fetch (default: 100) lazy: If True, use lazy loading (default: False) full: If True, fetch full community data (default: True) blockchain_instance: Blockchain instance to use for RPC access

search_title(title: str) → CommunityObject

Search for communities with titles containing the given string.

The search is case-insensitive.

Args:

title: Text to search for in community titles

Returns:

CommunityObject: A new CommunityObject containing matching communities

class nectar.community.Community(community: str | dict, observer: str = '', full: bool = True, lazy: bool = False, blockchain_instance=None)

Bases: BlockchainObject

A class representing a Hive community with methods to interact with it.

This class provides an interface to access and manipulate community data on the Hive blockchain. It extends BlockchainObject and provides additional community-specific functionality.

Args:

community: Either a community name (str) or a dictionary containing community data observer: Observer account for personalized results (default: “”) full: If True, fetch full community data (default: True) lazy: If True, use lazy loading (default: False) blockchain_instance: Blockchain instance for RPC access

Attributes:

type_id (int): Type identifier for blockchain objects (2 for communities)

Example:

>>> from nectar.community import Community
>>> from nectar import Hive
>>> from nectar.nodelist import NodeList
>>> nodelist = NodeList()
>>> nodelist.update_nodes()
>>> hv = Hive(node=nodelist.get_hive_nodes())
>>> community = Community("hive-139531", blockchain_instance=hv)
>>> print(community)
<Community hive-139531>

Note:

This class includes caching to reduce API server load. Use refresh() to update the data and clear_cache() to clear the cache.

flag_post(account: str, permlink: str, notes: str, reporter: str) → dict

Report a post to the community moderators for review.

This method allows community members to flag posts that may violate community guidelines. The post will be added to the community’s review queue for moderators to evaluate.

Args:

account: Author of the post being reported permlink: Permlink of the post being reported notes: Explanation of why the post is being reported reporter: Account name of the user reporting the post

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If any required parameter is invalid

get_activities(limit: int = 100, last_id: str | None = None) → list

Returns community activity

Args:

limit: Maximum number of activities to return (default: 100) last_id: ID of the last activity from previous page for pagination

Returns:

list: List of community activities

Raises:

OfflineHasNoRPCException: If not connected to the blockchain

get_community_roles(limit: int = 100, last: str | None = None) → list

Lists community roles

Args:

limit: Maximum number of roles to return (default: 100) last: Account name of the last role from previous page for pagination

Returns:

list: List of community roles

Raises:

OfflineHasNoRPCException: If not connected to the blockchain

get_ranked_posts(observer: str | None = None, limit: int = 100, start_author: str | None = None, start_permlink: str | None = None, sort: str = 'created') → list

Returns community posts

Args:

observer: Account name of the observer (optional) limit: Maximum number of posts to return (default: 100) start_author: Author of the post to start from for pagination (optional) start_permlink: Permlink of the post to start from for pagination (optional) sort: Sort order (default: “created”)

Returns:

list: List of community posts

Raises:

OfflineHasNoRPCException: If not connected to the blockchain

get_subscribers(limit: int = 100, last: str | None = None) → list

Returns subscribers

Args:

limit: Maximum number of subscribers to return (default: 100) last: Account name of the last subscriber from previous page for pagination

Returns:

list: List of subscribers

Raises:

OfflineHasNoRPCException: If not connected to the blockchain

json() → dict

Convert the community data to a JSON-serializable dictionary.

This method prepares the community data for JSON serialization by converting non-JSON-serializable types (like datetime objects) to strings.

Returns:

dict: A dictionary containing the community data in a JSON-serializable format

mute_post(account: str, permlink: str, notes: str, mod_account: str) → dict

Mutes a post in the community.

Args:

account: Author of the post to mute permlink: Permlink of the post to mute notes: Reason for muting the post mod_account: Account name of the moderator performing this action (must be mod or higher)

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If any required parameter is invalid

pin_post(account: str, permlink: str, mod_account: str) → dict

Pin a post to the top of the community feed.

This method allows community moderators to pin a specific post to the top of the community’s feed. The post will remain pinned until it is manually unpinned.

Args:

account: Author of the post to pin permlink: Permlink of the post to pin mod_account: Account name of the moderator performing this action (must be mod or higher)

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If any required parameter is invalid

refresh() → None

Refresh the community’s data from the blockchain.

Fetches the latest community record for this community’s name via the bridge RPC and reinitializes the Community object with the returned data (updating identifier and all fields). If the instance is offline, the method returns without performing any RPC call.

Raises:

AccountDoesNotExistsException: If no community data is returned for this community name.

set_role(account: str, role: str, mod_account: str) → dict

Set role for a given account in the community.

Args:

account: Account name to set the role for role: Role to assign (member, mod, admin, owner, or guest) mod_account: Account name of the moderator performing this action (must be mod or higher)

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If role is not one of the allowed values

set_user_title(account: str, title: str, mod_account: str) → dict

Set the title for a given account in the community.

Args:

account: Account name to set the title for title: Title to assign to the account mod_account: Account name of the moderator performing this action (must be mod or higher)

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If account or title is empty

subscribe(account: str) → dict

Subscribe an account to this community.

The account that calls this method will be subscribed to the community. The same account must be used to sign the transaction.

Args:

account: Account name that wants to subscribe to the community

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If account is invalid

type_id = 2

unmute_post(account: str, permlink: str, notes: str, mod_account: str) → dict

Unmute a previously muted post in the community.

Args:

account: Author of the post to unmute permlink: Permlink of the post to unmute notes: Reason for unmuting the post mod_account: Account name of the moderator performing this action (must be mod or higher)

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If any required parameter is invalid

unpin_post(account: str, permlink: str, mod_account: str) → dict

Remove a post from being pinned at the top of the community feed.

This method allows community moderators to unpin a previously pinned post. After unpinning, the post will return to its normal position in the feed.

Args:

account: Author of the post to unpin permlink: Permlink of the post to unpin mod_account: Account name of the moderator performing this action (must be mod or higher)

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If any required parameter is invalid

unsubscribe(account: str) → dict

Unsubscribe an account from this community.

The account that calls this method will be unsubscribed from the community. The same account must be used to sign the transaction.

Args:

account: Account name that wants to unsubscribe from the community

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If account is invalid

update_props(title: str, about: str, is_nsfw: bool, description: str, flag_text: str, admin_account: str) → dict

Update community properties.

Args:

title: New title for the community (must be non-empty) about: Brief description of the community is_nsfw: Whether the community contains NSFW content description: Detailed description of the community flag_text: Text shown when flagging content in this community admin_account: Account name of the admin performing this action

Returns:

dict: Transaction result

Raises:

OfflineHasNoRPCException: If not connected to the blockchain ValueError: If any required parameter is invalid

class nectar.community.CommunityObject(iterable=(), /)

Bases: list

A list-like container for Community objects with additional utility methods.

printAsTable() → None

Print a formatted table of communities with key metrics.

The table includes the following columns: - Nr.: Sequential number - Name: Community name - Title: Community title - lang: Language code - subscribers: Number of subscribers - sum_pending: Sum of pending payouts - num_pending: Number of pending posts - num_authors: Number of unique authors