Primary Modules¶

This section provides details around the primary modules used in the khoros package, which are listed below.

Init Module (khoros)
Core Module (khoros.core)
API Module (khoros.api)
Auth Module (khoros.auth)
Bulk Data Module (khoros.bulk_data)
LiQL Module (khoros.liql)
Objects Module (khoros.objects)
SAML Module (khoros.saml)
Structures Module (khoros.structures)
Studio Module (khoros.studio)
- Base Studio Module (khoros.studio.base)

Init Module (khoros)¶

The Init Module is covered on this page.

Core Module (khoros.core)¶

The Core Module is covered on this page.

API Module (khoros.api)¶

This module handles interactions with the Khoros Community REST APIs.

Module:: khoros.api
Synopsis:: This module handles interactions with the Khoros Community REST APIs
Usage:: import khoros.api
Example:: json_response = khoros.api.get_request_with_retries(url, auth_dict=khoros.auth)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 14 Jun 2023

khoros.api.combine_json_and_avatar_payload(json_payload, avatar_image_path)[source]¶

This function combines JSON payload with an uploaded avatar image (binary file) for a multipart API request.

New in version 2.6.0.

Parameters:

json_payload (dict) – The JSON payload for the API request
avatar_image_path (str) – The full path to the avatar image to use

Returns:

The full multipart payload for the API request

Raises:

FileNotFoundError

khoros.api.define_headers(khoros_object=None, auth_dict=None, params=None, accept=None, content_type=None, multipart=False, default_content_type=False, proxy_user_object=None)[source]¶

This function defines the headers to use in an API call.

Changed in version 5.3.0: Added logging error messages when exceptions are raised.

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: An unnecessary else statement after the khoros.errors.exceptions.MissingAuthDataError exception is raised has been removed.

Changed in version 2.7.5: Added the default_content_type argument which is defined as False by default.

Changed in version 2.7.4: The HTTP headers were changed to be all lowercase in order to be standardized across the library. A function call for khoros.api._normalize_headers() was also introduced.

Changed in version 2.3.0: Added the multipart Boolean argument to remove the content-type key value pair when appropriate.

Parameters:

