Khoros Core Object ¶

get_all_topic_messages(board_id, fields=None, descending=True)[source]¶

This function retrieves data for all topic messages (i.e. zero-depth messages) within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each topic message within the board

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError

static get_board_id(url)[source]¶

This method retrieves the Board ID for a given board when provided its URL.

New in version 2.6.0.

Parameters:: url (str) – The URL from which to parse out the Board ID
Returns:: The Board ID retrieved from the URL
Raises:: khoros.errors.exceptions.InvalidURLError

get_message_count(board_id)[source]¶

This method retrieves the total number of messages within a given board.

New in version 5.3.0.

Parameters:: board_id (str) – The ID of the board to query
Returns:: The number of messages within the node

structure_payload(board_id, board_title, discussion_style, description=None, parent_category_id=None, hidden=None, allowed_labels=None, use_freeform_labels=None, use_predefined_labels=None, predefined_labels=None, media_type=None, blog_authors=None, blog_author_ids=None, blog_author_logins=None, blog_comments_enabled=None, blog_moderators=None, blog_moderator_ids=None, blog_moderator_logins=None, one_entry_per_contest=None, one_kudo_per_contest=None, posting_date_end=None, posting_date_start=None, voting_date_end=None, voting_date_start=None, winner_announced_date=None)[source]¶

This method structures the payload to use in a Community API v2 request involving a board.

New in version 2.6.0.

Parameters:

board_id (str) – The unique identifier (i.e. id field) for the new board (Required)
board_title (str) – The title of the new board (Required)
discussion_style (str) – Defines the board as a blog, contest, forum, idea, qanda or tkb (Required)
description (str, None) – A brief description of the board
parent_category_id (str, None) – The ID of the parent category (if applicable)
hidden (bool, None) – Defines whether the new board should be hidden from lists and menus (disabled by default)
allowed_labels (str, None) – The type of labels allowed on the board (freeform-only, predefined-only or freeform and pre-defined)
use_freeform_labels (bool, None) – Determines if freeform labels should be utilized
use_predefined_labels (bool, None) – Determines if pre-defined labels should be utilized
predefined_labels (list, None) –
The pre-defined labels to utilized on the board as a list of dictionaries

Todo

The ability to provide labels as a simple list and optionally standardize their format (e.g. Pascal Case, etc.) will be available in a future release.
media_type (str, None) – The media type associated with a contest. (image, video or story i.e. text)
blog_authors (list, None) – The approved blog authors in a blog board as a list of user data dictionaries
blog_author_ids (list, None) – A list of User IDs representing the approved blog authors in a blog board
blog_author_logins (list, None) – A list of User Logins (i.e. usernames) representing approved blog authors in a blog board
blog_comments_enabled (bool, None) – Determines if comments should be enabled on blog posts within a blog board
blog_moderators (list, None) – The designated blog moderators in a blog board as a list of user data dictionaries
blog_moderator_ids (list, None) – A list of User IDs representing the blog moderators in a blog board
blog_moderator_logins (list, None) – A list of User Logins (i.e. usernames) representing blog moderators in a blog board
one_entry_per_contest (bool, None) – Defines whether a user can submit only one entry to a single contest
one_kudo_per_contest (bool, None) – Defines whether a user can vote only once per contest
posting_date_end (type[datetime.datetime], None) – The date/time when the contest is closed to submissions
posting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
voting_date_end (type[datetime.datetime], None) – The date/time when the voting period for a contest ends
voting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
winner_announced_date (type[datetime.datetime], None) – The date/time the contest winner will be announced

Returns:

The full and properly formatted payload for the API request

Raises:

class BulkData(khoros_object)[source]¶

This class includes methods for interacting with the Bulk Data API.

New in version 5.0.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Board inner class object.

New in version 5.0.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

static count_actions(bulk_data, action_key)[source]¶

This function counts the number of events for a specific action key in a collection of bulk data.

New in version 5.2.0.

Parameters:

bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)
action_key (str) – The action.key value

Returns:

The number of events as an integer

Raises:

khoros.errors.exceptions.DataMismatchError, khoros.errors.exceptions.InvalidParameterError

static count_logins(bulk_data)[source]¶

This function counts the number of login events in a collection of bulk data.

New in version 5.2.0.

Parameters:: bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)
Returns:: The number of login events as an integer
Raises:: khoros.errors.exceptions.DataMismatchError

static count_views(bulk_data)[source]¶

This function counts the number of view events in a collection of bulk data.

New in version 5.2.0.

Parameters:: bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)
Returns:: The number of view events as an integer
Raises:: khoros.errors.exceptions.DataMismatchError

static filter_anonymous(bulk_data, remove_anonymous=None, remove_registered=None)[source]¶

This method filters bulk data entries to keep only registered (default) or anonymous user activities.

New in version 5.2.0.

Parameters:

bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)
remove_anonymous (bool, None) – Determines if all anonymous user activities should be removed (Default)
remove_registered (bool, None) – Determines if all registered user activities should be removed

Returns:

The filtered JSON data as a dictionary

Raises:

static filter_by_action(action_key, bulk_data)[source]¶

This method filters a Bulk Data API export for only entries with a specific action.key value.

New in version 5.2.0.

Parameters:

action_key (str) – The action.key value
bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)

Returns:

The filtered JSON data as a dictionary

Raises:

TypeError, ValueError, khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.APIRequestError

get_base_url(community_id=None, europe=False)[source]¶

This method constructs and/or retrieves the base URL for the Bulk Data API.

New in version 5.0.0.

Note

The URL from the helper settings will be leveraged when available unless the community_id is explicitly defined as a function parameter.

Parameters:

community_id (str, None) – The Community ID to leverage in the URL
europe (bool) – Determines if the European URL should be utilized (False by default)

Returns:

The base URL for the Bulk Data API

query(community_id=None, client_id=None, token=None, from_date=None, to_date=None, fields=None, europe=None, export_type=None, full_response=False)[source]¶

This method performs a query against the Bulk Data API to retrieve CSV or JSON data.

New in version 5.0.0.

Parameters:

community_id (str, None) – The Community ID to leverage in the URL
client_id (str, None) – The Client ID used to authenticate to the Bulk Data API
token (str, None) – The access token used to authenticate to the Bulk Data API
from_date (str, None) – The From Date in YYYYmmDD or YYYYmmDDhhMM format.
to_date (str, None) – The To Date in YYYYmmDD or YYYYmmDDhhMM format.
fields (str, list, tuple, set, None) – Optional fields to include in the data export as a comma-separated string or iterable
europe (bool) – Determines if the European URL should be utilized (False by default)
export_type (str, None) – Determines if the data should be returned in csv (default) or json format
full_response (bool) – Determines if the full requests object should be returned (False by default)

Returns:

The CSV or JSON data for the Bulk Data API request (or the full requests object)

Raises:

class Category(khoros_object)[source]¶

This class includes methods for interacting with categories.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Category inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

category_exists(category_id=None, category_url=None)[source]¶

This method checks to see if a category exists.

New in version 2.7.0.

Parameters:

category_id (str, None) – The ID of the category to check
category_url (str, None) – The URL of the category to check

Returns:

Boolean value indicating whether the category already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

create(category_id, category_title, parent_id=None, return_json=True)[source]¶

This method creates a new category.

New in version 2.5.0.

Parameters:

category_id (str) – The Category ID of the new category (e.g. video-games)
category_title (str) – The title of the new category (e.g. Video Games)
parent_id (str, None) – The Category ID of the parent category (optional)
return_json (bool) – Determines whether the response should be returned in JSON format (True by default)

Returns:

The response from the API call

Raises:

ValueError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.APIConnectionError

friendly_date_enabled(identifier=None, category_details=None)[source]¶

This method identifies if friendly dates are enabled for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean indicating if friendly dates are enabled

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_active_skin(identifier=None, category_details=None)[source]¶

This method retrieves the skin being used with a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The name of the active skin in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_category_details(identifier, first_item=True)[source]¶

This method returns a dictionary of community configuration settings.

New in version 2.1.0.

Parameters:

identifier (str) – The Category ID or Category URL with which to identify the category
first_item (bool) – Filters the response data to the first item returned (True by default)

Returns:

The community details within a dictionary

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_category_field(field, identifier=None, category_details=None)[source]¶

This method returns a specific community field from the Khoros Community API.

New in version 2.1.0.

Parameters:

field (str) – The field whose value to return from the khoros.structures.base.Mapping class
identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

static get_category_id(url)[source]¶

This method retrieves the Category ID for a given category when provided its URL.

Parameters:: url (str) – The URL from which to parse out the Category ID
Returns:: The Category ID retrieved from the URL
Raises:: khoros.errors.exceptions.InvalidURLError

get_creation_date(identifier=None, category_details=None)[source]¶

This method retrieves the creation date of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The creation of the category in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_depth(identifier=None, category_details=None)[source]¶

This method retrieves the depth of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The depth of the category as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_description(identifier=None, category_details=None)[source]¶

This method retrieves the description for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The description in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_friendly_date_max_age(identifier=None, category_details=None)[source]¶

This method retrieves the maximum age where friendly dates should be used (if enabled) for a category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Integer representing the number of days the friendly date feature should be leveraged if enabled

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_language(identifier=None, category_details=None)[source]¶

This method retrieves the defined language for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The language (e.g. en) in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_id(identifier=None, category_details=None)[source]¶

This method retrieves the parent ID for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent ID in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_type(identifier=None, category_details=None)[source]¶

This method retrieves the parent type for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent type in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_url(identifier=None, category_details=None)[source]¶

This method retrieves the parent URL for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent URL in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_position(identifier=None, category_details=None)[source]¶

This method retrieves the position of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The position of the category as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_id(identifier=None, category_details=None)[source]¶

This method retrieves the root category ID for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category ID in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_type(identifier=None, category_details=None)[source]¶

This method retrieves the root category type for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category type in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_url(identifier=None, category_details=None)[source]¶

This method retrieves the root category URL for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category URL in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_title(identifier=None, full_title=True, short_title=False, category_details=None)[source]¶

This method retrieves the full and/or short title of the category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
full_title (bool) – Return the full title of the environment (True by default)
short_title (bool) – Return the short title of the environment (False by default)
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The title(s) of the environment as a string or a tuple of strings

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_total_category_count()[source]¶

This method returns the total number of categories within the Khoros Community environment.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Deprecated since version 2.6.0: Use the khoros.core.Khoros.Category.get_total_count() method instead.

Returns:: The total number of categories as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_total_count()[source]¶

This method returns the total number of categories within the Khoros Community environment.

New in version 2.6.0.

Returns:: The total number of categories as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_url(category_id=None, category_details=None)[source]¶

This method retrieves the URL of a given category.

New in version 2.1.0.

Parameters:

category_id (str, None) – The ID of the category to be evaluated (optional if category_details provided)
category_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The full URL of the category

Raises:

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_views(identifier=None, category_details=None)[source]¶

This method retrieves the total view count for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The total number of views

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

is_hidden(identifier=None, category_details=None)[source]¶

This method identifies whether a given category is hidden.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean value indicating if the category is hidden

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

class Community(khoros_object)[source]¶

This class includes methods for interacting with the overall Khoros Community.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Community inner class object.

New in version 2.1.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

email_confirmation_required_to_post(community_details=None)[source]¶

This method identifies if an email configuration is required before posting in the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if email configuration is required before posting
Raises:: khoros.errors.exceptions.GETRequestError

friendly_date_enabled(community_details=None)[source]¶

This method if the friendly date functionality is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the feature is enabled
Raises:: khoros.errors.exceptions.GETRequestError

get_active_skin(community_details=None)[source]¶

This method retrieves the primary active skin that is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The skin name as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_community_details()[source]¶

This method returns a dictionary of community configuration settings.

New in version 2.1.0.

Returns:: The community details within a dictionary
Raises:: khoros.errors.exceptions.GETRequestError

get_community_field(field, community_details=None)[source]¶

This method retrieves a particular field from the community collection in the API.

New in version 2.1.0.

Parameters:

field (str) – The field whose value to return from the khoros.structures.base.Mapping class
community_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_creation_date(community_details=None)[source]¶

This method retrieves the timestamp for the initial creation of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The creation date as a string (e.g. 2020-02-03T22:41:36.408-08:00)
Raises:: khoros.errors.exceptions.GETRequestError

get_date_pattern(community_details=None)[source]¶

This method retrieves the date pattern (e.g. yyyy-MM-dd) utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The date pattern in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_description(community_details=None)[source]¶

This method retrieves the description of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The description in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_friendly_date_max_age(community_details=None)[source]¶

This method identifies if the friendly date functionality is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the feature is enabled
Raises:: khoros.errors.exceptions.GETRequestError

get_language(community_details=None)[source]¶

This method retrieves the language (e.g. en) utilized in the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The language code as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_max_attachments(community_details=None)[source]¶

This method retrieves the maximum number of attachments permitted per message within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The value as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_ooyala_player_branding_id(community_details=None)[source]¶

This method retrieves the branding ID for the Ooyala Player utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The branding ID in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_permitted_attachment_types(community_details=None)[source]¶

This method retrieves the attachment file types permitted within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The permitted file types within a list
Raises:: khoros.errors.exceptions.GETRequestError

get_primary_url(community_details=None)[source]¶

This method retrieves the primary URL of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The primary URL in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_sign_out_url(community_details=None)[source]¶

This method retrieves the Sign Out URL for the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The Sign Out URL as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_tenant_id(community_details=None)[source]¶

This method retrieves the tenant ID of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The tenant ID in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_title(full_title=True, short_title=False, community_details=None)[source]¶

This method retrieves the full and/or short title of the environment.

New in version 2.1.0.

Parameters:

full_title (bool) – Return the full title of the environment (True by default)
short_title (bool) – Return the short title of the environment (False by default)
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The title(s) of the environment as a string or a tuple of strings

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

show_breadcrumb_at_top_level(community_details=None)[source]¶

This method identifies if breadcrumbs should be shown at the top level of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if breadcrumbs are displayed at the top level of the environment
Raises:: khoros.errors.exceptions.GETRequestError

show_community_node_in_breadcrumb(community_details=None)[source]¶

This method identifies if the community node should be shown in breadcrumbs.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the community node is displayed in bredcrumbs
Raises:: khoros.errors.exceptions.GETRequestError

sso_enabled(community_details=None)[source]¶

This function checks whether SSO is enabled for the community.

New in version 5.0.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: A Boolean value indicating whether SSO is enabled

top_level_categories_enabled(community_details=None)[source]¶

This method identifies if top level categories are enabled within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if top level categories are enabled
Raises:: khoros.errors.exceptions.GETRequestError

top_level_categories_on_community_page(community_details=None)[source]¶

This method identifies if top level categories are enabled on community pages.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if top level categories are enabled on community pages
Raises:: khoros.errors.exceptions.GETRequestError

class GroupHub(khoros_object)[source]¶

This class includes methods for interacting with group hubs.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.GroupHub inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

create(group_id, group_title, description=None, membership_type=None, open_group=None, closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None, enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None, enable_tkb=None, all_styles_default=True, parent_category_id=None, avatar_image_path=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)[source]¶

This method creates a new group hub within a Khoros Community environment.

New in version 2.6.0.

Parameters:

group_id (str, int) – The unique identifier (i.e. id field) for the new group hub (Required)
group_title (str) – The title of the group hub (Required)
description (str, None) – A brief description of the group hub
membership_type (dict, None) – The membership_type value (open, closed or closed_hidden)
open_group (bool, None) – Defines the group hub as an open group
closed_group (bool, None) – Defines the group hub as a closed group
hidden_group (bool, None) – Defines the group hub as a closed and hidden group
discussion_styles (list, None) – A list of discussion styles that will be permitted in the group hub
enable_blog (bool, None) – Defines that the blog discussion style should be enabled for the group hub
enable_contest (bool, None) – Defines that the contest discussion style should be enabled for the group hub
enable_forum (bool, None) – Defines that the forum discussion style should be enabled for the group hub
enable_idea (bool, None) – Defines that the idea discussion style should be enabled for the group hub
enable_qanda (bool, None) – Defines that the Q&A (qanda) discussion style should be enabled for the group hub
enable_tkb (bool, None) – Defines that the TKB (tkb) discussion style should be enabled for the group hub
all_styles_default (bool) – Enables all discussion styles if not otherwise specified
parent_category_id (str, int, None) – The parent category identifier (if applicable)
avatar_image_path (str, None) – The file path to the avatar image to be uploaded (if applicable)
full_response (bool, None) –
Determines whether the full, raw API response should be returned by the function

Caution

This argument overwrites the return_id, return_url, return_api_url, return_http_code, return_status and return_error_messages arguments.
return_id (bool, None) – Determines if the ID of the new group hub should be returned by the function
return_url (bool, None) – Determines if the URL of the new group hub should be returned by the function
return_api_url (bool, None) – Determines if the API URL of the new group hub should be returned by the function
return_http_code (bool, None) – Determines if the HTTP Code of the API response should be returned by the function
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if any error messages associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

get_total_count()[source]¶

This method returns the total number of group hubs within the Khoros Community environment.

Returns:: The total number of group hubs as an integer

grouphub_exists(grouphub_id=None, grouphub_url=None)[source]¶

This method checks to see if a group hub exists.

New in version 2.7.0.

Parameters:

grouphub_id (str, None) – The ID of the group hub to check
grouphub_url (str, None) – The URL of the group hub to check

Returns:

Boolean value indicating whether the group hub already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

structure_payload(group_id, group_title, description=None, membership_type=None, open_group=None, closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None, enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None, enable_tkb=None, all_styles_default=True, parent_category_id=None)[source]¶

This method structures the payload to use in a Group Hub API request.

New in version 2.6.0.

Parameters:

group_id (str, int) – The unique identifier (i.e. id field) for the new group hub (Required)
group_title (str) – The title of the group hub (Required)
description (str, None) – A brief description of the group hub
membership_type (dict, None) – The membership_type value (open, closed or closed_hidden)
open_group (bool, None) – Defines the group hub as an open group
closed_group (bool, None) – Defines the group hub as a closed group
hidden_group (bool, None) – Defines the group hub as a closed and hidden group
discussion_styles (list, None) – A list of discussion styles that will be permitted in the group hub
enable_blog (bool, None) – Defines if the blog discussion style should be enabled for the group hub
enable_contest (bool, None) – Defines if the contest discussion style should be enabled for the group hub
enable_forum (bool, None) – Defines if the forum discussion style should be enabled for the group hub
enable_idea (bool, None) – Defines if the idea discussion style should be enabled for the group hub
enable_qanda (bool, None) – Defines if the Q&A (qanda) discussion style should be enabled for the group hub
enable_tkb (bool, None) – Defines if the TKB (tkb) discussion style should be enabled for the group hub
all_styles_default (bool) – Defines if all discussion styles should be enabled if not otherwise specified
parent_category_id (str, int, None) – The parent category identifier (if applicable)

Returns:

The properly formatted payload for the API request

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError

update_title(new_title, group_hub_id=None, group_hub_url=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)[source]¶

This method updates the title of an existing group hub.

New in version 2.6.0.

Parameters:

new_title (str) – The new title for the group hub
group_hub_id (str, None) – The group hub ID that identifies the group hub to update (necessary if URL not provided)
group_hub_url (str, None) – The group hub URL that identifies the group hub to update (necessary if ID not provided)
full_response (bool, None) –
Determines whether the full, raw API response should be returned by the function

Caution

This argument overwrites the return_id, return_url, return_api_url, return_http_code, return_status and return_error_messages arguments.
return_id (bool, None) – Determines if the ID of the new group hub should be returned by the function
return_url (bool, None) – Determines if the URL of the new group hub should be returned by the function
return_api_url (bool, None) – Determines if the API URL of the new group hub should be returned by the function
return_http_code (bool, None) – Determines if the HTTP Code of the API response should be returned by the function
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if any error messages associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError

class Label(khoros_object)[source]¶

This class includes methods for interacting with labels.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Label inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

get_labels_for_message(message_id)[source]¶

This method retrieves the labels associated with a specific message.

New in version 5.3.0.

Parameters:: message_id (str, int) – The ID associated with the message to query
Returns:: A list of strings for the labels
Raises:: khoros.errors.exceptions.GETRequestError

class Message(khoros_object)[source]¶

This class includes methods for interacting with messages.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Message inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

create(subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None, context_id=None, context_url=None, cover_image=None, images=None, is_answer=None, is_draft=None, labels=None, product_category=None, products=None, read_only=None, seo_title=None, seo_description=None, tags=None, ignore_non_string_tags=False, teaser=None, topic=None, videos=None, attachment_file_paths=None, full_payload=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False, proxy_user_object=None)[source]¶

This method creates a new message within a given node.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be created on behalf of other users.

Changed in version 4.3.0: It is now possible to pass the pre-constructed full JSON payload into the function via the full_payload parameter as an alternative to defining each field individually.

Changed in version 2.8.0: The ignore_non_string_tags, return_status, return_error_messages and split_errors arguments were introduced.

New in version 2.3.0.

Parameters:

subject (str, None) – The title or subject of the message
body (str, None) – The body of the message in HTML format
node (dict, None) – A dictionary containing the id key and its associated value indicating the destination
node_id (str, None) – The ID of the node in which the message will be published
node_url (str, None) –
The URL of the node in which the message will be published

Note