khoros_object (class[khoros.Khoros], None) – The core Khoros object (Required if the auth_dict parameter is not supplied)
auth_dict (dict, None) – The auth dictionary within the khoros.Khoros class object
params (dict, None) – Header parameters in a dictionary format
accept (str, None) – The accept header value (e.g. application/json)
content_type (str, None) – The content-type header value (e.g. application/json)
multipart (bool) – Defines whether the query is a multipart/form-data query (False by default)
default_content_type (bool) – Determines if application/json should be used as the default content-type value if the key does not exist (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:

A dictionary with the header fields and associated values

Raises:

khoros.errors.exceptions.MissingAuthDataError

khoros.api.delete(url, return_json=False, khoros_object=None, auth_dict=None, headers=None, proxy_user_object=None, verify=None)[source]¶

This function performs a DELETE request against the Core API.

Changed in version 4.3.0: An issue has been fixed that prevented SSL verification from being disabled by the helper file setting.

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.4.0: Support has been introduced for the ssl_verify core setting in the khoros.core.Khoros object.

Parameters:

url (str) – The URI against which the DELETE request will be issued
return_json (bool) – Determines whether the response should be returned in JSON format (Default: False)
khoros_object (class[khoros.Khoros], None) – The core Khoros object (Required if the auth_dict parameter is not supplied)
auth_dict (dict, None) – The auth dictionary within the khoros.Khoros class object
headers (dict, None) – Any header values (in dictionary format) to pass in the API call (optional)
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.
verify (bool, None) – Determines whether to verify the server’s TLS certificate (True by default)

Returns:

The API response from the DELETE request (optionally in JSON format)

khoros.api.deliver_v2_results(response, 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, khoros_object=None)[source]¶

This function parses a Community API v2 response and returned specific data based on the function arguments.

Changed in version 2.8.0: Introduced the ability for error messages to be translated where possible to be more relevant, and added the optional khoros_object argument to facilitate this.

Changed in version 2.5.2: Replaced the return_developer_message argument with return_error_messages.

New in version 2.5.0: The code for this function was extracted from the khoros.objects.messages.create() function.

Parameters:

response – The API response to be parsed
full_response (bool, None) – Determines if the full raw API response should be returned
return_id (bool, None) – Determines if the id field value should be returned
return_url (bool, None) – Determines if the view_href field value should be returned
return_api_url (bool, None) – Determines if the href field value should be returned
return_http_code (bool, None) – Determines if the http_code field value should be returned
return_status (bool, None) – Determines if the http_code field value should be returned
return_error_messages (bool, None) – Determines if error messages should be returned when applicable
split_errors (bool) – Determines if error messages should be split into separate values or merged when applicable
khoros_object – The core khoros.Khoros object

Returns:

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

khoros.api.encode_multipart_data(data_fields)[source]¶

This function uses the Streaming Multipart Data Encoder to encode the payload for a multipart/form-data API call.

Changed in version 3.5.0: This function now import the requests_toolbelt module locally to avoid dependency errors during installation.

New in version 2.3.0.

Auth Module (khoros.auth)¶

This module contains functions that facilitate authenticating to Khoros Community environments.

Module:: khoros.auth
Synopsis:: This module handles authentication-related tasks and operations for the Khoros Community APIs
Usage:: import khoros.auth
Example:: session_key = khoros.auth(KhorosObject)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 14 Jun 2023

khoros.auth.get_oauth_authorization_url(khoros_object)[source]¶

This function constructs the authorization URL needed for the OAuth 2.0 Web Application Flow.

Changed in version 3.3.0: Updated khoros_object._settings to be khoros_object.core_settings.

Parameters:: khoros_object (class[khoros.Khoros]) – The core Khoros object
Returns:: The properly encoded authorization URL in string format

khoros.auth.get_oauth_callback_url_from_user(khoros_object)[source]¶

This function instructs the end-user to visit the authorization URL and provide the full callback URL.

Parameters:: khoros_object (class[khoros.Khoros]) – The core Khoros object
Returns:: The callback URL supplied by the end-user

khoros.auth.get_session_header(session_key)[source]¶

This function constructs and returns a proper API header containing the session key for authorization.

Parameters:: session_key (str) – The session key for the authorization session
Returns:: The API in dictionary format

khoros.auth.get_session_key(khoros_object, username=None, password=None)[source]¶

This function retrieves the session key for an authentication session.

Changed in version 5.3.0: Added logging error messages when exceptions are raised.

Changed in version 5.0.0: The error handling has been improved to provide more useful information when applicable.

Changed in version 4.2.0: The URI is now generated utilizing the khoros.auth._get_khoros_login_url() function.

Changed in version 3.5.0: This function can now be used to authenticate secondary users with either a username and password or with only a username if calling the function with a previously authenticated user with Administrator privileges.

Changed in version 3.4.0: Support has been introduced for the ssl_verify core setting in the khoros.core.Khoros object.

Changed in version 3.3.0: Updated khoros_object._settings to be khoros_object.core_settings.

Changed in version 2.7.4: The HTTP headers were changed to be all lowercase in order to be standardized across the library.

Parameters:

khoros_object (class[khoros.Khoros]) – The core Khoros object
username (str, None) – The username (i.e. login) of a secondary user to authenticate (optional)
password – The password of a secondary user to authentication (optional)

Returns:

The session key in string format

Raises:

khoros.errors.exceptions.SessionAuthenticationError

khoros.auth.get_sso_key(khoros_object)[source]¶

This function retrieves the session key for a LithiumSSO session.

Changed in version 5.3.0: Added logging error messages when exceptions are raised.

Changed in version 5.0.0: The two if statements have been merged.

New in version 4.2.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core Khoros object
Returns:: The session key in string format
Raises:: khoros.errors.exceptions.SsoAuthenticationError

khoros.auth.invalidate_session(khoros_object, user_id=None, sso_id=None)[source]¶

This function invalidates an active authentication session.

Changed in version 3.3.0: Updated khoros_object._settings to be khoros_object.core_settings.

Parameters:

khoros_object (class[khoros.Khoros]) – The core Khoros object
user_id (str, int, None) – The User ID of the service account (Lithium Registration)
sso_id (str, int, None) – The SSO ID of the service account (Single Sign-On)

Returns:

Boolean value defining if the session was invalidated successfully

Raises:

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

Return to Top

Bulk Data Module (khoros.bulk_data)¶

This module contains functions that relate to the Bulk Data API.

Module:: khoros.objects.bulk_data
Synopsis:: This module includes functions that relate to the Bulk Data API.
Usage:: from khoros import bulk_data
Example:: base_url = bulk_data.get_base_url(community_id='example.prod')
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 14 Jun 2023

khoros.bulk_data.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.bulk_data.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

khoros.bulk_data.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

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

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

Changed in version 5.3.0: Added logging error messages when exceptions are raised.

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:

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

khoros.bulk_data.filter_by_action(action_key, bulk_data)[source]¶

This function 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:

khoros.errors.exceptions.DataMismatchError

khoros.bulk_data.get_base_url(khoros_object=None, community_id=None, europe=False)[source]¶

This function 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:

khoros_object (class[khoros.Khoros], None) – The core khoros.Khoros object
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

khoros.bulk_data.query(khoros_object=None, 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 function performs a query against the Bulk Data API to retrieve CSV or JSON data.

Changed in version 5.3.0: Added logging error messages when exceptions are raised.

Changed in version 5.2.0: Improved the error handling to display the response text in the raised exception when available.

New in version 5.0.0.

Parameters:

khoros_object (class[khoros.Khoros], None) – The core khoros.Khoros object
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:

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

Return to Top

LiQL Module (khoros.liql)¶

This module contains functions that enable API queries using the LiQL syntax.

Module:: khoros.liql
Synopsis:: Collection of functions and classes to leverage the Community API v2 and LiQL for searches
Usage:: from khoros import liql (Imported by default in khoros.core package)
Example:: query_url = liql.format_query("SELECT * FROM messages WHERE id = '2' LIMIT 1")
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 23 May 2022

class khoros.liql.LiQLSyntax[source]¶: This class defines lists of syntax elements for use in LiQL queries.

khoros.liql.format_query(query, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='', format_statements=True)[source]¶

This function formats and URL-encodes a raw LiQL query to be able to use it within a Community v2 API URL.

Changed in version 2.1.0: Queries ending in a semicolon (;) will have that character stripped to avoid syntax errors.

Changed in version 2.0.0: Added URL-encoding support for several additional characters.

Parameters:

query (str) – The LiQL query to be formatted and url-encoded
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 properly formatted query to be inserted in the URL

khoros.liql.get_query_url(core_dict, query, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='', format_statements=True)[source]¶

This function defines the full Community API v2 query URL for the LiQL query.

Parameters:

core_dict (dict) – The core dictionary defined in the khoros.core.Khoros object
query (str) – The LiQL query to be encoded and embedded in the URL
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 full Community API v2 URL in string format

khoros.liql.get_returned_items(liql_response, only_first=False)[source]¶

This function prunes a full LiQL API response down to only the returned item(s).

Changed in version 3.3.2: The error handling has been improved to avoid IndexError exceptions from being raised when no items were found in the LiQL response.

New in version 3.2.0.

Parameters:

liql_response (dict) – The full JSON response from the LiQL query as a dictionary
only_first (bool) – Returns only the first item found rather than a list of items (False by default)

Returns:

A list of items (or a single item) found within the LiQL response

Raises:

khoros.errors.exceptions.LiQLParseError

khoros.liql.get_total_count(khoros_object, collection, where_filter='', verify_success=True)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The Khoros object initialized via the khoros.core module
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.GETRequestError

khoros.liql.parse_query_elements(select_fields, from_source, where_filter='', order_by=None, order_desc=True, limit=0)[source]¶

This function parses query elements to construct a full LiQL query in the appropriate syntax.

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)

Returns:

The query response in JSON format

Raises:

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

khoros.liql.parse_select_fields(_select_fields)[source]¶

This function parses the fields to be used in the SELECT statement of the LiQL query.

Changed in version 3.5.0: Refactored the function to leverage the isinstance() built-in function.

Changed in version 3.4.0: Renamed the function to adhere to PEP8 guidelines.

Parameters:: _select_fields (str, tuple, list, set) – The field(s) to be used in the SELECT statement
Returns:: The properly formatted SELECT fields in string format (comma-separated)
Raises:: khoros.errors.exceptions.InvalidFieldError

khoros.liql.parse_where_clause(where, join_logic='AND')[source]¶

This function parses the data supplied for the WHERE clause of a LiQL query.

Changed in version 4.3.0: Refactored the function to be more efficient and Pythonic, and added missing parenthesis on the exception classes.

Changed in version 3.4.0: Renamed the function to adhere to PEP8 guidelines and converted from a private to a public function.

Parameters:

where (str, tuple, list, set, dict) – The WHERE clause information
join_logic (str, tuple, list) – The logic to use

Returns:

A properly formatted WHERE clause (excluding the WHERE statement at the beginning)

Raises:

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

khoros.liql.perform_query(khoros_object, query_url=None, liql_query=None, return_json=True, verify_success=False, allow_exceptions=True, verify=None, return_items=False)[source]¶

This function performs a LiQL query using full Community API v2 URL containing the query.”

Changed in version 5.3.0: Added error logging to correspond with the raised exceptions.

Changed in version 5.0.0: Two if statements have been merged.

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

Changed in version 3.4.0: Support has been introduced for the verify parameter to determine if SSL certificate verification is needed.

Changed in version 2.3.0: Added the allow_exceptions argument (True by default) to allow exceptions to be disabled and updated the error/exception message to be more specific.

Changed in version 2.0.0: Added the ability for a raw LiQL query to be passed to this function rather than only a formatted query URL, and included the optional verify_success Boolean argument to verify a successful response.

Parameters:

khoros_object (class[khoros.Khoros]) – The Khoros object initialized via the khoros.core module
query_url (str, None) – The full Khoros Community API v2 URL for the query
liql_query (str, None) – The LiQL query to be performed, not yet embedded in the query URL
return_json (bool) – Determines if the response should be returned in JSON format (True 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.
verify (bool, None) – Determines whether to verify the server’s TLS certificate (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 API response (in JSON format by default)

Raises:

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

khoros.liql.structure_cursor_clause(cursor=None, liql_response=None)[source]¶

This function structures the CURSOR clause for a LiQL query.

Changed in version 4.0.0: The cursor string has been wrapped in single quotes to prevent the khoros.errors.exceptions.LiQLParseError exception from being raised.

New in version 3.5.0.

Parameters:

cursor (str, None) – A cursor value from the next_cursor key in a LiQL response
liql_response (dict, None) – A full LiQL query response in dictionary format

Returns:

The properly formatted CURSOR clause for use in a new LiQL query

Raises:

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

Return to Top

Objects Module (khoros.objects)¶

This module contains sub-modules that are specific to the various Community API objects.

Module:: khoros.objects
Synopsis:: This module contains sub-modules that are specific to the various Community API objects.
Usage:: from khoros import objects
Example:: objects.archives.archive(khoros_obj, '123', suggested_url, return_status=True)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 28 Sep 2021

Return to Top

Base Objects Module (khoros.objects.base)¶

This module contains functions that relate to the various Community API objects but which are object-agnostic.

Module:: khoros.objects.base
Synopsis:: This module handles general (i.e. object-agnostic) functions relating to API objects.
Usage:: from khoros.objects import base
Example:: node_id = base.get_node_id(absolute_url, 'blog')
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 22 Apr 2022

class khoros.objects.base.Mapping[source]¶: This class includes dictionaries that map API fields and values to those used in this SDK.

Deprecated since version 2.1.0: Use khoros.structures.nodes.Mapping instead.

khoros.objects.base.get_node_id(url, node_type=None)[source]¶

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

Deprecated since version 2.1.0: Use khoros.structures.nodes.get_node_id() instead.

Parameters:

url (str) – The URL from which to parse out the Node ID
node_type (str, NoneType) – 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

khoros.objects.base.get_node_type_from_url(url)[source]¶

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

Deprecated since version 2.1.0: Use khoros.structures.nodes.get_node_type_from_url() instead.

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

Return to Top

Albums Module (khoros.objects.albums)¶

This module includes functions that handle albums that contain images.

Module:: khoros.objects.albums
Synopsis:: This module includes functions that handle albums that contain images
Usage:: from khoros.objects import albums
Example:: response = albums.create_album(khoros_obj, title='My Album', hidden=True)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 17 Jul 2020

khoros.objects.albums.create(khoros_object, title=None, description=None, owner_id=None, hidden=False, default=False, full_response=False)[source]¶

This function creates a new image album for a user.

New in version 2.3.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.albums.format_album_json(title=None, description=None, owner_id=None, hidden=None, default=False)[source]¶

This function formats the JSON payload for the API call.

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)

Returns:

The JSON payload for the album API call

khoros.objects.albums.get_albums_for_user(khoros_object, user_id=None, login=None, public=None, private=None, verify_success=False, allow_exceptions=True)[source]¶

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

New in version 2.3.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not 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.GETRequestError, khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

Return to Top

Archives Module (khoros.objects.archives)¶

This module includes functions that handle the archiving of messages.

Module:: khoros.objects.archives
Synopsis:: This module includes functions that handle archiving messages.
Usage:: from khoros.objects import archives
Example:: archives.archive(khoros_obj, '123', suggested_url, return_status=True)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 02 Nov 2021

khoros.objects.archives.aggregate_results_data(results, include_raw=False)[source]¶

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

Changed in version 4.1.1: This function can now properly handle the ARCHIVED status when returned.

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

khoros.objects.archives.archive(khoros_object, message_id=None, message_url=None, suggested_url=None, archive_entries=None, aggregate_results=False, include_raw=False)[source]¶

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

Changed in version 4.1.0: Made some minor docstring and code adjustments and also removed the following parameters due to the unique response format: full_response, return_id, return_url, return_api_url, return_http_code, return_status, return_error_messages and split_errors

An issue with the khoros.objects.archives.structure_archive_payload() function call was also resolved.

The optional aggregate_results parameter has also been introduced.

New in version 2.7.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.archives.is_archived(khoros_object, message_id)[source]¶

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

New in version 5.2.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.archives.structure_archive_payload(message_id, suggested_url=None, new_board_id=None, archive_entries=None, unarchiving=False)[source]¶

This function structures the payload for an archive-related API call.

New in version 2.7.0.

Parameters:

message_id (str, int, None) – The message ID for the content to be archived
suggested_url (str, None) – The full URL to suggest to the user if the user tries to access the archived message
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 suggested URLs (archiving) or new board IDs (unarchiving)

Note

Alternatively, a list, tuple or set of message IDs can be supplied which will be converted into a dictionary with blank suggested URLs (archiving) or blank new board IDs (unarchiving).
unarchiving (bool) – Indicates that the payload is for an unarchive task (False by default)

Returns:

The payload for the API call as a list of dictionaries containing message IDs and/or suggested URLs

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.objects.archives.unarchive(khoros_object, message_id=None, message_url=None, new_board_id=None, archive_entries=None, aggregate_results=False, include_raw=False)[source]¶

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

Changed in version 4.1.0: Made some minor docstring and code adjustments and also removed the following parameters due to the unique response format: full_response, return_id, return_url, return_api_url, return_http_code, return_status, return_error_messages and split_errors

The optional aggregate_results parameter has also been introduced.

New in version 2.7.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

Return to Top

Attachments Module (khoros.objects.attachments)¶

This module includes functions that handle attachments for messages.

Module:: khoros.objects.attachments
Synopsis:: This module includes functions that handle attachments for messages
Usage:: from khoros.objects import attachments
Example:: payload = format_attachment_payload(titles, file_paths)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 17 Jul 2020

khoros.objects.attachments.construct_multipart_payload(message_json, file_paths, action='create')[source]¶

This function constructs the full multipart payload for a message with one or more attachment.

Changed in version 2.8.0: Support was added for updating existing messages.

New in version 2.3.0.

Parameters:

message_json (dict) – The message information in JSON format
file_paths (str, tuple, list, set) – The full path(s) to one or more attachment (e.g. path/to/file1.pdf)
action (str) – Indicates if the payload will be used to create (default) or update a message

Returns:

The full payload for the multipart API call as a dictionary

Note

See the Requests Documentation for added context on the return data.

Raises:

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

khoros.objects.attachments.format_attachment_payload(file_paths, action='create')[source]¶

This function formats the JSON payload for attachments to be used in an API call.

Changed in version 2.8.0: Support was added for updating existing messages.

New in version 2.3.0.

Parameters:

file_paths (str, tuple, list, set) – The full path(s) to one or more attachment (e.g. path/to/file1.pdf)
action (str) – Indicates if the payload will be used to create (default) or update a message

Returns:

The list of items (in list format) that represent the items API value

Raises:

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

khoros.objects.attachments.get_file_upload_info(file_paths, action='create')[source]¶

This function constructs the binary file(s) portion of the multipart API call.

Changed in version 2.8.0: Support was added for updating an existing message.

New in version 2.3.0.

Parameters:

file_paths (str, tuple, list, set) – The full path(s) to one or more attachment (e.g. path/to/file1.pdf)
action (str) – Indicates if the payload will be used to create (default) or update a message

Returns:

A dictionary with the file upload information for the API call

khoros.objects.attachments.get_list_items(file_paths)[source]¶

This function constructs the items field for the attachments API call.

New in version 2.3.0.

Parameters:: file_paths (str, tuple, list, set) – The full path(s) to one or more attachment (e.g. path/to/file1.pdf)
Returns:: The list of items (in list format) that represent the items API value
Raises:: khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

Return to Top

Labels Module (khoros.objects.labels)¶

This module includes functions that handle labels within a Khoros Community environment.

Module:: khoros.objects.labels
Synopsis:: This module includes functions that handle labels within a Khoros Community environment
Usage:: from khoros.objects import labels
Example:: labels = khoros.labels.get_labels_for_message(12345)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 06 Jul 2023

khoros.objects.labels.get_labels_for_message(khoros_object, message_id)[source]¶

This function retrieves the labels associated with a specific message.

New in version 5.3.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The Khoros object initialized via the khoros.core module
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

Return to Top

Messages Module (khoros.objects.messages)¶

This module includes functions that handle messages within a Khoros Community environment.

Module:: khoros.objects.messages
Synopsis:: This module includes functions that handle messages within a Khoros Community environment
Usage:: from khoros.objects import messages
Example:: response = messages.create_message(khoros_obj, 'My First Message', 'Hello World', node_id='support-tkb')
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 11 Sep 2023

khoros.objects.messages.construct_payload(subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None, context_id=None, context_url=None, is_answer=None, is_draft=None, read_only=None, seo_title=None, seo_description=None, teaser=None, tags=None, cover_image=None, images=None, labels=None, product_category=None, products=None, topic=None, videos=None, parent=None, status=None, moderation_status=None, attachments_to_add=None, attachments_to_remove=None, overwrite_tags=False, ignore_non_string_tags=False, msg_id=None, khoros_object=None, action='create')[source]¶

This function constructs and properly formats the JSON payload for a messages API request.

Todo

Add support for the following parameters which are currently present but unsupported: cover_image, images, labels, product_category, products, topic, videos, parent, status, attachments_to_add and attachments to remove

Changed in version 2.8.0: Added the parent, status, moderation_status, attachments_to_add, attachments_to_remove, overwrite_tags, ignore_non_string_tags, msg_id, khoros_object and action arguments, and added the raises section to the docstring.

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 choosing
context_url (str, None) – Metadata on a message representing a URL to associate with the message (external identifier)
is_answer (bool, None) – Designates the message as an answer on a Q&A board
is_draft (bool, None) – Indicates whether or not the message is still a draft (i.e. unpublished)
read_only (bool, None) – Indicates whether or not 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
teaser (str, None) – The message teaser (used with blog articles)
tags (dict, None) – The query to retrieve tags applied to the message
cover_image (dict, None) – The cover image set for the message
images (dict, None) – The query to retrieve images uploaded to the message
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
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
parent (str, None) – The parent of the message
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.
moderation_status (str, None) –
The moderation status of the message

Note

Acceptable values are unmoderated, approved, rejected, marked_undecided, marked_approved and marked_rejected.
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)
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)
msg_id (str, int, None) – Message ID of an existing message so that its existing tags can be retrieved (optional)
khoros_object (class[khoros.Khoros], None) –
The core khoros.Khoros object