This argument is necessary in the absence of the node and node_id arguments.
canonical_url (str, None) – The search engine-friendly URL to the message
context_id (str, None) – Metadata on a message to identify the message with an external identifier of your choice
context_url (str, None) – Metadata on a message representing a URL to associate with the message (external identifier)
cover_image (dict, None) – The cover image set for the message
images (dict, None) – The query to retrieve images uploaded to the message
is_answer (bool, None) – Designates the message as an answer on a Q&A board
is_draft (bool, None) – Indicates whether the message is still a draft (i.e. unpublished)
labels (dict, None) – The query to retrieve labels applied to the message
product_category (dict, None) – The product category (i.e. container for products) associated with the message
products (dict, None) – The product in a product catalog associated with the message
read_only (bool, None) – Indicates whether the message should be read-only or have replies/comments blocked
seo_title (str, None) – The title of the message used for SEO purposes
seo_description (str, None) – A description of the message used for SEO purposes
tags (dict, None) – The query to retrieve tags applied to the message
ignore_non_string_tags (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
teaser (str, None) – The message teaser (used with blog articles)
topic (dict, None) – The root message of the conversation in which the message appears
videos (dict, None) – The query to retrieve videos uploaded to the message
attachment_file_paths (str, tuple, list, set, None) – The full path(s) to one or more attachment (e.g. path/to/file1.pdf)
full_payload (dict, str, None) –
Pre-constructed full JSON payload as a dictionary (preferred) or a JSON string with the following syntax:
{ "data": { "type": "message", } }
Note

The type field shown above is essential for the payload to be valid.
full_response (bool, None) –
Defines if the full response should be returned instead of the outcome (False by default)

Caution

This argument overwrites the return_id, return_url, return_api_url and return_http_code arguments.
return_id (bool, None) – Indicates that the Message ID should be returned (False by default)
return_url (bool, None) – Indicates that the Message URL should be returned (False by default)
return_api_url (bool, None) – Indicates that the API URL of the message should be returned (False by default)
return_http_code (bool, None) – Indicates that the HTTP status code of the response should be returned (False by default)
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if the Developer Response Message (if any) associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to create the message on behalf of a secondary user.

Returns:

Boolean value indicating a successful outcome (default) or the full API response

Raises:

TypeError, ValueError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

define_context_id(msg_id, context_id='', full_response=False)[source]¶

This method defines the context_id metadata value for a given message.

New in version 5.0.0.

Parameters:

msg_id (str) – The message ID to query
context_id (str) – The value to be written to the context_id metadata field (Empty by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value to indicate the success of the operation or alternatively the full API response

Raises:

define_context_url(msg_id, context_url='', full_response=False)[source]¶

This function defines the context_url metadata value for a given message.

New in version 5.0.0.

Parameters:

msg_id (str) – The message ID to query
context_url (str) – The value to be written to the context_url metadata field (Empty by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value to indicate the success of the operation or alternatively the full API response

Raises:

khoros.errors.exceptions.MessageTypeNotFoundError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.MessageTypeNotFoundError, khoros.errors.exceptions.InvalidURLError

flag(msg_id)[source]¶

This method flags a message as spam.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be flagged
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

format_content_mention(content_info=None, content_id=None, title=None, url=None)[source]¶

This method formats the <li-message> HTML tag for a content @mention.

New in version 2.4.0.

Parameters:

content_info (dict, None) –
A dictionary containing the 'id' and/or 'login' key(s) with the user data

Note

This argument is necessary if the Title and URL are not explicitly passed using the title and url function arguments.
content_id (str, int, None) –
The Message ID (aka Content ID) associated with the content mention

Note

This is an optional argument as the ID can be retrieved from the URL.
title (str, None) – The display title for the content mention (e.g. "Click Here")
url (str, None) – The fully-qualified URL of the message being mentioned

Returns:

The properly formatted <li-message> HTML tag in string format

Raises:

format_user_mention(user_info=None, user_id=None, login=None)[source]¶

This method formats the <li-user> HTML tag for a user @mention.

New in version 2.4.0.

Parameters:

user_info (dict, None) –
A dictionary containing the 'id' and/or 'login' key(s) with the user information

Note

This argument is necessary if the User ID and/or Login are not explicitly passed using the user_id and/or login function arguments.
user_id (str, int, None) – The unique user identifier (i.e. User ID) for the user
login (str, None) – The login (i.e. username) for the user

Returns:

The properly formatted <li-user> HTML tag in string format

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

get_all_messages(board_id, fields=None, where_filter=None, descending=True)[source]¶

This function retrieves data for all messages within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
where_filter (str, tuple, list, set, None) – One or more optional WHERE filters to include in the LiQL query
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each message within the board

Raises:

get_all_topic_messages(board_id, fields=None, descending=True)[source]¶

This function retrieves data for all topic messages (i.e. zero-depth messages) within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each topic message within the board

Raises:

get_context_id(msg_id)[source]¶

This method retrieves the Context ID value for a given message ID.

New in version 5.0.0.

Parameters:: msg_id (str) – The message ID to query
Returns:: The value of the Context ID metadata field
Raises:: khoros.errors.exceptions.get_context_id

get_context_url(msg_id)[source]¶

This method retrieves the Context URL value for a given message ID.

New in version 5.0.0.

Parameters:: msg_id (str) – The message ID to query
Returns:: The value of the Context URL metadata field
Raises:: khoros.errors.exceptions.get_context_id

get_kudos_for_message(message_id, count_only=False)[source]¶

This function retrieves the kudos for a given message ID and returns the full data or the kudos count.

New in version 5.4.0.

Parameters:

message_id (str) – The ID of the message for which to retrieve the kudos
count_only (bool) – Determines if only the kudos count should be returned (False by default)

Returns:

The JSON data for the message kudos or the simple kudos count as an integer

Raises:

khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

get_metadata(msg_id, metadata_key)[source]¶

This method retrieves the value for a specific metadata key associated with a given message.

New in version 4.5.0.

Parameters:

msg_id (str, int) – The ID of the message for which the metadata will be retrieved
metadata_key (str) – The metadata key for which the value will be retrieved

Returns:

The metadata value

Raises:

khoros.errors.exceptions.MissingRequiredDataError', :py:exc:`khoros.errors.exceptions.InvalidMetadataError, khoros.errors.exceptions.GETRequestError

kudo(msg_id)[source]¶

This method kudos (i.e. “likes”) a message.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be kudoed
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

label(msg_id, label_text)[source]¶

This function adds a single label to a given message.

New in version 5.1.0.

Parameters:

msg_id (str, int) – The ID of the message to be flagged
label_text (str) – The label to be added

Returns:

The API response in JSON format

Raises:

static parse_v2_response(json_response, return_dict=False, status=False, response_msg=False, http_code=False, message_id=False, message_url=False, message_api_uri=False, v2_base='')[source]¶

This method parses an API response for a message operation (e.g. creating a message) and returns data.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Changed in version 3.2.0: The lower-level function call now utilizes keyword arguments to fix an argument mismatch issue.

Deprecated since version 2.5.0: Use the khoros.core.Khoros.parse_v2_response() function instead.

New in version 2.3.0.

Parameters:

json_response (dict) – The API response in JSON format
return_dict (bool) – Defines if the parsed data should be returned within a dictionary
status (bool) – Defines if the status value should be returned
response_msg (bool) – Defines if the developer response message should be returned
http_code (bool) – Defines if the HTTP status code should be returned
message_id (bool) – Defines if the message ID should be returned
message_url (bool) – Defines if the message URL should be returned
message_api_uri (bool) – Defines if the ** message API URI** should be returned
v2_base (str) – The base URL for the API v2

Returns:

A string, tuple or dictionary with the parsed data

Raises:

khoros.errors.exceptions.MissingRequiredDataError

tag(msg_id, tag_text)[source]¶

This function adds a single tag to a given message.

New in version 5.1.0.

Parameters:

msg_id (str, int) – The ID of the message to be flagged
tag_text (str) – The tag to be added

Returns:

The API response in JSON format

Raises:

khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

unflag(msg_id)[source]¶

This method flags a message as not being spam.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be flagged
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

update(msg_id=None, msg_url=None, subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None, context_id=None, context_url=None, cover_image=None, is_draft=None, labels=None, moderation_status=None, parent=None, product_category=None, products=None, read_only=None, topic=None, status=None, seo_title=None, seo_description=None, tags=None, overwrite_tags=False, ignore_non_string_tags=False, teaser=None, attachments_to_add=None, attachments_to_remove=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False, proxy_user_object=None)[source]¶

This method updates one or more elements of an existing message.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be updated on behalf of other users.

New in version 2.8.0.

Parameters:

msg_id (str, int, None) – The ID of the existing message
msg_url (str, None) – The URL of the existing message
subject (str, None) – The title or subject of the message
body (str, None) – The body of the message in HTML format
node (dict, None) – A dictionary containing the id key and its associated value indicating the destination
node_id (str, None) – The ID of the node in which the message will be published
node_url (str, None) –
The URL of the node in which the message will be published

Note

This argument is necessary in the absence of the node and node_id arguments.
canonical_url (str, None) – The search engine-friendly URL to the message
context_id (str, None) – Metadata on a message to identify the message with an external identifier of your choosing
context_url (str, None) – Metadata on a message representing a URL to associate with the message (external identifier)
cover_image (dict, None) – The cover image set for the message
is_draft (bool, None) – Indicates whether the message is still a draft (i.e. unpublished)
labels (dict, None) – The query to retrieve labels applied to the message
moderation_status (str, None) –
The moderation status of the message

Note

Acceptable values are unmoderated, approved, rejected, marked_undecided, marked_approved and marked_rejected.
parent (str, None) – The parent of the message
product_category (dict, None) – The product category (i.e. container for products) associated with the message
products (dict, None) – The product in a product catalog associated with the message
read_only (bool, None) – Indicates whether the message should be read-only or have replies/comments blocked
topic (dict, None) – The root message of the conversation in which the message appears
status (dict, None) –
The message status for messages where conversation.style is idea or contest

Caution

This property is not returned if the message has the default Unspecified status assigned. It will only be returned for ideas with a status of Completed or with a custom status created in Community Admin.
seo_title (str, None) – The title of the message used for SEO purposes
seo_description (str, None) – A description of the message used for SEO purposes
tags (dict, None) – The query to retrieve tags applied to the message
overwrite_tags (bool) – Determines if tags should overwrite any existing tags (where applicable) or if the tags should be appended to the existing tags (default)
ignore_non_string_tags (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
teaser (str, None) – The message teaser (used with blog articles)
attachments_to_add (str, tuple, list, set, None) – The full path(s) to one or more attachments (e.g. path/to/file1.pdf) to be added to the message
attachments_to_remove (str, tuple, list, set, None) –
One or more attachments to remove from the message

Note

Each attachment should specify the attachment id of the attachment to remove, which begins with m#_. (e.g. m283_file1.pdf)
full_response (bool, None) –
Defines if the full response should be returned instead of the outcome (False by default)

Caution

This argument overwrites the return_id, return_url, return_api_url and return_http_code arguments.
return_id (bool, None) – Indicates that the Message ID should be returned (False by default)
return_url (bool, None) – Indicates that the Message URL should be returned (False by default)
return_api_url (bool, None) – Indicates that the API URL of the message should be returned (False by default)
return_http_code (bool, None) – Indicates that the HTTP status code of the response should be returned (False by default)
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if the Developer Response Message (if any) associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to create the message on behalf of a secondary user.

Returns:

Boolean value indicating a successful outcome (default) or the full API response

Raises:

TypeError, ValueError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

static validate_message_payload(payload)[source]¶

This method validates the payload for a message to ensure that it can be successfully utilized.

New in version 4.3.0.

Parameters:: payload (dict, str) – The message payload to be validated as a dictionary (preferred) or a JSON string.
Returns:: The payload as a dictionary
Raises:: khoros.errors.exceptions.InvalidMessagePayloadError

class Node(khoros_object)[source]¶

This class includes methods for interacting with nodes.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Node inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

get_avatar_url(identifier, node_details=None, original=True, tiny=False, small=False, medium=False, large=False)[source]¶

This method retrieves one or more avatar URLs for a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
original (bool) – Indicates if the URL for the original-size image should be returned (True by default)
tiny (bool) – Indicates if the URL for the image in a tiny size should be returned (False by default)
small (bool) – Indicates if the URL for the image in a small size should be returned (False by default)
medium (bool) – Indicates if the URL for the image in a medium size should be returned (False by default)
large (bool) – Indicates if the URL for the image in a large size should be returned (False by default)

Returns:

A single URL as a string (default) or a dictionary of multiple URLs by size

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_creation_date(identifier, node_details=None, friendly=False)[source]¶

This method returns the creation date of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
friendly (bool) – Defines if the “friendly” date (e.g. Friday) should be returned (False by default)

Returns:

The creation date as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_depth(identifier, node_details=None)[source]¶

This method returns the depth of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The depth as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_description(identifier, node_details=None)[source]¶

This method returns the description of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node description as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_discussion_style(identifier, node_details=None)[source]¶

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_node_details(identifier, first_item=True)[source]¶

This method returns a dictionary of node configuration settings.

New in version 2.1.0.

Parameters:

identifier (str) – The Node ID or Node URL with which to identify the node
first_item (bool) – Filters the response data to the first item returned (True by default)

Returns:

The node details within a dictionary

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_node_field(field, identifier=None, node_details=None)[source]¶

This method returns a specific node field from the Khoros Community API.

New in version 2.1.0.

Parameters:

field (str) – The field to return from the khoros.structures.base.Mapping class
identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

static get_node_id(url, node_type=None)[source]¶

This method retrieves the Node ID for a given node within a URL.

Parameters:

url (str) – The URL from which to parse out the Node ID
node_type (str, None) – The node type (e.g. blog, tkb, message, etc.) for the object in the URL

Returns:

The Node ID retrieved from the URL

Raises:

khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.NodeIDNotFoundError, khoros.errors.exceptions.NodeTypeNotFoundError

static get_node_type_from_url(url)[source]¶

This method attempts to retrieve a node type by analyzing a supplied URL.

Parameters:: url (str) – The URL from which to extract the node type
Returns:: The node type based on the URL provided
Raises:: khoros.errors.exceptions.NodeTypeNotFoundError

get_parent_id(identifier, node_details=None, include_prefix=False)[source]¶

This method returns the Parent ID of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
include_prefix (bool) – Determines if the prefix (e.g. category:) should be included (Default: False)

Returns:

The Parent ID as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_type(identifier, node_details=None)[source]¶

This method returns the parent type of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The parent type as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_url(identifier, node_details=None)[source]¶

This method returns the parent URL of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The parent URL as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_position(identifier, node_details=None)[source]¶

This method returns the position of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The position as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_id(identifier, node_details=None, include_prefix=False)[source]¶

This method returns the Root Category ID of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
include_prefix (bool) – Defines if the prefix (e.g. category:) should be included (False by default)

Returns:

The Root Category ID as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_type(identifier, node_details=None)[source]¶

This method returns the root category type of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The root category type as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_url(identifier, node_details=None)[source]¶

This method returns the root category URL of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The root category URL as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_title(identifier=None, full_title=True, short_title=False, node_details=None)[source]¶

This method retrieves the full and/or short title of the node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
full_title (bool) – Determines if the full title of the node should be returned (True by default)
short_title (bool) – Determines if the short title of the node should be returned (False by default)
node_details (dict, None) – Dictionary containing node details (optional)

Returns:

The node title(s) as a string or a tuple of strings

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_total_node_count()[source]¶

This method returns the total number of nodes within the Khoros Community environment.

Returns:: The total number of nodes as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_type(identifier, node_details=None)[source]¶

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_url(node_id=None, node_details=None)[source]¶

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

node_id (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_views(identifier, node_details=None)[source]¶

This method returns the views for a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The views as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

is_hidden(identifier, node_details=None)[source]¶

This method identifies whether a given node is hidden.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

Boolean indicating whether the node is hidden

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

node_exists(node_id=None, node_url=None)[source]¶

This method checks to see if a node exists.

New in version 2.7.0.

Parameters:

node_id (str, None) – The ID of the node to check
node_url (str, None) – The URL of the node to check

Returns:

Boolean value indicating whether the node already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

class Role(khoros_object)[source]¶

This class includes methods relating to roles and permissions.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Role inner class object.

New in version 2.4.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

assign_roles_to_user(user, lookup_type='id', roles_to_add=None, node=None, node_type='board', v1=False, return_json=True)[source]¶

This method assigns a user to one or more roles.

New in version 4.0.0.

Parameters:

user (str) – The identifier (i.e. ID, login or email) of the user to be assigned to the role
lookup_type (str) – The lookup type for the user identifier (id, login or email)
roles_to_add (str, list, tuple, set) – One or more roles (Role IDs or Role Names) to which the user will be assigned
node (str, None) – The Node ID of the node to which the role is scoped when applicable
node_type (str) – The type of node to which the role is scoped (e.g. board (default), category, etc.)
v1 (bool) – Determines if the Community API v1 should be used to perform the operation (False by default)
return_json (bool) – Determines if the response should be returned as JSON rather than XML (True by default)

Returns:

The response from the API request

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.UnsupportedNodeTypeError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PUTRequestError

static get_role_id(role_name, scope='community', node_id=None)[source]¶

This method constructs and returns the Role ID associated with a given role name and scope.

New in version 4.0.0.

Parameters:

role_name (str) – The name of the role (e.g. Administrator, Moderator, Owner, etc.)
scope (str) – The scope of the role (community by default)
node_id (str, None) – The associated Node ID for any role that does not have a global/community scope.

Returns:

The properly constructed Role ID where applicable

Raises:

khoros.errors.exceptions.InvalidRoleError, khoros.errors.exceptions.MissingRequiredDataError

get_roles_for_user(user_id, fields=None)[source]¶

This method returns all roles associated with a given User ID.

Changed in version 4.1.0: The docstring has been updated to reference the correct exception raised by this method.

Changed in version 3.5.0: Fields to return in the LiQL query can now be explicitly defined.

New in version 2.4.0.

Parameters:

user_id (str) – The User ID for which to retrieve the roles data
fields (str, list, tuple, set, None) –
The field(s) to retrieve from the LiQL query as a string or list

Note

All fields (i.e. SELECT *) are returned unless fields are explicitly defined.

Returns:

A dictionary with data for each role associated with the given User ID

Raises:

khoros.errors.exceptions.DataMismatchError, khoros.errors.exceptions.MissingRequiredDataError

get_total_role_count(return_dict=False, total=True, top_level=False, board=False, category=False, group_hub=False)[source]¶

This method retrieves the total role count for one or more role type(s).

New in version 2.4.0.

Parameters:

return_dict (bool) – Determines if the data should be returned as a dictionary (False by default)
total (bool) – Indicates that the total overall role count should be returned (True by default)
top_level (bool) – Indicates that the total top-level role count should be returned (False by default)
board (bool) – Indicates that the total board-level role count should be returned (False by default)
category (bool) – Indicates that the total category-level role count should be returned (False by default)
group_hub (bool) – Indicates that the total group hub-level role count should be returned (False by default)

Returns:

The role count(s) as an integer, tuple or dictionary, depending on the arguments supplied

Raises:

khoros.objects.roles.InvalidRoleTypeError

get_users_with_role(fields='login', role_id=None, role_name=None, scope=None, node_id=None, limit_per_query=1000, simple=False)[source]¶

This method retrieves a list of all users that have a specific role.

New in version 3.5.0.

Parameters:

fields (str, tuple, list, set) –
One or more fields from the Users object to return (login field by default)

See also

The fields that can be used are found in the Khoros developer documentation.
role_id (str, None) – The identifier for the role in node_type:node_id:role_name format
role_name (str, None) –
The simple role name (e.g. Administrator)

Caution

This option should only be used when the role name is unique within the community at all node levels.
scope (str, None) –
The scope of the role (e.g. board, category, community, grouphub)

Note

If a value is not supplied and only a role name is defined then the role scope is assumed to be at the community level. (i.e. global)
node_id (str, None) –
The Node ID associated with the role (where applicable)

Note

If a value is not supplied and only a role name is defined then the role scope is assumed to be at the community level. (i.e. global)
limit_per_query (int, str) –
Defines a LIMIT constraint other than the default 1000 limit per LiQL query

Note

Unless modified by Khoros Support or Professional Services, 1000 is the maximum number of entries that can be returned in a single LiQL query.
simple (bool) – Returns a simple list of the strings or tuples of the value(s) for each user (False by default)

Returns:

A list of users as strings, tuples or dictionaries depending if simple mode is enabled

Raises:

class SAML(khoros_object)[source]¶

This class includes methods relating to SAML 2.0 authentication and user provisioning.

New in version 4.3.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.SAML inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

static import_assertion(file_path, base64_encode=True, url_encode=True)[source]¶

This method imports an XML SAML assertion as a string and optionally base64- and/or URL-encodes it.

New in version 4.3.0.

Parameters:

file_path (str) – The file path to the XML file to import
base64_encode (bool) – Determines if the assertion should be base64-encoded (True by default)
url_encode (bool) – Determines if the assertion should be URL-encoded (True by default)

Returns:

The SAML assertion string

Raises:

FileNotFoundError

send_assertion(assertion=None, file_path=None, base64_encode=True, url_encode=True)[source]¶

This method sends a SAML assertion as a POST request in order to provision a new user.

New in version 4.3.0.

Parameters:

assertion (str, None) – The SAML assertion in string format and optionally base64- and/or URL-encoded
file_path (str, None) – The file path to the XML file to import that contains the SAML assertion
base64_encode (bool) – Determines if the assertion should be base64-encoded (True by default)
url_encode (bool) – Determines if the assertion should be URL-encoded (True by default)

Returns:

The API response from the POST request

Raises:

khoros.errors.exceptions.MissingRequiredDataError

class Settings(khoros_object)[source]¶

This class includes methods relating to the retrieval and defining of various settings.

New in version 3.2.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Settings inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

define_node_setting(setting_name, setting_val, node_id, node_type='board', return_json=True)[source]¶

This method defines a particular setting value for a given node.

Changed in version 4.0.0: The default value for the return_json parameter is now True.

Changed in version 3.3.2: The return_json parameter has been introduced which returns a simple JSON object (as a dict) indicating whether the operation was successful. (Currently False by default)

New in version 3.2.0.

Parameters:

setting_name (str) – The name of the setting field for which to retrieve the value
setting_val (str) – The value of the setting to be defined
node_id (str) – The ID of the node associated with the setting to retrieve
node_type (str) – Defines the node as a board (default), category or grouphub
return_json (bool) –
Returns a simple JSON dictionary indicating the operation result (True by default)

Caution

An unsuccessful REST call will result in the raising of the khoros.errors.exceptions.PostRequestError exception if the return_json parameter is set to False.

Returns:

The API response as a dictionary

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.PayloadMismatchError

get_node_setting(setting_name, node_id, node_type='board', v1=None, convert_json=False)[source]¶

This method retrieves the value of a specific node setting.

Changed in version 3.3.2: The convert_json parameter has been introduced which optionally converts a JSON string into a dictionary.

New in version 3.2.0.

Parameters:

setting_name (str) – The name of the setting field for which to retrieve the value
node_id (str) – The ID of the node associated with the setting to retrieve
node_type (str) – Defines the node as a board (default), category or grouphub
v1 (bool, None) – Optionally defines a specific Community API version to use when retrieving the value
convert_json (bool) – Optionally converts a JSON string into a Python dictionary (False by default)

Returns:

The value of the setting for the node

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.LiQLParseError

class Studio(khoros_object)[source]¶

This class includes methods relating to the Lithium SDK and Studio Plugin.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Studio inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

static get_node_version()[source]¶

This method identifies and returns the installed Node.js version.

New in version 2.5.1.

Returns:: The version as a string or None if not installed

static get_npm_version()[source]¶

This method identifies and returns the installed npm version.

New in version 2.5.1.

Returns:: The version as a string or None if not installed

static get_sdk_version()[source]¶

This method identifies the currently installed version of the Lithium SDK.

New in version 2.5.1.

Returns:: The SDK version in string format or None if not installed

static node_installed()[source]¶

This method checks whether Node.js is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether Node.js is installed

static npm_installed()[source]¶

This method checks whether npm is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether npm is installed

static sdk_installed()[source]¶

This method checks to see if the Lithium SDK is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether the Lithium SDK is installed

class Subscription(khoros_object)[source]¶

This class includes methods relating to subscriptions.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Subscription inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

add_subscription(target_id, target_type='board', payload=None, included_boards=None, excluded_boards=None, proxy_user_object=None)[source]¶

This method adds a subscription to a given target for the current user.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

target_id (str, int) – The unique identifier for the target (e.g. Node ID, Message ID, etc.)
target_type – The target type such as board (default), message, category, etc.
payload (dict, None) – Pre-constructed payload to use in the API call
included_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be included in the partial subscription
excluded_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be excluded from the partial subscription
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

get_subscription_uri()[source]¶

This method returns the subscriptions URI for the v2 API to perform API calls.

New in version 3.5.0.

Returns:: The full (absolute) URI for the subscriptions v2 API endpoint

subscribe_to_board(node_id, proxy_user_object=None)[source]¶

This method subscribes the current user to an individual message.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

node_id (str) – The unique identifier for a board (i.e. Board ID)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_category(node_id, included_boards=None, excluded_boards=None, proxy_user_object=None)[source]¶

This method subscribes the current user to a full or partial category.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

node_id (str) – The unique identifier (i.e. Node ID) for the category
included_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be included in the partial subscription
excluded_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be excluded from the partial subscription
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_label(label, board_id, proxy_user_object=None)[source]¶

This method subscribes the current user to label found on a board.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

label (str, int) – The label to which to subscribe
board_id (str) – The unique identifier (i.e. Node ID) for the board where the label is found
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_message(msg_id, proxy_user_object=None)[source]¶

This method subscribes the current user to an individual message.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

msg_id (str, int) – The unique identifier for an individual message
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_product(product_id, proxy_user_object=None)[source]¶

This method subscribes the current user to a product.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

product_id (str, int) – The unique identifier for a product
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

class Tag(khoros_object)[source]¶

This class includes methods relating to the tagging of content.

New in version 4.1.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Tag inner class object.

New in version 4.1.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

add_single_tag_to_message(tag, msg_id, allow_exceptions=False)[source]¶

This method adds a single tag to an existing message.

New in version 4.1.0.

Parameters:

tag (str) – The tag value to be added
msg_id (str, int) – The unique identifier for the message
allow_exceptions (bool) – Determines if exceptions are permitted to be raised (False by default)

Returns:

None

Raises:

add_tags_to_message(tags, msg_id, allow_exceptions=False)[source]¶

This method adds one or more tags to an existing message.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 4.1.0.

..caution:: This function is not the most effective way to add multiple tags to a message. It is recommended: that the khoros.core.Khoros.messages.update() method be used instead with its tags argument, which is more efficient and performance-conscious.

Parameters:

tags (str, tuple, list, set) – One or more tags to be added to the message
msg_id (str, int) – The unique identifier for the message
allow_exceptions (bool) – Determines if exceptions are permitted to be raised (False by default)

Returns:

None

Raises:

khoros.errors.exceptions.UserCreationError

get_tags_for_message(msg_id)[source]¶

This method retrieves the tags for a given message.

New in version 4.1.0.

Parameters:: msg_id (str, int) – The Message ID for the message from which to retrieve tags
Returns:: A list of tags associated with the message

static structure_single_tag_payload(tag_text)[source]¶

This method structures the payload for a single tag.

New in version 4.1.0.

Parameters:: tag_text (str) – The tag to be included in the payload
Returns:: The payload as a dictionary
Raises:: khoros.errors.exceptions.InvalidPayloadValueError

structure_tags_for_message(*tags, msg_id=None, overwrite=False, ignore_non_strings=False, wrap_json=False)[source]¶

This method structures tags to use within the payload for creating or updating a message.

Changed in version 4.3.0: Introduced the wrap_json parameter to wrap the tags in a dictionary within the items key.

New in version 4.1.0.

Parameters:

tags (str, list, tuple, set) – One or more tags or list of tags to be structured
msg_id (str, int, None) – Message ID of an existing message so that its existing tags can be retrieved (optional)
overwrite (bool) – Determines if tags should overwrite any existing tags (where applicable) or if the tags should be appended to the existing tags (default)
ignore_non_strings (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
wrap_json (bool) – Determines if the list of tags should be wrapped in the {"items": []} JSON structure – In other words, a dictionary rather than a list (False by default)

Returns:

A list of properly formatted tags to act as the value for the tags field in the message payload

class User(khoros_object)[source]¶

This class includes methods for interacting with users.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.User inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

create(user_settings=None, login=None, email=None, password=None, first_name=None, last_name=None, biography=None, sso_id=None, web_page_url=None, cover_image=None, ignore_exceptions=False)[source]¶

This method creates a new user in the Khoros Community environment.

Changed in version 4.0.0: This function now returns the API response and the ignore_exceptions parameter has been introduced.

Changed in version 3.5.0: The unnecessary return statement at the end of the method has been removed.

Parameters:

user_settings (dict, None) – Allows all user settings to be passed to the function within a single dictionary
login (str, None) – The username (i.e. login) for the user (required)
email (str, None) – The email address for the user (required)
password (str, None) – The password for the user
first_name (str, None) – The user’s first name (i.e. given name)
last_name (str, None) – The user’s last name (i.e. surname)
biography (str, None) – The user’s biography for their profile
sso_id (str, None) – The Single Sign-On (SSO) ID for the user
web_page_url (str, None) – The URL to the user’s website
cover_image (str, None) – The cover image to be used on the user’s profile
ignore_exceptions (bool) – Defines whether to raise the khoros.errors.exceptions.UserCreationError exception if the creation attempt fails (False by default)

Returns:

The response to the user creation API request

Raises:

delete(user_id, return_json=False)[source]¶

This method deletes a user from the Khoros Community environment.

Parameters:

user_id (str, int) – The User ID of the user to be deleted
return_json (bool) – Determines if the API response should be returned in JSON format (False by default)

Returns:

The API response (optionally in JSON format)

Raises:

khoros.errors.exceptions.FeatureNotConfiguredError

get_album_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the number of albums for a user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of albums found for the user as an integer

Raises:

get_all_users(fields=None, order_by='last_visit_time', order_by_desc=True)[source]¶

This function retrieves data for all users.

New in version 5.3.0.

Parameters:

fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
order_by (str) – The order by which to sort the data (last_visit_time by default)
order_by_desc (bool) – Indicates if the data should be sorted in descending (default) or ascending order

Returns:

A list containing a dictionary of data for each user

Raises:

get_all_users_count()[source]¶

This method retrieves the total number of users on the community.

New in version 5.2.0.

Returns:: The user count for total users as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_email(user_settings=None, user_id=None, login=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶

This method retrieves the email address for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: User ID, username, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (str, None) – The User ID of the user
login (str, None) – The username of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of email addresses to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The email address of the user as a string or a list of emails if allow_multiple is True

get_followers_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of community members who have added the user as a friend in the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of community members who have added the user as a friend in integer format

Raises:

get_following_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of community members the user has added as a friend in the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of community members the user has added as a friend in integer format

Raises:

get_ids_from_login_list(login_list, return_type='list')[source]¶

This method identifies the User IDs associated with a list of user logins. (i.e. usernames)

Parameters:

login_list (list, tuple) – List of user login (i.e. username) values in string format
return_type (str) – Determines if the data should be returned as a list (default) or a dict

Returns:

A list or dictionary with the User IDs

Raises:

get_images_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of images uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of images uploaded by the user in integer format

Raises:

get_kudos_given_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of kudos a user has given.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of kudos given by the user in integer format

Raises:

get_kudos_received_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of kudos a user has received.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of kudos received by the user in integer format

Raises:

get_last_visit_timestamp(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves the timestamp for the last time the user logged into the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The last visit timestamp in string format

Raises:

get_login(user_settings=None, user_id=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶: This is an alternative method name for the khoros.core.Khoros.User.get_username() method.

get_messages_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of messages (topics and replies) posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of messages (topics and replies) posted by the user in integer format

Raises:

get_online_user_count()[source]¶

This method retrieves the number of users currently online.

Returns:: The user count for online users as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_online_users_count(anonymous=None, registered=None)[source]¶

This method returns the total count of users currently online.

New in version 5.0.0.

Parameters:

anonymous (bool, None) – Filters the results to only anonymous (non-registered) users
registered (bool, None) – Filters the results to only registered users

Returns:

An integer of the total online users count

Raises:

get_public_images_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of public images uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of public images uploaded by the user in integer format

Raises:

get_registered_users_count()[source]¶

This method returns the total count of registered users on the community.

New in version 5.0.0.

Returns:: An integer of the total registered users count

get_registration_data(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves the registration data for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

A dictionary containing the registration data for the user

Raises:

get_registration_status(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves the registration status for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The registration status in string format

Raises:

get_registration_timestamp(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves the timestamp for when a given user registered for an account.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The registration timestamp in string format

Raises:

get_replies_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of replies posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of replies posted by the user in integer format

Raises:

get_roles_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of roles applied to the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of roles applied to the user in integer format

Raises:

get_solutions_authored_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of messages created by the user that are marked as accepted solutions.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of messages created by the user that are marked as accepted solutions in integer format

Raises:

get_topics_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of topic messages (excluding replies) posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of topic messages (excluding replies) posted by the user in integer format

Raises:

get_user_data(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves all user data for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

A dictionary containing the user data for the user

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidParameterError

get_user_id(user_settings=None, login=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶

This method looks up and retrieves the User ID for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: login, email, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
login (str, None) – The username of the user
email (str, None) – The email address of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of User IDs to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The User ID of the user as an integer or a list of User IDs if allow_multiple is True

get_username(user_settings=None, user_id=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶

This method looks up and retrieves the username for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: User ID, email, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (str, None) – The User ID of the user
email (str, None) – The email address of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of usernames to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The username (i.e. login) of the user or a list of usernames if allow_multiple is True

get_users_count(registered=False, online=False)[source]¶

This method returns the total number of users in an environment. (Filtering possible for registered and online)

New in version 5.3.0.

Parameters:

registered (bool) – Return a count of registered users (False by default)
online (bool) – Return a count of online users (False by default)

Returns:

An integer defining the total user count for the environment

Raises:

get_videos_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of videos uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of videos uploaded by the user in integer format

Raises:

impersonate_user(user_login)[source]¶

This method instantiates and returns the :py:class`khoros.objects.users.ImpersonatedUser` object which: can then be passed to other methods and functions to perform operations as a secondary user.

Note

The authenticated user must have the Administrator role and/or have the Switch User permission enabled.

New in version 4.0.0.

Parameters:: user_login (str) – The username (i.e. login) of the user to be impersonated
Returns:: The instantiated :py:class`khoros.objects.users.ImpersonatedUser` object

query_users_table_by_id(select_fields, user_id)[source]¶

This method queries the users table for one or more given SELECT fields for a specific User ID.

Parameters:

select_fields (str, tuple, list, set) – One or more SELECT field (e.g. login, messages.count(*), etc.) to query
user_id (int, str) – The User ID associated with the user

Returns:

The API response for the performed LiQL query

Raises:

ValueError, TypeError, khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError

update_sso_id(new_sso_id, user_id=None, user_login=None)[source]¶

This method updates the SSO ID for a user.

New in version 4.5.0.

Parameters:

new_sso_id (str) – The new SSO ID for the user
user_id (str, int, None) – The numeric User ID that identifies the user
user_login (str, None) – The username that identifies the user

Returns:

The API response

Raises:

py:exc:khoros.errors.exceptions.MissingRequiredDataError

class V1(khoros_object)[source]¶

This class includes methods for performing base Community API v1 requests.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.V1 inner class object.

New in version 3.0.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

get(endpoint, query_params=None, return_json=True, proxy_user_object=None)[source]¶

This method makes a Community API v1 GET request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.0.0.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

post(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False, proxy_user_object=None)[source]¶

This method makes a Community API v1 POST request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.2.0: Introduced the ability to pass the query parameters as payload to avoid URI length limits.

New in version 3.0.0.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
params_in_uri (bool) – Determines if query parameters should be passed in the URI rather than in the request body (False by default)
json_payload (bool) –
Determines if query parameters should be passed as JSON payload rather than in the URI (False by default)

Caution

This is not yet fully supported and therefore should not be used at this time.
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

ValueError, TypeError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

put(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False, proxy_user_object=None)[source]¶

This method makes a Community API v1 PUT request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.2.0: Introduced the ability to pass the query parameters as payload to avoid URI length limits.

New in version 3.0.0.

Caution

While PUT requests are technically supported in this library, at this time they are not yet supported by the Khoros Community API v1 endpoints.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
params_in_uri (bool) – Determines if query parameters should be passed in the URI rather than in the request body (False by default)
json_payload (bool) –
Determines if query parameters should be passed as JSON payload rather than in the URI (False by default)

Caution

This is not yet fully supported and therefore should not be used at this time.
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

ValueError, TypeError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

search(endpoint, filter_field, filter_value, return_json=False, fail_on_no_results=False, proxy_user_object=None)[source]¶

This method performs a search for a particular field value using a Community API v1 call.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.0.0.

Parameters:

endpoint (str) – The API v1 endpoint against which to perform the search query
filter_field (str) – The name of the field being queried within the API v1 endpoint
filter_value (str, int) – The value associated with the field being queried
return_json (bool) – Determines if the response should be returned in JSON format (False by default)
fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response (optionally in JSON format)

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError

class V2(khoros_object)[source]¶

This class includes methods for performing base Community API v2 requests.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.V2 inner class object.

New in version 4.0.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

get(endpoint, return_json=True, headers=None, proxy_user_object=None)[source]¶

This method performs a Community API v2 GET request that leverages the Khoros authorization headers.

New in version 4.0.0.

Parameters:

endpoint (str) – The API v2 endpoint aginst which to query
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the GET request

Raises:

post(endpoint, payload=None, return_json=True, content_type=None, headers=None, multipart=False, proxy_user_object=None)[source]¶

This method performs a Community API v2 POST request that leverages the Khoros authorization headers.

New in version 4.0.0.

Parameters:

endpoint (str) – The relative (default) or fully-qualified URL for the API call
payload (dict, str, None) –
The JSON or plaintext payload (if any) to be supplied with the API request

Todo

Add support for other payload formats such as binary, etc.
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
content_type (str, None) –
Allows the content-type value to be explicitly defined if necessary

Note

If this parameter is not defined then the content type will be identified based on the payload format and/or type of request.
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the POST request

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

put(endpoint, payload=None, return_json=True, content_type=None, headers=None, multipart=False, proxy_user_object=None)[source]¶

This method performs a Community API v2 PUT request that leverages the Khoros authorization headers.

New in version 4.0.0.

Parameters:

endpoint (str) – The relative (default) or fully-qualified URL for the API call
payload (dict, str, None) –
The JSON or plaintext payload (if any) to be supplied with the API request

Todo

Add support for other payload formats such as binary, etc.
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
content_type (str, None) –
Allows the content-type value to be explicitly defined if necessary

Note

If this parameter is not defined then the content type will be identified based on the payload format and/or type of request.
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the PUT request

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.PayloadMismatchError

__init__(defined_settings=None, community_url=None, tenant_id=None, community_name=None, auth_type=None, session_auth=None, oauth2=None, sso=None, helper=None, env_variables=None, auto_connect=True, use_community_name=False, prefer_json=True, debug_mode=False, skip_env_variables=False, empty=False, ssl_verify=None, bulk_data_settings=None, logging_level=None)[source]¶

This method instantiates the core Khoros object.

Changed in version 5.0.0: Added support for the Bulk Data API.

Changed in version 4.3.0: Fixed an issue where the ssl_verify parameter was being mostly disregarded.

Changed in version 4.2.0: Introduced support for LithiumSSO Token authentication and made some general code improvements.

Changed in version 3.4.0: Introduced the ssl_verify parameter and established a key-value pair for it in the core_settings dictionary for the object.

Changed in version 3.3.2: Method arguments are no longer ignored if they are implicitly False and instead only the arguments that explicitly have a None value are ignored. The skip_env_variables argument has also been introduced to explicitly ignore any valid environment variables, as well as the empty argument to optionally instantiate an empty instantiated object. Logging was also added in various locations throughout the method.

Changed in version 3.3.0: Changed settings to defined_settings and _settings to _core_settings.

Parameters:

defined_settings (dict, None) – Predefined settings that the object should use
community_url (str, None) – The base URL of the Khoros community instance (e.g. community.khoros.com)
tenant_id (str, None) – The tenant ID for the Khoros community instance (e.g. lithosphere)
community_name (str, None) – The community name (e.g. community-name) for the Khoros community instance
auth_type (str, None) – The authentication type to use when connecting to the instance (session_auth by default)
session_auth (dict, None) – The username and password values for session key authentication
oauth2 (dict, None) – The client_id, client_secret and redirect_url values for OAuth 2.0 authentication
sso (dict, None) – The values for single sign-on (SSO) authentication
helper (str, tuple, list, dict, None) – The path (and optional file type) to the YAML or JSON helper configuration file
env_variables (dict, str, None) – A dictionary (or file path to a YAML or JSON file) that maps environment variable names
auto_connect (bool) – Determines if a connection should be established when initialized (True by default)
use_community_name (bool) – Defines if the community name should be used in the API URLs (False by default)
prefer_json (bool) – Defines preference that API responses be returned in JSON format (True by default)
debug_mode (bool) – Determines if Debug Mode should be enabled for development purposes (False by default)
skip_env_variables (bool) – Explicitly ignores any valid environment variables (False by default)
empty (bool) – Instantiates an empty object to act as a placeholder with default values (False by default)
ssl_verify (bool, None) – Determines whether to verify the server’s TLS certificate (True by default)
bulk_data (dict, None) – The values for utilizing the Bulk Data API

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.SessionAuthenticationError

close()[source]¶: This core method destroys the instance.

Changed in version 3.5.0: The unnecessary pass statement at the end of the method has been removed.

connect(connection_type=None)[source]¶

This method establishes a connection to the environment using a specified authentication type.

Changed in version 4.2.0: Introduced support for LithiumSSO Token authentication and made general code improvements to avoid unnecessary KeyError exceptions. Also fixed an issue with the exception error message.

Changed in version 3.3.2: Added logging for the khoros.errors.exceptions.CurrentlyUnsupportedError exception.

Parameters:: connection_type (str, None) – The type of authentication method (e.g. session_auth)
Returns:: None
Raises:: khoros.errors.exceptions.CurrentlyUnsupportedError

get(query_url, relative_url=True, return_json=True, headers=None, proxy_user_object=None)[source]¶

This method performs a simple GET request that leverages the Khoros authorization headers.

Changed in version 4.2.0: Resolved an issue that caused errors with absolute URLs, and made general code improvements were made to avoid unnecessary KeyError exceptions.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Parameters:

query_url (str) – The relative (default) or fully-qualified URL for the API call
relative_url (bool) – Determines if the URL should be appended to the community domain (True by default)
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the GET request

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError

get_platform_version(full_release=False, simple=False, commit_id=False, timestamp=False)[source]¶

This method retrieves the Khoros Community platform version information for a given environment.

New in version 3.4.0.

Parameters:

full_release (bool) –
Defines if the full platform release version should be returned

Note

If none of the options are enabled then the full_release option will be enabled by default.
simple (bool) – Defines if the simple X.Y version (e.g. 20.6) should be returned (False by default)
commit_id (bool) – Defines if the Commit ID (i.e. hash) for the release should be returned (False by default)
timestamp (bool) – Defines if the timestamp of the release (e.g. 2007092156) should be returned (False by default)

Returns:

One or more string with version information

Raises:

khoros.errors.exceptions.SessionAuthenticationError

get_session_key(username=None, password=None)[source]¶

This method retrieves the session key for an authentication session.

New in version 3.5.0.

Parameters:

username (str, None) – The username (i.e. login) of a secondary user to authenticate (optional)
password (str, None) –
The password of a secondary user to authenticate (optional)

Caution

It is recommended that the khoros.core.Khoros.users.impersonate_user`() method be used instead of authenticating as a secondary user with this method.

Returns:

The session key in string format

Raises:

get_total_count(collection, where_filter='', verify_success=True)[source]¶

This method retrieves the total asset count from a given collection (e.g. categories).

Parameters:

collection (str) – The collection object to use in the FROM clause of the LiQL query (e.g. users)
where_filter (str) – An optional filter to use as the WHERE clause in the LiQL query
verify_success (bool) – Determines if the API query should be verified as successful (True by default)

Returns:

The total count as an integer

Raises:

khoros.errors.exceptions.MissingRequiredDataError

static parse_v2_response(json_response, return_dict=False, status=False, error_msg=False, http_code=False, data_id=False, data_url=False, data_api_uri=False, v2_base='')[source]¶

This method parses an API response for a Community API v2 operation and returns parsed data.

Changed in version 3.2.0: The lower-level function call now utilizes keyword arguments to fix an argument mismatch issue.

New in version 2.5.0.

Parameters:

json_response (dict) – The API response in JSON format
return_dict (bool) – Defines if the parsed data should be returned within a dictionary
status (bool) – Defines if the status value should be returned
error_msg (bool) – Defines if the error message (and developer response message) should be returned
http_code (bool) – Defines if the HTTP status code should be returned
data_id (bool) – Defines if the ID should be returned
data_url (bool) – Defines if the URL should be returned
data_api_uri (bool) – Defines if the API URI should be returned
v2_base (str) – The base URL for the API v2

Returns:

A string, tuple or dictionary with the parsed data

Raises:

perform_v1_search(endpoint, filter_field, filter_value, return_json=False, fail_on_no_results=False)[source]¶

This method performs a search for a particular field value using a Community API v1 call.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Deprecated since version 3.0.0: Use the khoros.core.Khoros.V1.search() method instead.

Parameters:

endpoint (str) – The API v1 endpoint against which to perform the search query
filter_field (str) – The name of the field being queried within the API v1 endpoint
filter_value (str, int) – The value associated with the field being queried
return_json (bool) – Determines if the response should be returned in JSON format (False by default)
fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)

Returns:

The API response (optionally in JSON format)

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

post(query_url, payload=None, relative_url=True, return_json=True, content_type=None, headers=None, multipart=False, proxy_user_object=None)[source]¶

This method performs a simple POST request that leverages the Khoros authorization headers.

Changed in version 4.2.0: Resolved an issue that caused errors with absolute URLs, and made general code improvements were made to avoid unnecessary KeyError exceptions.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.5.0: The query_url no longer gets prefixed with a slash (/) if relative_url is set to False.

Changed in version 3.1.1: The content_type parameter now gets defined as an empty string prior to calling the sub-function.

New in version 3.1.0.

Parameters:

query_url (str) – The relative (default) or fully-qualified URL for the API call
payload (dict, str, None) –
The JSON or plaintext payload (if any) to be supplied with the API request

Todo

Add support for other payload formats such as binary, etc.
relative_url (bool) – Determines if the URL should be appended to the community domain (True by default)
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
content_type (str, None) –
Allows the content-type value to be explicitly defined if necessary

Note

If this parameter is not defined then the content type will be identified based on the payload format and/or type of request.
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the POST request

Raises:

put(query_url, payload=None, relative_url=True, return_json=True, content_type=None, headers=None, multipart=False, proxy_user_object=None)[source]¶

This method performs a simple PUT request that leverages the Khoros authorization headers.

Changed in version 4.2.0: Resolved an issue that caused errors with absolute URLs, and made general code improvements were made to avoid unnecessary KeyError exceptions.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.1.1: The content_type parameter now gets defined as an empty string prior to calling the sub-function.

New in version 3.1.0.

Parameters:

query_url (str) – The relative (default) or fully-qualified URL for the API call
payload (dict, str, None) –
The JSON or plaintext payload (if any) to be supplied with the API request

Todo

Add support for other payload formats such as binary, etc.
relative_url (bool) – Determines if the URL should be appended to the community domain (True by default)
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
content_type (str, None) –
Allows the content-type value to be explicitly defined if necessary

Note

If this parameter is not defined then the content type will be identified based on the payload format and/or type of request.
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the PUT request

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.PayloadMismatchError

query(query, return_json=True, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='', format_statements=True, return_items=False)[source]¶

This method performs a Community API v2 query using LiQL with the full LiQL syntax.

Changed in version 4.1.0: The JSON response can now be reduced to just the returned items by passing return_items=True.

Parameters:

query (str) – The full LiQL query in its standard syntax (not URL-encoded)
return_json (bool) – Determines if the API response should be returned in JSON format (True by default)
pretty_print (bool) – Defines if the response should be “pretty printed” (False by default)
track_in_lsi (bool) – Defines if the query should be tracked within LSI (False by default)
always_ok (bool) – Defines if the HTTP response should always be 200 OK (False by default)
error_code (str) – Allows an error code to optionally be supplied for testing purposes (ignored by default)
format_statements (bool) – Determines if statements (e.g. SELECT, FROM, et.) should be formatted to be in all caps (True by default)
return_items (bool) –
Reduces the JSON response to be only the list of items returned from the LiQL response (False by default)

Note

If an error response is returned then an empty list will be returned.

Returns:

The query response from the API in JSON format (unless defined otherwise)

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.GETRequestError

search(select_fields, from_source, where_filter='', order_by=None, order_desc=True, limit=0, return_json=True, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='', format_statements=True)[source]¶

This method performs a LiQL query in the Community API v2 by specifying the query elements.

Parameters:

select_fields (str, tuple, list, set) – One or more fields to be selected within the SELECT statement (e.g. id)
from_source (str) – The source of the data to use in the FROM statement (e.g. messages)
where_filter (str, tuple, list, dict, set) – The filters (if any) to use in the WHERE clause (e.g. id = '2')
order_by (str, tuple, set, dict, list) – The field(s) by which to order the response data (optional)
order_desc (bool) – Defines if the ORDER BY directionality is DESC (default) or ASC
limit (int) – Allows an optional limit to be placed on the response items (ignored by default)
return_json (bool) – Determines if the API response should be returned in JSON format (True by default)
pretty_print (bool) – Defines if the response should be “pretty printed” (False by default)
track_in_lsi (bool) – Defines if the query should be tracked within LSI (False by default)
always_ok (bool) – Defines if the HTTP response should always be 200 OK (False by default)
error_code (str) – Allows an error code to optionally be supplied for testing purposes (ignored by default)
format_statements (bool) – Determines if statements (e.g. SELECT, FROM, et.) should be formatted to be in all caps (True by default)

Returns:

The query response from the API in JSON format (unless defined otherwise)

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.OperatorMismatchError, khoros.errors.exceptions.InvalidOperatorError

signout()[source]¶: This method invalidates the active session key or SSO authentication session.

Changed in version 3.5.0: The unnecessary return statement at the end of the method has been removed.

Changed in version 3.3.2: Logging was introduced to report the successful session invalidation.

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

Core Module (khoros.core)¶

This module contains the core object and functions to establish the connection to the API and leverage it to perform various actions.

Module:: khoros.core
Synopsis:: Collection of core functions and tools to work with the Khoros Community APIs
Usage:: import khoros.core (Imported by default in primary package)
Example:: khoros = Khoros(helper='helper.yml')
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 11 Sep 2023

class khoros.core.Khoros(defined_settings=None, community_url=None, tenant_id=None, community_name=None, auth_type=None, session_auth=None, oauth2=None, sso=None, helper=None, env_variables=None, auto_connect=True, use_community_name=False, prefer_json=True, debug_mode=False, skip_env_variables=False, empty=False, ssl_verify=None, bulk_data_settings=None, logging_level=None)[source]¶

This is the class for the core object leveraged in this library.

class Album(khoros_object)[source]¶

This class includes methods for interacting with the albums collection.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Album inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

create(title=None, description=None, owner_id=None, hidden=False, default=False, full_response=False)[source]¶

This method creates a new image album for a user.

New in version 2.3.0.

Parameters:

title (str, None) – The title of the album to be created
description (str, None) – The description of the album
owner_id (str, int, None) –
The User ID of the album owner

Note

If not defined, the owner will be the user performing the API call.
hidden (bool) – Defines if the album should be public (default) or hidden
default (bool) – Defines if this will be the default album for the user (False by default)
full_response (bool) – Defines if the full response should be returned instead of the outcome (False by default)

Returns:

Boolean value indicating a successful outcome (default) or the full API response

get_albums_for_user(user_id=None, login=None, public=None, private=None, verify_success=False, allow_exceptions=True)[source]¶

This method returns data for the albums owned by a given user.

New in version 2.3.0.

Parameters:

user_id (str, int) – The User ID for the album owner
login (str) – The username of the album owner
public (bool) – Indicates that public albums should be returned (all albums returned by default)
private (bool) – Indicates that private albums should be returned (all albums returned by default)
verify_success (bool) – Optionally check to confirm that the API query was successful (False by default)
allow_exceptions (bool) –
Defines whether exceptions can be raised for responses returning errors

Caution

This does not apply to exceptions for missing required data.

Returns:

A list of dictionaries representing each album

Raises:

class Archives(khoros_object)[source]¶

This class includes methods for archiving content.

New in version 4.1.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Archives inner class object.

New in version 4.1.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

static aggregate_results(results, include_raw=False)[source]¶

This method aggregates the results of an archive/unarchive operation into an easy-to-parse dictionary.

New in version 4.1.0.

Parameters:

results (list, dict) – The results from an archive or unarchive operation
include_raw (bool) – Includes the raw API response in the aggregated data dictionary under the raw key (False by default)

Returns:

A dictionary with fields for status, archived, unarchived, failed and unknown or the raw response when the API call completely fails, with the optional raw data when requested

archive(message_id=None, message_url=None, suggested_url=None, archive_entries=None, aggregate_results=False, include_raw=False)[source]¶

This method archives one or more messages while providing an optional suggested URL as a placeholder.

New in version 4.1.0.

Parameters:

message_id (str, int, None) – The message ID for the content to be archived
message_url (str, None) – The URL of the message to be archived (as an alternative to the message_id argument)
suggested_url (str, None) – The full URL to suggest to the user when navigating to the archived message
archive_entries (dict, list, tuple, set, None) –
A dictionary mapping one or more message IDs with accompanying suggested URLs

Note

Alternatively, a list, tuple or set of message IDs can be supplied which will be converted into a dictionary with blank suggested URLs.
aggregate_results (bool) – Aggregates the operation results into an easy-to-parse dictionary (False by default)
include_raw (bool) –
Includes the raw API response in the aggregated data dictionary under the raw key (False by default)

Note

This parameter is only relevant when the aggregate_results parameter is True.

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

is_archived(message_id)[source]¶

This method checks to see whether a message is currently archived.

New in version 5.2.0.

Parameters:: message_id (str, int) – The message ID for the content to be archived
Returns:: Boolean value indicating whether the message is archived
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError

unarchive(message_id=None, message_url=None, new_board_id=None, archive_entries=None, aggregate_results=False, include_raw=False)[source]¶

This method unarchives one or more messages and moves them to a given board.

New in version 4.1.0.

Parameters:

message_id (str, int, None) – The message ID for the content to be archived
message_url (str, None) – The URL of the message to be archived (as an alternative to the message_id argument)
new_board_id (str, None) – The board ID of what will be the new parent board of a message getting unarchived
archive_entries (dict, list, tuple, set, None) –
A dictionary mapping one or more message IDs with accompanying board IDs

Note

Alternatively, a list, tuple or set of message IDs can be supplied which will be converted into a dictionary with blank board IDs.
aggregate_results (bool) – Aggregates the operation results into an easy-to-parse dictionary (False by default)
include_raw (bool) –
Includes the raw API response in the aggregated data dictionary under the raw key (False by default)

Note

This parameter is only relevant when the aggregate_results parameter is True.

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

class Board(khoros_object)[source]¶

This class includes methods for interacting with boards.

New in version 2.5.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Board inner class object.

New in version 2.5.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

board_exists(board_id=None, board_url=None)[source]¶

This method checks to see if a board (i.e. blog, contest, forum, idea exchange, Q&A or TKB) exists.

New in version 2.7.0.

Parameters:

board_id (str, None) – The ID of the board to check
board_url (str, None) – The URL of the board to check

Returns:

Boolean value indicating whether the board already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

create(board_id, board_title, discussion_style, description=None, parent_category_id=None, hidden=None, allowed_labels=None, use_freeform_labels=None, use_predefined_labels=None, predefined_labels=None, media_type=None, blog_authors=None, blog_author_ids=None, blog_author_logins=None, blog_comments_enabled=None, blog_moderators=None, blog_moderator_ids=None, blog_moderator_logins=None, one_entry_per_contest=None, one_kudo_per_contest=None, posting_date_end=None, posting_date_start=None, voting_date_end=None, voting_date_start=None, winner_announced_date=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)[source]¶

This method creates a new board within a Khoros Community environment.

Changed in version 2.5.2: Changed the functionality around the return_error_messages argument and added the split_errors argument.

New in version 2.5.0.

Parameters:

board_id (str) – The unique identifier (i.e. id field) for the new board (Required)
board_title (str) – The title of the new board (Required)
discussion_style (str) – Defines the board as a blog, contest, forum, idea, qanda or tkb (Required)
description (str, None) – A brief description of the board
parent_category_id (str, None) – The ID of the parent category (if applicable)
hidden (bool, None) – Defines whether the new board should be hidden from lists and menus (disabled by default)
allowed_labels (str, None) – The type of labels allowed on the board (freeform-only, predefined-only or freeform and pre-defined)
use_freeform_labels (bool, None) – Determines if freeform labels should be utilized
use_predefined_labels (bool, None) – Determines if pre-defined labels should be utilized
predefined_labels (list, None) –
The pre-defined labels to utilized on the board as a list of dictionaries

Todo

The ability to provide labels as a simple list and optionally standardize their format (e.g. Pascal Case, etc.) will be available in a future release.
media_type (str, None) – The media type associated with a contest. (image, video or story meaning text)
blog_authors (list, None) – The approved blog authors in a blog board as a list of user data dictionaries
blog_author_ids (list, None) – A list of User IDs representing the approved blog authors in a blog board
blog_author_logins (list, None) – A list of User Logins (i.e. usernames) representing approved blog authors in a blog board
blog_comments_enabled (bool, None) – Determines if comments should be enabled on blog posts within a blog board
blog_moderators (list, None) – The designated blog moderators in a blog board as a list of user data dictionaries
blog_moderator_ids (list, None) – A list of User IDs representing the blog moderators in a blog board
blog_moderator_logins (list, None) – A list of User Logins (i.e. usernames) representing blog moderators in a blog board
one_entry_per_contest (bool, None) – Defines whether a user can submit only one entry to a single contest
one_kudo_per_contest (bool, None) – Defines whether a user can vote only once per contest
posting_date_end (type[datetime.datetime], None) – The date/time when the contest is closed to submissions
posting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
voting_date_end (type[datetime.datetime], None) – The date/time when the voting period for a contest ends
voting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
winner_announced_date (type[datetime.datetime], None) – The date/time the contest winner will be announced
full_response (bool, None) – Determines whether the full, raw API response should be returned by the function
return_id (bool, None) – Determines if the ID of the new board should be returned by the function
return_url (bool, None) – Determines if the URL of the new board should be returned by the function
return_api_url (bool, None) – Determines if the API URL of the new board should be returned by the function
return_http_code (bool, None) – Determines if the HTTP Code of the API response should be returned by the function
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if the Developer Response Message (if any) associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError, ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

get_all_messages(board_id, fields=None, where_filter=None, descending=True)[source]¶

This function retrieves data for all messages within a given board.

Changed in version 5.4.0: Introduced the where_filter and descending parameters to optionally filter the LiQL query.

New in version 5.3.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
where_filter (str, tuple, list, set, None) – One or more optional WHERE filters to include in the LiQL query
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each message within the board

Raises:

get_all_topic_messages(board_id, fields=None, descending=True)[source]¶

This function retrieves data for all topic messages (i.e. zero-depth messages) within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each topic message within the board

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError

static get_board_id(url)[source]¶

This method retrieves the Board ID for a given board when provided its URL.

New in version 2.6.0.

Parameters:: url (str) – The URL from which to parse out the Board ID
Returns:: The Board ID retrieved from the URL
Raises:: khoros.errors.exceptions.InvalidURLError

get_message_count(board_id)[source]¶

This method retrieves the total number of messages within a given board.

New in version 5.3.0.

Parameters:: board_id (str) – The ID of the board to query
Returns:: The number of messages within the node

structure_payload(board_id, board_title, discussion_style, description=None, parent_category_id=None, hidden=None, allowed_labels=None, use_freeform_labels=None, use_predefined_labels=None, predefined_labels=None, media_type=None, blog_authors=None, blog_author_ids=None, blog_author_logins=None, blog_comments_enabled=None, blog_moderators=None, blog_moderator_ids=None, blog_moderator_logins=None, one_entry_per_contest=None, one_kudo_per_contest=None, posting_date_end=None, posting_date_start=None, voting_date_end=None, voting_date_start=None, winner_announced_date=None)[source]¶

This method structures the payload to use in a Community API v2 request involving a board.

New in version 2.6.0.

Parameters:

board_id (str) – The unique identifier (i.e. id field) for the new board (Required)
board_title (str) – The title of the new board (Required)
discussion_style (str) – Defines the board as a blog, contest, forum, idea, qanda or tkb (Required)
description (str, None) – A brief description of the board
parent_category_id (str, None) – The ID of the parent category (if applicable)
hidden (bool, None) – Defines whether the new board should be hidden from lists and menus (disabled by default)
allowed_labels (str, None) – The type of labels allowed on the board (freeform-only, predefined-only or freeform and pre-defined)
use_freeform_labels (bool, None) – Determines if freeform labels should be utilized
use_predefined_labels (bool, None) – Determines if pre-defined labels should be utilized
predefined_labels (list, None) –
The pre-defined labels to utilized on the board as a list of dictionaries

Todo

The ability to provide labels as a simple list and optionally standardize their format (e.g. Pascal Case, etc.) will be available in a future release.
media_type (str, None) – The media type associated with a contest. (image, video or story i.e. text)
blog_authors (list, None) – The approved blog authors in a blog board as a list of user data dictionaries
blog_author_ids (list, None) – A list of User IDs representing the approved blog authors in a blog board
blog_author_logins (list, None) – A list of User Logins (i.e. usernames) representing approved blog authors in a blog board
blog_comments_enabled (bool, None) – Determines if comments should be enabled on blog posts within a blog board
blog_moderators (list, None) – The designated blog moderators in a blog board as a list of user data dictionaries
blog_moderator_ids (list, None) – A list of User IDs representing the blog moderators in a blog board
blog_moderator_logins (list, None) – A list of User Logins (i.e. usernames) representing blog moderators in a blog board
one_entry_per_contest (bool, None) – Defines whether a user can submit only one entry to a single contest
one_kudo_per_contest (bool, None) – Defines whether a user can vote only once per contest
posting_date_end (type[datetime.datetime], None) – The date/time when the contest is closed to submissions
posting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
voting_date_end (type[datetime.datetime], None) – The date/time when the voting period for a contest ends
voting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
winner_announced_date (type[datetime.datetime], None) – The date/time the contest winner will be announced

Returns:

The full and properly formatted payload for the API request

Raises:

class BulkData(khoros_object)[source]¶

This class includes methods for interacting with the Bulk Data API.

New in version 5.0.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Board inner class object.

New in version 5.0.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

static count_actions(bulk_data, action_key)[source]¶

This function counts the number of events for a specific action key in a collection of bulk data.

New in version 5.2.0.

Parameters:

bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)
action_key (str) – The action.key value

Returns:

The number of events as an integer

Raises:

khoros.errors.exceptions.DataMismatchError, khoros.errors.exceptions.InvalidParameterError

static count_logins(bulk_data)[source]¶

This function counts the number of login events in a collection of bulk data.

New in version 5.2.0.

Parameters:: bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)
Returns:: The number of login events as an integer
Raises:: khoros.errors.exceptions.DataMismatchError

static count_views(bulk_data)[source]¶

This function counts the number of view events in a collection of bulk data.

New in version 5.2.0.

Parameters:: bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)
Returns:: The number of view events as an integer
Raises:: khoros.errors.exceptions.DataMismatchError

static filter_anonymous(bulk_data, remove_anonymous=None, remove_registered=None)[source]¶

This method filters bulk data entries to keep only registered (default) or anonymous user activities.

New in version 5.2.0.

Parameters:

bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)
remove_anonymous (bool, None) – Determines if all anonymous user activities should be removed (Default)
remove_registered (bool, None) – Determines if all registered user activities should be removed

Returns:

The filtered JSON data as a dictionary

Raises:

static filter_by_action(action_key, bulk_data)[source]¶

This method filters a Bulk Data API export for only entries with a specific action.key value.

New in version 5.2.0.

Parameters:

action_key (str) – The action.key value
bulk_data (dict) – The Bulk Data API export in JSON format (i.e. dictionary)

Returns:

The filtered JSON data as a dictionary

Raises:

TypeError, ValueError, khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.APIRequestError

get_base_url(community_id=None, europe=False)[source]¶

This method constructs and/or retrieves the base URL for the Bulk Data API.

New in version 5.0.0.

Note

The URL from the helper settings will be leveraged when available unless the community_id is explicitly defined as a function parameter.

Parameters:

community_id (str, None) – The Community ID to leverage in the URL
europe (bool) – Determines if the European URL should be utilized (False by default)

Returns:

The base URL for the Bulk Data API

query(community_id=None, client_id=None, token=None, from_date=None, to_date=None, fields=None, europe=None, export_type=None, full_response=False)[source]¶

This method performs a query against the Bulk Data API to retrieve CSV or JSON data.

New in version 5.0.0.

Parameters:

community_id (str, None) – The Community ID to leverage in the URL
client_id (str, None) – The Client ID used to authenticate to the Bulk Data API
token (str, None) – The access token used to authenticate to the Bulk Data API
from_date (str, None) – The From Date in YYYYmmDD or YYYYmmDDhhMM format.
to_date (str, None) – The To Date in YYYYmmDD or YYYYmmDDhhMM format.
fields (str, list, tuple, set, None) – Optional fields to include in the data export as a comma-separated string or iterable
europe (bool) – Determines if the European URL should be utilized (False by default)
export_type (str, None) – Determines if the data should be returned in csv (default) or json format
full_response (bool) – Determines if the full requests object should be returned (False by default)

Returns:

The CSV or JSON data for the Bulk Data API request (or the full requests object)

Raises:

class Category(khoros_object)[source]¶

This class includes methods for interacting with categories.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Category inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

category_exists(category_id=None, category_url=None)[source]¶

This method checks to see if a category exists.

New in version 2.7.0.

Parameters:

category_id (str, None) – The ID of the category to check
category_url (str, None) – The URL of the category to check

Returns:

Boolean value indicating whether the category already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

create(category_id, category_title, parent_id=None, return_json=True)[source]¶

This method creates a new category.

New in version 2.5.0.

Parameters:

category_id (str) – The Category ID of the new category (e.g. video-games)
category_title (str) – The title of the new category (e.g. Video Games)
parent_id (str, None) – The Category ID of the parent category (optional)
return_json (bool) – Determines whether the response should be returned in JSON format (True by default)

Returns:

The response from the API call

Raises:

ValueError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.APIConnectionError

friendly_date_enabled(identifier=None, category_details=None)[source]¶

This method identifies if friendly dates are enabled for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean indicating if friendly dates are enabled

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_active_skin(identifier=None, category_details=None)[source]¶

This method retrieves the skin being used with a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The name of the active skin in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_category_details(identifier, first_item=True)[source]¶

This method returns a dictionary of community configuration settings.

New in version 2.1.0.

Parameters:

identifier (str) – The Category ID or Category URL with which to identify the category
first_item (bool) – Filters the response data to the first item returned (True by default)

Returns:

The community details within a dictionary

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_category_field(field, identifier=None, category_details=None)[source]¶

This method returns a specific community field from the Khoros Community API.

New in version 2.1.0.

Parameters:

field (str) – The field whose value to return from the khoros.structures.base.Mapping class
identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

static get_category_id(url)[source]¶

This method retrieves the Category ID for a given category when provided its URL.

Parameters:: url (str) – The URL from which to parse out the Category ID
Returns:: The Category ID retrieved from the URL
Raises:: khoros.errors.exceptions.InvalidURLError

get_creation_date(identifier=None, category_details=None)[source]¶

This method retrieves the creation date of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The creation of the category in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_depth(identifier=None, category_details=None)[source]¶

This method retrieves the depth of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The depth of the category as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_description(identifier=None, category_details=None)[source]¶

This method retrieves the description for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The description in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_friendly_date_max_age(identifier=None, category_details=None)[source]¶

This method retrieves the maximum age where friendly dates should be used (if enabled) for a category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Integer representing the number of days the friendly date feature should be leveraged if enabled

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_language(identifier=None, category_details=None)[source]¶

This method retrieves the defined language for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The language (e.g. en) in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_id(identifier=None, category_details=None)[source]¶

This method retrieves the parent ID for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent ID in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_type(identifier=None, category_details=None)[source]¶

This method retrieves the parent type for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent type in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_url(identifier=None, category_details=None)[source]¶

This method retrieves the parent URL for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent URL in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_position(identifier=None, category_details=None)[source]¶

This method retrieves the position of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The position of the category as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_id(identifier=None, category_details=None)[source]¶

This method retrieves the root category ID for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category ID in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_type(identifier=None, category_details=None)[source]¶

This method retrieves the root category type for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category type in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_url(identifier=None, category_details=None)[source]¶

This method retrieves the root category URL for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category URL in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_title(identifier=None, full_title=True, short_title=False, category_details=None)[source]¶

This method retrieves the full and/or short title of the category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
full_title (bool) – Return the full title of the environment (True by default)
short_title (bool) – Return the short title of the environment (False by default)
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The title(s) of the environment as a string or a tuple of strings

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_total_category_count()[source]¶

This method returns the total number of categories within the Khoros Community environment.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Deprecated since version 2.6.0: Use the khoros.core.Khoros.Category.get_total_count() method instead.

Returns:: The total number of categories as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_total_count()[source]¶

This method returns the total number of categories within the Khoros Community environment.

New in version 2.6.0.

Returns:: The total number of categories as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_url(category_id=None, category_details=None)[source]¶

This method retrieves the URL of a given category.

New in version 2.1.0.

Parameters:

category_id (str, None) – The ID of the category to be evaluated (optional if category_details provided)
category_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The full URL of the category

Raises:

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_views(identifier=None, category_details=None)[source]¶

This method retrieves the total view count for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The total number of views

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

is_hidden(identifier=None, category_details=None)[source]¶

This method identifies whether a given category is hidden.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean value indicating if the category is hidden

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

class Community(khoros_object)[source]¶

This class includes methods for interacting with the overall Khoros Community.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Community inner class object.

New in version 2.1.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

email_confirmation_required_to_post(community_details=None)[source]¶

This method identifies if an email configuration is required before posting in the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if email configuration is required before posting
Raises:: khoros.errors.exceptions.GETRequestError

friendly_date_enabled(community_details=None)[source]¶

This method if the friendly date functionality is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the feature is enabled
Raises:: khoros.errors.exceptions.GETRequestError

get_active_skin(community_details=None)[source]¶

This method retrieves the primary active skin that is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The skin name as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_community_details()[source]¶

This method returns a dictionary of community configuration settings.

New in version 2.1.0.

Returns:: The community details within a dictionary
Raises:: khoros.errors.exceptions.GETRequestError

get_community_field(field, community_details=None)[source]¶

This method retrieves a particular field from the community collection in the API.

New in version 2.1.0.

Parameters:

field (str) – The field whose value to return from the khoros.structures.base.Mapping class
community_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_creation_date(community_details=None)[source]¶

This method retrieves the timestamp for the initial creation of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The creation date as a string (e.g. 2020-02-03T22:41:36.408-08:00)
Raises:: khoros.errors.exceptions.GETRequestError

get_date_pattern(community_details=None)[source]¶

This method retrieves the date pattern (e.g. yyyy-MM-dd) utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The date pattern in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_description(community_details=None)[source]¶

This method retrieves the description of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The description in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_friendly_date_max_age(community_details=None)[source]¶

This method identifies if the friendly date functionality is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the feature is enabled
Raises:: khoros.errors.exceptions.GETRequestError

get_language(community_details=None)[source]¶

This method retrieves the language (e.g. en) utilized in the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The language code as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_max_attachments(community_details=None)[source]¶

This method retrieves the maximum number of attachments permitted per message within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The value as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_ooyala_player_branding_id(community_details=None)[source]¶

This method retrieves the branding ID for the Ooyala Player utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The branding ID in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_permitted_attachment_types(community_details=None)[source]¶

This method retrieves the attachment file types permitted within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The permitted file types within a list
Raises:: khoros.errors.exceptions.GETRequestError

get_primary_url(community_details=None)[source]¶

This method retrieves the primary URL of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The primary URL in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_sign_out_url(community_details=None)[source]¶

This method retrieves the Sign Out URL for the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The Sign Out URL as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_tenant_id(community_details=None)[source]¶

This method retrieves the tenant ID of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The tenant ID in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_title(full_title=True, short_title=False, community_details=None)[source]¶

This method retrieves the full and/or short title of the environment.

New in version 2.1.0.

Parameters:

full_title (bool) – Return the full title of the environment (True by default)
short_title (bool) – Return the short title of the environment (False by default)
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The title(s) of the environment as a string or a tuple of strings

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

show_breadcrumb_at_top_level(community_details=None)[source]¶

This method identifies if breadcrumbs should be shown at the top level of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if breadcrumbs are displayed at the top level of the environment
Raises:: khoros.errors.exceptions.GETRequestError

show_community_node_in_breadcrumb(community_details=None)[source]¶

This method identifies if the community node should be shown in breadcrumbs.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the community node is displayed in bredcrumbs
Raises:: khoros.errors.exceptions.GETRequestError

sso_enabled(community_details=None)[source]¶

This function checks whether SSO is enabled for the community.

New in version 5.0.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: A Boolean value indicating whether SSO is enabled

top_level_categories_enabled(community_details=None)[source]¶

This method identifies if top level categories are enabled within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if top level categories are enabled
Raises:: khoros.errors.exceptions.GETRequestError

top_level_categories_on_community_page(community_details=None)[source]¶

This method identifies if top level categories are enabled on community pages.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if top level categories are enabled on community pages
Raises:: khoros.errors.exceptions.GETRequestError

class GroupHub(khoros_object)[source]¶

This class includes methods for interacting with group hubs.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.GroupHub inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

create(group_id, group_title, description=None, membership_type=None, open_group=None, closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None, enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None, enable_tkb=None, all_styles_default=True, parent_category_id=None, avatar_image_path=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)[source]¶

This method creates a new group hub within a Khoros Community environment.

New in version 2.6.0.

Parameters:

group_id (str, int) – The unique identifier (i.e. id field) for the new group hub (Required)
group_title (str) – The title of the group hub (Required)
description (str, None) – A brief description of the group hub
membership_type (dict, None) – The membership_type value (open, closed or closed_hidden)
open_group (bool, None) – Defines the group hub as an open group
closed_group (bool, None) – Defines the group hub as a closed group
hidden_group (bool, None) – Defines the group hub as a closed and hidden group
discussion_styles (list, None) – A list of discussion styles that will be permitted in the group hub
enable_blog (bool, None) – Defines that the blog discussion style should be enabled for the group hub
enable_contest (bool, None) – Defines that the contest discussion style should be enabled for the group hub
enable_forum (bool, None) – Defines that the forum discussion style should be enabled for the group hub
enable_idea (bool, None) – Defines that the idea discussion style should be enabled for the group hub
enable_qanda (bool, None) – Defines that the Q&A (qanda) discussion style should be enabled for the group hub
enable_tkb (bool, None) – Defines that the TKB (tkb) discussion style should be enabled for the group hub
all_styles_default (bool) – Enables all discussion styles if not otherwise specified
parent_category_id (str, int, None) – The parent category identifier (if applicable)
avatar_image_path (str, None) – The file path to the avatar image to be uploaded (if applicable)
full_response (bool, None) –
Determines whether the full, raw API response should be returned by the function

Caution

This argument overwrites the return_id, return_url, return_api_url, return_http_code, return_status and return_error_messages arguments.
return_id (bool, None) – Determines if the ID of the new group hub should be returned by the function
return_url (bool, None) – Determines if the URL of the new group hub should be returned by the function
return_api_url (bool, None) – Determines if the API URL of the new group hub should be returned by the function
return_http_code (bool, None) – Determines if the HTTP Code of the API response should be returned by the function
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if any error messages associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

get_total_count()[source]¶

This method returns the total number of group hubs within the Khoros Community environment.

Returns:: The total number of group hubs as an integer

grouphub_exists(grouphub_id=None, grouphub_url=None)[source]¶

This method checks to see if a group hub exists.

New in version 2.7.0.

Parameters:

grouphub_id (str, None) – The ID of the group hub to check
grouphub_url (str, None) – The URL of the group hub to check

Returns:

Boolean value indicating whether the group hub already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

structure_payload(group_id, group_title, description=None, membership_type=None, open_group=None, closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None, enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None, enable_tkb=None, all_styles_default=True, parent_category_id=None)[source]¶

This method structures the payload to use in a Group Hub API request.

New in version 2.6.0.

Parameters:

group_id (str, int) – The unique identifier (i.e. id field) for the new group hub (Required)
group_title (str) – The title of the group hub (Required)
description (str, None) – A brief description of the group hub
membership_type (dict, None) – The membership_type value (open, closed or closed_hidden)
open_group (bool, None) – Defines the group hub as an open group
closed_group (bool, None) – Defines the group hub as a closed group
hidden_group (bool, None) – Defines the group hub as a closed and hidden group
discussion_styles (list, None) – A list of discussion styles that will be permitted in the group hub
enable_blog (bool, None) – Defines if the blog discussion style should be enabled for the group hub
enable_contest (bool, None) – Defines if the contest discussion style should be enabled for the group hub
enable_forum (bool, None) – Defines if the forum discussion style should be enabled for the group hub
enable_idea (bool, None) – Defines if the idea discussion style should be enabled for the group hub
enable_qanda (bool, None) – Defines if the Q&A (qanda) discussion style should be enabled for the group hub
enable_tkb (bool, None) – Defines if the TKB (tkb) discussion style should be enabled for the group hub
all_styles_default (bool) – Defines if all discussion styles should be enabled if not otherwise specified
parent_category_id (str, int, None) – The parent category identifier (if applicable)

Returns:

The properly formatted payload for the API request

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError

update_title(new_title, group_hub_id=None, group_hub_url=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)[source]¶

This method updates the title of an existing group hub.

New in version 2.6.0.

Parameters:

new_title (str) – The new title for the group hub
group_hub_id (str, None) – The group hub ID that identifies the group hub to update (necessary if URL not provided)
group_hub_url (str, None) – The group hub URL that identifies the group hub to update (necessary if ID not provided)
full_response (bool, None) –
Determines whether the full, raw API response should be returned by the function

Caution

This argument overwrites the return_id, return_url, return_api_url, return_http_code, return_status and return_error_messages arguments.
return_id (bool, None) – Determines if the ID of the new group hub should be returned by the function
return_url (bool, None) – Determines if the URL of the new group hub should be returned by the function
return_api_url (bool, None) – Determines if the API URL of the new group hub should be returned by the function
return_http_code (bool, None) – Determines if the HTTP Code of the API response should be returned by the function
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if any error messages associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError

class Label(khoros_object)[source]¶

This class includes methods for interacting with labels.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Label inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

get_labels_for_message(message_id)[source]¶

This method retrieves the labels associated with a specific message.

New in version 5.3.0.

Parameters:: message_id (str, int) – The ID associated with the message to query
Returns:: A list of strings for the labels
Raises:: khoros.errors.exceptions.GETRequestError

class Message(khoros_object)[source]¶

This class includes methods for interacting with messages.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Message inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

create(subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None, context_id=None, context_url=None, cover_image=None, images=None, is_answer=None, is_draft=None, labels=None, product_category=None, products=None, read_only=None, seo_title=None, seo_description=None, tags=None, ignore_non_string_tags=False, teaser=None, topic=None, videos=None, attachment_file_paths=None, full_payload=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False, proxy_user_object=None)[source]¶

This method creates a new message within a given node.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be created on behalf of other users.

Changed in version 4.3.0: It is now possible to pass the pre-constructed full JSON payload into the function via the full_payload parameter as an alternative to defining each field individually.

Changed in version 2.8.0: The ignore_non_string_tags, return_status, return_error_messages and split_errors arguments were introduced.

New in version 2.3.0.

Parameters:

subject (str, None) – The title or subject of the message
body (str, None) – The body of the message in HTML format
node (dict, None) – A dictionary containing the id key and its associated value indicating the destination
node_id (str, None) – The ID of the node in which the message will be published
node_url (str, None) –
The URL of the node in which the message will be published

Note

This argument is necessary in the absence of the node and node_id arguments.
canonical_url (str, None) – The search engine-friendly URL to the message
context_id (str, None) – Metadata on a message to identify the message with an external identifier of your choice
context_url (str, None) – Metadata on a message representing a URL to associate with the message (external identifier)
cover_image (dict, None) – The cover image set for the message
images (dict, None) – The query to retrieve images uploaded to the message
is_answer (bool, None) – Designates the message as an answer on a Q&A board
is_draft (bool, None) – Indicates whether the message is still a draft (i.e. unpublished)
labels (dict, None) – The query to retrieve labels applied to the message
product_category (dict, None) – The product category (i.e. container for products) associated with the message
products (dict, None) – The product in a product catalog associated with the message
read_only (bool, None) – Indicates whether the message should be read-only or have replies/comments blocked
seo_title (str, None) – The title of the message used for SEO purposes
seo_description (str, None) – A description of the message used for SEO purposes
tags (dict, None) – The query to retrieve tags applied to the message
ignore_non_string_tags (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
teaser (str, None) – The message teaser (used with blog articles)
topic (dict, None) – The root message of the conversation in which the message appears
videos (dict, None) – The query to retrieve videos uploaded to the message
attachment_file_paths (str, tuple, list, set, None) – The full path(s) to one or more attachment (e.g. path/to/file1.pdf)
full_payload (dict, str, None) –
Pre-constructed full JSON payload as a dictionary (preferred) or a JSON string with the following syntax:
{ "data": { "type": "message", } }
Note

The type field shown above is essential for the payload to be valid.
full_response (bool, None) –
Defines if the full response should be returned instead of the outcome (False by default)

Caution

This argument overwrites the return_id, return_url, return_api_url and return_http_code arguments.
return_id (bool, None) – Indicates that the Message ID should be returned (False by default)
return_url (bool, None) – Indicates that the Message URL should be returned (False by default)
return_api_url (bool, None) – Indicates that the API URL of the message should be returned (False by default)
return_http_code (bool, None) – Indicates that the HTTP status code of the response should be returned (False by default)
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if the Developer Response Message (if any) associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to create the message on behalf of a secondary user.

Returns:

Boolean value indicating a successful outcome (default) or the full API response

Raises:

TypeError, ValueError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

define_context_id(msg_id, context_id='', full_response=False)[source]¶

This method defines the context_id metadata value for a given message.

New in version 5.0.0.

Parameters:

msg_id (str) – The message ID to query
context_id (str) – The value to be written to the context_id metadata field (Empty by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value to indicate the success of the operation or alternatively the full API response

Raises:

define_context_url(msg_id, context_url='', full_response=False)[source]¶

This function defines the context_url metadata value for a given message.

New in version 5.0.0.

Parameters:

msg_id (str) – The message ID to query
context_url (str) – The value to be written to the context_url metadata field (Empty by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value to indicate the success of the operation or alternatively the full API response

Raises:

khoros.errors.exceptions.MessageTypeNotFoundError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.MessageTypeNotFoundError, khoros.errors.exceptions.InvalidURLError

flag(msg_id)[source]¶

This method flags a message as spam.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be flagged
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

format_content_mention(content_info=None, content_id=None, title=None, url=None)[source]¶

This method formats the <li-message> HTML tag for a content @mention.

New in version 2.4.0.

Parameters:

content_info (dict, None) –
A dictionary containing the 'id' and/or 'login' key(s) with the user data

Note

This argument is necessary if the Title and URL are not explicitly passed using the title and url function arguments.
content_id (str, int, None) –
The Message ID (aka Content ID) associated with the content mention

Note

This is an optional argument as the ID can be retrieved from the URL.
title (str, None) – The display title for the content mention (e.g. "Click Here")
url (str, None) – The fully-qualified URL of the message being mentioned

Returns:

The properly formatted <li-message> HTML tag in string format

Raises:

format_user_mention(user_info=None, user_id=None, login=None)[source]¶

This method formats the <li-user> HTML tag for a user @mention.

New in version 2.4.0.

Parameters:

user_info (dict, None) –
A dictionary containing the 'id' and/or 'login' key(s) with the user information

Note

This argument is necessary if the User ID and/or Login are not explicitly passed using the user_id and/or login function arguments.
user_id (str, int, None) – The unique user identifier (i.e. User ID) for the user
login (str, None) – The login (i.e. username) for the user

Returns:

The properly formatted <li-user> HTML tag in string format

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

get_all_messages(board_id, fields=None, where_filter=None, descending=True)[source]¶

This function retrieves data for all messages within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
where_filter (str, tuple, list, set, None) – One or more optional WHERE filters to include in the LiQL query
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each message within the board

Raises:

get_all_topic_messages(board_id, fields=None, descending=True)[source]¶

This function retrieves data for all topic messages (i.e. zero-depth messages) within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each topic message within the board

Raises:

get_context_id(msg_id)[source]¶

This method retrieves the Context ID value for a given message ID.

New in version 5.0.0.

Parameters:: msg_id (str) – The message ID to query
Returns:: The value of the Context ID metadata field
Raises:: khoros.errors.exceptions.get_context_id

get_context_url(msg_id)[source]¶

This method retrieves the Context URL value for a given message ID.

New in version 5.0.0.

Parameters:: msg_id (str) – The message ID to query
Returns:: The value of the Context URL metadata field
Raises:: khoros.errors.exceptions.get_context_id

get_kudos_for_message(message_id, count_only=False)[source]¶

This function retrieves the kudos for a given message ID and returns the full data or the kudos count.

New in version 5.4.0.

Parameters:

message_id (str) – The ID of the message for which to retrieve the kudos
count_only (bool) – Determines if only the kudos count should be returned (False by default)

Returns:

The JSON data for the message kudos or the simple kudos count as an integer

Raises:

khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

get_metadata(msg_id, metadata_key)[source]¶

This method retrieves the value for a specific metadata key associated with a given message.

New in version 4.5.0.

Parameters:

msg_id (str, int) – The ID of the message for which the metadata will be retrieved
metadata_key (str) – The metadata key for which the value will be retrieved

Returns:

The metadata value

Raises:

khoros.errors.exceptions.MissingRequiredDataError', :py:exc:`khoros.errors.exceptions.InvalidMetadataError, khoros.errors.exceptions.GETRequestError

kudo(msg_id)[source]¶

This method kudos (i.e. “likes”) a message.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be kudoed
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

label(msg_id, label_text)[source]¶

This function adds a single label to a given message.

New in version 5.1.0.

Parameters:

msg_id (str, int) – The ID of the message to be flagged
label_text (str) – The label to be added

Returns:

The API response in JSON format

Raises:

static parse_v2_response(json_response, return_dict=False, status=False, response_msg=False, http_code=False, message_id=False, message_url=False, message_api_uri=False, v2_base='')[source]¶

This method parses an API response for a message operation (e.g. creating a message) and returns data.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Changed in version 3.2.0: The lower-level function call now utilizes keyword arguments to fix an argument mismatch issue.

Deprecated since version 2.5.0: Use the khoros.core.Khoros.parse_v2_response() function instead.

New in version 2.3.0.

Parameters:

json_response (dict) – The API response in JSON format
return_dict (bool) – Defines if the parsed data should be returned within a dictionary
status (bool) – Defines if the status value should be returned
response_msg (bool) – Defines if the developer response message should be returned
http_code (bool) – Defines if the HTTP status code should be returned
message_id (bool) – Defines if the message ID should be returned
message_url (bool) – Defines if the message URL should be returned
message_api_uri (bool) – Defines if the ** message API URI** should be returned
v2_base (str) – The base URL for the API v2

Returns:

A string, tuple or dictionary with the parsed data

Raises:

khoros.errors.exceptions.MissingRequiredDataError

tag(msg_id, tag_text)[source]¶

This function adds a single tag to a given message.

New in version 5.1.0.

Parameters:

msg_id (str, int) – The ID of the message to be flagged
tag_text (str) – The tag to be added

Returns:

The API response in JSON format

Raises:

khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

unflag(msg_id)[source]¶

This method flags a message as not being spam.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be flagged
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

update(msg_id=None, msg_url=None, subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None, context_id=None, context_url=None, cover_image=None, is_draft=None, labels=None, moderation_status=None, parent=None, product_category=None, products=None, read_only=None, topic=None, status=None, seo_title=None, seo_description=None, tags=None, overwrite_tags=False, ignore_non_string_tags=False, teaser=None, attachments_to_add=None, attachments_to_remove=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False, proxy_user_object=None)[source]¶

This method updates one or more elements of an existing message.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be updated on behalf of other users.

New in version 2.8.0.

Parameters:

msg_id (str, int, None) – The ID of the existing message
msg_url (str, None) – The URL of the existing message
subject (str, None) – The title or subject of the message
body (str, None) – The body of the message in HTML format
node (dict, None) – A dictionary containing the id key and its associated value indicating the destination
node_id (str, None) – The ID of the node in which the message will be published
node_url (str, None) –
The URL of the node in which the message will be published

Note

This argument is necessary in the absence of the node and node_id arguments.
canonical_url (str, None) – The search engine-friendly URL to the message
context_id (str, None) – Metadata on a message to identify the message with an external identifier of your choosing
context_url (str, None) – Metadata on a message representing a URL to associate with the message (external identifier)
cover_image (dict, None) – The cover image set for the message
is_draft (bool, None) – Indicates whether the message is still a draft (i.e. unpublished)
labels (dict, None) – The query to retrieve labels applied to the message
moderation_status (str, None) –
The moderation status of the message

Note

Acceptable values are unmoderated, approved, rejected, marked_undecided, marked_approved and marked_rejected.
parent (str, None) – The parent of the message
product_category (dict, None) – The product category (i.e. container for products) associated with the message
products (dict, None) – The product in a product catalog associated with the message
read_only (bool, None) – Indicates whether the message should be read-only or have replies/comments blocked
topic (dict, None) – The root message of the conversation in which the message appears
status (dict, None) –
The message status for messages where conversation.style is idea or contest

Caution

This property is not returned if the message has the default Unspecified status assigned. It will only be returned for ideas with a status of Completed or with a custom status created in Community Admin.
seo_title (str, None) – The title of the message used for SEO purposes
seo_description (str, None) – A description of the message used for SEO purposes
tags (dict, None) – The query to retrieve tags applied to the message
overwrite_tags (bool) – Determines if tags should overwrite any existing tags (where applicable) or if the tags should be appended to the existing tags (default)
ignore_non_string_tags (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
teaser (str, None) – The message teaser (used with blog articles)
attachments_to_add (str, tuple, list, set, None) – The full path(s) to one or more attachments (e.g. path/to/file1.pdf) to be added to the message
attachments_to_remove (str, tuple, list, set, None) –
One or more attachments to remove from the message

Note

Each attachment should specify the attachment id of the attachment to remove, which begins with m#_. (e.g. m283_file1.pdf)
full_response (bool, None) –
Defines if the full response should be returned instead of the outcome (False by default)

Caution

This argument overwrites the return_id, return_url, return_api_url and return_http_code arguments.
return_id (bool, None) – Indicates that the Message ID should be returned (False by default)
return_url (bool, None) – Indicates that the Message URL should be returned (False by default)
return_api_url (bool, None) – Indicates that the API URL of the message should be returned (False by default)
return_http_code (bool, None) – Indicates that the HTTP status code of the response should be returned (False by default)
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if the Developer Response Message (if any) associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to create the message on behalf of a secondary user.

Returns:

Boolean value indicating a successful outcome (default) or the full API response

Raises:

TypeError, ValueError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

static validate_message_payload(payload)[source]¶

This method validates the payload for a message to ensure that it can be successfully utilized.

New in version 4.3.0.

Parameters:: payload (dict, str) – The message payload to be validated as a dictionary (preferred) or a JSON string.
Returns:: The payload as a dictionary
Raises:: khoros.errors.exceptions.InvalidMessagePayloadError

class Node(khoros_object)[source]¶

This class includes methods for interacting with nodes.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Node inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

get_avatar_url(identifier, node_details=None, original=True, tiny=False, small=False, medium=False, large=False)[source]¶

This method retrieves one or more avatar URLs for a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
original (bool) – Indicates if the URL for the original-size image should be returned (True by default)
tiny (bool) – Indicates if the URL for the image in a tiny size should be returned (False by default)
small (bool) – Indicates if the URL for the image in a small size should be returned (False by default)
medium (bool) – Indicates if the URL for the image in a medium size should be returned (False by default)
large (bool) – Indicates if the URL for the image in a large size should be returned (False by default)

Returns:

A single URL as a string (default) or a dictionary of multiple URLs by size

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_creation_date(identifier, node_details=None, friendly=False)[source]¶

This method returns the creation date of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
friendly (bool) – Defines if the “friendly” date (e.g. Friday) should be returned (False by default)

Returns:

The creation date as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_depth(identifier, node_details=None)[source]¶

This method returns the depth of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The depth as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_description(identifier, node_details=None)[source]¶

This method returns the description of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node description as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_discussion_style(identifier, node_details=None)[source]¶

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_node_details(identifier, first_item=True)[source]¶

This method returns a dictionary of node configuration settings.

New in version 2.1.0.

Parameters:

identifier (str) – The Node ID or Node URL with which to identify the node
first_item (bool) – Filters the response data to the first item returned (True by default)

Returns:

The node details within a dictionary

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_node_field(field, identifier=None, node_details=None)[source]¶

This method returns a specific node field from the Khoros Community API.

New in version 2.1.0.

Parameters:

field (str) – The field to return from the khoros.structures.base.Mapping class
identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

static get_node_id(url, node_type=None)[source]¶

This method retrieves the Node ID for a given node within a URL.

Parameters:

url (str) – The URL from which to parse out the Node ID
node_type (str, None) – The node type (e.g. blog, tkb, message, etc.) for the object in the URL

Returns:

The Node ID retrieved from the URL

Raises:

khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.NodeIDNotFoundError, khoros.errors.exceptions.NodeTypeNotFoundError

static get_node_type_from_url(url)[source]¶

This method attempts to retrieve a node type by analyzing a supplied URL.

Parameters:: url (str) – The URL from which to extract the node type
Returns:: The node type based on the URL provided
Raises:: khoros.errors.exceptions.NodeTypeNotFoundError

get_parent_id(identifier, node_details=None, include_prefix=False)[source]¶

This method returns the Parent ID of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
include_prefix (bool) – Determines if the prefix (e.g. category:) should be included (Default: False)

Returns:

The Parent ID as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_type(identifier, node_details=None)[source]¶

This method returns the parent type of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The parent type as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_url(identifier, node_details=None)[source]¶

This method returns the parent URL of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The parent URL as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_position(identifier, node_details=None)[source]¶

This method returns the position of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The position as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_id(identifier, node_details=None, include_prefix=False)[source]¶

This method returns the Root Category ID of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
include_prefix (bool) – Defines if the prefix (e.g. category:) should be included (False by default)

Returns:

The Root Category ID as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_type(identifier, node_details=None)[source]¶

This method returns the root category type of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The root category type as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_url(identifier, node_details=None)[source]¶

This method returns the root category URL of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The root category URL as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_title(identifier=None, full_title=True, short_title=False, node_details=None)[source]¶

This method retrieves the full and/or short title of the node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
full_title (bool) – Determines if the full title of the node should be returned (True by default)
short_title (bool) – Determines if the short title of the node should be returned (False by default)
node_details (dict, None) – Dictionary containing node details (optional)

Returns:

The node title(s) as a string or a tuple of strings

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_total_node_count()[source]¶

This method returns the total number of nodes within the Khoros Community environment.

Returns:: The total number of nodes as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_type(identifier, node_details=None)[source]¶

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_url(node_id=None, node_details=None)[source]¶

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

node_id (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_views(identifier, node_details=None)[source]¶

This method returns the views for a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The views as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

is_hidden(identifier, node_details=None)[source]¶

This method identifies whether a given node is hidden.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

Boolean indicating whether the node is hidden

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

node_exists(node_id=None, node_url=None)[source]¶

This method checks to see if a node exists.

New in version 2.7.0.

Parameters:

node_id (str, None) – The ID of the node to check
node_url (str, None) – The URL of the node to check

Returns:

Boolean value indicating whether the node already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

class Role(khoros_object)[source]¶

This class includes methods relating to roles and permissions.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Role inner class object.

New in version 2.4.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

assign_roles_to_user(user, lookup_type='id', roles_to_add=None, node=None, node_type='board', v1=False, return_json=True)[source]¶

This method assigns a user to one or more roles.

New in version 4.0.0.

Parameters:

user (str) – The identifier (i.e. ID, login or email) of the user to be assigned to the role
lookup_type (str) – The lookup type for the user identifier (id, login or email)
roles_to_add (str, list, tuple, set) – One or more roles (Role IDs or Role Names) to which the user will be assigned
node (str, None) – The Node ID of the node to which the role is scoped when applicable
node_type (str) – The type of node to which the role is scoped (e.g. board (default), category, etc.)
v1 (bool) – Determines if the Community API v1 should be used to perform the operation (False by default)
return_json (bool) – Determines if the response should be returned as JSON rather than XML (True by default)

Returns:

The response from the API request

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.UnsupportedNodeTypeError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PUTRequestError

static get_role_id(role_name, scope='community', node_id=None)[source]¶

This method constructs and returns the Role ID associated with a given role name and scope.

New in version 4.0.0.

Parameters:

role_name (str) – The name of the role (e.g. Administrator, Moderator, Owner, etc.)
scope (str) – The scope of the role (community by default)
node_id (str, None) – The associated Node ID for any role that does not have a global/community scope.

Returns:

The properly constructed Role ID where applicable

Raises:

khoros.errors.exceptions.InvalidRoleError, khoros.errors.exceptions.MissingRequiredDataError

get_roles_for_user(user_id, fields=None)[source]¶

This method returns all roles associated with a given User ID.

Changed in version 4.1.0: The docstring has been updated to reference the correct exception raised by this method.

Changed in version 3.5.0: Fields to return in the LiQL query can now be explicitly defined.

New in version 2.4.0.

Parameters:

user_id (str) – The User ID for which to retrieve the roles data
fields (str, list, tuple, set, None) –
The field(s) to retrieve from the LiQL query as a string or list

Note

All fields (i.e. SELECT *) are returned unless fields are explicitly defined.

Returns:

A dictionary with data for each role associated with the given User ID

Raises:

khoros.errors.exceptions.DataMismatchError, khoros.errors.exceptions.MissingRequiredDataError

get_total_role_count(return_dict=False, total=True, top_level=False, board=False, category=False, group_hub=False)[source]¶

This method retrieves the total role count for one or more role type(s).

New in version 2.4.0.

Parameters:

return_dict (bool) – Determines if the data should be returned as a dictionary (False by default)
total (bool) – Indicates that the total overall role count should be returned (True by default)
top_level (bool) – Indicates that the total top-level role count should be returned (False by default)
board (bool) – Indicates that the total board-level role count should be returned (False by default)
category (bool) – Indicates that the total category-level role count should be returned (False by default)
group_hub (bool) – Indicates that the total group hub-level role count should be returned (False by default)

Returns:

The role count(s) as an integer, tuple or dictionary, depending on the arguments supplied

Raises:

khoros.objects.roles.InvalidRoleTypeError

get_users_with_role(fields='login', role_id=None, role_name=None, scope=None, node_id=None, limit_per_query=1000, simple=False)[source]¶

This method retrieves a list of all users that have a specific role.

New in version 3.5.0.

Parameters:

fields (str, tuple, list, set) –
One or more fields from the Users object to return (login field by default)

See also

The fields that can be used are found in the Khoros developer documentation.
role_id (str, None) – The identifier for the role in node_type:node_id:role_name format
role_name (str, None) –
The simple role name (e.g. Administrator)

Caution

This option should only be used when the role name is unique within the community at all node levels.
scope (str, None) –
The scope of the role (e.g. board, category, community, grouphub)

Note

If a value is not supplied and only a role name is defined then the role scope is assumed to be at the community level. (i.e. global)
node_id (str, None) –
The Node ID associated with the role (where applicable)

Note

If a value is not supplied and only a role name is defined then the role scope is assumed to be at the community level. (i.e. global)
limit_per_query (int, str) –
Defines a LIMIT constraint other than the default 1000 limit per LiQL query

Note

Unless modified by Khoros Support or Professional Services, 1000 is the maximum number of entries that can be returned in a single LiQL query.
simple (bool) – Returns a simple list of the strings or tuples of the value(s) for each user (False by default)

Returns:

A list of users as strings, tuples or dictionaries depending if simple mode is enabled

Raises:

class SAML(khoros_object)[source]¶

This class includes methods relating to SAML 2.0 authentication and user provisioning.

New in version 4.3.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.SAML inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

static import_assertion(file_path, base64_encode=True, url_encode=True)[source]¶

This method imports an XML SAML assertion as a string and optionally base64- and/or URL-encodes it.

New in version 4.3.0.

Parameters:

file_path (str) – The file path to the XML file to import
base64_encode (bool) – Determines if the assertion should be base64-encoded (True by default)
url_encode (bool) – Determines if the assertion should be URL-encoded (True by default)

Returns:

The SAML assertion string

Raises:

FileNotFoundError

send_assertion(assertion=None, file_path=None, base64_encode=True, url_encode=True)[source]¶

This method sends a SAML assertion as a POST request in order to provision a new user.

New in version 4.3.0.

Parameters:

assertion (str, None) – The SAML assertion in string format and optionally base64- and/or URL-encoded
file_path (str, None) – The file path to the XML file to import that contains the SAML assertion
base64_encode (bool) – Determines if the assertion should be base64-encoded (True by default)
url_encode (bool) – Determines if the assertion should be URL-encoded (True by default)

Returns:

The API response from the POST request

Raises:

khoros.errors.exceptions.MissingRequiredDataError

class Settings(khoros_object)[source]¶

This class includes methods relating to the retrieval and defining of various settings.

New in version 3.2.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Settings inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

define_node_setting(setting_name, setting_val, node_id, node_type='board', return_json=True)[source]¶

This method defines a particular setting value for a given node.

Changed in version 4.0.0: The default value for the return_json parameter is now True.

Changed in version 3.3.2: The return_json parameter has been introduced which returns a simple JSON object (as a dict) indicating whether the operation was successful. (Currently False by default)

New in version 3.2.0.

Parameters:

setting_name (str) – The name of the setting field for which to retrieve the value
setting_val (str) – The value of the setting to be defined
node_id (str) – The ID of the node associated with the setting to retrieve
node_type (str) – Defines the node as a board (default), category or grouphub
return_json (bool) –
Returns a simple JSON dictionary indicating the operation result (True by default)

Caution

An unsuccessful REST call will result in the raising of the khoros.errors.exceptions.PostRequestError exception if the return_json parameter is set to False.

Returns:

The API response as a dictionary

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.PayloadMismatchError

get_node_setting(setting_name, node_id, node_type='board', v1=None, convert_json=False)[source]¶

This method retrieves the value of a specific node setting.

Changed in version 3.3.2: The convert_json parameter has been introduced which optionally converts a JSON string into a dictionary.

New in version 3.2.0.

Parameters:

setting_name (str) – The name of the setting field for which to retrieve the value
node_id (str) – The ID of the node associated with the setting to retrieve
node_type (str) – Defines the node as a board (default), category or grouphub
v1 (bool, None) – Optionally defines a specific Community API version to use when retrieving the value
convert_json (bool) – Optionally converts a JSON string into a Python dictionary (False by default)

Returns:

The value of the setting for the node

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.LiQLParseError

class Studio(khoros_object)[source]¶

This class includes methods relating to the Lithium SDK and Studio Plugin.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Studio inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

static get_node_version()[source]¶

This method identifies and returns the installed Node.js version.

New in version 2.5.1.

Returns:: The version as a string or None if not installed

static get_npm_version()[source]¶

This method identifies and returns the installed npm version.

New in version 2.5.1.

Returns:: The version as a string or None if not installed

static get_sdk_version()[source]¶

This method identifies the currently installed version of the Lithium SDK.

New in version 2.5.1.

Returns:: The SDK version in string format or None if not installed

static node_installed()[source]¶

This method checks whether Node.js is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether Node.js is installed

static npm_installed()[source]¶

This method checks whether npm is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether npm is installed

static sdk_installed()[source]¶

This method checks to see if the Lithium SDK is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether the Lithium SDK is installed

class Subscription(khoros_object)[source]¶

This class includes methods relating to subscriptions.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Subscription inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

add_subscription(target_id, target_type='board', payload=None, included_boards=None, excluded_boards=None, proxy_user_object=None)[source]¶

This method adds a subscription to a given target for the current user.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

target_id (str, int) – The unique identifier for the target (e.g. Node ID, Message ID, etc.)
target_type – The target type such as board (default), message, category, etc.
payload (dict, None) – Pre-constructed payload to use in the API call
included_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be included in the partial subscription
excluded_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be excluded from the partial subscription
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

get_subscription_uri()[source]¶

This method returns the subscriptions URI for the v2 API to perform API calls.

New in version 3.5.0.

Returns:: The full (absolute) URI for the subscriptions v2 API endpoint

subscribe_to_board(node_id, proxy_user_object=None)[source]¶

This method subscribes the current user to an individual message.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

node_id (str) – The unique identifier for a board (i.e. Board ID)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_category(node_id, included_boards=None, excluded_boards=None, proxy_user_object=None)[source]¶

This method subscribes the current user to a full or partial category.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

node_id (str) – The unique identifier (i.e. Node ID) for the category
included_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be included in the partial subscription
excluded_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be excluded from the partial subscription
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_label(label, board_id, proxy_user_object=None)[source]¶

This method subscribes the current user to label found on a board.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

label (str, int) – The label to which to subscribe
board_id (str) – The unique identifier (i.e. Node ID) for the board where the label is found
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_message(msg_id, proxy_user_object=None)[source]¶

This method subscribes the current user to an individual message.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

msg_id (str, int) – The unique identifier for an individual message
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_product(product_id, proxy_user_object=None)[source]¶

This method subscribes the current user to a product.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

product_id (str, int) – The unique identifier for a product
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

class Tag(khoros_object)[source]¶

This class includes methods relating to the tagging of content.

New in version 4.1.0.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.Tag inner class object.

New in version 4.1.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

add_single_tag_to_message(tag, msg_id, allow_exceptions=False)[source]¶

This method adds a single tag to an existing message.

New in version 4.1.0.

Parameters:

tag (str) – The tag value to be added
msg_id (str, int) – The unique identifier for the message
allow_exceptions (bool) – Determines if exceptions are permitted to be raised (False by default)

Returns:

None

Raises:

add_tags_to_message(tags, msg_id, allow_exceptions=False)[source]¶

This method adds one or more tags to an existing message.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 4.1.0.

..caution:: This function is not the most effective way to add multiple tags to a message. It is recommended: that the khoros.core.Khoros.messages.update() method be used instead with its tags argument, which is more efficient and performance-conscious.

Parameters:

tags (str, tuple, list, set) – One or more tags to be added to the message
msg_id (str, int) – The unique identifier for the message
allow_exceptions (bool) – Determines if exceptions are permitted to be raised (False by default)

Returns:

None

Raises:

khoros.errors.exceptions.UserCreationError

get_tags_for_message(msg_id)[source]¶

This method retrieves the tags for a given message.

New in version 4.1.0.

Parameters:: msg_id (str, int) – The Message ID for the message from which to retrieve tags
Returns:: A list of tags associated with the message

static structure_single_tag_payload(tag_text)[source]¶

This method structures the payload for a single tag.

New in version 4.1.0.

Parameters:: tag_text (str) – The tag to be included in the payload
Returns:: The payload as a dictionary
Raises:: khoros.errors.exceptions.InvalidPayloadValueError

structure_tags_for_message(*tags, msg_id=None, overwrite=False, ignore_non_strings=False, wrap_json=False)[source]¶

This method structures tags to use within the payload for creating or updating a message.

Changed in version 4.3.0: Introduced the wrap_json parameter to wrap the tags in a dictionary within the items key.

New in version 4.1.0.

Parameters:

tags (str, list, tuple, set) – One or more tags or list of tags to be structured
msg_id (str, int, None) – Message ID of an existing message so that its existing tags can be retrieved (optional)
overwrite (bool) – Determines if tags should overwrite any existing tags (where applicable) or if the tags should be appended to the existing tags (default)
ignore_non_strings (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
wrap_json (bool) – Determines if the list of tags should be wrapped in the {"items": []} JSON structure – In other words, a dictionary rather than a list (False by default)

Returns:

A list of properly formatted tags to act as the value for the tags field in the message payload

class User(khoros_object)[source]¶

This class includes methods for interacting with users.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.User inner class object.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

create(user_settings=None, login=None, email=None, password=None, first_name=None, last_name=None, biography=None, sso_id=None, web_page_url=None, cover_image=None, ignore_exceptions=False)[source]¶

This method creates a new user in the Khoros Community environment.

Changed in version 4.0.0: This function now returns the API response and the ignore_exceptions parameter has been introduced.

Changed in version 3.5.0: The unnecessary return statement at the end of the method has been removed.

Parameters:

user_settings (dict, None) – Allows all user settings to be passed to the function within a single dictionary
login (str, None) – The username (i.e. login) for the user (required)
email (str, None) – The email address for the user (required)
password (str, None) – The password for the user
first_name (str, None) – The user’s first name (i.e. given name)
last_name (str, None) – The user’s last name (i.e. surname)
biography (str, None) – The user’s biography for their profile
sso_id (str, None) – The Single Sign-On (SSO) ID for the user
web_page_url (str, None) – The URL to the user’s website
cover_image (str, None) – The cover image to be used on the user’s profile
ignore_exceptions (bool) – Defines whether to raise the khoros.errors.exceptions.UserCreationError exception if the creation attempt fails (False by default)

Returns:

The response to the user creation API request

Raises:

delete(user_id, return_json=False)[source]¶

This method deletes a user from the Khoros Community environment.

Parameters:

user_id (str, int) – The User ID of the user to be deleted
return_json (bool) – Determines if the API response should be returned in JSON format (False by default)

Returns:

The API response (optionally in JSON format)

Raises:

khoros.errors.exceptions.FeatureNotConfiguredError

get_album_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the number of albums for a user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of albums found for the user as an integer

Raises:

get_all_users(fields=None, order_by='last_visit_time', order_by_desc=True)[source]¶

This function retrieves data for all users.

New in version 5.3.0.

Parameters:

fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
order_by (str) – The order by which to sort the data (last_visit_time by default)
order_by_desc (bool) – Indicates if the data should be sorted in descending (default) or ascending order

Returns:

A list containing a dictionary of data for each user

Raises:

get_all_users_count()[source]¶

This method retrieves the total number of users on the community.

New in version 5.2.0.

Returns:: The user count for total users as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_email(user_settings=None, user_id=None, login=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶

This method retrieves the email address for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: User ID, username, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (str, None) – The User ID of the user
login (str, None) – The username of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of email addresses to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The email address of the user as a string or a list of emails if allow_multiple is True

get_followers_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of community members who have added the user as a friend in the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of community members who have added the user as a friend in integer format

Raises:

get_following_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of community members the user has added as a friend in the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of community members the user has added as a friend in integer format

Raises:

get_ids_from_login_list(login_list, return_type='list')[source]¶

This method identifies the User IDs associated with a list of user logins. (i.e. usernames)

Parameters:

login_list (list, tuple) – List of user login (i.e. username) values in string format
return_type (str) – Determines if the data should be returned as a list (default) or a dict

Returns:

A list or dictionary with the User IDs

Raises:

get_images_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of images uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of images uploaded by the user in integer format

Raises:

get_kudos_given_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of kudos a user has given.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of kudos given by the user in integer format

Raises:

get_kudos_received_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of kudos a user has received.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of kudos received by the user in integer format

Raises:

get_last_visit_timestamp(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves the timestamp for the last time the user logged into the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The last visit timestamp in string format

Raises:

get_login(user_settings=None, user_id=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶: This is an alternative method name for the khoros.core.Khoros.User.get_username() method.

get_messages_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of messages (topics and replies) posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of messages (topics and replies) posted by the user in integer format

Raises:

get_online_user_count()[source]¶

This method retrieves the number of users currently online.

Returns:: The user count for online users as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_online_users_count(anonymous=None, registered=None)[source]¶

This method returns the total count of users currently online.

New in version 5.0.0.

Parameters:

anonymous (bool, None) – Filters the results to only anonymous (non-registered) users
registered (bool, None) – Filters the results to only registered users

Returns:

An integer of the total online users count

Raises:

get_public_images_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of public images uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of public images uploaded by the user in integer format

Raises:

get_registered_users_count()[source]¶

This method returns the total count of registered users on the community.

New in version 5.0.0.

Returns:: An integer of the total registered users count

get_registration_data(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves the registration data for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

A dictionary containing the registration data for the user

Raises:

get_registration_status(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves the registration status for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The registration status in string format

Raises:

get_registration_timestamp(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves the timestamp for when a given user registered for an account.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The registration timestamp in string format

Raises:

get_replies_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of replies posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of replies posted by the user in integer format

Raises:

get_roles_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of roles applied to the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of roles applied to the user in integer format

Raises:

get_solutions_authored_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of messages created by the user that are marked as accepted solutions.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of messages created by the user that are marked as accepted solutions in integer format

Raises:

get_topics_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of topic messages (excluding replies) posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of topic messages (excluding replies) posted by the user in integer format

Raises:

get_user_data(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method retrieves all user data for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

A dictionary containing the user data for the user

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidParameterError

get_user_id(user_settings=None, login=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶

This method looks up and retrieves the User ID for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: login, email, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
login (str, None) – The username of the user
email (str, None) – The email address of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of User IDs to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The User ID of the user as an integer or a list of User IDs if allow_multiple is True

get_username(user_settings=None, user_id=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶

This method looks up and retrieves the username for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: User ID, email, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (str, None) – The User ID of the user
email (str, None) – The email address of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of usernames to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The username (i.e. login) of the user or a list of usernames if allow_multiple is True

get_users_count(registered=False, online=False)[source]¶

This method returns the total number of users in an environment. (Filtering possible for registered and online)

New in version 5.3.0.

Parameters:

registered (bool) – Return a count of registered users (False by default)
online (bool) – Return a count of online users (False by default)

Returns:

An integer defining the total user count for the environment

Raises:

get_videos_count(user_settings=None, user_id=None, login=None, email=None)[source]¶

This method gets the count of videos uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of videos uploaded by the user in integer format

Raises:

impersonate_user(user_login)[source]¶

This method instantiates and returns the :py:class`khoros.objects.users.ImpersonatedUser` object which: can then be passed to other methods and functions to perform operations as a secondary user.

Note

The authenticated user must have the Administrator role and/or have the Switch User permission enabled.

New in version 4.0.0.

Parameters:: user_login (str) – The username (i.e. login) of the user to be impersonated
Returns:: The instantiated :py:class`khoros.objects.users.ImpersonatedUser` object

query_users_table_by_id(select_fields, user_id)[source]¶

This method queries the users table for one or more given SELECT fields for a specific User ID.

Parameters:

select_fields (str, tuple, list, set) – One or more SELECT field (e.g. login, messages.count(*), etc.) to query
user_id (int, str) – The User ID associated with the user

Returns:

The API response for the performed LiQL query

Raises:

ValueError, TypeError, khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError

update_sso_id(new_sso_id, user_id=None, user_login=None)[source]¶

This method updates the SSO ID for a user.

New in version 4.5.0.

Parameters:

new_sso_id (str) – The new SSO ID for the user
user_id (str, int, None) – The numeric User ID that identifies the user
user_login (str, None) – The username that identifies the user

Returns:

The API response

Raises:

py:exc:khoros.errors.exceptions.MissingRequiredDataError

class V1(khoros_object)[source]¶

This class includes methods for performing base Community API v1 requests.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.V1 inner class object.

New in version 3.0.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

get(endpoint, query_params=None, return_json=True, proxy_user_object=None)[source]¶

This method makes a Community API v1 GET request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.0.0.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

post(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False, proxy_user_object=None)[source]¶

This method makes a Community API v1 POST request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.2.0: Introduced the ability to pass the query parameters as payload to avoid URI length limits.

New in version 3.0.0.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
params_in_uri (bool) – Determines if query parameters should be passed in the URI rather than in the request body (False by default)
json_payload (bool) –
Determines if query parameters should be passed as JSON payload rather than in the URI (False by default)

Caution

This is not yet fully supported and therefore should not be used at this time.
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

ValueError, TypeError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

put(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False, proxy_user_object=None)[source]¶

This method makes a Community API v1 PUT request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.2.0: Introduced the ability to pass the query parameters as payload to avoid URI length limits.

New in version 3.0.0.

Caution

While PUT requests are technically supported in this library, at this time they are not yet supported by the Khoros Community API v1 endpoints.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
params_in_uri (bool) – Determines if query parameters should be passed in the URI rather than in the request body (False by default)
json_payload (bool) –
Determines if query parameters should be passed as JSON payload rather than in the URI (False by default)

Caution

This is not yet fully supported and therefore should not be used at this time.
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

ValueError, TypeError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

search(endpoint, filter_field, filter_value, return_json=False, fail_on_no_results=False, proxy_user_object=None)[source]¶

This method performs a search for a particular field value using a Community API v1 call.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.0.0.

Parameters:

endpoint (str) – The API v1 endpoint against which to perform the search query
filter_field (str) – The name of the field being queried within the API v1 endpoint
filter_value (str, int) – The value associated with the field being queried
return_json (bool) – Determines if the response should be returned in JSON format (False by default)
fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response (optionally in JSON format)

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError

class V2(khoros_object)[source]¶

This class includes methods for performing base Community API v2 requests.

__init__(khoros_object)[source]¶

This method initializes the khoros.core.Khoros.V2 inner class object.

New in version 4.0.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object

get(endpoint, return_json=True, headers=None, proxy_user_object=None)[source]¶

This method performs a Community API v2 GET request that leverages the Khoros authorization headers.

New in version 4.0.0.

Parameters:

endpoint (str) – The API v2 endpoint aginst which to query
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the GET request

Raises:

post(endpoint, payload=None, return_json=True, content_type=None, headers=None, multipart=False, proxy_user_object=None)[source]¶

This method performs a Community API v2 POST request that leverages the Khoros authorization headers.

New in version 4.0.0.

Parameters:

endpoint (str) – The relative (default) or fully-qualified URL for the API call
payload (dict, str, None) –
The JSON or plaintext payload (if any) to be supplied with the API request

Todo

Add support for other payload formats such as binary, etc.
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
content_type (str, None) –
Allows the content-type value to be explicitly defined if necessary

Note

If this parameter is not defined then the content type will be identified based on the payload format and/or type of request.
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the POST request

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

put(endpoint, payload=None, return_json=True, content_type=None, headers=None, multipart=False, proxy_user_object=None)[source]¶

This method performs a Community API v2 PUT request that leverages the Khoros authorization headers.

New in version 4.0.0.

Parameters:

endpoint (str) – The relative (default) or fully-qualified URL for the API call
payload (dict, str, None) –
The JSON or plaintext payload (if any) to be supplied with the API request

Todo

Add support for other payload formats such as binary, etc.
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
content_type (str, None) –
Allows the content-type value to be explicitly defined if necessary

Note

If this parameter is not defined then the content type will be identified based on the payload format and/or type of request.
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the PUT request

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.PayloadMismatchError

__init__(defined_settings=None, community_url=None, tenant_id=None, community_name=None, auth_type=None, session_auth=None, oauth2=None, sso=None, helper=None, env_variables=None, auto_connect=True, use_community_name=False, prefer_json=True, debug_mode=False, skip_env_variables=False, empty=False, ssl_verify=None, bulk_data_settings=None, logging_level=None)[source]¶

This method instantiates the core Khoros object.

Changed in version 5.0.0: Added support for the Bulk Data API.

Changed in version 4.3.0: Fixed an issue where the ssl_verify parameter was being mostly disregarded.

Changed in version 4.2.0: Introduced support for LithiumSSO Token authentication and made some general code improvements.

Changed in version 3.4.0: Introduced the ssl_verify parameter and established a key-value pair for it in the core_settings dictionary for the object.

Changed in version 3.3.2: Method arguments are no longer ignored if they are implicitly False and instead only the arguments that explicitly have a None value are ignored. The skip_env_variables argument has also been introduced to explicitly ignore any valid environment variables, as well as the empty argument to optionally instantiate an empty instantiated object. Logging was also added in various locations throughout the method.

Changed in version 3.3.0: Changed settings to defined_settings and _settings to _core_settings.

Parameters:

defined_settings (dict, None) – Predefined settings that the object should use
community_url (str, None) – The base URL of the Khoros community instance (e.g. community.khoros.com)
tenant_id (str, None) – The tenant ID for the Khoros community instance (e.g. lithosphere)
community_name (str, None) – The community name (e.g. community-name) for the Khoros community instance
auth_type (str, None) – The authentication type to use when connecting to the instance (session_auth by default)
session_auth (dict, None) – The username and password values for session key authentication
oauth2 (dict, None) – The client_id, client_secret and redirect_url values for OAuth 2.0 authentication
sso (dict, None) – The values for single sign-on (SSO) authentication
helper (str, tuple, list, dict, None) – The path (and optional file type) to the YAML or JSON helper configuration file
env_variables (dict, str, None) – A dictionary (or file path to a YAML or JSON file) that maps environment variable names
auto_connect (bool) – Determines if a connection should be established when initialized (True by default)
use_community_name (bool) – Defines if the community name should be used in the API URLs (False by default)
prefer_json (bool) – Defines preference that API responses be returned in JSON format (True by default)
debug_mode (bool) – Determines if Debug Mode should be enabled for development purposes (False by default)
skip_env_variables (bool) – Explicitly ignores any valid environment variables (False by default)
empty (bool) – Instantiates an empty object to act as a placeholder with default values (False by default)
ssl_verify (bool, None) – Determines whether to verify the server’s TLS certificate (True by default)
bulk_data (dict, None) – The values for utilizing the Bulk Data API

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.SessionAuthenticationError

close()[source]¶: This core method destroys the instance.

Changed in version 3.5.0: The unnecessary pass statement at the end of the method has been removed.

connect(connection_type=None)[source]¶

This method establishes a connection to the environment using a specified authentication type.

Changed in version 4.2.0: Introduced support for LithiumSSO Token authentication and made general code improvements to avoid unnecessary KeyError exceptions. Also fixed an issue with the exception error message.

Changed in version 3.3.2: Added logging for the khoros.errors.exceptions.CurrentlyUnsupportedError exception.

Parameters:: connection_type (str, None) – The type of authentication method (e.g. session_auth)
Returns:: None
Raises:: khoros.errors.exceptions.CurrentlyUnsupportedError

get(query_url, relative_url=True, return_json=True, headers=None, proxy_user_object=None)[source]¶

This method performs a simple GET request that leverages the Khoros authorization headers.

Changed in version 4.2.0: Resolved an issue that caused errors with absolute URLs, and made general code improvements were made to avoid unnecessary KeyError exceptions.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Parameters:

query_url (str) – The relative (default) or fully-qualified URL for the API call
relative_url (bool) – Determines if the URL should be appended to the community domain (True by default)
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the GET request

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError

get_platform_version(full_release=False, simple=False, commit_id=False, timestamp=False)[source]¶

This method retrieves the Khoros Community platform version information for a given environment.

New in version 3.4.0.

Parameters:

full_release (bool) –
Defines if the full platform release version should be returned

Note

If none of the options are enabled then the full_release option will be enabled by default.
simple (bool) – Defines if the simple X.Y version (e.g. 20.6) should be returned (False by default)
commit_id (bool) – Defines if the Commit ID (i.e. hash) for the release should be returned (False by default)
timestamp (bool) – Defines if the timestamp of the release (e.g. 2007092156) should be returned (False by default)

Returns:

One or more string with version information

Raises:

khoros.errors.exceptions.SessionAuthenticationError

get_session_key(username=None, password=None)[source]¶

This method retrieves the session key for an authentication session.

New in version 3.5.0.

Parameters:

username (str, None) – The username (i.e. login) of a secondary user to authenticate (optional)
password (str, None) –
The password of a secondary user to authenticate (optional)

Caution

It is recommended that the khoros.core.Khoros.users.impersonate_user`() method be used instead of authenticating as a secondary user with this method.

Returns:

The session key in string format

Raises:

get_total_count(collection, where_filter='', verify_success=True)[source]¶

This method retrieves the total asset count from a given collection (e.g. categories).

Parameters:

collection (str) – The collection object to use in the FROM clause of the LiQL query (e.g. users)
where_filter (str) – An optional filter to use as the WHERE clause in the LiQL query
verify_success (bool) – Determines if the API query should be verified as successful (True by default)

Returns:

The total count as an integer

Raises:

khoros.errors.exceptions.MissingRequiredDataError

static parse_v2_response(json_response, return_dict=False, status=False, error_msg=False, http_code=False, data_id=False, data_url=False, data_api_uri=False, v2_base='')[source]¶

This method parses an API response for a Community API v2 operation and returns parsed data.

Changed in version 3.2.0: The lower-level function call now utilizes keyword arguments to fix an argument mismatch issue.

New in version 2.5.0.

Parameters:

json_response (dict) – The API response in JSON format
return_dict (bool) – Defines if the parsed data should be returned within a dictionary
status (bool) – Defines if the status value should be returned
error_msg (bool) – Defines if the error message (and developer response message) should be returned
http_code (bool) – Defines if the HTTP status code should be returned
data_id (bool) – Defines if the ID should be returned
data_url (bool) – Defines if the URL should be returned
data_api_uri (bool) – Defines if the API URI should be returned
v2_base (str) – The base URL for the API v2

Returns:

A string, tuple or dictionary with the parsed data

Raises:

perform_v1_search(endpoint, filter_field, filter_value, return_json=False, fail_on_no_results=False)[source]¶

This method performs a search for a particular field value using a Community API v1 call.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Deprecated since version 3.0.0: Use the khoros.core.Khoros.V1.search() method instead.

Parameters:

endpoint (str) – The API v1 endpoint against which to perform the search query
filter_field (str) – The name of the field being queried within the API v1 endpoint
filter_value (str, int) – The value associated with the field being queried
return_json (bool) – Determines if the response should be returned in JSON format (False by default)
fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)

Returns:

The API response (optionally in JSON format)

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

post(query_url, payload=None, relative_url=True, return_json=True, content_type=None, headers=None, multipart=False, proxy_user_object=None)[source]¶

This method performs a simple POST request that leverages the Khoros authorization headers.

Changed in version 4.2.0: Resolved an issue that caused errors with absolute URLs, and made general code improvements were made to avoid unnecessary KeyError exceptions.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.5.0: The query_url no longer gets prefixed with a slash (/) if relative_url is set to False.

Changed in version 3.1.1: The content_type parameter now gets defined as an empty string prior to calling the sub-function.

New in version 3.1.0.

Parameters:

query_url (str) – The relative (default) or fully-qualified URL for the API call
payload (dict, str, None) –
The JSON or plaintext payload (if any) to be supplied with the API request

Todo

Add support for other payload formats such as binary, etc.
relative_url (bool) – Determines if the URL should be appended to the community domain (True by default)
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
content_type (str, None) –
Allows the content-type value to be explicitly defined if necessary

Note

If this parameter is not defined then the content type will be identified based on the payload format and/or type of request.
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the POST request

Raises:

put(query_url, payload=None, relative_url=True, return_json=True, content_type=None, headers=None, multipart=False, proxy_user_object=None)[source]¶

This method performs a simple PUT request that leverages the Khoros authorization headers.

Changed in version 4.2.0: Resolved an issue that caused errors with absolute URLs, and made general code improvements were made to avoid unnecessary KeyError exceptions.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.1.1: The content_type parameter now gets defined as an empty string prior to calling the sub-function.

New in version 3.1.0.

Parameters:

query_url (str) – The relative (default) or fully-qualified URL for the API call
payload (dict, str, None) –
The JSON or plaintext payload (if any) to be supplied with the API request

Todo

Add support for other payload formats such as binary, etc.
relative_url (bool) – Determines if the URL should be appended to the community domain (True by default)
return_json (bool) – Determines if the API response should be converted into JSON format (True by default)
content_type (str, None) –
Allows the content-type value to be explicitly defined if necessary

Note

If this parameter is not defined then the content type will be identified based on the payload format and/or type of request.
headers (dict, None) – Allows the API call headers to be manually defined rather than using only the core object
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response from the PUT request

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.PayloadMismatchError

query(query, return_json=True, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='', format_statements=True, return_items=False)[source]¶

This method performs a Community API v2 query using LiQL with the full LiQL syntax.

Changed in version 4.1.0: The JSON response can now be reduced to just the returned items by passing return_items=True.

Parameters:

query (str) – The full LiQL query in its standard syntax (not URL-encoded)
return_json (bool) – Determines if the API response should be returned in JSON format (True by default)
pretty_print (bool) – Defines if the response should be “pretty printed” (False by default)
track_in_lsi (bool) – Defines if the query should be tracked within LSI (False by default)
always_ok (bool) – Defines if the HTTP response should always be 200 OK (False by default)
error_code (str) – Allows an error code to optionally be supplied for testing purposes (ignored by default)
format_statements (bool) – Determines if statements (e.g. SELECT, FROM, et.) should be formatted to be in all caps (True by default)
return_items (bool) –
Reduces the JSON response to be only the list of items returned from the LiQL response (False by default)

Note

If an error response is returned then an empty list will be returned.

Returns:

The query response from the API in JSON format (unless defined otherwise)

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.GETRequestError

search(select_fields, from_source, where_filter='', order_by=None, order_desc=True, limit=0, return_json=True, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='', format_statements=True)[source]¶

This method performs a LiQL query in the Community API v2 by specifying the query elements.

Parameters:

select_fields (str, tuple, list, set) – One or more fields to be selected within the SELECT statement (e.g. id)
from_source (str) – The source of the data to use in the FROM statement (e.g. messages)
where_filter (str, tuple, list, dict, set) – The filters (if any) to use in the WHERE clause (e.g. id = '2')
order_by (str, tuple, set, dict, list) – The field(s) by which to order the response data (optional)
order_desc (bool) – Defines if the ORDER BY directionality is DESC (default) or ASC
limit (int) – Allows an optional limit to be placed on the response items (ignored by default)
return_json (bool) – Determines if the API response should be returned in JSON format (True by default)
pretty_print (bool) – Defines if the response should be “pretty printed” (False by default)
track_in_lsi (bool) – Defines if the query should be tracked within LSI (False by default)
always_ok (bool) – Defines if the HTTP response should always be 200 OK (False by default)
error_code (str) – Allows an error code to optionally be supplied for testing purposes (ignored by default)
format_statements (bool) – Determines if statements (e.g. SELECT, FROM, et.) should be formatted to be in all caps (True by default)

Returns:

The query response from the API in JSON format (unless defined otherwise)

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.OperatorMismatchError, khoros.errors.exceptions.InvalidOperatorError

signout()[source]¶: This method invalidates the active session key or SSO authentication session.

Changed in version 3.5.0: The unnecessary return statement at the end of the method has been removed.

Changed in version 3.3.2: Logging was introduced to report the successful session invalidation.

Core Functionality Subclasses (khoros.core.Khoros)¶

These classes below are inner/nested classes within the core khoros.core.Khoros class.

Note

The classes themselves are PascalCase format and singular (e.g. Node, Category, etc.) whereas the names used to call the inner class methods are all lowercase (or snake_case) and plural. (e.g. core_object.nodes.get_node_id(), core_object.categories.get_category_id(), etc.)

Studio Subclass (khoros.core.Khoros.Studio)¶

class Khoros.Studio(khoros_object)[source]

This class includes methods relating to the Lithium SDK and Studio Plugin.

static get_node_version()[source]

This method identifies and returns the installed Node.js version.

New in version 2.5.1.

Returns:: The version as a string or None if not installed

static get_npm_version()[source]

This method identifies and returns the installed npm version.

New in version 2.5.1.

Returns:: The version as a string or None if not installed

static get_sdk_version()[source]

This method identifies the currently installed version of the Lithium SDK.

New in version 2.5.1.

Returns:: The SDK version in string format or None if not installed

static node_installed()[source]

This method checks whether Node.js is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether Node.js is installed

static npm_installed()[source]

This method checks whether npm is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether npm is installed

static sdk_installed()[source]

This method checks to see if the Lithium SDK is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether the Lithium SDK is installed

ValueError, TypeError, khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError

V1 Subclass (khoros.core.Khoros.V1)¶

class Khoros.V1(khoros_object)[source]

This class includes methods for performing base Community API v1 requests.

get(endpoint, query_params=None, return_json=True, proxy_user_object=None)[source]

This method makes a Community API v1 GET request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.0.0.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

post(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False, proxy_user_object=None)[source]

This method makes a Community API v1 POST request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.2.0: Introduced the ability to pass the query parameters as payload to avoid URI length limits.

New in version 3.0.0.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
params_in_uri (bool) – Determines if query parameters should be passed in the URI rather than in the request body (False by default)
json_payload (bool) –
Determines if query parameters should be passed as JSON payload rather than in the URI (False by default)

Caution

This is not yet fully supported and therefore should not be used at this time.
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

ValueError, TypeError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

put(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False, proxy_user_object=None)[source]

This method makes a Community API v1 PUT request.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

Changed in version 3.2.0: Introduced the ability to pass the query parameters as payload to avoid URI length limits.

New in version 3.0.0.

Caution

While PUT requests are technically supported in this library, at this time they are not yet supported by the Khoros Community API v1 endpoints.

Parameters:

endpoint (str) – The API endpoint to be queried
query_params (dict) – The field and associated values to be leveraged in the query string
return_json (bool) – Determines if the response should be returned in JSON format rather than the default
params_in_uri (bool) – Determines if query parameters should be passed in the URI rather than in the request body (False by default)
json_payload (bool) –
Determines if query parameters should be passed as JSON payload rather than in the URI (False by default)

Caution

This is not yet fully supported and therefore should not be used at this time.
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response

Raises:

ValueError, TypeError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

search(endpoint, filter_field, filter_value, return_json=False, fail_on_no_results=False, proxy_user_object=None)[source]

This method performs a search for a particular field value using a Community API v1 call.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.0.0.

Parameters:

endpoint (str) – The API v1 endpoint against which to perform the search query
filter_field (str) – The name of the field being queried within the API v1 endpoint
filter_value (str, int) – The value associated with the field being queried
return_json (bool) – Determines if the response should be returned in JSON format (False by default)
fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response (optionally in JSON format)

Raises:

khoros.errors.exceptions.MissingRequiredDataError

Core Structure Subclasses (khoros.core.Khoros)¶

The classes below are inner/nested classes within the core khoros.core.Khoros class.

Note

The classes themselves are PascalCase format and singular (e.g. Node, Category, etc.) whereas the names used to call the inner class methods are all lowercase (or snake_case) and plural. (e.g. core_object.nodes.get_node_id(), core_object.categories.get_category_id(), etc.)

Board Subclass (khoros.core.Khoros.Board)¶

class Khoros.Board(khoros_object)[source]

This class includes methods for interacting with boards.

New in version 2.5.0.

board_exists(board_id=None, board_url=None)[source]

This method checks to see if a board (i.e. blog, contest, forum, idea exchange, Q&A or TKB) exists.

New in version 2.7.0.

Parameters:

board_id (str, None) – The ID of the board to check
board_url (str, None) – The URL of the board to check

Returns:

Boolean value indicating whether the board already exists

Raises:

create(board_id, board_title, discussion_style, description=None, parent_category_id=None, hidden=None, allowed_labels=None, use_freeform_labels=None, use_predefined_labels=None, predefined_labels=None, media_type=None, blog_authors=None, blog_author_ids=None, blog_author_logins=None, blog_comments_enabled=None, blog_moderators=None, blog_moderator_ids=None, blog_moderator_logins=None, one_entry_per_contest=None, one_kudo_per_contest=None, posting_date_end=None, posting_date_start=None, voting_date_end=None, voting_date_start=None, winner_announced_date=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)[source]

This method creates a new board within a Khoros Community environment.

Changed in version 2.5.2: Changed the functionality around the return_error_messages argument and added the split_errors argument.

New in version 2.5.0.

Parameters:

board_id (str) – The unique identifier (i.e. id field) for the new board (Required)
board_title (str) – The title of the new board (Required)
discussion_style (str) – Defines the board as a blog, contest, forum, idea, qanda or tkb (Required)
description (str, None) – A brief description of the board
parent_category_id (str, None) – The ID of the parent category (if applicable)
hidden (bool, None) – Defines whether the new board should be hidden from lists and menus (disabled by default)
allowed_labels (str, None) – The type of labels allowed on the board (freeform-only, predefined-only or freeform and pre-defined)
use_freeform_labels (bool, None) – Determines if freeform labels should be utilized
use_predefined_labels (bool, None) – Determines if pre-defined labels should be utilized
predefined_labels (list, None) –
The pre-defined labels to utilized on the board as a list of dictionaries

Todo

The ability to provide labels as a simple list and optionally standardize their format (e.g. Pascal Case, etc.) will be available in a future release.
media_type (str, None) – The media type associated with a contest. (image, video or story meaning text)
blog_authors (list, None) – The approved blog authors in a blog board as a list of user data dictionaries
blog_author_ids (list, None) – A list of User IDs representing the approved blog authors in a blog board
blog_author_logins (list, None) – A list of User Logins (i.e. usernames) representing approved blog authors in a blog board
blog_comments_enabled (bool, None) – Determines if comments should be enabled on blog posts within a blog board
blog_moderators (list, None) – The designated blog moderators in a blog board as a list of user data dictionaries
blog_moderator_ids (list, None) – A list of User IDs representing the blog moderators in a blog board
blog_moderator_logins (list, None) – A list of User Logins (i.e. usernames) representing blog moderators in a blog board
one_entry_per_contest (bool, None) – Defines whether a user can submit only one entry to a single contest
one_kudo_per_contest (bool, None) – Defines whether a user can vote only once per contest
posting_date_end (type[datetime.datetime], None) – The date/time when the contest is closed to submissions
posting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
voting_date_end (type[datetime.datetime], None) – The date/time when the voting period for a contest ends
voting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
winner_announced_date (type[datetime.datetime], None) – The date/time the contest winner will be announced
full_response (bool, None) – Determines whether the full, raw API response should be returned by the function
return_id (bool, None) – Determines if the ID of the new board should be returned by the function
return_url (bool, None) – Determines if the URL of the new board should be returned by the function
return_api_url (bool, None) – Determines if the API URL of the new board should be returned by the function
return_http_code (bool, None) – Determines if the HTTP Code of the API response should be returned by the function
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if the Developer Response Message (if any) associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError, ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

get_all_messages(board_id, fields=None, where_filter=None, descending=True)[source]

This function retrieves data for all messages within a given board.

Changed in version 5.4.0: Introduced the where_filter and descending parameters to optionally filter the LiQL query.

New in version 5.3.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
where_filter (str, tuple, list, set, None) – One or more optional WHERE filters to include in the LiQL query
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each message within the board

Raises:

get_all_topic_messages(board_id, fields=None, descending=True)[source]

This function retrieves data for all topic messages (i.e. zero-depth messages) within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each topic message within the board

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError

static get_board_id(url)[source]

This method retrieves the Board ID for a given board when provided its URL.

New in version 2.6.0.

Parameters:: url (str) – The URL from which to parse out the Board ID
Returns:: The Board ID retrieved from the URL
Raises:: khoros.errors.exceptions.InvalidURLError

get_message_count(board_id)[source]

This method retrieves the total number of messages within a given board.

New in version 5.3.0.

Parameters:: board_id (str) – The ID of the board to query
Returns:: The number of messages within the node

structure_payload(board_id, board_title, discussion_style, description=None, parent_category_id=None, hidden=None, allowed_labels=None, use_freeform_labels=None, use_predefined_labels=None, predefined_labels=None, media_type=None, blog_authors=None, blog_author_ids=None, blog_author_logins=None, blog_comments_enabled=None, blog_moderators=None, blog_moderator_ids=None, blog_moderator_logins=None, one_entry_per_contest=None, one_kudo_per_contest=None, posting_date_end=None, posting_date_start=None, voting_date_end=None, voting_date_start=None, winner_announced_date=None)[source]

This method structures the payload to use in a Community API v2 request involving a board.

New in version 2.6.0.

Parameters:

board_id (str) – The unique identifier (i.e. id field) for the new board (Required)
board_title (str) – The title of the new board (Required)
discussion_style (str) – Defines the board as a blog, contest, forum, idea, qanda or tkb (Required)
description (str, None) – A brief description of the board
parent_category_id (str, None) – The ID of the parent category (if applicable)
hidden (bool, None) – Defines whether the new board should be hidden from lists and menus (disabled by default)
allowed_labels (str, None) – The type of labels allowed on the board (freeform-only, predefined-only or freeform and pre-defined)
use_freeform_labels (bool, None) – Determines if freeform labels should be utilized
use_predefined_labels (bool, None) – Determines if pre-defined labels should be utilized
predefined_labels (list, None) –
The pre-defined labels to utilized on the board as a list of dictionaries

Todo

The ability to provide labels as a simple list and optionally standardize their format (e.g. Pascal Case, etc.) will be available in a future release.
media_type (str, None) – The media type associated with a contest. (image, video or story i.e. text)
blog_authors (list, None) – The approved blog authors in a blog board as a list of user data dictionaries
blog_author_ids (list, None) – A list of User IDs representing the approved blog authors in a blog board
blog_author_logins (list, None) – A list of User Logins (i.e. usernames) representing approved blog authors in a blog board
blog_comments_enabled (bool, None) – Determines if comments should be enabled on blog posts within a blog board
blog_moderators (list, None) – The designated blog moderators in a blog board as a list of user data dictionaries
blog_moderator_ids (list, None) – A list of User IDs representing the blog moderators in a blog board
blog_moderator_logins (list, None) – A list of User Logins (i.e. usernames) representing blog moderators in a blog board
one_entry_per_contest (bool, None) – Defines whether a user can submit only one entry to a single contest
one_kudo_per_contest (bool, None) – Defines whether a user can vote only once per contest
posting_date_end (type[datetime.datetime], None) – The date/time when the contest is closed to submissions
posting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
voting_date_end (type[datetime.datetime], None) – The date/time when the voting period for a contest ends
voting_date_start (type[datetime.datetime], None) – The date/time when the voting period for a contest begins
winner_announced_date (type[datetime.datetime], None) – The date/time the contest winner will be announced

Returns:

The full and properly formatted payload for the API request

Raises:

khoros.errors.exceptions.MissingRequiredDataError

Category Subclass (khoros.core.Khoros.Category)¶

class Khoros.Category(khoros_object)[source]

This class includes methods for interacting with categories.

category_exists(category_id=None, category_url=None)[source]

This method checks to see if a category exists.

New in version 2.7.0.

Parameters:

category_id (str, None) – The ID of the category to check
category_url (str, None) – The URL of the category to check

Returns:

Boolean value indicating whether the category already exists

Raises:

create(category_id, category_title, parent_id=None, return_json=True)[source]

This method creates a new category.

New in version 2.5.0.

Parameters:

category_id (str) – The Category ID of the new category (e.g. video-games)
category_title (str) – The title of the new category (e.g. Video Games)
parent_id (str, None) – The Category ID of the parent category (optional)
return_json (bool) – Determines whether the response should be returned in JSON format (True by default)

Returns:

The response from the API call

Raises:

ValueError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.APIConnectionError

friendly_date_enabled(identifier=None, category_details=None)[source]

This method identifies if friendly dates are enabled for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean indicating if friendly dates are enabled

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_active_skin(identifier=None, category_details=None)[source]

This method retrieves the skin being used with a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The name of the active skin in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_category_details(identifier, first_item=True)[source]

This method returns a dictionary of community configuration settings.

New in version 2.1.0.

Parameters:

identifier (str) – The Category ID or Category URL with which to identify the category
first_item (bool) – Filters the response data to the first item returned (True by default)

Returns:

The community details within a dictionary

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_category_field(field, identifier=None, category_details=None)[source]

This method returns a specific community field from the Khoros Community API.

New in version 2.1.0.

Parameters:

field (str) – The field whose value to return from the khoros.structures.base.Mapping class
identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

static get_category_id(url)[source]

This method retrieves the Category ID for a given category when provided its URL.

Parameters:: url (str) – The URL from which to parse out the Category ID
Returns:: The Category ID retrieved from the URL
Raises:: khoros.errors.exceptions.InvalidURLError

get_creation_date(identifier=None, category_details=None)[source]

This method retrieves the creation date of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The creation of the category in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_depth(identifier=None, category_details=None)[source]

This method retrieves the depth of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The depth of the category as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_description(identifier=None, category_details=None)[source]

This method retrieves the description for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The description in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_friendly_date_max_age(identifier=None, category_details=None)[source]

This method retrieves the maximum age where friendly dates should be used (if enabled) for a category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Integer representing the number of days the friendly date feature should be leveraged if enabled

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_language(identifier=None, category_details=None)[source]

This method retrieves the defined language for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The language (e.g. en) in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_id(identifier=None, category_details=None)[source]

This method retrieves the parent ID for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent ID in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_type(identifier=None, category_details=None)[source]

This method retrieves the parent type for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent type in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_url(identifier=None, category_details=None)[source]

This method retrieves the parent URL for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The parent URL in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_position(identifier=None, category_details=None)[source]

This method retrieves the position of a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The position of the category as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_id(identifier=None, category_details=None)[source]

This method retrieves the root category ID for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category ID in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_type(identifier=None, category_details=None)[source]

This method retrieves the root category type for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category type in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_url(identifier=None, category_details=None)[source]

This method retrieves the root category URL for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The root category URL in string format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_title(identifier=None, full_title=True, short_title=False, category_details=None)[source]

This method retrieves the full and/or short title of the category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
full_title (bool) – Return the full title of the environment (True by default)
short_title (bool) – Return the short title of the environment (False by default)
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The title(s) of the environment as a string or a tuple of strings

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_total_category_count()[source]

This method returns the total number of categories within the Khoros Community environment.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Deprecated since version 2.6.0: Use the khoros.core.Khoros.Category.get_total_count() method instead.

Returns:: The total number of categories as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_total_count()[source]

This method returns the total number of categories within the Khoros Community environment.

New in version 2.6.0.

Returns:: The total number of categories as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_url(category_id=None, category_details=None)[source]

This method retrieves the URL of a given category.

New in version 2.1.0.

Parameters:

category_id (str, None) – The ID of the category to be evaluated (optional if category_details provided)
category_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The full URL of the category

Raises:

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_views(identifier=None, category_details=None)[source]

This method retrieves the total view count for a given category.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

The total number of views

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

is_hidden(identifier=None, category_details=None)[source]

This method identifies whether a given category is hidden.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Category ID or Category URL with which to identify the category
category_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean value indicating if the category is hidden

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

Community Subclass (khoros.core.Khoros.Community)¶

class Khoros.Community(khoros_object)[source]

This class includes methods for interacting with the overall Khoros Community.

email_confirmation_required_to_post(community_details=None)[source]

This method identifies if an email configuration is required before posting in the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if email configuration is required before posting
Raises:: khoros.errors.exceptions.GETRequestError

friendly_date_enabled(community_details=None)[source]

This method if the friendly date functionality is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the feature is enabled
Raises:: khoros.errors.exceptions.GETRequestError

get_active_skin(community_details=None)[source]

This method retrieves the primary active skin that is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The skin name as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_community_details()[source]

This method returns a dictionary of community configuration settings.

New in version 2.1.0.

Returns:: The community details within a dictionary
Raises:: khoros.errors.exceptions.GETRequestError

get_community_field(field, community_details=None)[source]

This method retrieves a particular field from the community collection in the API.

New in version 2.1.0.

Parameters:

field (str) – The field whose value to return from the khoros.structures.base.Mapping class
community_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

get_creation_date(community_details=None)[source]

This method retrieves the timestamp for the initial creation of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The creation date as a string (e.g. 2020-02-03T22:41:36.408-08:00)
Raises:: khoros.errors.exceptions.GETRequestError

get_date_pattern(community_details=None)[source]

This method retrieves the date pattern (e.g. yyyy-MM-dd) utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The date pattern in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_description(community_details=None)[source]

This method retrieves the description of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The description in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_friendly_date_max_age(community_details=None)[source]

This method identifies if the friendly date functionality is utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the feature is enabled
Raises:: khoros.errors.exceptions.GETRequestError

get_language(community_details=None)[source]

This method retrieves the language (e.g. en) utilized in the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The language code as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_max_attachments(community_details=None)[source]

This method retrieves the maximum number of attachments permitted per message within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The value as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_ooyala_player_branding_id(community_details=None)[source]

This method retrieves the branding ID for the Ooyala Player utilized within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The branding ID in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_permitted_attachment_types(community_details=None)[source]

This method retrieves the attachment file types permitted within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The permitted file types within a list
Raises:: khoros.errors.exceptions.GETRequestError

get_primary_url(community_details=None)[source]

This method retrieves the primary URL of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The primary URL in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_sign_out_url(community_details=None)[source]

This method retrieves the Sign Out URL for the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The Sign Out URL as a string
Raises:: khoros.errors.exceptions.GETRequestError

get_tenant_id(community_details=None)[source]

This method retrieves the tenant ID of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: The tenant ID in string format
Raises:: khoros.errors.exceptions.GETRequestError

get_title(full_title=True, short_title=False, community_details=None)[source]

This method retrieves the full and/or short title of the environment.

New in version 2.1.0.

Parameters:

full_title (bool) – Return the full title of the environment (True by default)
short_title (bool) – Return the short title of the environment (False by default)
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The title(s) of the environment as a string or a tuple of strings

Raises:

show_breadcrumb_at_top_level(community_details=None)[source]

This method identifies if breadcrumbs should be shown at the top level of the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if breadcrumbs are displayed at the top level of the environment
Raises:: khoros.errors.exceptions.GETRequestError

show_community_node_in_breadcrumb(community_details=None)[source]

This method identifies if the community node should be shown in breadcrumbs.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if the community node is displayed in bredcrumbs
Raises:: khoros.errors.exceptions.GETRequestError

sso_enabled(community_details=None)[source]

This function checks whether SSO is enabled for the community.

New in version 5.0.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: A Boolean value indicating whether SSO is enabled

top_level_categories_enabled(community_details=None)[source]

This method identifies if top level categories are enabled within the environment.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if top level categories are enabled
Raises:: khoros.errors.exceptions.GETRequestError

top_level_categories_on_community_page(community_details=None)[source]

This method identifies if top level categories are enabled on community pages.

New in version 2.1.0.

Parameters:: community_details (dict, None) – Dictionary containing community details (optional)
Returns:: Boolean value indicating if top level categories are enabled on community pages
Raises:: khoros.errors.exceptions.GETRequestError

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

Group Hub Subclass (khoros.core.Khoros.GroupHub)¶

class Khoros.GroupHub(khoros_object)[source]

This class includes methods for interacting with group hubs.

create(group_id, group_title, description=None, membership_type=None, open_group=None, closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None, enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None, enable_tkb=None, all_styles_default=True, parent_category_id=None, avatar_image_path=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)[source]

This method creates a new group hub within a Khoros Community environment.

New in version 2.6.0.

Parameters:

group_id (str, int) – The unique identifier (i.e. id field) for the new group hub (Required)
group_title (str) – The title of the group hub (Required)
description (str, None) – A brief description of the group hub
membership_type (dict, None) – The membership_type value (open, closed or closed_hidden)
open_group (bool, None) – Defines the group hub as an open group
closed_group (bool, None) – Defines the group hub as a closed group
hidden_group (bool, None) – Defines the group hub as a closed and hidden group
discussion_styles (list, None) – A list of discussion styles that will be permitted in the group hub
enable_blog (bool, None) – Defines that the blog discussion style should be enabled for the group hub
enable_contest (bool, None) – Defines that the contest discussion style should be enabled for the group hub
enable_forum (bool, None) – Defines that the forum discussion style should be enabled for the group hub
enable_idea (bool, None) – Defines that the idea discussion style should be enabled for the group hub
enable_qanda (bool, None) – Defines that the Q&A (qanda) discussion style should be enabled for the group hub
enable_tkb (bool, None) – Defines that the TKB (tkb) discussion style should be enabled for the group hub
all_styles_default (bool) – Enables all discussion styles if not otherwise specified
parent_category_id (str, int, None) – The parent category identifier (if applicable)
avatar_image_path (str, None) – The file path to the avatar image to be uploaded (if applicable)
full_response (bool, None) –
Determines whether the full, raw API response should be returned by the function

Caution

This argument overwrites the return_id, return_url, return_api_url, return_http_code, return_status and return_error_messages arguments.
return_id (bool, None) – Determines if the ID of the new group hub should be returned by the function
return_url (bool, None) – Determines if the URL of the new group hub should be returned by the function
return_api_url (bool, None) – Determines if the API URL of the new group hub should be returned by the function
return_http_code (bool, None) – Determines if the HTTP Code of the API response should be returned by the function
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if any error messages associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

get_total_count()[source]

This method returns the total number of group hubs within the Khoros Community environment.

Returns:: The total number of group hubs as an integer

grouphub_exists(grouphub_id=None, grouphub_url=None)[source]

This method checks to see if a group hub exists.

New in version 2.7.0.

Parameters:

grouphub_id (str, None) – The ID of the group hub to check
grouphub_url (str, None) – The URL of the group hub to check

Returns:

Boolean value indicating whether the group hub already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

structure_payload(group_id, group_title, description=None, membership_type=None, open_group=None, closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None, enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None, enable_tkb=None, all_styles_default=True, parent_category_id=None)[source]

This method structures the payload to use in a Group Hub API request.

New in version 2.6.0.

Parameters:

group_id (str, int) – The unique identifier (i.e. id field) for the new group hub (Required)
group_title (str) – The title of the group hub (Required)
description (str, None) – A brief description of the group hub
membership_type (dict, None) – The membership_type value (open, closed or closed_hidden)
open_group (bool, None) – Defines the group hub as an open group
closed_group (bool, None) – Defines the group hub as a closed group
hidden_group (bool, None) – Defines the group hub as a closed and hidden group
discussion_styles (list, None) – A list of discussion styles that will be permitted in the group hub
enable_blog (bool, None) – Defines if the blog discussion style should be enabled for the group hub
enable_contest (bool, None) – Defines if the contest discussion style should be enabled for the group hub
enable_forum (bool, None) – Defines if the forum discussion style should be enabled for the group hub
enable_idea (bool, None) – Defines if the idea discussion style should be enabled for the group hub
enable_qanda (bool, None) – Defines if the Q&A (qanda) discussion style should be enabled for the group hub
enable_tkb (bool, None) – Defines if the TKB (tkb) discussion style should be enabled for the group hub
all_styles_default (bool) – Defines if all discussion styles should be enabled if not otherwise specified
parent_category_id (str, int, None) – The parent category identifier (if applicable)

Returns:

The properly formatted payload for the API request

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError

update_title(new_title, group_hub_id=None, group_hub_url=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)[source]

This method updates the title of an existing group hub.

New in version 2.6.0.

Parameters:

new_title (str) – The new title for the group hub
group_hub_id (str, None) – The group hub ID that identifies the group hub to update (necessary if URL not provided)
group_hub_url (str, None) – The group hub URL that identifies the group hub to update (necessary if ID not provided)
full_response (bool, None) –
Determines whether the full, raw API response should be returned by the function

Caution

This argument overwrites the return_id, return_url, return_api_url, return_http_code, return_status and return_error_messages arguments.
return_id (bool, None) – Determines if the ID of the new group hub should be returned by the function
return_url (bool, None) – Determines if the URL of the new group hub should be returned by the function
return_api_url (bool, None) – Determines if the API URL of the new group hub should be returned by the function
return_http_code (bool, None) – Determines if the HTTP Code of the API response should be returned by the function
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if any error messages associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

Node Subclass (khoros.core.Khoros.Node)¶

class Khoros.Node(khoros_object)[source]

This class includes methods for interacting with nodes.

get_avatar_url(identifier, node_details=None, original=True, tiny=False, small=False, medium=False, large=False)[source]

This method retrieves one or more avatar URLs for a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
original (bool) – Indicates if the URL for the original-size image should be returned (True by default)
tiny (bool) – Indicates if the URL for the image in a tiny size should be returned (False by default)
small (bool) – Indicates if the URL for the image in a small size should be returned (False by default)
medium (bool) – Indicates if the URL for the image in a medium size should be returned (False by default)
large (bool) – Indicates if the URL for the image in a large size should be returned (False by default)

Returns:

A single URL as a string (default) or a dictionary of multiple URLs by size

Raises:

get_creation_date(identifier, node_details=None, friendly=False)[source]

This method returns the creation date of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
friendly (bool) – Defines if the “friendly” date (e.g. Friday) should be returned (False by default)

Returns:

The creation date as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_depth(identifier, node_details=None)[source]

This method returns the depth of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The depth as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_description(identifier, node_details=None)[source]

This method returns the description of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node description as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_discussion_style(identifier, node_details=None)[source]

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_node_details(identifier, first_item=True)[source]

This method returns a dictionary of node configuration settings.

New in version 2.1.0.

Parameters:

identifier (str) – The Node ID or Node URL with which to identify the node
first_item (bool) – Filters the response data to the first item returned (True by default)

Returns:

The node details within a dictionary

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_node_field(field, identifier=None, node_details=None)[source]

This method returns a specific node field from the Khoros Community API.

New in version 2.1.0.

Parameters:

field (str) – The field to return from the khoros.structures.base.Mapping class
identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The requested field in its native format

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

static get_node_id(url, node_type=None)[source]

This method retrieves the Node ID for a given node within a URL.

Parameters:

url (str) – The URL from which to parse out the Node ID
node_type (str, None) – The node type (e.g. blog, tkb, message, etc.) for the object in the URL

Returns:

The Node ID retrieved from the URL

Raises:

khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.NodeIDNotFoundError, khoros.errors.exceptions.NodeTypeNotFoundError

static get_node_type_from_url(url)[source]

This method attempts to retrieve a node type by analyzing a supplied URL.

Parameters:: url (str) – The URL from which to extract the node type
Returns:: The node type based on the URL provided
Raises:: khoros.errors.exceptions.NodeTypeNotFoundError

get_parent_id(identifier, node_details=None, include_prefix=False)[source]

This method returns the Parent ID of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
include_prefix (bool) – Determines if the prefix (e.g. category:) should be included (Default: False)

Returns:

The Parent ID as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_type(identifier, node_details=None)[source]

This method returns the parent type of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The parent type as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_url(identifier, node_details=None)[source]

This method returns the parent URL of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The parent URL as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_position(identifier, node_details=None)[source]

This method returns the position of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The position as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_id(identifier, node_details=None, include_prefix=False)[source]

This method returns the Root Category ID of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function
include_prefix (bool) – Defines if the prefix (e.g. category:) should be included (False by default)

Returns:

The Root Category ID as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_type(identifier, node_details=None)[source]

This method returns the root category type of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The root category type as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_url(identifier, node_details=None)[source]

This method returns the root category URL of a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The root category URL as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_title(identifier=None, full_title=True, short_title=False, node_details=None)[source]

This method retrieves the full and/or short title of the node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
full_title (bool) – Determines if the full title of the node should be returned (True by default)
short_title (bool) – Determines if the short title of the node should be returned (False by default)
node_details (dict, None) – Dictionary containing node details (optional)

Returns:

The node title(s) as a string or a tuple of strings

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_total_node_count()[source]

This method returns the total number of nodes within the Khoros Community environment.

Returns:: The total number of nodes as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_type(identifier, node_details=None)[source]

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_url(node_id=None, node_details=None)[source]

This method returns the full URL of a given Node ID.

New in version 2.1.0.

Parameters:

node_id (str, None) – The Node ID with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The node URl as a string

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_views(identifier, node_details=None)[source]

This method returns the views for a given node.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The views as an integer

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

is_hidden(identifier, node_details=None)[source]

This method identifies whether a given node is hidden.

New in version 2.1.0.

Parameters:

identifier (str, None) – The Node ID or Node URL with which to identify the node
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

Boolean indicating whether the node is hidden

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

node_exists(node_id=None, node_url=None)[source]

This method checks to see if a node exists.

New in version 2.7.0.

Parameters:

node_id (str, None) – The ID of the node to check
node_url (str, None) – The URL of the node to check

Returns:

Boolean value indicating whether the node already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

Core Object Subclasses (khoros.core.Khoros)¶

The classes below are inner/nested classes within the core khoros.core.Khoros class.

Note

The classes themselves are CamelCase format and singular (e.g. Role, User, etc.) whereas the names used to call the inner class methods are all lowercase (or snake_case) and plural. (e.g. core_object.roles.get_role_id(), core_object.users.create(), etc.)

Album Subclass (khoros.core.Khoros.Album)¶

class Khoros.Album(khoros_object)[source]

This class includes methods for interacting with the albums collection.

create(title=None, description=None, owner_id=None, hidden=False, default=False, full_response=False)[source]

This method creates a new image album for a user.

New in version 2.3.0.

Parameters:

title (str, None) – The title of the album to be created
description (str, None) – The description of the album
owner_id (str, int, None) –
The User ID of the album owner

Note

If not defined, the owner will be the user performing the API call.
hidden (bool) – Defines if the album should be public (default) or hidden
default (bool) – Defines if this will be the default album for the user (False by default)
full_response (bool) – Defines if the full response should be returned instead of the outcome (False by default)

Returns:

Boolean value indicating a successful outcome (default) or the full API response

get_albums_for_user(user_id=None, login=None, public=None, private=None, verify_success=False, allow_exceptions=True)[source]

This method returns data for the albums owned by a given user.

New in version 2.3.0.

Parameters:

user_id (str, int) – The User ID for the album owner
login (str) – The username of the album owner
public (bool) – Indicates that public albums should be returned (all albums returned by default)
private (bool) – Indicates that private albums should be returned (all albums returned by default)
verify_success (bool) – Optionally check to confirm that the API query was successful (False by default)
allow_exceptions (bool) –
Defines whether exceptions can be raised for responses returning errors

Caution

This does not apply to exceptions for missing required data.

Returns:

A list of dictionaries representing each album

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

Archives Subclass (khoros.core.Khoros.Archives)¶

class Khoros.Archives(khoros_object)[source]

This class includes methods for archiving content.

New in version 4.1.0.

static aggregate_results(results, include_raw=False)[source]

This method aggregates the results of an archive/unarchive operation into an easy-to-parse dictionary.

New in version 4.1.0.

Parameters:

results (list, dict) – The results from an archive or unarchive operation
include_raw (bool) – Includes the raw API response in the aggregated data dictionary under the raw key (False by default)

Returns:

A dictionary with fields for status, archived, unarchived, failed and unknown or the raw response when the API call completely fails, with the optional raw data when requested

archive(message_id=None, message_url=None, suggested_url=None, archive_entries=None, aggregate_results=False, include_raw=False)[source]

This method archives one or more messages while providing an optional suggested URL as a placeholder.

New in version 4.1.0.

Parameters:

message_id (str, int, None) – The message ID for the content to be archived
message_url (str, None) – The URL of the message to be archived (as an alternative to the message_id argument)
suggested_url (str, None) – The full URL to suggest to the user when navigating to the archived message
archive_entries (dict, list, tuple, set, None) –
A dictionary mapping one or more message IDs with accompanying suggested URLs

Note

Alternatively, a list, tuple or set of message IDs can be supplied which will be converted into a dictionary with blank suggested URLs.
aggregate_results (bool) – Aggregates the operation results into an easy-to-parse dictionary (False by default)
include_raw (bool) –
Includes the raw API response in the aggregated data dictionary under the raw key (False by default)

Note

This parameter is only relevant when the aggregate_results parameter is True.

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

is_archived(message_id)[source]

This method checks to see whether a message is currently archived.

New in version 5.2.0.

Parameters:: message_id (str, int) – The message ID for the content to be archived
Returns:: Boolean value indicating whether the message is archived
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError

unarchive(message_id=None, message_url=None, new_board_id=None, archive_entries=None, aggregate_results=False, include_raw=False)[source]

This method unarchives one or more messages and moves them to a given board.

New in version 4.1.0.

Parameters:

message_id (str, int, None) – The message ID for the content to be archived
message_url (str, None) – The URL of the message to be archived (as an alternative to the message_id argument)
new_board_id (str, None) – The board ID of what will be the new parent board of a message getting unarchived
archive_entries (dict, list, tuple, set, None) –
A dictionary mapping one or more message IDs with accompanying board IDs

Note

Alternatively, a list, tuple or set of message IDs can be supplied which will be converted into a dictionary with blank board IDs.
aggregate_results (bool) – Aggregates the operation results into an easy-to-parse dictionary (False by default)
include_raw (bool) –
Includes the raw API response in the aggregated data dictionary under the raw key (False by default)

Note

This parameter is only relevant when the aggregate_results parameter is True.

Returns:

Boolean value indicating a successful outcome (default), the full API response or one or more specific fields defined by function arguments

Raises:

khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

TypeError, ValueError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

Message Subclass (khoros.core.Khoros.Message)¶

class Khoros.Message(khoros_object)[source]

This class includes methods for interacting with messages.

create(subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None, context_id=None, context_url=None, cover_image=None, images=None, is_answer=None, is_draft=None, labels=None, product_category=None, products=None, read_only=None, seo_title=None, seo_description=None, tags=None, ignore_non_string_tags=False, teaser=None, topic=None, videos=None, attachment_file_paths=None, full_payload=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False, proxy_user_object=None)[source]

This method creates a new message within a given node.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be created on behalf of other users.

Changed in version 4.3.0: It is now possible to pass the pre-constructed full JSON payload into the function via the full_payload parameter as an alternative to defining each field individually.

Changed in version 2.8.0: The ignore_non_string_tags, return_status, return_error_messages and split_errors arguments were introduced.

New in version 2.3.0.

Parameters:

subject (str, None) – The title or subject of the message
body (str, None) – The body of the message in HTML format
node (dict, None) – A dictionary containing the id key and its associated value indicating the destination
node_id (str, None) – The ID of the node in which the message will be published
node_url (str, None) –
The URL of the node in which the message will be published

Note

This argument is necessary in the absence of the node and node_id arguments.
canonical_url (str, None) – The search engine-friendly URL to the message
context_id (str, None) – Metadata on a message to identify the message with an external identifier of your choice
context_url (str, None) – Metadata on a message representing a URL to associate with the message (external identifier)
cover_image (dict, None) – The cover image set for the message
images (dict, None) – The query to retrieve images uploaded to the message
is_answer (bool, None) – Designates the message as an answer on a Q&A board
is_draft (bool, None) – Indicates whether the message is still a draft (i.e. unpublished)
labels (dict, None) – The query to retrieve labels applied to the message
product_category (dict, None) – The product category (i.e. container for products) associated with the message
products (dict, None) – The product in a product catalog associated with the message
read_only (bool, None) – Indicates whether the message should be read-only or have replies/comments blocked
seo_title (str, None) – The title of the message used for SEO purposes
seo_description (str, None) – A description of the message used for SEO purposes
tags (dict, None) – The query to retrieve tags applied to the message
ignore_non_string_tags (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
teaser (str, None) – The message teaser (used with blog articles)
topic (dict, None) – The root message of the conversation in which the message appears
videos (dict, None) – The query to retrieve videos uploaded to the message
attachment_file_paths (str, tuple, list, set, None) – The full path(s) to one or more attachment (e.g. path/to/file1.pdf)
full_payload (dict, str, None) –
Pre-constructed full JSON payload as a dictionary (preferred) or a JSON string with the following syntax:
{ "data": { "type": "message", } }
Note

The type field shown above is essential for the payload to be valid.
full_response (bool, None) –
Defines if the full response should be returned instead of the outcome (False by default)

Caution

This argument overwrites the return_id, return_url, return_api_url and return_http_code arguments.
return_id (bool, None) – Indicates that the Message ID should be returned (False by default)
return_url (bool, None) – Indicates that the Message URL should be returned (False by default)
return_api_url (bool, None) – Indicates that the API URL of the message should be returned (False by default)
return_http_code (bool, None) – Indicates that the HTTP status code of the response should be returned (False by default)
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if the Developer Response Message (if any) associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to create the message on behalf of a secondary user.

Returns:

Boolean value indicating a successful outcome (default) or the full API response

Raises:

define_context_id(msg_id, context_id='', full_response=False)[source]

This method defines the context_id metadata value for a given message.

New in version 5.0.0.

Parameters:

msg_id (str) – The message ID to query
context_id (str) – The value to be written to the context_id metadata field (Empty by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value to indicate the success of the operation or alternatively the full API response

Raises:

define_context_url(msg_id, context_url='', full_response=False)[source]

This function defines the context_url metadata value for a given message.

New in version 5.0.0.

Parameters:

msg_id (str) – The message ID to query
context_url (str) – The value to be written to the context_url metadata field (Empty by default)
full_response (bool) – Determines if the full API response should be returned (False by default)

Returns:

A Boolean value to indicate the success of the operation or alternatively the full API response

Raises:

khoros.errors.exceptions.MessageTypeNotFoundError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.MessageTypeNotFoundError, khoros.errors.exceptions.InvalidURLError

flag(msg_id)[source]

This method flags a message as spam.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be flagged
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

format_content_mention(content_info=None, content_id=None, title=None, url=None)[source]

This method formats the <li-message> HTML tag for a content @mention.

New in version 2.4.0.

Parameters:

content_info (dict, None) –
A dictionary containing the 'id' and/or 'login' key(s) with the user data

Note

This argument is necessary if the Title and URL are not explicitly passed using the title and url function arguments.
content_id (str, int, None) –
The Message ID (aka Content ID) associated with the content mention

Note

This is an optional argument as the ID can be retrieved from the URL.
title (str, None) – The display title for the content mention (e.g. "Click Here")
url (str, None) – The fully-qualified URL of the message being mentioned

Returns:

The properly formatted <li-message> HTML tag in string format

Raises:

format_user_mention(user_info=None, user_id=None, login=None)[source]

This method formats the <li-user> HTML tag for a user @mention.

New in version 2.4.0.

Parameters:

user_info (dict, None) –
A dictionary containing the 'id' and/or 'login' key(s) with the user information

Note

This argument is necessary if the User ID and/or Login are not explicitly passed using the user_id and/or login function arguments.
user_id (str, int, None) – The unique user identifier (i.e. User ID) for the user
login (str, None) – The login (i.e. username) for the user

Returns:

The properly formatted <li-user> HTML tag in string format

Raises:

khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

get_all_messages(board_id, fields=None, where_filter=None, descending=True)[source]

This function retrieves data for all messages within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
where_filter (str, tuple, list, set, None) – One or more optional WHERE filters to include in the LiQL query
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each message within the board

Raises:

get_all_topic_messages(board_id, fields=None, descending=True)[source]

This function retrieves data for all topic messages (i.e. zero-depth messages) within a given board.

New in version 5.4.0.

Parameters:

board_id (str) – The ID of the board to query
fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
descending (bool) – Determines if the data should be returned in descending order (True by default)

Returns:

A list containing a dictionary of data for each topic message within the board

Raises:

get_context_id(msg_id)[source]

This method retrieves the Context ID value for a given message ID.

New in version 5.0.0.

Parameters:: msg_id (str) – The message ID to query
Returns:: The value of the Context ID metadata field
Raises:: khoros.errors.exceptions.get_context_id

get_context_url(msg_id)[source]

This method retrieves the Context URL value for a given message ID.

New in version 5.0.0.

Parameters:: msg_id (str) – The message ID to query
Returns:: The value of the Context URL metadata field
Raises:: khoros.errors.exceptions.get_context_id

get_kudos_for_message(message_id, count_only=False)[source]

This function retrieves the kudos for a given message ID and returns the full data or the kudos count.

New in version 5.4.0.

Parameters:

message_id (str) – The ID of the message for which to retrieve the kudos
count_only (bool) – Determines if only the kudos count should be returned (False by default)

Returns:

The JSON data for the message kudos or the simple kudos count as an integer

Raises:

khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

get_metadata(msg_id, metadata_key)[source]

This method retrieves the value for a specific metadata key associated with a given message.

New in version 4.5.0.

Parameters:

msg_id (str, int) – The ID of the message for which the metadata will be retrieved
metadata_key (str) – The metadata key for which the value will be retrieved

Returns:

The metadata value

Raises:

khoros.errors.exceptions.MissingRequiredDataError', :py:exc:`khoros.errors.exceptions.InvalidMetadataError, khoros.errors.exceptions.GETRequestError

kudo(msg_id)[source]

This method kudos (i.e. “likes”) a message.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be kudoed
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

label(msg_id, label_text)[source]

This function adds a single label to a given message.

New in version 5.1.0.

Parameters:

msg_id (str, int) – The ID of the message to be flagged
label_text (str) – The label to be added

Returns:

The API response in JSON format

Raises:

static parse_v2_response(json_response, return_dict=False, status=False, response_msg=False, http_code=False, message_id=False, message_url=False, message_api_uri=False, v2_base='')[source]

This method parses an API response for a message operation (e.g. creating a message) and returns data.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Changed in version 3.2.0: The lower-level function call now utilizes keyword arguments to fix an argument mismatch issue.

Deprecated since version 2.5.0: Use the khoros.core.Khoros.parse_v2_response() function instead.

New in version 2.3.0.

Parameters:

json_response (dict) – The API response in JSON format
return_dict (bool) – Defines if the parsed data should be returned within a dictionary
status (bool) – Defines if the status value should be returned
response_msg (bool) – Defines if the developer response message should be returned
http_code (bool) – Defines if the HTTP status code should be returned
message_id (bool) – Defines if the message ID should be returned
message_url (bool) – Defines if the message URL should be returned
message_api_uri (bool) – Defines if the ** message API URI** should be returned
v2_base (str) – The base URL for the API v2

Returns:

A string, tuple or dictionary with the parsed data

Raises:

khoros.errors.exceptions.MissingRequiredDataError

tag(msg_id, tag_text)[source]

This function adds a single tag to a given message.

New in version 5.1.0.

Parameters:

msg_id (str, int) – The ID of the message to be flagged
tag_text (str) – The tag to be added

Returns:

The API response in JSON format

Raises:

khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

unflag(msg_id)[source]

This method flags a message as not being spam.

New in version 5.1.0.

Parameters:: msg_id (str, int) – The ID of the message to be flagged
Returns:: The API response in JSON format
Raises:: khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

update(msg_id=None, msg_url=None, subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None, context_id=None, context_url=None, cover_image=None, is_draft=None, labels=None, moderation_status=None, parent=None, product_category=None, products=None, read_only=None, topic=None, status=None, seo_title=None, seo_description=None, tags=None, overwrite_tags=False, ignore_non_string_tags=False, teaser=None, attachments_to_add=None, attachments_to_remove=None, full_response=None, return_id=None, return_url=None, return_api_url=None, return_http_code=None, return_status=None, return_error_messages=None, split_errors=False, proxy_user_object=None)[source]

This method updates one or more elements of an existing message.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be updated on behalf of other users.

New in version 2.8.0.

Parameters:

msg_id (str, int, None) – The ID of the existing message
msg_url (str, None) – The URL of the existing message
subject (str, None) – The title or subject of the message
body (str, None) – The body of the message in HTML format
node (dict, None) – A dictionary containing the id key and its associated value indicating the destination
node_id (str, None) – The ID of the node in which the message will be published
node_url (str, None) –
The URL of the node in which the message will be published

Note

This argument is necessary in the absence of the node and node_id arguments.
canonical_url (str, None) – The search engine-friendly URL to the message
context_id (str, None) – Metadata on a message to identify the message with an external identifier of your choosing
context_url (str, None) – Metadata on a message representing a URL to associate with the message (external identifier)
cover_image (dict, None) – The cover image set for the message
is_draft (bool, None) – Indicates whether the message is still a draft (i.e. unpublished)
labels (dict, None) – The query to retrieve labels applied to the message
moderation_status (str, None) –
The moderation status of the message

Note

Acceptable values are unmoderated, approved, rejected, marked_undecided, marked_approved and marked_rejected.
parent (str, None) – The parent of the message
product_category (dict, None) – The product category (i.e. container for products) associated with the message
products (dict, None) – The product in a product catalog associated with the message
read_only (bool, None) – Indicates whether the message should be read-only or have replies/comments blocked
topic (dict, None) – The root message of the conversation in which the message appears
status (dict, None) –
The message status for messages where conversation.style is idea or contest

Caution

This property is not returned if the message has the default Unspecified status assigned. It will only be returned for ideas with a status of Completed or with a custom status created in Community Admin.
seo_title (str, None) – The title of the message used for SEO purposes
seo_description (str, None) – A description of the message used for SEO purposes
tags (dict, None) – The query to retrieve tags applied to the message
overwrite_tags (bool) – Determines if tags should overwrite any existing tags (where applicable) or if the tags should be appended to the existing tags (default)
ignore_non_string_tags (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
teaser (str, None) – The message teaser (used with blog articles)
attachments_to_add (str, tuple, list, set, None) – The full path(s) to one or more attachments (e.g. path/to/file1.pdf) to be added to the message
attachments_to_remove (str, tuple, list, set, None) –
One or more attachments to remove from the message

Note

Each attachment should specify the attachment id of the attachment to remove, which begins with m#_. (e.g. m283_file1.pdf)
full_response (bool, None) –
Defines if the full response should be returned instead of the outcome (False by default)

Caution

This argument overwrites the return_id, return_url, return_api_url and return_http_code arguments.
return_id (bool, None) – Indicates that the Message ID should be returned (False by default)
return_url (bool, None) – Indicates that the Message URL should be returned (False by default)
return_api_url (bool, None) – Indicates that the API URL of the message should be returned (False by default)
return_http_code (bool, None) – Indicates that the HTTP status code of the response should be returned (False by default)
return_status (bool, None) – Determines if the Status of the API response should be returned by the function
return_error_messages (bool, None) – Determines if the Developer Response Message (if any) associated with the API response should be returned by the function
split_errors (bool) – Defines whether error messages should be merged when applicable
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to create the message on behalf of a secondary user.

Returns:

Boolean value indicating a successful outcome (default) or the full API response

Raises:

TypeError, ValueError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

static validate_message_payload(payload)[source]

This method validates the payload for a message to ensure that it can be successfully utilized.

New in version 4.3.0.

Parameters:: payload (dict, str) – The message payload to be validated as a dictionary (preferred) or a JSON string.
Returns:: The payload as a dictionary
Raises:: khoros.errors.exceptions.InvalidMessagePayloadError

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.UnsupportedNodeTypeError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PUTRequestError

Role Subclass (khoros.core.Khoros.Role)¶

class Khoros.Role(khoros_object)[source]

This class includes methods relating to roles and permissions.

assign_roles_to_user(user, lookup_type='id', roles_to_add=None, node=None, node_type='board', v1=False, return_json=True)[source]

This method assigns a user to one or more roles.

New in version 4.0.0.

Parameters:

user (str) – The identifier (i.e. ID, login or email) of the user to be assigned to the role
lookup_type (str) – The lookup type for the user identifier (id, login or email)
roles_to_add (str, list, tuple, set) – One or more roles (Role IDs or Role Names) to which the user will be assigned
node (str, None) – The Node ID of the node to which the role is scoped when applicable
node_type (str) – The type of node to which the role is scoped (e.g. board (default), category, etc.)
v1 (bool) – Determines if the Community API v1 should be used to perform the operation (False by default)
return_json (bool) – Determines if the response should be returned as JSON rather than XML (True by default)

Returns:

The response from the API request

Raises:

static get_role_id(role_name, scope='community', node_id=None)[source]

This method constructs and returns the Role ID associated with a given role name and scope.

New in version 4.0.0.

Parameters:

role_name (str) – The name of the role (e.g. Administrator, Moderator, Owner, etc.)
scope (str) – The scope of the role (community by default)
node_id (str, None) – The associated Node ID for any role that does not have a global/community scope.

Returns:

The properly constructed Role ID where applicable

Raises:

khoros.errors.exceptions.InvalidRoleError, khoros.errors.exceptions.MissingRequiredDataError

get_roles_for_user(user_id, fields=None)[source]

This method returns all roles associated with a given User ID.

Changed in version 4.1.0: The docstring has been updated to reference the correct exception raised by this method.

Changed in version 3.5.0: Fields to return in the LiQL query can now be explicitly defined.

New in version 2.4.0.

Parameters:

user_id (str) – The User ID for which to retrieve the roles data
fields (str, list, tuple, set, None) –
The field(s) to retrieve from the LiQL query as a string or list

Note

All fields (i.e. SELECT *) are returned unless fields are explicitly defined.

Returns:

A dictionary with data for each role associated with the given User ID

Raises:

khoros.errors.exceptions.DataMismatchError, khoros.errors.exceptions.MissingRequiredDataError

get_total_role_count(return_dict=False, total=True, top_level=False, board=False, category=False, group_hub=False)[source]

This method retrieves the total role count for one or more role type(s).

New in version 2.4.0.

Parameters:

return_dict (bool) – Determines if the data should be returned as a dictionary (False by default)
total (bool) – Indicates that the total overall role count should be returned (True by default)
top_level (bool) – Indicates that the total top-level role count should be returned (False by default)
board (bool) – Indicates that the total board-level role count should be returned (False by default)
category (bool) – Indicates that the total category-level role count should be returned (False by default)
group_hub (bool) – Indicates that the total group hub-level role count should be returned (False by default)

Returns:

The role count(s) as an integer, tuple or dictionary, depending on the arguments supplied

Raises:

khoros.objects.roles.InvalidRoleTypeError

get_users_with_role(fields='login', role_id=None, role_name=None, scope=None, node_id=None, limit_per_query=1000, simple=False)[source]

This method retrieves a list of all users that have a specific role.

New in version 3.5.0.

Parameters:

fields (str, tuple, list, set) –
One or more fields from the Users object to return (login field by default)

See also

The fields that can be used are found in the Khoros developer documentation.
role_id (str, None) – The identifier for the role in node_type:node_id:role_name format
role_name (str, None) –
The simple role name (e.g. Administrator)

Caution

This option should only be used when the role name is unique within the community at all node levels.
scope (str, None) –
The scope of the role (e.g. board, category, community, grouphub)

Note

If a value is not supplied and only a role name is defined then the role scope is assumed to be at the community level. (i.e. global)
node_id (str, None) –
The Node ID associated with the role (where applicable)

Note

If a value is not supplied and only a role name is defined then the role scope is assumed to be at the community level. (i.e. global)
limit_per_query (int, str) –
Defines a LIMIT constraint other than the default 1000 limit per LiQL query

Note

Unless modified by Khoros Support or Professional Services, 1000 is the maximum number of entries that can be returned in a single LiQL query.
simple (bool) – Returns a simple list of the strings or tuples of the value(s) for each user (False by default)

Returns:

A list of users as strings, tuples or dictionaries depending if simple mode is enabled

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.PayloadMismatchError

Settings Subclass (khoros.core.Khoros.Settings)¶

class Khoros.Settings(khoros_object)[source]

This class includes methods relating to the retrieval and defining of various settings.

New in version 3.2.0.

define_node_setting(setting_name, setting_val, node_id, node_type='board', return_json=True)[source]

This method defines a particular setting value for a given node.

Changed in version 4.0.0: The default value for the return_json parameter is now True.

Changed in version 3.3.2: The return_json parameter has been introduced which returns a simple JSON object (as a dict) indicating whether the operation was successful. (Currently False by default)

New in version 3.2.0.

Parameters:

setting_name (str) – The name of the setting field for which to retrieve the value
setting_val (str) – The value of the setting to be defined
node_id (str) – The ID of the node associated with the setting to retrieve
node_type (str) – Defines the node as a board (default), category or grouphub
return_json (bool) –
Returns a simple JSON dictionary indicating the operation result (True by default)

Caution

An unsuccessful REST call will result in the raising of the khoros.errors.exceptions.PostRequestError exception if the return_json parameter is set to False.

Returns:

The API response as a dictionary

Raises:

get_node_setting(setting_name, node_id, node_type='board', v1=None, convert_json=False)[source]

This method retrieves the value of a specific node setting.

Changed in version 3.3.2: The convert_json parameter has been introduced which optionally converts a JSON string into a dictionary.

New in version 3.2.0.

Parameters:

setting_name (str) – The name of the setting field for which to retrieve the value
node_id (str) – The ID of the node associated with the setting to retrieve
node_type (str) – Defines the node as a board (default), category or grouphub
v1 (bool, None) – Optionally defines a specific Community API version to use when retrieving the value
convert_json (bool) – Optionally converts a JSON string into a Python dictionary (False by default)

Returns:

The value of the setting for the node

Raises:

ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.LiQLParseError

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

Subscription Subclass (khoros.core.Khoros.Subscription)¶

class Khoros.Subscription(khoros_object)[source]

This class includes methods relating to subscriptions.

add_subscription(target_id, target_type='board', payload=None, included_boards=None, excluded_boards=None, proxy_user_object=None)[source]

This method adds a subscription to a given target for the current user.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

target_id (str, int) – The unique identifier for the target (e.g. Node ID, Message ID, etc.)
target_type – The target type such as board (default), message, category, etc.
payload (dict, None) – Pre-constructed payload to use in the API call
included_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be included in the partial subscription
excluded_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be excluded from the partial subscription
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

get_subscription_uri()[source]

This method returns the subscriptions URI for the v2 API to perform API calls.

New in version 3.5.0.

Returns:: The full (absolute) URI for the subscriptions v2 API endpoint

subscribe_to_board(node_id, proxy_user_object=None)[source]

This method subscribes the current user to an individual message.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

node_id (str) – The unique identifier for a board (i.e. Board ID)
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_category(node_id, included_boards=None, excluded_boards=None, proxy_user_object=None)[source]

This method subscribes the current user to a full or partial category.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

node_id (str) – The unique identifier (i.e. Node ID) for the category
included_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be included in the partial subscription
excluded_boards (list, tuple, set, str, None) – One or more boards (represented by Node ID) to be excluded from the partial subscription
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_label(label, board_id, proxy_user_object=None)[source]

This method subscribes the current user to label found on a board.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

label (str, int) – The label to which to subscribe
board_id (str) – The unique identifier (i.e. Node ID) for the board where the label is found
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_message(msg_id, proxy_user_object=None)[source]

This method subscribes the current user to an individual message.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

msg_id (str, int) – The unique identifier for an individual message
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

subscribe_to_product(product_id, proxy_user_object=None)[source]

This method subscribes the current user to a product.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performed on behalf of other users.

New in version 3.5.0.

Parameters:

product_id (str, int) – The unique identifier for a product
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to perform the API request on behalf of a secondary user.

Returns:

The API response in JSON format

Raises:

ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

Tag Subclass (khoros.core.Khoros.Tag)¶

class Khoros.Tag(khoros_object)[source]

This class includes methods relating to the tagging of content.

New in version 4.1.0.

add_single_tag_to_message(tag, msg_id, allow_exceptions=False)[source]

This method adds a single tag to an existing message.

New in version 4.1.0.

Parameters:

tag (str) – The tag value to be added
msg_id (str, int) – The unique identifier for the message
allow_exceptions (bool) – Determines if exceptions are permitted to be raised (False by default)

Returns:

None

Raises:

add_tags_to_message(tags, msg_id, allow_exceptions=False)[source]

This method adds one or more tags to an existing message.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 4.1.0.

..caution:: This function is not the most effective way to add multiple tags to a message. It is recommended: that the khoros.core.Khoros.messages.update() method be used instead with its tags argument, which is more efficient and performance-conscious.

Parameters:

tags (str, tuple, list, set) – One or more tags to be added to the message
msg_id (str, int) – The unique identifier for the message
allow_exceptions (bool) – Determines if exceptions are permitted to be raised (False by default)

Returns:

None

Raises:

get_tags_for_message(msg_id)[source]

This method retrieves the tags for a given message.

New in version 4.1.0.

Parameters:: msg_id (str, int) – The Message ID for the message from which to retrieve tags
Returns:: A list of tags associated with the message

static structure_single_tag_payload(tag_text)[source]

This method structures the payload for a single tag.

New in version 4.1.0.

Parameters:: tag_text (str) – The tag to be included in the payload
Returns:: The payload as a dictionary
Raises:: khoros.errors.exceptions.InvalidPayloadValueError

structure_tags_for_message(*tags, msg_id=None, overwrite=False, ignore_non_strings=False, wrap_json=False)[source]

This method structures tags to use within the payload for creating or updating a message.

Changed in version 4.3.0: Introduced the wrap_json parameter to wrap the tags in a dictionary within the items key.

New in version 4.1.0.

Parameters:

tags (str, list, tuple, set) – One or more tags or list of tags to be structured
msg_id (str, int, None) – Message ID of an existing message so that its existing tags can be retrieved (optional)
overwrite (bool) – Determines if tags should overwrite any existing tags (where applicable) or if the tags should be appended to the existing tags (default)
ignore_non_strings (bool) – Determines if non-strings (excluding iterables) should be ignored rather than converted to strings (False by default)
wrap_json (bool) – Determines if the list of tags should be wrapped in the {"items": []} JSON structure – In other words, a dictionary rather than a list (False by default)

Returns:

A list of properly formatted tags to act as the value for the tags field in the message payload

khoros.errors.exceptions.UserCreationError

User Subclass (khoros.core.Khoros.User)¶

class Khoros.User(khoros_object)[source]

This class includes methods for interacting with users.

create(user_settings=None, login=None, email=None, password=None, first_name=None, last_name=None, biography=None, sso_id=None, web_page_url=None, cover_image=None, ignore_exceptions=False)[source]

This method creates a new user in the Khoros Community environment.

Changed in version 4.0.0: This function now returns the API response and the ignore_exceptions parameter has been introduced.

Changed in version 3.5.0: The unnecessary return statement at the end of the method has been removed.

Parameters:

user_settings (dict, None) – Allows all user settings to be passed to the function within a single dictionary
login (str, None) – The username (i.e. login) for the user (required)
email (str, None) – The email address for the user (required)
password (str, None) – The password for the user
first_name (str, None) – The user’s first name (i.e. given name)
last_name (str, None) – The user’s last name (i.e. surname)
biography (str, None) – The user’s biography for their profile
sso_id (str, None) – The Single Sign-On (SSO) ID for the user
web_page_url (str, None) – The URL to the user’s website
cover_image (str, None) – The cover image to be used on the user’s profile
ignore_exceptions (bool) – Defines whether to raise the khoros.errors.exceptions.UserCreationError exception if the creation attempt fails (False by default)

Returns:

The response to the user creation API request

Raises:

delete(user_id, return_json=False)[source]

This method deletes a user from the Khoros Community environment.

Parameters:

user_id (str, int) – The User ID of the user to be deleted
return_json (bool) – Determines if the API response should be returned in JSON format (False by default)

Returns:

The API response (optionally in JSON format)

Raises:

khoros.errors.exceptions.FeatureNotConfiguredError

get_album_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the number of albums for a user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of albums found for the user as an integer

Raises:

get_all_users(fields=None, order_by='last_visit_time', order_by_desc=True)[source]

This function retrieves data for all users.

New in version 5.3.0.

Parameters:

fields (str, tuple, list, set, None) – Specific fields to query if not all fields are needed (comma-separated string or iterable)
order_by (str) – The order by which to sort the data (last_visit_time by default)
order_by_desc (bool) – Indicates if the data should be sorted in descending (default) or ascending order

Returns:

A list containing a dictionary of data for each user

Raises:

get_all_users_count()[source]

This method retrieves the total number of users on the community.

New in version 5.2.0.

Returns:: The user count for total users as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_email(user_settings=None, user_id=None, login=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]

This method retrieves the email address for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: User ID, username, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (str, None) – The User ID of the user
login (str, None) – The username of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of email addresses to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The email address of the user as a string or a list of emails if allow_multiple is True

get_followers_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of community members who have added the user as a friend in the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of community members who have added the user as a friend in integer format

Raises:

get_following_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of community members the user has added as a friend in the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of community members the user has added as a friend in integer format

Raises:

get_ids_from_login_list(login_list, return_type='list')[source]

This method identifies the User IDs associated with a list of user logins. (i.e. usernames)

Parameters:

login_list (list, tuple) – List of user login (i.e. username) values in string format
return_type (str) – Determines if the data should be returned as a list (default) or a dict

Returns:

A list or dictionary with the User IDs

Raises:

get_images_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of images uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of images uploaded by the user in integer format

Raises:

get_kudos_given_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of kudos a user has given.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of kudos given by the user in integer format

Raises:

get_kudos_received_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of kudos a user has received.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of kudos received by the user in integer format

Raises:

get_last_visit_timestamp(user_settings=None, user_id=None, login=None, email=None)[source]

This method retrieves the timestamp for the last time the user logged into the community.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The last visit timestamp in string format

Raises:

get_login(user_settings=None, user_id=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]: This is an alternative method name for the khoros.core.Khoros.User.get_username() method.

get_messages_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of messages (topics and replies) posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of messages (topics and replies) posted by the user in integer format

Raises:

get_online_user_count()[source]

This method retrieves the number of users currently online.

Returns:: The user count for online users as an integer
Raises:: khoros.errors.exceptions.GETRequestError

get_online_users_count(anonymous=None, registered=None)[source]

This method returns the total count of users currently online.

New in version 5.0.0.

Parameters:

anonymous (bool, None) – Filters the results to only anonymous (non-registered) users
registered (bool, None) – Filters the results to only registered users

Returns:

An integer of the total online users count

Raises:

get_public_images_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of public images uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of public images uploaded by the user in integer format

Raises:

get_registered_users_count()[source]

This method returns the total count of registered users on the community.

New in version 5.0.0.

Returns:: An integer of the total registered users count

get_registration_data(user_settings=None, user_id=None, login=None, email=None)[source]

This method retrieves the registration data for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

A dictionary containing the registration data for the user

Raises:

get_registration_status(user_settings=None, user_id=None, login=None, email=None)[source]

This method retrieves the registration status for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The registration status in string format

Raises:

get_registration_timestamp(user_settings=None, user_id=None, login=None, email=None)[source]

This method retrieves the timestamp for when a given user registered for an account.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The registration timestamp in string format

Raises:

get_replies_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of replies posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of replies posted by the user in integer format

Raises:

get_roles_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of roles applied to the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of roles applied to the user in integer format

Raises:

get_solutions_authored_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of messages created by the user that are marked as accepted solutions.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of messages created by the user that are marked as accepted solutions in integer format

Raises:

get_topics_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of topic messages (excluding replies) posted by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of topic messages (excluding replies) posted by the user in integer format

Raises:

get_user_data(user_settings=None, user_id=None, login=None, email=None)[source]

This method retrieves all user data for a given user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

A dictionary containing the user data for the user

Raises:

khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidParameterError

get_user_id(user_settings=None, login=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]

This method looks up and retrieves the User ID for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: login, email, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
login (str, None) – The username of the user
email (str, None) – The email address of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of User IDs to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The User ID of the user as an integer or a list of User IDs if allow_multiple is True

get_username(user_settings=None, user_id=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]

This method looks up and retrieves the username for a user by leveraging supplied user information.

Note

The priority of supplied fields are as follows: User ID, email, first and last name, last name, first name

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (str, None) – The User ID of the user
email (str, None) – The email address of the user
first_name (str, None) – The first name (i.e. given name) of the user
last_name (str, None) – The last name (i.e. surname) of the user
allow_multiple (bool) – Allows a list of usernames to be returned if multiple results are found
display_warnings (bool) – Determines if warning messages should be displayed (True by default)

Returns:

The username (i.e. login) of the user or a list of usernames if allow_multiple is True

get_users_count(registered=False, online=False)[source]

This method returns the total number of users in an environment. (Filtering possible for registered and online)

New in version 5.3.0.

Parameters:

registered (bool) – Return a count of registered users (False by default)
online (bool) – Return a count of online users (False by default)

Returns:

An integer defining the total user count for the environment

Raises:

get_videos_count(user_settings=None, user_id=None, login=None, email=None)[source]

This method gets the count of videos uploaded by the user.

Parameters:

user_settings (dict, None) – A dictionary containing all relevant user settings supplied in the parent function
user_id (int, str, None) – The User ID associated with the user
login (str, None) – The username of the user
email (str, None) – The email address of the user

Returns:

The number of videos uploaded by the user in integer format

Raises:

impersonate_user(user_login)[source]

This method instantiates and returns the :py:class`khoros.objects.users.ImpersonatedUser` object which: can then be passed to other methods and functions to perform operations as a secondary user.

Note

The authenticated user must have the Administrator role and/or have the Switch User permission enabled.

New in version 4.0.0.

Parameters:: user_login (str) – The username (i.e. login) of the user to be impersonated
Returns:: The instantiated :py:class`khoros.objects.users.ImpersonatedUser` object

query_users_table_by_id(select_fields, user_id)[source]

This method queries the users table for one or more given SELECT fields for a specific User ID.

Parameters:

select_fields (str, tuple, list, set) – One or more SELECT field (e.g. login, messages.count(*), etc.) to query
user_id (int, str) – The User ID associated with the user

Returns:

The API response for the performed LiQL query

Raises:

update_sso_id(new_sso_id, user_id=None, user_login=None)[source]

This method updates the SSO ID for a user.

New in version 4.5.0.

Parameters:

new_sso_id (str) – The new SSO ID for the user
user_id (str, int, None) – The numeric User ID that identifies the user
user_login (str, None) – The username that identifies the user

Returns:

The API response

Raises:

py:exc:khoros.errors.exceptions.MissingRequiredDataError