Note

The core object is only necessary when providing a Message ID as it will be needed to retrieve the existing tags from the message.
action (str) – Defines if the payload will be used to create (default) or update a message

Returns:

The properly formatted JSON payload

Raises:

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

khoros.objects.messages.create(khoros_object, 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=False, return_id=False, return_url=False, return_api_url=False, return_http_code=False, return_status=None, return_error_messages=None, split_errors=False, proxy_user_object=None)[source]¶

This function creates a new message within a given node.

Changed in version 4.5.0: The Content-Type header is now explicitly defined as application/json when handling non-multipart requests.

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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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
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 or not 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 or not 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) –
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) – Indicates that the Message ID should be returned (False by default)
return_url (bool) – Indicates that the Message URL should be returned (False by default)
return_api_url (bool) – Indicates that the API URL of the message should be returned (False by default)
return_http_code (bool) – 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 or not 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

khoros.objects.messages.define_context_id(khoros_object, msg_id, context_id='', full_response=False)[source]¶

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

New in version 5.0.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.APIRequestError

khoros.objects.messages.define_context_url(khoros_object, 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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.APIRequestError

khoros.objects.messages.flag(khoros_object, msg_id)[source]¶

This function flags a message as spam.

New in version 5.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.messages.format_content_mention(khoros_object=None, content_info=None, content_id=None, title=None, url=None)[source]¶

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

New in version 2.4.0.

Parameters:

khoros_object (class[khoros.Khoros], None) –
The core khoros.Khoros object

Note

This argument is necessary if the URL (i.e. url argument) is not an absolute URL, as the base community URL will need to be retrieved from the object.
content_info (dict, None) –
A dictionary containing the 'id' and/or 'login' key(s) with the user information

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:

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

khoros.objects.messages.format_user_mention(khoros_object=None, user_info=None, user_id=None, login=None)[source]¶

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

New in version 2.4.0.

Parameters:

khoros_object (class[khoros.Khoros], None) –
The core khoros.Khoros object

Note

This argument is necessary if only one of the user values (i.e. user_id or login) are passed in the function, as a lookup will need to be performed to define the missing value.
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

khoros.objects.messages.get_all_messages(khoros_object, 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.messages.get_all_topic_messages(khoros_object, 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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.GETRequestError

khoros.objects.messages.get_context_id(khoros_object, msg_id)[source]¶

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

New in version 5.0.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
msg_id (str) – The message ID to query

Returns:

The value of the Context ID metadata field

Raises:

khoros.errors.exceptions.get_context_id

khoros.objects.messages.get_context_url(khoros_object, msg_id)[source]¶

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

New in version 5.0.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
msg_id (str) – The message ID to query

Returns:

The value of the Context URL metadata field

Raises:

khoros.errors.exceptions.get_context_id

khoros.objects.messages.get_id_from_url(url)[source]¶

This function retrieves the message ID from a given URL.

New in version 2.4.0.

Parameters:: url (str) – The URL from which the ID will be parsed
Returns:: The ID associated with the message in string format
Raises:: khoros.errors.exceptions.MessageTypeNotFoundError

khoros.objects.messages.get_kudos_for_message(khoros_object, 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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.GETRequestError

khoros.objects.messages.get_metadata(khoros_object, msg_id, metadata_key)[source]¶

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

New in version 4.5.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.messages.is_read_only(khoros_object=None, msg_id=None, msg_url=None, api_response=None)[source]¶

This function checks to see whether or not a message is read-only.

New in version 2.8.0.

Parameters:

khoros_object (class[khoros.Khoros], None) – The core khoros.Khoros object
msg_id (str, int, None) – The unique identifier for the message
msg_url (str, None) – THe URL of the message
api_response (dict, None) – The JSON data from an API response

Returns:

Boolean value indicating whether or not the message is read-only

Raises:

errors.exceptions.MissingRequiredDataError, errors.exceptions.MessageTypeNotFoundError

khoros.objects.messages.kudo(khoros_object, msg_id)[source]¶

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

New in version 5.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.messages.label(khoros_object, msg_id, label_text)[source]¶

This function adds a single label to a given message.

New in version 5.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

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

khoros.objects.messages.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 function parses an API response for a message operation (e.g. creating a message) and returns parsed data.

Deprecated since version 2.5.0: Use the khoros.api.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

khoros.objects.messages.set_read_only(khoros_object, enable=True, msg_id=None, msg_url=None, suppress_warnings=False)[source]¶

This function sets (i.e. enables or disables) the read-only flag for a given message.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
enable (bool) – Determines if the read-only flag should be enabled (True by default)
msg_id (str, int, None) – The unique identifier for the message
msg_url (str, None) – The URL for the message
suppress_warnings (bool) – Determines whether or not warning messages should be suppressed (False by default)

Returns:

None

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.objects.messages.tag(khoros_object, msg_id, tag_text)[source]¶

This function adds a single tag to a given message.

New in version 5.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.messages.unflag(khoros_object, msg_id)[source]¶

This function flags a message as not being spam.

New in version 5.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.messages.update(khoros_object, 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 function 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not 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 or not 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 or not error messages should be merged when applicable
proxy_user_object (class[khoros.objects.users.ImpersonatedUser], None) – Instantiated khoros.objects.users.ImpersonatedUser object to update 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

khoros.objects.messages.validate_message_payload(payload)[source]¶

This function 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

Return to Top

Roles Module (khoros.objects.roles)¶

This module includes functions that handle roles and permissions.

Module:: khoros.objects.roles
Synopsis:: This module includes functions that handle roles and permissions.
Usage:: from khoros.objects import roles
Example:: count = roles.get_total_role_count()
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 24 Sep 2021

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

This function assigns a user to one or more roles.

New in version 4.0.0.

Parameters:

khoros_object:_khoros_object – The core khoros.Khoros object
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

khoros.objects.roles.count_role_types(role_type, roles_dict)[source]¶

This function returns the total count for a specific role type.

New in version 2.4.0.

Parameters:

role_type (str) – The role type for which to return the count (e.g. board, category, etc.)
roles_dict (dict) – Dictionary of the roles for a given Khoros Community environment

Returns:

The total count for the role type as an integer

Raises:

khoros.errors.exceptions.InvalidRoleTypeError

khoros.objects.roles.get_role_id(role_name, scope='community', node_id=None)[source]¶

This function 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

khoros.objects.roles.get_roles_for_user(khoros_object, user_id, fields=None)[source]¶

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

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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
user_id (str, int) – 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.GETRequestError

khoros.objects.roles.get_total_role_count(khoros_object, return_dict=False, total=True, top_level=False, board=False, category=False, group_hub=False)[source]¶

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

New in version 2.4.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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.errors.exceptions.InvalidRoleTypeError

khoros.objects.roles.get_users_with_role(khoros_object, fields='login', role_id=None, role_name=None, scope=None, node_id=None, limit_per_query=1000, cursor=None, where_clause=None, users_list=None, simple=False)[source]¶

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

Changed in version 4.0.0: The function now leverages a while loop instead of recursion in order to avoid raising a RecursionError exception with larger queries.

New in version 3.5.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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.
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.
cursor (str, None) –
Specifies a cursor to be referenced in a LiQL query

Note

This parameter is intended for use by the function when calling itself recursively to retrieve users that exceed the limit_per_query value and will not be leveraged directly in standalone function calls.
where_clause (str, None) –
Specifies an exact WHERE clause for the query to be performed

Note

While technically possible to leverage this parameter in function calls, its primary use is by the function when calling itself recursively to retrieve users that exceed the limit_per_query value.
users_list (list, None) – Provides an existing list of users that is leveraged when the function is called recursively
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:

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

Return to Top

Settings Module (khoros.objects.settings)¶

This module includes functions that handle community, node and user settings.

Module:: khoros.objects.settings
Synopsis:: This module contains functions specific to settings for various structures and objects
Usage:: from khoros.objects import settings
Example:: value = settings.get_node_settings(khoros_object, 'custom.purpose', 'my-board')
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 20 May 2021

khoros.objects.settings.define_node_setting(khoros_object, setting_name, setting_val, node_id, node_type='board', return_json=True)[source]¶

This function 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 and group hubs are now supported.

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)

Changed in version 3.3.1: A minor fix was made to the docstring to correct a Sphinx parsing issue. The function itself was not changed.

New in version 3.2.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.settings.get_node_setting(khoros_object, setting_name, node_id, node_type='board', v1=None, convert_json=False)[source]¶

This function retrieves the value of a specific node setting.

Changed in version 4.0.0: The node type validation has been moved form this function to the lower-level private functions.

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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

Return to Top

Subscriptions Module (khoros.objects.subscriptions)¶

This module includes functions that handle subscriptions.

Module:: khoros.objects.sub
Synopsis:: This module includes functions that handle tags within a Khoros Community environment
Usage:: from khoros.objects import subscriptions
Example:: response = subscribe_to_board(khoros_object, 'my-forum')
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 07 Apr 2021

khoros.objects.subscriptions.add_subscription(khoros_object, target_id, target_type='board', payload=None, included_boards=None, excluded_boards=None, label_board=None, proxy_user_object=None)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core Khoros object
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
label_board (str, int, None) – The Board ID associated with a label (required for label subscriptions)
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

khoros.objects.subscriptions.get_subscription_uri(khoros_object)[source]¶

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

New in version 3.5.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core Khoros object
Returns:: The full (absolute) URI for the subscriptions v2 API endpoint

khoros.objects.subscriptions.subscribe_to_board(khoros_object, node_id, proxy_user_object=None)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core Khoros object
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

khoros.objects.subscriptions.subscribe_to_category(khoros_object, node_id, included_boards=None, excluded_boards=None, proxy_user_object=None)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core Khoros object
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

khoros.objects.subscriptions.subscribe_to_label(khoros_object, label, board_id, proxy_user_object=None)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core Khoros object
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

khoros.objects.subscriptions.subscribe_to_message(khoros_object, msg_id, proxy_user_object=None)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core Khoros object
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

khoros.objects.subscriptions.subscribe_to_product(khoros_object, product_id, proxy_user_object=None)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core Khoros object
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

Return to Top

Tags Module (khoros.objects.tags)¶

This module includes functions that handle tags within a Khoros Community environment.

Module:: khoros.objects.tags
Synopsis:: This module includes functions that handle tags within a Khoros Community environment
Usage:: from khoros.objects import tags
Example:: tags.add_single_tag_to_message('tutorial', 123)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 01 Oct 2022

khoros.objects.tags.add_single_tag_to_message(khoros_object, tag, msg_id, allow_exceptions=False)[source]¶

This function adds a single tag to an existing message.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 2.8.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.POSTRequestError

khoros.objects.tags.add_tags_to_message(khoros_object, tags, msg_id, allow_exceptions=False)[source]¶

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

Changed in version 5.0.0: Removed the redundant return statement.

New in version 2.8.0.

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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.POSTRequestError

khoros.objects.tags.get_tags_for_message(khoros_object, msg_id)[source]¶

This function retrieves the tags for a given message.

New in version 2.8.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
msg_id (str, int) – The Message ID for the message from which to retrieve tags

Returns:

A list of tags associated with the message

khoros.objects.tags.structure_single_tag_payload(tag_text)[source]¶

This function structures the payload for a single tag.

New in version 2.8.0.

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

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

This function 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.

Changed in version 4.1.0: The missing type declaration for the overwrite parameter has been added to the docstring.

New in version 2.8.0.

Parameters:

tags (str, list, tuple, set) – One or more tags or list of tags to be structured
khoros_object (class[khoros.Khoros], None) –
The core khoros.Khoros object

Note

The core object is only necessary when providing a Message ID as it will be needed to retrieve the existing tags from the message.
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

Raises:

khoros.errors.exceptions.MissingRequiredDataError

Return to Top

Users Module (khoros.objects.users)¶

This module includes functions that handle user-related operations.

Module:: khoros.objects.users
Synopsis:: This module includes functions that handle user-related operations.
Usage:: from khoros.objects import users
Example:: khoros.users.create(username='john_doe', email='john.doe@example.com')
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 10 Jul 2023

class khoros.objects.users.ImpersonatedUser(user_login=None, admin_object=None)[source]¶

This class is used for impersonating another user when performing other functions throughout the library.

Changed in version 4.2.0: Added support for user impersonation with LithiumSSO token authentication.

New in version 4.0.0.

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

New in version 4.0.0.

khoros.objects.users.create(khoros_object, 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 function 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.3.0: Updated khoros_object._settings to be khoros_object.core_settings.

Changed in version 2.7.4: The HTTP headers were changed to be all lowercase in order to be standardized across the library.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

KeyError, khoros.errors.exceptions.UserCreationError

khoros.objects.users.delete(khoros_object, user_id, return_json=False)[source]¶

This function deletes a user from the Khoros Community environment.

Changed in version 3.3.0: Updated khoros_object._settings to be khoros_object.core_settings.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.objects.users.get_album_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

This function gets the number of albums for a user.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_all_users(khoros_object, 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_all_users_count(khoros_object)[source]¶

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

New in version 5.2.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
Returns:: The user count for total users as an integer
Raises:: khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_email(khoros_object, user_settings=None, user_id=None, login=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True)[source]¶

This function looks up and 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 email addresses if allow_multiple is True

khoros.objects.users.get_followers_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_following_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_ids_from_login_list(khoros_object, login_list, return_type='list')[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_images_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_kudos_given_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_kudos_received_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_last_visit_timestamp(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_login(khoros_object, 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 function name for the khoros.objects.users.get_username() function.

khoros.objects.users.get_messages_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_online_user_count(khoros_object)[source]¶

This function retrieves the number of users currently online.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
Returns:: The user count for online users as an integer
Raises:: khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_online_users_count(khoros_object, anonymous=None, registered=None)[source]¶

This function returns the total count of users currently online.

New in version 5.0.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_public_images_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_registered_users_count(khoros_object)[source]¶

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

New in version 5.0.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
Returns:: An integer of the total registered users count
Raises:: khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_registration_data(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

This function retrieves the registration data for a given user.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_registration_status(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

This function retrieves the registration status for a given user.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_registration_timestamp(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_replies_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_roles_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_solutions_authored_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_topics_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.get_user_data(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

This function retrieves all user data for a given user.

Parameters:

khoros_object (class[khoros.Khoros]) – he core khoros.Khoros object
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.objects.users.get_user_data_with_v1(khoros_object, return_field, filter_value, filter_field='email', fail_on_no_results=False)[source]¶

This function retrieves user data using a Community API v1 call.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
return_field (str) – The field being retrieved by the function (e.g. id, login, etc.)
filter_value (str, int) – The value for which to filter the user data being queried
filter_field (str) – The field by which the API call should be filtered (email by default)
fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)

Returns:

The value of the return field for the user being queried

khoros.objects.users.get_user_id(khoros_object, user_settings=None, login=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True, fail_on_no_results=False)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 (False by default)
display_warnings (bool) – Determines if warning messages should be displayed (True by default)
fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)

Returns:

The username of the user as a string or a list of usernames if allow_multiple is True

khoros.objects.users.get_username(khoros_object, user_settings=None, user_id=None, email=None, first_name=None, last_name=None, allow_multiple=False, display_warnings=True, fail_on_no_results=False)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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)
fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)

Returns:

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

khoros.objects.users.get_users_count(khoros_object, registered=False, online=False)[source]¶

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

New in version 5.3.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

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

khoros.objects.users.get_videos_count(khoros_object, user_settings=None, user_id=None, login=None, email=None)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.impersonate_user(khoros_object, user_login)[source]¶

This function 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.

New in version 4.0.0.

Parameters:

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

Note

The authenticated user must have the Administrator role and/or have the Switch User permission enabled.
user_login (str) – The username (i.e. login) of ther user to be impersonated

Returns:

The instantiated :py:class`khoros.objects.users.ImpersonatedUser` object

khoros.objects.users.process_user_settings(user_settings=None, user_id=None, albums=None, avatar=None, banned=None, biography=None, bonus_points=None, cover_image=None, deleted=None, email=None, email_excluded=None, first_name=None, followers=None, following=None, href=None, images=None, kudos_given=None, kudos_received=None, kudos_weight=None, language=None, last_name=None, last_visit_time=None, location=None, login=None, messages=None, metrics=None, online_status=None, password=None, personal_data=None, public_images=None, rank=None, registration_data=None, reviews=None, roles=None, signature_topics=None, solutions_authored=None, sso_id=None, threads_participated=None, topics=None, user_badges=None, videos=None, view_href=None, web_page_url=None)[source]¶

This function processes the user_settings for functions and formats them into a normalized dictionary.

Parameters:

user_settings (dict, None) – Allows all user settings to be passed to the function within a single dictionary
user_id (int, str, None) – The unique User ID associated with the user
albums (dict, None) – The image albums associated with the user’s profile
avatar (str, None) – The avatar (profile image) of the user
banned (bool, None) – Defines whether or not the user is banned (True if banned)
biography (str, None) – The user’s biography for their profile
bonus_points (int, None) – Bonus points that an admin has assigned to the user
cover_image (str, None) – The cover image to be used on the user’s profile
deleted (bool, None) – Defines whether or not the user’s account is deleted. (True if deleted)
email (str, None) – The email address for the user
email_excluded (bool, None) – Defines whether or not the user has selected the “don’t send me any community emails” option
first_name (str, None) – The user’s first name (i.e. given name)
followers (dict, None) – The community members who are subscribed to the user (i.e. “friends”)
following (dict, None) – The community members who the user follows (i.e. “friends”)
href (str, None) – Relative href to the user resource (i.e. canonical path to the resource relative to the API root)
images (dict, None) – Images uploaded by the user
kudos_given (dict, None) – The kudos given to the user by other community members
kudos_received (dict, None) – The kudos received by the user from other community members
kudos_weight (int, None) – The weight of the kudos awarded
language (str, None) – The default language selected by the user
last_name (str, None) – The user’s last name (i.e. surname)
last_visit_time (type[datetime.datetime], None) – The date/time the user was last active on the community
location (str, None) – The user’s location
login (str, None) – The username (i.e. login) for the user
messages (dict, None) – The messages (topics and replies) posted by the user
metrics – The metrics of the user activity
online_status (str, None) – The status of the user (ONLINE or OFFLINE)
password (str, None) – The password for the user
personal_data – The personal_data object associated with the user account containing PII about the user
public_images (dict, None) – Images uploaded by the user that the user has made public
rank (dict, None) – The rank of the user in the community (Value is -1 if no rank has been achieved)
registration_data (dict, None) – Registration information about the user
reviews (dict, None) – Product reviews written by the user
roles (dict, None) – The roles that have been assigned to the user
signature_topics – Topics of interest associated with this user account that the user has selected to display
solutions_authored (dict, None) – The solutions authored by the user (i.e posts selected as an accepted solutions)
sso_id (str, None) – The Single Sign-On (SSO) ID for the user
threads_participated (list, None) – The topic IDs of message threads in which the user has participated
topics (dict, None) – Topic messages (i.e the root message of a conversation) authored by the user
user_badges – Badges earned by the user (as well as visible but unearned badges depending on admin settings)
videos (dict, None) – Videos uploaded by the user
view_href (str, None) – The fully-qualified href to the user resource in the Web UI (i.e. the URI of the ViewProfile page)
web_page_url (str, None) – The URL to the user’s website

Returns:

The dictionary containing the user settings

khoros.objects.users.query_users_table_by_id(khoros_object, select_fields, user_id, first_item=False)[source]¶

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

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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
first_item (bool) – Determines if only the first item should be returned (False by default)

Returns:

The API response for the performed LiQL query

Raises:

khoros.errors.exceptions.GETRequestError

khoros.objects.users.structure_payload(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)[source]¶

This function properly structures the payload to be passed when creating or manipulating users via the API.

Changed in version 4.0.0: Fixed an issue that was resulting in a KeyError exception potentially getting raised, and added the missing type key that was preventing users from getting created successfully.

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

Returns:

The properly formatted payload within a dictionary

khoros.objects.users.structure_user_dict_list(khoros_object=None, user_dicts=None, id_list=None, login_list=None)[source]¶

This function structures a list of user data dictionaries for use in various API request payloads.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
user_dicts (list, dict, None) – A list of dictionaries (or single dictionary) containing user data (id at a minimum)
id_list (list, tuple, set, None) – A list of user IDs to be converted into user data dictionaries
login_list (list, tuple, set, None) – A list of usernames (i.e. logins) to be converted into user data dictionaries

Returns:

The properly formatted list of user data dictionaries for the supplied users

Raises:

TypeError, khoros.errors.exceptions.MissingRequiredDataError

khoros.objects.users.update_sso_id(khoros_object, new_sso_id, user_id=None, user_login=None)[source]¶

This function updates the SSO ID for a user.

New in version 4.5.0.

Caution

This functionality is currently unsupported directly via REST API. It is recommended that FreeMarker and a custom endpoint be leveraged instead. See Khoros Atlas for more details.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

Return to Top

SAML Module (khoros.saml)¶

This module includes functions that relate to SAML Single Sign-On (SSO).

Module:: khoros.objects.saml
Synopsis:: This module includes functions that relate to SAML SSO.
Usage:: from khoros import saml
Example:: assertion = saml.import_assertion(file_path)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 23 May 2022

khoros.saml.import_assertion(file_path, base64_encode=True, url_encode=True)[source]¶

This function 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

khoros.saml.send_assertion(khoros_object, assertion=None, file_path=None, base64_encode=True, url_encode=True)[source]¶

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

New in version 4.3.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

Return to Top

Structures Module (khoros.structures)¶

This module contains sub-modules that are specific to the various Community structures.

Module:: khoros.structures
Synopsis:: This module contains submodules that are specific to the various Community structures.
Usage:: from khoros import structures
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 20 Sep 2022

Return to Top

Base Structures Module (khoros.structures.base)¶

This module contains functions relating to structures. (i.e. categories, nodes and tenants/communities)

Module:: khoros.structures.base
Synopsis:: This module contains functions relating to structures (i.e. categories, nodes and tenants)
Usage:: from khoros.structures import base
Example:: details = base.get_details(khoros_object, 'category', 'category-id')
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 29 Sep 2022

class khoros.structures.base.Mapping[source]¶: This class contains lists and dictionaries used to map structure data.

khoros.structures.base.get_details(khoros_object, identifier='', structure_type=None, first_item=None, community=False)[source]¶

This function retrieves all details for a structure type via LiQL.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
identifier (str) – The identifier (Category/Node ID or URL) by which to filter the results in the WHERE clause.
structure_type –
Designates the structure as a category, node or community

Note

Optional if the identifier is a URL or the community Boolean is True
first_item (bool) – Filters the response data to the first item returned (True by default)
community (bool) – Alternate way of defining the structure type as a community (False by default)

Returns:

The details for the structure type as a dictionary

Raises:

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

khoros.structures.base.get_structure_field(khoros_object, field, identifier='', details=None, structure_type=None, first_item=True, community=False)[source]¶

This function returns a specific API field value for a community, category or node collection.

Changed in version 5.1.1: Error handling was introduced to account for root-level categories.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
field (str) – The field from the khoros.structures.base.Mapping class whose value should be returned
identifier (str) – The identifier (Category/Node ID or URL) by which to filter the results in the WHERE clause.
structure_type (str, None) –
Designates the structure as a category, node or community

Note

Optional if the identifier is a URL or the community Boolean is True
first_item (bool) – Filters the response data to the first item returned (True by default)
community (bool) – Alternate way of defining the structure type as a community (False by default)

Returns:

The API field value in its appropriate format

Raises:

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

khoros.structures.base.get_structure_id(url)[source]¶

This function retrieves the Node ID from a full URL.

Changed in version 2.6.0: The function was renamed from _get_node_id to get_structure_id and converted from private to public.

New in version 2.1.0.

Parameters:: url (str) – The full URL of the node
Returns:: The ID in string format

khoros.structures.base.get_structure_type_from_url(url, ignore_exceptions=False)[source]¶

This function determines if a URL is for a category or node (or neither).

New in version 2.1.0.

Parameters:

url (str) – The URL to be evaluated
ignore_exceptions (bool) – Determines if exceptions should not be raised

Returns:

A string with category or node, or a blank string if neither

khoros.structures.base.is_category_url(url, ignore_exceptions=False)[source]¶

This function identifies if a provided URL is for a category in the environment.

New in version 2.1.0.

Parameters:

url (str) – The URL to be evaluated
ignore_exceptions (bool) – Determines if exceptions should not be raised

Returns:

Boolean value indicating if the URL is associated with a category

Raises:

khoros.errors.exceptions.InvalidStructureTypeError

khoros.structures.base.is_node_url(url, ignore_exceptions=False)[source]¶

This function identifies if a provided URL is for a node in the environment.

New in version 2.1.0.

Parameters:

url (str) – The URL to be evaluated
ignore_exceptions (bool) – Determines if exceptions should not be raised

Returns:

Boolean value indicating if the URL is associated with a node

Raises:

khoros.errors.exceptions.InvalidStructureTypeError

khoros.structures.base.limit_to_first_child(structure_data)[source]¶

This function limits structure data to be only for the first child.

New in version 2.1.0.

Parameters:: structure_data (dict) – The data captured from the khoros.structures.base.get_details() function
Returns:: The data dictionary that has been restricted to the first child
Raises:: TypeError, KeyError

khoros.structures.base.structure_exists(khoros_object, structure_type, structure_id=None, structure_url=None)[source]¶

This function checks to see if a structure (i.e. node, board, category or group hub) exists.

New in version 2.7.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
structure_type (str) – The type of structure (e.g. board, category, node or grouphub) .. note:: The group hub value (as two words) is also acceptable.
structure_id (str, None) – The ID of the structure to check
structure_url (str, None) – The URL of the structure to check

Returns:

Boolean value indicating whether the structure already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.structures.base.verify_structure_type(identifier, structure_type, community=False)[source]¶

This function verifies the structure type by examining the identifier(s) and provided structure type value.

New in version 2.1.0.

Parameters:

identifier (str) – The identifier (Category/Node ID or URL) by which to filter the results in the parent function
structure_type (str) –
Designates the structure as a category, node or community

Note

Optional if the identifier is a URL or the community Boolean is True
community (bool) – Alternate way of defining the structure type as a community (False by default)

Returns:

The appropriately labeled and verified structure type

Raises:

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

Return to Top

Boards Module (khoros.structures.boards)¶

This module contains functions specific to boards within the Khoros Community platform.

Module:: khoros.structures.boards
Synopsis:: This module contains functions specific to boards within the Khoros Community platform
Usage:: from khoros.structures import boards
Example:: board_url = boards.create(khoros_object, 'my-board', 'My Board', 'forum', return_url=True)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 11 Sep 2023

khoros.structures.boards.board_exists(khoros_object, board_id=None, board_url=None)[source]¶

This function 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.boards.create(khoros_object, 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 function 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not 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

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 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 or not 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

khoros.structures.boards.get_all_messages(khoros_object, 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 more specifically adjust the LiQL query.

New in version 5.3.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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:

khoros.errors.exceptions.GETRequestError

khoros.structures.boards.get_all_topic_messages(khoros_object, 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:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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.GETRequestError

khoros.structures.boards.get_board_id(url)[source]¶

This function 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

khoros.structures.boards.get_message_count(khoros_object, board_id)[source]¶

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

New in version 5.3.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
board_id (str) – The ID of the board to query

Returns:

The number of messages within the node

khoros.structures.boards.structure_payload(khoros_object, 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 function structures the payload to use in a Community API v2 request involving a board.

New in version 2.5.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not 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

Returns:

The full and properly formatted payload for the API request

Raises:

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

Return to Top

Categories Module (khoros.structures.categories)¶

This module contains functions specific to categories within the Khoros Community platform.

Module:: khoros.structures.categories
Synopsis:: This module contains functions specific to categories within the Khoros Community platform
Usage:: from khoros.structures import categories
Example:: category_id = categories.get_category_id(url)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 17 Jul 2020

khoros.structures.categories.category_exists(khoros_object, category_id=None, category_url=None)[source]¶

This function checks to see if a category exists.

New in version 2.7.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not the category already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.structures.categories.create(khoros_object, category_id, category_title, parent_id=None, return_json=True)[source]¶

This function creates a new category.

New in version 2.5.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not 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

khoros.structures.categories.friendly_date_enabled(khoros_object, identifier=None, category_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_active_skin(khoros_object, identifier=None, category_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_category_details(khoros_object, identifier, first_item=True)[source]¶

This function returns a dictionary of category configuration settings.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 category details within a dictionary

Raises:

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

khoros.structures.categories.get_category_field(khoros_object, field, identifier=None, category_details=None)[source]¶

This function returns a specific category field from the Khoros Community API.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
field (str) – The field from the khoros.structures.base.Mapping class whose value should be returned
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.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

khoros.structures.categories.get_category_id(url)[source]¶

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

Changed in version 2.6.0: The function was refactored to leverage the khoros.structures.base.get_structure_id() function.

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

khoros.structures.categories.get_creation_date(khoros_object, identifier=None, category_details=None)[source]¶

This function retrieves the creation date of a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_depth(khoros_object, identifier=None, category_details=None)[source]¶

This function retrieves the depth of a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_description(khoros_object, identifier=None, category_details=None)[source]¶

This function retrieves the description for a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_friendly_date_max_age(khoros_object, identifier=None, category_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_language(khoros_object, identifier=None, category_details=None)[source]¶

This function retrieves the defined language for a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_parent_id(khoros_object, identifier=None, category_details=None)[source]¶

This function retrieves the parent ID for a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_parent_type(khoros_object, identifier=None, category_details=None)[source]¶

This function retrieves the parent type for a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_parent_url(khoros_object, identifier=None, category_details=None)[source]¶

This function retrieves the parent URL for a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_position(khoros_object, identifier=None, category_details=None)[source]¶

This function retrieves the position of a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_root_id(khoros_object, identifier=None, category_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_root_type(khoros_object, identifier=None, category_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_root_url(khoros_object, identifier=None, category_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.get_title(khoros_object, identifier=None, full_title=True, short_title=False, category_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
identifier (str, None) – The Category ID or Category URL with which to identify the category
full_title (bool) – Return the full title of the category (True by default)
short_title (bool) – Return the short title of the category (False by default)
category_details (dict, None) – Dictionary containing category details (optional)

Returns:

The category 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

khoros.structures.categories.get_total_category_count(khoros_object)[source]¶

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

Deprecated since version 2.6.0: Use the khoros.structures.categories.get_total_count() function instead.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
Returns:: The total number of categories as an integer
Raises:: khoros.errors.exceptions.GETRequestError

khoros.structures.categories.get_total_count(khoros_object)[source]¶

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

New in version 2.6.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
Returns:: The total number of categories as an integer
Raises:: khoros.errors.exceptions.GETRequestError

khoros.structures.categories.get_url(khoros_object, category_id=None, category_details=None)[source]¶

This function retrieves the URL of a given category.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
category_id (str, None) – The ID of the category to be evaluated (optional if category_details dictionary is 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

khoros.structures.categories.get_views(khoros_object, identifier=None, category_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.categories.is_hidden(khoros_object, identifier=None, category_details=None)[source]¶

This function identifies whether or not a given category is hidden.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

Return to Top

Communities Module (khoros.structures.communities)¶

This module contains functions specific to the high-level community configuration.

Module:: khoros.structures.communities
Synopsis:: This module contains functions specific to the high-level community configuration
Usage:: from khoros.structures import communities
Example:: details = get_community_details(khoros_object)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 24 May 2022

khoros.structures.communities.email_confirmation_required_to_post(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.communities.friendly_date_enabled(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean value indicating if the feature is enabled

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_active_skin(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The skin name as a string

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_community_details(khoros_object)[source]¶

This function returns a dictionary of community configuration settings.

New in version 2.1.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
Returns:: The community details within a dictionary
Raises:: khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_community_field(khoros_object, field, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
field (str) – The field from the khoros.structures.base.Mapping class whose value should be returned
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

khoros.structures.communities.get_creation_date(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.communities.get_date_pattern(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The date pattern in string format

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_description(khoros_object, community_details=None)[source]¶

This function retrieves the description of the environment.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The description in string format

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_friendly_date_max_age(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean value indicating if the feature is enabled

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_language(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The language code as a string

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_max_attachments(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The value as an integer

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_ooyala_player_branding_id(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The branding ID in string format

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_permitted_attachment_types(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The permitted file types within a list

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_primary_url(khoros_object, community_details=None)[source]¶

This function retrieves the primary URL of the environment.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The primary URL in string format

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_sign_out_url(khoros_object, community_details=None)[source]¶

This function retrieves the Sign Out URL for the environment.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The Sign Out URL as a string

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_tenant_id(khoros_object, community_details=None)[source]¶

This function retrieves the tenant ID of the environment.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

The tenant ID in string format

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.get_title(khoros_object, full_title=True, short_title=False, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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.GETRequestError

khoros.structures.communities.show_breadcrumb_at_top_level(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.communities.show_community_node_in_breadcrumb(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.communities.sso_enabled(khoros_object, community_details=None)[source]¶

This function checks whether SSO is enabled for the community.

New in version 5.0.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

A Boolean value indicating whether SSO is enabled

khoros.structures.communities.top_level_categories_enabled(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
community_details (dict, None) – Dictionary containing community details (optional)

Returns:

Boolean value indicating if top level categories are enabled

Raises:

khoros.errors.exceptions.GETRequestError

khoros.structures.communities.top_level_categories_on_community_page(khoros_object, community_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

Return to Top

Group Hubs Module (khoros.structures.grouphubs)¶

This module contains functions specific to group hubs within the Khoros Community platform.

Module:: khoros.structures.grouphubs
Synopsis:: This module contains functions specific to group hubs within the Khoros Community platform
Usage:: from khoros.structures import grouphubs
Example:: group_hub_url = grouphubs.create(khoros_object, gh_id, gh_title, disc_styles, return_url=True)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 23 May 2022

khoros.structures.grouphubs.create(khoros_object, 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 function creates a new group hub within a Khoros Community environment.

Changed in version 2.7.2: Changed the data type for membership_type from dict to str in the docstring.

New in version 2.6.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 (str, 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) – Defines that all discussion styles should be enabled 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 or not 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.InvalidPayloadValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

khoros.structures.grouphubs.get_grouphub_id(url)[source]¶

This function retrieves the Group Hub ID for a given group hub when provided its URL.

New in version 2.6.0.

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

khoros.structures.grouphubs.get_total_count(khoros_object)[source]¶

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

New in version 2.6.0.

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
Returns:: The total number of group hubs as an integer

khoros.structures.grouphubs.grouphub_exists(khoros_object, grouphub_id=None, grouphub_url=None)[source]¶

This function checks to see if a group hub exists.

New in version 2.7.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not the group hub already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.structures.grouphubs.refresh_enabled_discussion_styles(khoros_object)[source]¶

This function refreshes the all_discussion_styles global variable to match what is in the: core object settings when applicable.

Changed in version 5.0.0: Removed the redundant return statement.

Changed in version 3.3.0: Updated khoros_object._settings to be khoros_object.core_settings.

New in version 2.6.0.

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

khoros.structures.grouphubs.structure_payload(khoros_object, 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 function structures the payload to use in a Group Hub API request.

Changed in version 2.7.3: Changed the grouphub value in the initial payload definition to be a dictionary rather than a string to mitigate a TypeError exception getting raised.

Changed in version 2.7.2: Changed the data type for membership_type from dict to str in the docstring and fixed some bad logic raising false positive exceptions.

New in version 2.6.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 (str, 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) – Defines that 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

khoros.structures.grouphubs.update_title(khoros_object, 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 function updates the title of an existing group hub.

New in version 2.6.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not 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

Return to Top

Nodes Module (khoros.structures.nodes)¶

This module contains functions specific to nodes within the Khoros Community platform.

Module:: khoros.structures.nodes
Synopsis:: This module contains functions specific to nodes within the Khoros Community platform
Usage:: from khoros.structures import nodes
Example:: node_id = nodes.get_id(url)
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 10 Mar 2021

class khoros.structures.nodes.Mapping[source]¶: This class includes dictionaries that map API fields and values to those used in this SDK.

khoros.structures.nodes.get_avatar_url(khoros_object, identifier, node_details=None, original=True, tiny=False, small=False, medium=False, large=False)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 image in its original size 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

khoros.structures.nodes.get_creation_date(khoros_object, identifier, node_details=None, friendly=False)[source]¶

This function returns the creation date of a given node.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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) – Determines whether to return the “friendly” date (e.g. Friday) instead (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

khoros.structures.nodes.get_depth(khoros_object, identifier, node_details=None)[source]¶

This function returns the depth of a given node.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_description(khoros_object, identifier, node_details=None)[source]¶

This function returns the description of a given node.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_discussion_style(khoros_object, identifier, node_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_node_details(khoros_object, identifier, first_item=True)[source]¶

This function returns a dictionary of node configuration settings.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_node_field(khoros_object, field, identifier=None, node_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
field (str) – The field from the khoros.structures.base.Mapping class whose value should be returned
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

khoros.structures.nodes.get_node_id(url=None, node_type=None, node_details=None)[source]¶

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

Parameters:

url (str, None) – 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
node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns:

The Node ID retrieved from the URL

Raises:

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

khoros.structures.nodes.get_node_type_from_url(url)[source]¶

This function 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

khoros.structures.nodes.get_parent_id(khoros_object, identifier, node_details=None, include_prefix=False)[source]¶

This function returns the Parent ID of a given node.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 (False by default)

Returns:

The Parent ID as a string

Raises:

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

khoros.structures.nodes.get_parent_type(khoros_object, identifier, node_details=None)[source]¶

This function returns the parent type of a given node.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_parent_url(khoros_object, identifier, node_details=None)[source]¶

This function returns the parent URL of a given node.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_position(khoros_object, identifier, node_details=None)[source]¶

This function returns the position of a given node.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_root_id(khoros_object, identifier, node_details=None, include_prefix=False)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 (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

khoros.structures.nodes.get_root_type(khoros_object, identifier, node_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_root_url(khoros_object, identifier, node_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_title(khoros_object, identifier=None, full_title=True, short_title=False, node_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_total_node_count(khoros_object)[source]¶

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

Parameters:: khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
Returns:: The total number of nodes as an integer
Raises:: khoros.errors.exceptions.GETRequestError

khoros.structures.nodes.get_type(khoros_object, identifier, node_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_url(khoros_object, node_id=None, node_details=None)[source]¶

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

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.get_views(khoros_object, identifier, node_details=None)[source]¶

This function returns the views for a given node.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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

khoros.structures.nodes.is_hidden(khoros_object, identifier, node_details=None)[source]¶

This function identifies whether or not a given node is hidden.

New in version 2.1.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not the node is hidden

Raises:

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

khoros.structures.nodes.node_exists(khoros_object, node_id=None, node_url=None)[source]¶

This function checks to see if a node exists.

New in version 2.7.0.

Parameters:

khoros_object (class[khoros.Khoros]) – The core khoros.Khoros object
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 or not the node already exists

Raises:

khoros.errors.exceptions.MissingRequiredDataError

Return to Top

Studio Module (khoros.studio)¶

This module contains sub-modules that relate to the Lithium SDK and the Khoros Community Studio Plugin.

Module:: khoros.studio
Synopsis:: This module performs tasks that relate to the Lithium SDK and the Khoros Community Studio Plugin.
Usage:: from khoros import studio
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 20 May 2020

Return to Top

Base Studio Module (khoros.studio.base)¶

This module contains functions that handle the base functionality of the khoros.studio module.

Module:: khoros.studio.base
Synopsis:: This module handles the base functionality of the studio module.
Usage:: import khoros.studio.base as studio_base
Created By:: Jeff Shurtliff
Last Modified:: Jeff Shurtliff
Modified Date:: 17 Jul 2020

khoros.studio.base.get_node_version()[source]¶

This function 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

khoros.studio.base.get_npm_version()[source]¶

This function identifies and returns the installed npm version.

New in version 2.5.1.

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

khoros.studio.base.get_sdk_version()[source]¶

This function 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

khoros.studio.base.node_installed()[source]¶

This function checks whether Node.js is installed.

New in version 2.5.1.

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

khoros.studio.base.npm_installed()[source]¶

This function checks whether npm is installed.

New in version 2.5.1.

Returns:: Boolean value indicating whether npm is installed

khoros.studio.base.sdk_installed()[source]¶

This function 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

Return to Top

The previous page addresses Khoros Core Object within the khoros package. The next page addresses the Supporting Modules within the khoros package.

Primary Modules¶

Init Module (khoros)¶

Core Module (khoros.core)¶

API Module (khoros.api)¶

Auth Module (khoros.auth)¶

Bulk Data Module (khoros.bulk_data)¶

LiQL Module (khoros.liql)¶

Objects Module (khoros.objects)¶

Base Objects Module (khoros.objects.base)¶

Albums Module (khoros.objects.albums)¶

Archives Module (khoros.objects.archives)¶

Attachments Module (khoros.objects.attachments)¶

Labels Module (khoros.objects.labels)¶

Messages Module (khoros.objects.messages)¶

Roles Module (khoros.objects.roles)¶

Settings Module (khoros.objects.settings)¶

Subscriptions Module (khoros.objects.subscriptions)¶

Tags Module (khoros.objects.tags)¶

Users Module (khoros.objects.users)¶

SAML Module (khoros.saml)¶

Structures Module (khoros.structures)¶

Base Structures Module (khoros.structures.base)¶

Boards Module (khoros.structures.boards)¶

Categories Module (khoros.structures.categories)¶

Communities Module (khoros.structures.communities)¶

Group Hubs Module (khoros.structures.grouphubs)¶

Nodes Module (khoros.structures.nodes)¶

Studio Module (khoros.studio)¶

Base Studio Module (khoros.studio.base)¶

Navigation

Related Topics

Donate/support