Supporting Modules

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


Classes & Exceptions

This section includes modules that contain the classes and exceptions used throughout the package.


Errors Module (khoros.errors)

This module contains all of the exception classes and error handling functions leveraged throughout the library.

Package:

khoros.errors

Synopsis:

This module includes custom exceptions

Usage:

import khoros.errors (Imported by default in primary package)

Example:

raise errors.exceptions.MissingAuthDataError

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

01 Jul 2020

Return to Top


Exceptions Module (khoros.errors.exceptions)

This sub-module contains all of the exception classes leveraged in functions throughout the library.

Module:

khoros.errors.exceptions

Synopsis:

Collection of exception classes relating to the khoros library

Usage:

import khoros.errors.exceptions

Example:

raise khoros.errors.exceptions.BadCredentialsError()

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

01 Nov 2022

exception khoros.errors.exceptions.APIConnectionError(*args, **kwargs)[source]

This exception is used when the API query could not be completed due to connection aborts and/or timeouts.

exception khoros.errors.exceptions.APIRequestError(*args, **kwargs)[source]

This exception is used for generic API request errors when there isn’t a more specific exception.

Changed in version 4.5.0: Fixed an issue with the default message.

exception khoros.errors.exceptions.CurrentlyUnsupportedError(*args, **kwargs)[source]

This exception is used when a feature or functionality being used is currently unsupported.

Changed in version 4.5.0: Introduced the ability for a fully customized message to be displayed.

Changed in version 2.0.0: The unsupported feature can be passed as a string argument to explicitly reference it in the exception.

exception khoros.errors.exceptions.DELETERequestError(*args, **kwargs)[source]

This exception is used for generic DELETE request errors when there isn’t a more specific exception.

exception khoros.errors.exceptions.DataMismatchError(*args, **kwargs)[source]

This exception is used when there is a mismatch between two data sources.

Changed in version 5.1.2: Fixed an issue where the message would not display properly.

New in version 2.3.0.

exception khoros.errors.exceptions.FeatureNotConfiguredError(*args, **kwargs)[source]

This exception is used when an API request fails because a feature is not configured.

New in version 4.0.0.

exception khoros.errors.exceptions.GETRequestError(*args, **kwargs)[source]

This exception is used for generic GET request errors when there isn’t a more specific exception.

Changed in version 3.2.0: Enabled the ability to optionally pass status_code and/or message arguments.

exception khoros.errors.exceptions.HelperFunctionNotFoundError(*args, **kwargs)[source]

This exception is used when a function referenced in the helper config file does not exist.

exception khoros.errors.exceptions.InvalidCallbackURLError(*args, **kwargs)[source]

This exception is used when an invalid Callback URL for OAuth 2.0 was not provided.

exception khoros.errors.exceptions.InvalidEndpointError(*args, **kwargs)[source]

This exception is used when an invalid API endpoint / service is provided.

Changed in version 5.1.2: Removed part of the default message that was specifically for Khoros JX, which is obsolete.

exception khoros.errors.exceptions.InvalidFieldError(*args, **kwargs)[source]

This exception is used when an invalid field is provided.

New in version 2.1.0.

exception khoros.errors.exceptions.InvalidHelperArgumentsError(*args, **kwargs)[source]

This exception is used when the helper function was supplied arguments instead of keyword arguments.

exception khoros.errors.exceptions.InvalidHelperFileTypeError(*args, **kwargs)[source]

This exception is used when an invalid file type is provided for the helper file.

exception khoros.errors.exceptions.InvalidLookupTypeError(*args, **kwargs)[source]

This exception is used when an invalid API lookup type is provided.

exception khoros.errors.exceptions.InvalidMessagePayloadError(*args, **kwargs)[source]

This exception is used when the payload for creating a message is invalid.

exception khoros.errors.exceptions.InvalidMetadataError(*args, **kwargs)[source]

This exception is used when there is an issue involving message metadata.

New in version 4.5.0.

exception khoros.errors.exceptions.InvalidNodeTypeError(*args, **kwargs)[source]

This exception is used when an invalid node type is provided.

exception khoros.errors.exceptions.InvalidOperatorError(*args, **kwargs)[source]

This exception is used when an invalid operator is provided for the LiQL query.

exception khoros.errors.exceptions.InvalidParameterError(*args, **kwargs)[source]

This exception is used when an invalid parameter is provided.

New in version 5.2.0.

exception khoros.errors.exceptions.InvalidPayloadValueError(*args, **kwargs)[source]

This exception is used when an invalid value is provided for a payload field.

New in version 2.6.0.

exception khoros.errors.exceptions.InvalidRequestTypeError(*args, **kwargs)[source]

This exception is used when an invalid API request type is provided.

exception khoros.errors.exceptions.InvalidRoleError(*args, **kwargs)[source]

This exception is used when an invalid role is provided.

Changed in version 5.1.2: Fixed an issue with how the message is displayed when a value is passed as an argument.

exception khoros.errors.exceptions.InvalidRoleTypeError(*args, **kwargs)[source]

This exception is used when an invalid role type is provided.

Changed in version 5.1.2: Fixed an issue with how the message is displayed when a value is passed as an argument.

exception khoros.errors.exceptions.InvalidStructureTypeError(*args, **kwargs)[source]

This exception is used when an invalid node type is provided.

New in version 2.1.0.

exception khoros.errors.exceptions.InvalidURLError(*args, **kwargs)[source]

This exception is used when a provided URL is invalid.

New in version 2.1.0.

exception khoros.errors.exceptions.KhorosError[source]

This is the base class for Khoros exceptions.

exception khoros.errors.exceptions.LiQLParseError(*args, **kwargs)[source]

This exception is used when a function is unable to successfully parse a LiQL response.

New in version 3.2.0.

exception khoros.errors.exceptions.LookupMismatchError(*args, **kwargs)[source]

This exception is used when an a lookup value doesn’t match the supplied lookup type.

exception khoros.errors.exceptions.MessageTypeNotFoundError(*args, **kwargs)[source]

This exception is used when a message type cannot be identified from a given URL.

Changed in version 5.1.2: Fixed an issue with the message displaying properly when a message type is explicitly defined.

exception khoros.errors.exceptions.MissingAuthDataError(*args, **kwargs)[source]

This exception is used when authentication data is not supplied and therefore a connection cannot occur.

exception khoros.errors.exceptions.MissingRequiredDataError(*args, **kwargs)[source]

This exception is used when a function or method is missing one or more required arguments.

Changed in version 4.0.0: The exception can now accept the param keyword argument.

New in version 2.0.0.

exception khoros.errors.exceptions.NodeIDNotFoundError(*args, **kwargs)[source]

This exception is used when a valid Node ID could not be found in a provided URL.

Changed in version 5.1.2: Fixed an issue with how the message is displayed when a value is passed as an argument.

exception khoros.errors.exceptions.NodeTypeNotFoundError(*args, **kwargs)[source]

This exception is used when a valid node type could not be found in a provided URL.

Changed in version 5.1.2: Fixed an issue with how the message is displayed when a value is passed as an argument.

exception khoros.errors.exceptions.NotFoundResponseError(*args, **kwargs)[source]

This exception is used when an API query returns a 404 response and there isn’t a more specific class.

exception khoros.errors.exceptions.OperatorMismatchError(*args, **kwargs)[source]

This exception is used when the number of operators in the LiQL query does not match the number of fields.

exception khoros.errors.exceptions.POSTRequestError(*args, **kwargs)[source]

This exception is used for generic POST request errors when there isn’t a more specific exception.

Changed in version 3.2.0: Enabled the ability to optionally pass status_code and/or message arguments.

exception khoros.errors.exceptions.PUTRequestError(*args, **kwargs)[source]

This exception is used for generic PUT request errors when there isn’t a more specific exception.

Changed in version 3.2.0: Enabled the ability to optionally pass status_code and/or message arguments.

exception khoros.errors.exceptions.PayloadMismatchError(*args, **kwargs)[source]

This exception is used when more than one payload is supplied for an API request.

New in version 3.2.0.

exception khoros.errors.exceptions.SessionAuthenticationError(*args, **kwargs)[source]

This exception is used when the session key authentication attempt failed.

exception khoros.errors.exceptions.SsoAuthenticationError(*args, **kwargs)[source]

This exception is used when the SSO authentication attempt failed.

New in version 4.2.0.

exception khoros.errors.exceptions.TooManyResultsError(*args, **kwargs)[source]

This exception is used when more results are returned than were expected in a LiQL query.

Changed in version 3.2.0: Fixed the default message to be appropriate as it was the same message found in another exception.

New in version 2.0.0.

exception khoros.errors.exceptions.UnknownFileTypeError(*args, **kwargs)[source]

This exception is used when a file type of a given file cannot be identified.

New in version 2.2.0.

exception khoros.errors.exceptions.UnsupportedNodeTypeError(*args, **kwargs)[source]

This exception is used when an unsupported node type has been provided.

New in version 3.2.0.

exception khoros.errors.exceptions.UserCreationError(*args, **kwargs)[source]

This exception is used when an attempt to create a user fails.

Changed in version 5.1.2: Fixed an issue with how the message is displayed when a value is passed as an argument.

Return to Top


Handlers Module (khoros.errors.handlers)

This sub-module contains various error handling functions that are leveraged throughout the library.

Module:

khoros.errors.handlers

Synopsis:

Functions that handle various error situations within the namespace

Usage:

from khoros.errors import handlers

Example:

error_msg = handlers.get_error_from_html(html_string)

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

20 Sep 2022

khoros.errors.handlers.eprint(*args, **kwargs)[source]

This function behaves the same as the print() function but is leveraged to print errors to sys.stderr.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.errors.handlers.get_error_from_html(html_error, v1=False)[source]

This function parses an error message from Khoros displayed in HTML format.

Changed in version 2.0.0: Added the v1 Boolean argument

Parameters:
  • html_error (str) – The raw HTML returned via the requests module

  • v1 (bool) – Determines if the error is from a Community API v1 call (False by default)

Returns:

The concise error message parsed from the HTML

khoros.errors.handlers.get_error_from_json(json_error, v1=False, include_error_bool=True, fail_on_no_results=True)[source]

This function retrieves any API errors returned from one of the Community APIs in JSON format.

Parameters:
  • json_error (dict) – The API response in JSON format

  • v1 (bool) – Determines if the error is from a Community API v1 call (False by default)

  • include_error_bool (bool) – Returns a Boolean as well that defines if an error was found (True by default)

  • fail_on_no_results (bool) – Defines if an exception should be raised if no results are returned (True by default)

Returns:

A Boolean value stating if an error was found (optional) and the error details in a tuple

khoros.errors.handlers.get_error_from_xml(xml_error, endpoint='', fail_on_no_results=True)[source]

This function retrieves any API errors returned from one of the Community APIs in XML format.

Parameters:
  • xml_error (str) – The API response in JSON format

  • endpoint (str) – The endpoint being queried by the API call (optional)

  • fail_on_no_results (bool) – Defines if an exception should be raised if no results are returned (True by default)

Returns:

A Boolean value stating if an error was found (optional) and the error details in a tuple

khoros.errors.handlers.verify_core_object_present(khoros_object)[source]

This function verifies whether the core object was supposed and raises an exception if not.

Changed in version 5.0.0: Removed the redundant return statement.

Parameters:

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

Returns:

None

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.errors.handlers.verify_v1_response(api_response, query_type='get', endpoint='', fail_on_no_results=False)[source]

This function evaluates a Community API v1 response to identify any failures.

Changed in version 5.0.0: Removed the redundant return statement.

Parameters:
  • api_response – The response from the API call

  • query_type (str) – The type of API call that was made, such as get (default), post, put, etc.

  • endpoint (str) – The endpoint being queried by the API call (optional)

  • fail_on_no_results (bool) – Raises an exception if no results are returned (False by default)

Returns:

None

Raises:

khoros.errors.exceptions.APIRequestError, khoros.errors.exceptions.DELETERequestError, khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PUTRequestError

Return to Top


Translations Module (khoros.errors.translations)

This sub-module provides more relevant translations for error messages in API responses where possible.

Module:

khoros.errors.translations

Synopsis:

Provides more relevant translations for error messages in API responses where possible

Usage:

from khoros.errors import translations

Example:

error_msg = translations.translate_error(error_msg, khoros_object)

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

26 Dec 2020

khoros.errors.translations.parse_message(error_msg)[source]

This function parses error messages when necessary to prepare them for translation.

Parameters:

error_msg (str) – The original error message

Returns:

The prepared error message

khoros.errors.translations.translate_error(error_msg, khoros_object=None, translate_errors=True)[source]

This function translates API response errors into more relevant messages where possible and permitted.

Parameters:
  • error_msg (str) – The original error message

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

  • translate_errors (bool) – Defines if errors can be transmitted (True by default) even with no core object

Returns:

khoros.errors.translations.translation_enabled(translate_errors=True, khoros_object=None)[source]

This function identifies whether or not error translation is permitted.

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

Parameters:
  • translate_errors (bool) – Defines if errors can be transmitted (True by default) even with no core object

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

Returns:

Boolean value defining if translation is enabled

Return to Top


Tools & Utilities

This section includes modules that contain tools and utilities leveraged by other scripts.


Core Utilities Module (khoros.utils.core_utils)

This module includes various utilities to assist in converting dictionaries to JSON, formatting timestamps, etc.

Module:

khoros.utils.core_utils

Synopsis:

Collection of supporting utilities and functions to complement the primary modules

Usage:

from khoros.utils import core_utils

Example:

encoded_string = core_utils.encode_url(decoded_string)

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

23 May 2022

khoros.utils.core_utils.convert_dict_id_values_to_strings(dict_list)[source]

This function ensures that the id keys in a list of dictionaries use string values.

Parameters:

dict_list (list, tuple, dict, None) – List (or tuple) of dictionaries (or a single dictionary) containing API object data

Returns:

A new dictionary list with properly formatted id values

Raises:

TypeError

khoros.utils.core_utils.convert_dict_list_to_simple_list(dict_list, fields)[source]

This function converts a list of dictionaries into a simple list consisting of the provided field(s).

New in version 3.5.0.

Parameters:
  • dict_list (list) – The original list of dictionaries

  • fields (str, tuple, list) – The field(s) with which to filter the dictionary list into a simple list

Returns:

The simple list of stings or tuples depending on the number of fields

khoros.utils.core_utils.convert_list_values(values_list, convert_to='str', split_values=False, split_delimiter=',')[source]

This function converts the values in a list to a different type.

Parameters:
  • values_list (list, tuple, set) – The list of values to be converted

  • convert_to – One of the following types: str (Default), int, float, tuple or set

  • split_values (bool) –

    Determines if the values should be split with a specific delimiter (False by default)

    Note

    This only applies when converting to the tuple or set types.

  • split_delimiter (str) – The delimiter for which to split the values when applicable (comma by default)

Returns:

A new list of converted values

Raises:

TypeError, ValueError

khoros.utils.core_utils.convert_set(iterable, convert_to='list')[source]

This function casts a set variable to be a list instead so that it can be scriptable.

Parameters:
  • iterable – The iterable to be evaluated to see if it has a set type

  • convert_to (str) – Defines if the iterable should be cast to a list (default) or a tuple

Returns:

The converted variable as a list or tuple (or untouched if not a set)

khoros.utils.core_utils.convert_single_value_to_tuple(value)[source]

This function converts a single value of nearly any type into a tuple.

Changed in version 3.2.0: The function has been aesthetically updated to be more PEP8 compliant.

New in version 2.3.0.

Parameters:

value – The value to convert into a tuple

khoros.utils.core_utils.convert_string_to_tuple(value, delimiter='')[source]

THis function converts a value to a tuple if in string format.

Changed in version 3.5.0: The typecheck has been updated to use isinstance and the function can now split delimited strings as needed.

New in version 2.3.0.

Parameters:
  • value (str) – The potential string to convert

  • delimiter – The value (e.g. ,) used to separate values in a delimited string (empty by default)

Returns:

The tuple (if original value was in string format) or the original value/type

khoros.utils.core_utils.decode_binary(binary)[source]

This function decodes a binary into a UTF-8 encoded string.

New in version 2.6.0.

Parameters:

binary – The binary to be decoded

Returns:

The properly decoded string

Raises:

TypeError, ValueError

khoros.utils.core_utils.decode_html_entities(html_string)[source]

This function converts HTML entities (e.g. &, ', etc.) back to their original characters.

Parameters:

html_string (str) – The string containing HTML entities to be decoded

Returns:

The string with decoded HTML entities

khoros.utils.core_utils.display_warning(warn_msg)[source]

This function displays a UserWarning message via the warnings module.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 2.1.0.

Parameters:

warn_msg (str) – The message to be displayed

Returns:

None

khoros.utils.core_utils.encode_base64(object_to_encode, str_encoding='utf-8', url_encode_object=False, return_bytes=False)[source]

This function encodes a string or bytes-like object

New in version 3.0.0.

Parameters:
  • object_to_encode – The string or bytes-like object to encode as base64

  • str_encoding (str) – Defines the encoding (utf-8 by default) to utilize

  • url_encode_object (bool) – Determines if the base64 string should be url-encoded (False by default)

  • return_bytes – Determines if the base64-encoded object should be returned as a bytes-like object rather than a string (False by default)

Returns:

The encoded object as a string or bytes-like object

Raises:

TypeError

khoros.utils.core_utils.encode_query_string(url_dict, no_encode=None, json_payload=False)[source]

This function compiles a URL query string from a dictionary of parameters.

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

Parameters:
  • url_dict (dict) – Dictionary of URL query string keys and values

  • no_encode (list, tuple, set, str, None) – Designates any dictionary keys (i.e. field names) whose values should not be URL-encoded

  • json_payload (bool) – Determines if query parameters should be passed as JSON payload rather than in the URI (False by default)

Returns:

The URL query string in string format

khoros.utils.core_utils.extract_key_values_from_dict_list(key_name, dict_list, exclude_if_present=None, convert_to_string=True)[source]

This function extracts values for a specific key from a list of dictionaries.

Parameters:
  • key_name (str) – The name of the dictionary key from which to extract the value(s)

  • dict_list (list, dict) – The list of dictionaries (or single dictionary) from which to extract the value(s)

  • exclude_if_present (str, None) – Will skip extracting the key value if this given key is also present (Optional)

  • convert_to_string (bool) – Determines if the values should be converted to string format (True by default)

Returns:

A list of values extracted from the dictionary list for the given key

Raises:

TypeError

khoros.utils.core_utils.get_file_type(file_path)[source]

This function attempts to identify if a given file path is for a YAML or JSON file.

New in version 2.2.0.

Parameters:

file_path (str) – The full path to the file

Returns:

The file type in string format (e.g. yaml or json)

Raises:

FileNotFoundError, khoros.errors.exceptions.UnknownFileTypeError

khoros.utils.core_utils.get_random_string(length=32, prefix_string='')[source]

This function returns a random alphanumeric string to use as a salt or password.

Parameters:
  • length (int) – The length of the string (32 by default)

  • prefix_string (str) – A string to which the salt should be appended (optional)

Returns:

The alphanumeric string

khoros.utils.core_utils.is_iterable(var)[source]

This function identifies if a given variable is an iterable.

New in version 3.5.0.

Parameters:

var – The variable to check

Returns:

A boolean value indicating whether or not the variable is an iterable

khoros.utils.core_utils.is_numeric(value)[source]

This function checks whether or not a value is numeric either as an integer or a numeric string.

New in version 2.3.0.

Parameters:

value (str, int) – The value to be examined

Returns:

Boolean value indicating if the examined value is numeric

khoros.utils.core_utils.merge_and_dedup(*data)[source]

This function merges various data elements into a single, deduplicated list.

Parameters:

data – One or more data elements to merge and deduplicate

Returns:

A merged and deduplicated list of data

khoros.utils.core_utils.remove_tld(url, strip_anchors=True)[source]

This function removes the top-level domain (TLD) from a Khoros Community platform URL.

Parameters:
  • url (str) – The URL from which the TLD should be removed

  • strip_anchors (bool) – Determines if anchors (e.g. #top) should be stripped (True by default)

Returns:

The URL beginning with /t5/

Raises:

khoros.errors.exceptions.InvalidURLError

khoros.utils.core_utils.run_cmd(cmd, return_type='dict', shell=False, decode_output=True, strip_output=False, exclude_stdout=False, exclude_stderr=False, exclude_return_code=False)[source]

This function executes a shell command on the operating system.

Changed in version 3.5.0: The default value of the shell parameter has been changed to False to avoid unnecessary security risk and added a logged warning if the value is manually set to True.

New in version 2.5.1.

Parameters:
  • cmd (str) – The command to be executed

  • return_type (str) – Determines the format in which the results should be returned (dict by default)

  • shell (bool) – Determines if the shell argument in the subprocess.run() function should be True

  • decode_output (bool) – Determines if the binary output should be decoded as a UTF-8 string (True by default)

  • strip_output (bool) – Determines if the escape character(s) should be stripped from the output (False by default)

  • exclude_stdout (bool) – Determines if the stdout output should be excluded (False by default)

  • exclude_stderr (bool) – Determines if the stderr output should be excluded (False by default)

  • exclude_return_code (bool) – Determines if the return code from the command should be excluded (False by default)

Returns:

The results from the executed script

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.utils.core_utils.url_decode(encoded_string)[source]

This function decodes a url-encoded string.

Parameters:

encoded_string (str) – The url-encoded string

Returns:

The unencoded string

khoros.utils.core_utils.url_encode(raw_string)[source]

This function encodes a string for use in URLs.

Parameters:

raw_string (str) – The raw string to be encoded

Returns:

The encoded string

Return to Top


Logging Utilities Module (khoros.utils.log_utils)

This module includes various utilities to assist with logging.

Module:

khoros.utils.log_utils

Synopsis:

Collection of logging utilities and functions

Usage:

from khoros.utils import log_utils

Example:

logger = log_utils.initialize_logging(__name__)

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

23 May 2022

class khoros.utils.log_utils.LessThanFilter(exclusive_maximum, name='')[source]

This class allows filters to be set to limit log levels to only less than a specified level.

New in version 3.0.0.

See also

Zoey Greer is the original author of this class which was provided on Stack Overflow.

filter(record)[source]

This method returns a Boolean integer value indicating whether or not a message should be logged.

New in version 3.0.0.

Note

A non-zero return indicates that the message will be logged.

khoros.utils.log_utils.initialize_logging(logger_name=None, log_level=None, formatter=None, debug=None, no_output=None, file_output=None, file_log_level=None, log_file=None, overwrite_log_files=None, console_output=None, console_log_level=None, syslog_output=None, syslog_log_level=None, syslog_address=None, syslog_port=None)[source]

This function initializes logging for the khoros library.

Return to Top


Environment Module (khoros.utils.environment)

This module identifies any environmental variables that have been defined for use within the khoros library.

Module:

khoros.objects.messages

Synopsis:

This module includes functions that identify environment variables for the khoros library

Usage:

from khoros.utils import environment

Example:

environment.update_env_variable_names()

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

23 May 2022

khoros.utils.environment.get_env_variables()[source]

This function retrieves any defined environment variables associate with the khoros library.

New in version 2.2.0.

Returns:

A dictionary with any relevant, defined environment variables

khoros.utils.environment.update_env_variable_names(custom_names)[source]

This function updates the original environment variable names with custom names when applicable.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 2.2.0.

Parameters:

custom_names (dict, str) – A dictionary (or file path to a YAML or JSON file) that maps the original and custom names

Returns:

None

Return to Top


Helper Module (khoros.utils.helper)

This module allows a “helper” configuration file to be imported and parsed to facilitate the use of the library (e.g. defining the base URL and API credentials) and defining additional settings.

Module:

khoros.utils.helper

Synopsis:

Module that allows the khoros library to leverage a helper configuration file

Usage:

from khoros.utils import helper

Example:

helper_settings = helper.get_settings('/tmp/helper.yml', 'yaml')

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

12 Mar 2022

class khoros.utils.helper.HelperParsing[source]

This class is used to help parse values imported from a YAML configuration file.

khoros.utils.helper.get_helper_settings(file_path, file_type='yaml', defined_settings=None)[source]

This function returns a dictionary of the defined helper settings.

Changed in version 4.3.0: Fixed an issue where the ssl_verify field was being overridden even if defined elsewhere.

Changed in version 3.4.0: This function now supports the ssl_verify key and defines a default value when not found.

Changed in version 2.8.0: The function was updated to capture the translate_errors value when defined.

Changed in version 2.2.0: Support was added for JSON-formatted helper configuration files.

Parameters:
  • file_path (str) – The file path to the helper configuration file

  • file_type (str) – Defines the helper configuration file as a yaml file (default) or a json file

  • defined_settings (dict, None) – Core object settings (if any) defined via the defined_settings parameter

Returns:

Dictionary of helper variables

Raises:

khoros.errors.exceptions.InvalidHelperFileTypeError

khoros.utils.helper.import_helper_file(file_path, file_type)[source]

This function imports a YAML (.yml) or JSON (.json) helper config file.

Changed in version 3.3.0: A log entry was added to report when the helper file has been imported successfully.

Changed in version 2.2.0: Changed the name and replaced the yaml.load function call with yaml.safe_load to be more secure.

Parameters:
  • file_path (str) – The file path to the YAML file

  • file_type (str) – Defines the file type as either yaml or json

Returns:

The parsed configuration data

Raises:

FileNotFoundError, khoros.errors.exceptions.InvalidHelperFileTypeError

Return to Top


Version Module (khoros.utils.version)

This module is the primary source of the current version of the khoros package, and includes two simple functions to return either the full version or the major.minor (i.e. X.Y) version.

Module:

khoros.utils.version

Synopsis:

This simple script contains the package version

Usage:

from .utils import version

Example:

__version__ = version.get_full_version()

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

01 Nov 2023

khoros.utils.version.get_full_version()[source]

This function returns the current full version of the khoros package.

khoros.utils.version.get_latest_stable()[source]

This function returns the latest stable version of the khoros package.

Changed in version 3.4.0: This function has been refactored to leverage the standard library instead of the requests library.

Changed in version 3.0.0: Error handling and logging was added to avoid an exception if PyPI cannot be queried successfully.

Returns:

The latest stable version in string format

khoros.utils.version.get_major_minor_version()[source]

This function returns the current major.minor (i.e. X.Y) version of the khoros package.

khoros.utils.version.latest_version()[source]

This function defines if the current version matches the latest stable version on PyPI.

Changed in version 3.0.0: The function was reduced to a single return statement.

Returns:

Boolean value indicating if the versions match

khoros.utils.version.log_current_version(debug=False)[source]

This function reports the current running version of the library in a debug log entry.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 3.0.0.

Parameters:

debug (bool) – Defines if the message should be logged with the DEBUG log level. (False by default)

Returns:

None

khoros.utils.version.warn_when_not_latest()[source]

This function displays a RuntimeWarning if the running version doesn’t match the latest stable version.

Changed in version 5.0.0: Removed the redundant return statement and merged two if statements.

Changed in version 3.0.0: The function was updated to use logging for the warning rather than the warnings module.

Returns:

None

Return to Top


Unit Testing

This section includes modules that are used in unit testing the library.


Tests Module (khoros.utils.tests)

This module includes unit tests for the package that are performed using pytest.

Module:

khoros.utils.tests

Synopsis:

This package includes tests for the khoros library.

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

26 Mar 2020

Return to Top


Resources Module (khoros.utils.tests.resources)

This module includes frequently used resources for performing unit testing.

Module:

khoros.utils.tests.resources

Synopsis:

Frequently used resources for performing unit testing

Usage:

from khoros.utils.tests import resources

Example:

exceptions = resources.import_exceptions_module()

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

25 Nov 2022

class khoros.utils.tests.resources.MockResponse(json_body, status_code=200)[source]

This class simulates an API response for testing purposes.

Changed in version 5.2.0: The status_code attribute has been added to the object.

New in version 5.1.2.

khoros.utils.tests.resources.control_data_exists(dataset_name)[source]

This function checks to see if a local control data file exists.

Changed in version 5.1.1: The function has been updated to support GitHub Workflow control data.

New in version 5.1.0.

Parameters:

dataset_name (str) – The name of the dataset

Returns:

Boolean value indicating whether the file was found

khoros.utils.tests.resources.get_control_data(dataset_name)[source]

This function retrieves the control data used in various tests.

New in version 5.1.1.

khoros.utils.tests.resources.get_core_object()[source]

This function instantiates and returns the core object using a local helper file.

New in version 5.1.1.

khoros.utils.tests.resources.get_structure_collection(structure_type)[source]

This function identifies the API collection for a given structure type.

New in version 4.1.0.

Parameters:

structure_type – The structure type for which to return the corresponding collection.

Returns:

The appropriate collection

khoros.utils.tests.resources.get_testing_config()[source]

This function returns the test config data from the local/khorostest.yml file when present.

New in version 4.1.0.

khoros.utils.tests.resources.import_control_data(dataset_name)[source]

This function imports a local control data file as a dictionary.

Changed in version 5.1.1: The function has been updated to support GitHub Workflows control data.

New in version 5.1.0.

Parameters:

dataset_name (str) – The name of the dataset

Returns:

The JSON data as a dictionary

Raises:

FileNotFoundError

khoros.utils.tests.resources.import_modules(*modules)[source]

This function imports and returns one or more modules to utilize in a unit test.

New in version 2.7.4.

Parameters:

modules – One or more module paths (absolute) in string format

Returns:

The imported module(s) as an individual object or a tuple of objects

khoros.utils.tests.resources.initialize_khoros_object(use_defined_settings=False, defined_settings=None, append_to_default=False)[source]

This function imports the khoros.core.Khoros class and initializes an object.

Changed in version 4.3.0: Added support for utilizing the defined_settings parameter.

New in version 2.7.4.

Returns:

The initialized khoros.core.Khoros object

khoros.utils.tests.resources.instantiate_with_local_helper(production=False)[source]

This function instantiates a Khoros object using a local helper file for unit testing.

Changed in version 5.1.0: The function has been updated to raise the FileNotFoundError exception if the file is not found.

New in version 4.1.0.

Parameters:

production (bool, None) – Defines whether the helper file is associated with a Production environment

Returns:

The instantiated khoros.core.Khoros object

Raises:

FileNotFoundError

khoros.utils.tests.resources.instantiate_with_placeholder()[source]

This function instantiates a Khoros object with placeholder data.

New in version 5.0.0.

Returns:

The instantiated khoros.core.Khoros object

khoros.utils.tests.resources.instantiate_with_secrets_helper()[source]

This function instantiates a Khoros object using the unencrypted helper file intended for GitHub Workflows.

New in version 5.1.1.

Returns:

The instantiated khoros.core.Khoros object

Raises:

FileNotFoundError

khoros.utils.tests.resources.local_helper_exists(production=False)[source]

This function checks to see if a helper file is present in the local/ directory.

New in version 4.1.0.

Parameters:

production (bool, None) – Defines whether the helper file is associated with a Production environment

Returns:

Boolean value indicating whether the local helper file was found

khoros.utils.tests.resources.local_test_config_exists()[source]

This function checks to see if the khorostest.yml file is present in the local/ directory.

New in version 4.1.0.

Returns:

Boolean value indicating whether the file was found

khoros.utils.tests.resources.mock_bulk_data_json(*args, **kwargs)[source]

This function works with the MockedResponse class to simulate a Bulk Data API JSON response.

New in version 5.2.0.

khoros.utils.tests.resources.mock_error_post(*args, **kwargs)[source]

This function works with the MockedResponse class to simulate a failed API response.

New in version 5.1.2.

khoros.utils.tests.resources.mock_success_post(*args, **kwargs)[source]

This function works with the MockedResponse class to simulate a successful API response.

New in version 5.1.2.

khoros.utils.tests.resources.parse_testing_config_file()[source]

This function parses the local/khorostest.yml file when present.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 4.1.0.

khoros.utils.tests.resources.secrets_helper_exists()[source]

This function checks to see if the unencrypted helper file exists for GitHub Workflows.

New in version 5.1.1.

khoros.utils.tests.resources.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

Changed in version 5.0.0: Removed the redundant return statement.

New in version 2.7.4.

Return to Top


Test Albums Module (khoros.utils.tests.test_albums)

This module is used by pytest to verify that the albums module works properly.

Module:

khoros.utils.tests.test_albums

Synopsis:

This module is used by pytest to verify that the albums module functions properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

30 Sep 2022

khoros.utils.tests.test_albums.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 5.1.2.

khoros.utils.tests.test_albums.test_create_album(monkeypatch)[source]

This function tests the ability to create an album.

New in version 5.1.2.

khoros.utils.tests.test_albums.test_failed_create_album(monkeypatch)[source]

This function tests the response of the create method when the API returns an error.

New in version 5.1.2.

Return to Top


Test Archives Module (khoros.utils.tests.test_archives)

This module is used by pytest to verify that the archives module works properly.

Module:

khoros.utils.tests.test_archives

Synopsis:

This module is used by pytest to verify that the archives module functions properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

02 Nov 2022

khoros.utils.tests.test_archives.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 5.1.2.

khoros.utils.tests.test_archives.test_archive_check()[source]

This function tests the ability to check whether a message is archived.

New in version 5.2.0.

khoros.utils.tests.test_archives.test_archive_content(monkeypatch)[source]

This function tests the ability to archive content.

New in version 5.1.2.

khoros.utils.tests.test_archives.test_unarchive_content(monkeypatch)[source]

This function tests the ability to unarchive content.

New in version 5.1.2.

Return to Top


Test Board Creation Module (khoros.utils.tests.test_board_creation)

This module is used by pytest to verify that the board creation works properly.

Module:

khoros.utils.tests.test_board_creation

Synopsis:

This module is used by pytest to verify that the board creation works properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_board_creation.get_dict_for_required_fields(required_fields)[source]

This function places the required fields in a properly formatted dictionary.

Parameters:

required_fields (tuple, list, set) – The board ID, title and type

Returns:

Dictionary containing the required fields

khoros.utils.tests.test_board_creation.get_required_fields(board_type='forum', all_types=False)[source]

This function defines required fields that can be used in other tests.

Parameters:
  • board_type (str) – The type of board (e.g. forum, blog, etc.) to use

  • all_types (bool) – Defines if required fields for all board types should be returned

Returns:

A tuple or list of tuples with the required fields for one or more board types

khoros.utils.tests.test_board_creation.test_description()[source]

This function tests the description argument to ensure it gets formatted properly for all board types.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_board_creation.test_invalid_board_type()[source]

This function tests to ensure an InvalidNodeTypeError exception is raised for an invalid board type.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_board_creation.test_no_arguments()[source]

This function tests to ensure that a TypeError is raised if no arguments are passed to the function.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_board_creation.test_required_fields()[source]

This function tests that the payload is structured properly with only the required fields supplied.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_board_creation.test_valid_board_types()[source]

This function tests to ensure that the payload for all valid board types gets formatted appropriately.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_board_creation.verify_data_fields(payload, data_fields)[source]

This function checks a dictionary of data fields and values to ensure they match what is in the payload.

Parameters:
  • payload (dict) – The payload for a new board

  • data_fields (dict) – The data fields and corresponding values to check

Returns:

Boolean value indicating whether or not the verification checks out

Return to Top


Test Bulk Data Module (khoros.utils.tests.test_bulk_data)

This module is used by pytest to verify that the Bulk Data API module works properly.

Module:

khoros.utils.tests.test_bulk_data

Synopsis:

This module is used by pytest to test the Bulk Data API module

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

25 Nov 2022

khoros.utils.tests.test_bulk_data.test_base_url_without_helper()[source]

This function tests the functionality of the khoros.bulk_data.get_base-url() function.

New in version 5.0.0.

khoros.utils.tests.test_bulk_data.test_bulk_data_query(monkeypatch)[source]

This function tests the ability to query the Bulk Data API and retrieve a JSON response.

New in version 5.2.0.

khoros.utils.tests.test_bulk_data.test_core_object_settings()[source]

This function tests to ensure the bulk_data element exists in the core object with all of its fields.

New in version 5.0.0.

khoros.utils.tests.test_bulk_data.test_export_type_header()[source]

This function tests the retrieval of the appropriate Accept header value depending on the export type.

New in version 5.0.0.

khoros.utils.tests.test_bulk_data.test_valid_header_construction()[source]

This function tests the construction of the API call headers when valid parameters are provided.

New in version 5.0.0.

khoros.utils.tests.test_bulk_data.test_valid_parameter_construction()[source]

This function tests to ensure the parameters get constructed appropriately with valid data.

New in version 5.0.0.

Return to Top


Test Categories Module (khoros.utils.tests.test_categories)

This module is used by pytest to verify that the categories module works properly.

Module:

khoros.utils.tests.test_categories

Synopsis:

This module is used by pytest to verify that the categories module functions properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

30 Sep 2022

khoros.utils.tests.test_categories.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 5.1.0.

khoros.utils.tests.test_categories.test_category_details()[source]

This function tests the retrieval of various category details.

Changed in version 5.1.3: Fixed an issue with testing the retrieval of views to ensure a successful assertion.

Changed in version 5.1.1: This function has been updated to leverage the functions in the resources module.

New in version 5.1.0.

khoros.utils.tests.test_categories.test_create_category(monkeypatch)[source]

This function tests the ability to create a category.

New in version 5.1.2.

khoros.utils.tests.test_categories.test_get_category_id()[source]

This function tests the ability to get a category ID from a URL.

Changed in version 5.1.1: This function has been updated to leverage the functions in the resources module.

New in version 5.1.0.

khoros.utils.tests.test_categories.test_if_category_exists()[source]

This function tests if the existence of categories can be successfully determined.

Changed in version 5.1.1: This function has been updated to leverage the functions in the resources module.

New in version 5.1.0.

khoros.utils.tests.test_categories.test_total_count()[source]

This function tests the ability to retrieve the total category count.

Changed in version 5.1.1: This function has been updated to leverage the functions in the resources module.

New in version 5.1.0.

Return to Top


Test Communities Module (khoros.utils.tests.test_communities)

This module is used by pytest to verify that the communities module works properly.

Module:

khoros.utils.tests.test_communities

Synopsis:

This module is used by pytest to verify that the communities module functions properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

29 Sep 2022

khoros.utils.tests.test_communities.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 5.1.0.

khoros.utils.tests.test_communities.test_community_details()[source]

This function tests the ability to retrieve community details.

Changed in version 5.1.1: The function has been updated to support GitHub Workflows control data.

New in version 5.1.0.

Return to Top


Test Core Utilities Module (khoros.utils.tests.test_core_utils)

This module is used by pytest to verify that the core package utilities work properly.

Module:

khoros.utils.tests.test_core_utils

Synopsis:

This module is used by pytest to verify that the core package utilities work properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_core_utils.import_core_utils()[source]

This function imports the khoros.utils.core_utils module.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_core_utils.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_core_utils.test_base64_conversions()[source]

This function tests various types of base64 string conversions.

New in version 5.1.2.

khoros.utils.tests.test_core_utils.test_convert_set()[source]

This function tests the khoros.utils.core_utils.convert_set() function.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_core_utils.test_decode_binary()[source]

This function tests the ability to decode binary into a string.

New in version 5.1.2.

khoros.utils.tests.test_core_utils.test_display_warning()[source]

This function tests the ability to display a warning message.

New in version 5.1.2.

khoros.utils.tests.test_core_utils.test_html_entity_convert()[source]

This function tests the khoros.utils.core_utils.decode_html_entitles() function.

New in version 5.1.2.

khoros.utils.tests.test_core_utils.test_merge_and_dedup()[source]

This function tests the khoros.utils.core_utils.merge_and_dedup() function.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_core_utils.test_numeric_eval()[source]

This function tests the khoros.utils.core_utils.is_numeric() function.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_core_utils.test_query_string_encoding()[source]

This function tests the khoros.utils.core_utils.encode_query_string() function.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_core_utils.test_remove_tld()[source]

This function tests to the khoros.utils.core_utils.remove_tld() function.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_core_utils.test_url_encoding()[source]
This function tests the khoros.utils.core_utils.url_encode() and

khoros.utils.core_utils.url_decode() functions.

Changed in version 5.0.0: Removed the redundant return statement.

Return to Top


Test Error Handling Module (khoros.utils.tests.test_error_handling)

This module is used by pytest to verify that error handling works properly.

Module:

khoros.utils.tests.test_error_handling

Synopsis:

This module is used by pytest to verify that error handling works properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

03 Oct 2022

khoros.utils.tests.test_error_handling.test_eprint()[source]

This function tests printing an error message to the stderr output.

New in version 5.1.2.

khoros.utils.tests.test_error_handling.test_get_html_error()[source]

This function tests the ability to parse an HTML error to get an error message.

New in version 5.1.2.

khoros.utils.tests.test_error_handling.test_parse_translation_error()[source]

This function tests the ability to parse an error message to remove extraneous escape characters.

New in version 5.1.2.

khoros.utils.tests.test_error_handling.test_translate_error()[source]

This function tests the ability to translate obscure messages.

New in version 5.1.2.

khoros.utils.tests.test_error_handling.test_translation_check()[source]

This function tests the ability to check if error translation is enabled.

New in version 5.1.2.

khoros.utils.tests.test_error_handling.test_verify_core_object_present()[source]

This function tests the ability to verify that a Khoros core object is present.

New in version 5.1.2.

Return to Top


Test Exceptions Module (khoros.utils.tests.test_exceptions)

This module is used by pytest to verify that exceptions are raised properly.

Module:

khoros.utils.tests.test_exceptions

Synopsis:

This module is used by pytest to verify that the exceptions can be raised properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

03 Oct 2022

khoros.utils.tests.test_exceptions.test_raising_exceptions()[source]

This function tests that exceptions are raised successfully.

New in version 5.1.2.

Return to Top


Test Group Hub Creation Module (khoros.utils.tests.test_grouphub_creation)

This module is used by pytest to verify that the group hub creation works properly.

Module:

khoros.utils.tests.test_grouphub_creation

Synopsis:

This module is used by pytest to verify that the group hub creation process works properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_grouphub_creation.test_no_arguments()[source]

This function tests to ensure that a TypeError is raised if no arguments are passed to the function.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_grouphub_creation.test_only_id()[source]

This function tests to ensure passing only the ID references the group_title argument in the exception.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_grouphub_creation.verify_data_fields(payload, data_fields)[source]

This function checks a dictionary of data fields and values to ensure they match what is in the payload.

Parameters:
  • payload (dict) – The payload for a new group hub

  • data_fields (dict) – The data fields and corresponding values to check

Returns:

Boolean value indicating whether or not the verification checks out

Return to Top


Test Helper File Module (khoros.utils.tests.test_helper_file)

This module is used by pytest to verify that the helper configuration files work properly.

Module:

khoros.utils.tests.test_helper_file

Synopsis:

This module is used by pytest to verify that the helper configuration files work properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_helper_file.get_helper_path()[source]

This function defines the appropriate path to the helper file.

khoros.utils.tests.test_helper_file.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_helper_file.test_yaml_file()[source]

This function tests the import of a YAML file.

Return to Top


Test HTTP Headers Module (khoros.utils.tests.test_http_headers)

This module is used by pytest to verify that HTTP headers are formatted appropriately.

Module:

khoros.utils.tests.test_http_headers

Synopsis:

This module is used by pytest to verify that HTTP headers are formatted appropriately

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_http_headers.compare_headers(headers)[source]

This function compares two HTTP headers to ensure they are the same.

New in version 2.7.4.

khoros.utils.tests.test_http_headers.test_normalize_empty_headers()[source]
This function verifies that passing an empty dictionary to khoros.api._normalize_headers()

returns the same empty dictionary.

New in version 2.7.4.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_http_headers.test_normalize_headers()[source]

This function tests the khoros.api._normalize_headers() function to ensure it works properly.

New in version 2.7.4.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_http_headers.test_normalize_type_error()[source]
This function verifies that passing no arguments to khoros.api._normalize_headers() raises

a TypeError exception.

New in version 2.7.4.

Changed in version 5.0.0: Removed the redundant return statement.

Return to Top


Test Library Import Module (khoros.utils.tests.test_library_import)

This module tests importing each of the primary modules in the library.

Module:

khoros.utils.tests.test_library_import

Synopsis:

This module is used by pytest to verify that the primary package can be imported successfully

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_library_import.import_pkg_operation()[source]

This function imports the primary package and returns True when successful.

khoros.utils.tests.test_library_import.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_library_import.test_library_import()[source]

This function tests to confirm that the primary package can be imported successfully.

Return to Top


Test LiQL Module (khoros.utils.tests.test_liql)

This module tests parsing and/or executing LiQL queries.

Module:

khoros.utils.tests.test_liql

Synopsis:

This module is used by pytest to verify that LiQL queries can be performed and parsed successfully.

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

29 Sep 2022

khoros.utils.tests.test_liql.parse_where_clauses()[source]

This function runs through several parsing examples to ensure they all complete successfully.

Changed in version 3.4.0: Updated the name of the khoros.liql.parse_where_clause() function in its respective call.

khoros.utils.tests.test_liql.perform_test_query(return_items=False)[source]

This function performs a LiQL query and saves the response in a global variable.

Changed in version 5.1.1: This function has been updated to support GitHub Workflows unit testing.

Changed in version 5.0.0: Removed the redundant return statement.

Parameters:

return_items (bool) – Determines if the response should be scoped to only the returned items (False by default)

Returns:

None

khoros.utils.tests.test_liql.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

Changed in version 4.1.0: This function now leverages a global variable to ensure it only performs the operation once.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_liql.test_liql_query()[source]

This function tests to confirm that a standard LiQL query can be performed successfully.

Changed in version 5.1.1: This function has been updated to support GitHub Workflows unit testing.

New in version 4.1.0.

khoros.utils.tests.test_liql.test_return_items_option()[source]

This function tests the return_items argument in the khoros.core.Khoros.query() method.

Changed in version 5.1.1: This function has been updated to support GitHub Workflows unit testing.

New in version 4.1.0.

khoros.utils.tests.test_liql.test_where_clause_parsing()[source]

This function tests to confirm that LiQL WHERE clauses are getting parsed properly without failing.

Return to Top


Test Mentions Module (khoros.utils.tests.test_mentions)

This module is used by pytest to verify that user and content mentions work properly.

Module:

khoros.utils.tests.test_mentions

Synopsis:

This module is used by pytest to verify that user and content mentions work properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_mentions.expected_content_response(response)[source]

This function replaces the TLD to match the example constant and then identifies if the response was expected.

New in version 2.4.0.

Parameters:

response (str) – The response received from the function

Returns:

Boolean value indicating if the response was expected

khoros.utils.tests.test_mentions.expected_user_response(response)[source]

This function identifies if the response was expected.

New in version 2.4.0.

Parameters:

response (str) – The response received from the function

Returns:

Boolean value indicating if the response was expected

khoros.utils.tests.test_mentions.get_content_test_data(include_id=True, false_id=False, relative_url=False)[source]

This function returns the test data to use in the various test functions.

New in version 2.4.0.

Parameters:
  • include_id (bool) – Determines if the Content ID should be returned (True by default)

  • false_id (bool) – Determines if an incorrect Content ID should be returned (False by default)

  • relative_url – Determines if a relative URL should be returned (False by default)

Returns:

A tuple containing the appropriate test data

khoros.utils.tests.test_mentions.get_user_test_data()[source]

This function returns the test data to use in the user mention tests.

New in version 2.4.0.

Returns:

The User ID and login as a tuple of two strings

khoros.utils.tests.test_mentions.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_mentions.test_bad_content_url()[source]

This function tests creating a content mention when an invalid URL is supplied.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

Raises:

khoros.errors.exceptions.MessageTypeNotFoundError

khoros.utils.tests.test_mentions.test_content_mention_with_all_arguments()[source]
This function tests the khoros.objects.messages.format_content_mention() when all required arguments

have been supplied.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_content_mention_with_false_id_arg()[source]

This function tests creating a content mention when an invalid Content ID is supplied as an argument.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_content_mention_with_false_id_dict()[source]

This function tests creating a content mention when an invalid Content ID is supplied in the dictionary.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_content_mention_with_full_dict()[source]
This function tests the khoros.objects.messages.format_content_mention() when all required dictionary

keys and values have been supplied.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_content_mention_with_no_id_arg()[source]

This function tests creating a content mention when no Content ID has been supplied as an argument.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_content_mention_with_no_id_dict()[source]

This function tests creating a content mention when no Content ID has been supplied in the dictionary.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_relative_content_url_with_object()[source]

This function tests creating a content mention with a relative content URL but with a Khoros object.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_relative_content_url_without_object()[source]

This function tests creating a content mention with a relative content URL and no Khoros object.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

Raises:

khoros.errors.exceptions.MissingRequiredDataError

khoros.utils.tests.test_mentions.test_user_mention_with_args_no_object()[source]

This function tests creating a user mention with a single argument and no Khoros object.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

Raises:

khoros.errors.exceptions.MissingAuthDataError

khoros.utils.tests.test_mentions.test_user_mention_with_arguments()[source]

This function tests creating a user mention with all required arguments provided.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_user_mention_with_dict_and_object()[source]

This function tests creating a user mention with one key value pair and with a Khoros object.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_user_mention_with_dictionary()[source]

This function tests creating a user mention with all required dictionary key value pairs provided.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

khoros.utils.tests.test_mentions.test_user_mention_with_dictionary_no_object()[source]

This function tests creating a user mention with a single key value pair and no Khoros object.

New in version 2.4.0.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

Raises:

khoros.errors.exceptions.MissingAuthDataError

Return to Top


Test Messages Module (khoros.utils.tests.test_messages)

This module is used by pytest to verify that messages work properly.

Module:

khoros.utils.tests.test_messages

Synopsis:

This module is used by pytest to verify that messages function properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

10 Jul 2023

khoros.utils.tests.test_messages.assert_tags_present(payload, tags_to_find)[source]

This function asserts that specific tags are found within API payload.

Changed in version 5.0.0: Removed the redundant return statement.

Parameters:
  • payload (dict) – The payload in which to search for tags

  • tags_to_find (list, tuple, set) – A list or tuple of tags for which to search in the payload

Returns:

None

Raises:

AssertionError

khoros.utils.tests.test_messages.get_control_data(test_type)[source]

This function retrieves control data to use in unit tests.

Parameters:

test_type (str) – Nickname of the test to be performed

Returns:

Payload control data in dictionary format

khoros.utils.tests.test_messages.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 5.1.0.

khoros.utils.tests.test_messages.test_construct_only_subject()[source]

This function tests to ensure that a khoros.errors.exceptions.MissingRequiredDataError exception gets raised when only a subject is passed to the khoros.objects.messages.construct_payload() function.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_body()[source]

This function tests constructing payload using a message body.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_node()[source]

This function tests constructing payload using properly formatted node data.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_node_id()[source]

This function tests constructing payload using a Node ID.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_node_url()[source]

This function tests constructing payload using a Node URL.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_one_int_tag()[source]

This function tests constructing payload using a single tag in integer format.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_one_str_tag()[source]

This function tests constructing payload using a single tag in string format.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_str_iter_int_tags()[source]

This function tests constructing payload providing tags in string, list and integer formats.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_str_iter_int_tags_ignore()[source]

This function tests constructing payload providing tags in string, list and integer formats, and with the ignore_non_string_tags argument set to True as well.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_construct_with_tag_iterables()[source]

This function tests constructing payload providing tags as a list containing two strings.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_count_messages()[source]

This function tests the ability to retrieve a messages count for a specific board.

New in version 5.3.0.

khoros.utils.tests.test_messages.test_flagging_message(monkeypatch)[source]

This function tests the ability to flag and unflag a message as spam.

Changed in version 5.1.2: The function has been updated to use monkeypatching.

Changed in version 5.1.1: This function has been updated to support GitHub Workflows unit testing.

New in version 5.1.0.

khoros.utils.tests.test_messages.test_kudo_message(monkeypatch)[source]

This function tests the ability to kudo a message.

Changed in version 5.1.2: The function has been updated to use monkeypatching.

Changed in version 5.1.1: This function has been updated to support GitHub Workflows unit testing.

New in version 5.1.0.

khoros.utils.tests.test_messages.test_label_message(monkeypatch)[source]

This function tests the ability to add a label to a message.

Changed in version 5.1.2: The function has been updated to use monkeypatching.

Changed in version 5.1.1: This function has been updated to support GitHub Workflows unit testing.

New in version 5.1.0.

khoros.utils.tests.test_messages.test_payload_validation()[source]

This function tests the validation of the message payload to ensure invalid data raises an exception.

New in version 4.3.0.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_messages.test_tag_message(monkeypatch)[source]

This function tests the ability to add a tag to a message.

Changed in version 5.1.2: The function has been updated to use monkeypatching.

Changed in version 5.1.1: This function has been updated to support GitHub Workflows unit testing.

New in version 5.1.0.

Return to Top


Test Node ID Extract Module (khoros.utils.tests.test_node_id_extract)

This module is used by pytest to verify that Node IDs can be extracted successfully from URLs.

Module:

khoros.utils.tests.test_node_id_extract

Synopsis:

This module is used by pytest to verify that Node IDs can be extracted successfully from URLs.

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_node_id_extract.get_test_data()[source]

This function retrieves the test data that will be used in the test functions.

Returns:

The test_data dictionary with the node types and associated test URLs

khoros.utils.tests.test_node_id_extract.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_node_id_extract.test_url_without_node()[source]

This function tests to ensure that an appropriate exception is raised when a URL does not contain a valid node.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

Raises:

AssertionError, khoros.errors.exceptions.NodeTypeNotFoundError

khoros.utils.tests.test_node_id_extract.test_with_invalid_node_types()[source]

This function tests to ensure that invalid node types will raise the appropriate exception.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

Raises:

AssertionError, khoros.errors.exceptions.InvalidNodeTypeError

khoros.utils.tests.test_node_id_extract.test_with_only_url()[source]

This function tests the khoros.objects.base.get_node_id() function when only a URL is passed.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

Raises:

AssertionError

khoros.utils.tests.test_node_id_extract.test_with_valid_node_types()[source]

This function tests that Node IDs can be extracted from URLs when valid node types are given.

Changed in version 5.0.0: Removed the redundant return statement.

Returns:

None

Raises:

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

Return to Top


Test Roles Module (khoros.utils.tests.test_roles)

This module is used by pytest to verify that roles-related functions work properly.

Module:

khoros.utils.tests.test_roles

Synopsis:

This module is used by pytest to verify the khoros.objects.roles functionality.

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

03 Oct 2022

khoros.utils.tests.test_roles.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 5.0.0.

khoros.utils.tests.test_roles.test_get_role_id()[source]

This function tests the khoros.objects.roles.get_role_id() function and corresponding method.

Changed in version 5.1.2: The function has been updated to support GitHub Workflows and to include a couple extra tests.

New in version 5.0.0.

khoros.utils.tests.test_roles.test_get_roles_for_user()[source]

This function tests the khoros.core.Khoros.Role.get_roles_for_user() method and related function.

Changed in version 5.1.2: The function has been updated to support GitHub Workflows.

New in version 5.0.0.

khoros.utils.tests.test_roles.test_get_users_with_role()[source]

This function tests the khoros.core.Khoros.Role.get_users_with_role() method and related function.

Changed in version 5.1.2: The function has been updated to support GitHub Workflows.

New in version 5.0.0.

khoros.utils.tests.test_roles.test_invalid_role_type()[source]

This function tests passing an invalid role type to khoros.objects.roles.count_role_types().

New in version 5.0.0.

khoros.utils.tests.test_roles.test_total_role_type_counts()[source]

This function tests the khoros.core.Khoros.Role.get_total_role_count() method and related function.

Changed in version 5.1.2: The function has been updated to support GitHub Workflows.

New in version 5.0.0.

Return to Top


Test Settings Module (khoros.utils.tests.test_settings)

This module is used by pytest to verify that settings can be retrieved and updated properly.

Module:

khoros.utils.tests.test_settings

Synopsis:

This module is used by pytest to verify the khoros.objects.settings functionality.

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_settings.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 4.1.0.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_settings.test_invalid_node_type_exception()[source]

This function tests to confirm that invalid nodes will raise the khoros.errors.exceptions.InvalidNodeTypeError exception.

New in version 4.1.0.

khoros.utils.tests.test_settings.test_node_setting_retrieval()[source]

This function tests the retrieval of API v1 and v2 node settings.

New in version 4.1.0.

khoros.utils.tests.test_settings.test_sso_status_retrieval()[source]

This function tests to confirm that the khoros.core.Khoros.Community.sso_enabled() method is able to return a Boolean value.

New in version 5.0.0.

Return to Top


Test SSL Verification Module (khoros.utils.tests.test_ssl_verify)

This module is used by pytest to verify the SSL verification functionality.

Module:

khoros.utils.tests.test_ssl_verify

Synopsis:

This module is used by pytest to test the ability to disable SSL verification on API requests

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

09 Jun 2022

khoros.utils.tests.test_ssl_verify.test_api_global_variable_assignment()[source]

This function tests to verify that the ssl_verify_disabled global variable gets defined appropriately.

New in version 4.3.0.

khoros.utils.tests.test_ssl_verify.test_api_should_verify_function()[source]

This function tests to verify that the khoros.api.should_verify_tls() function works properly.

New in version 4.3.0.

khoros.utils.tests.test_ssl_verify.test_core_object_with_param_setting()[source]

This function tests to verify the ssl_verify setting is honored when explicitly defined.

New in version 4.3.0.

khoros.utils.tests.test_ssl_verify.test_default_core_object_setting()[source]

This function tests to verify the ssl_verify setting is True by default.

New in version 4.3.0.

Changed in version 5.0.0: Removed the redundant return statement.

Return to Top


Test Studio Module (khoros.utils.tests.test_studio)

This module is used by pytest to verify that the studio module functions properly.

Module:

khoros.utils.tests.test_studio

Synopsis:

This module is used by pytest to verify that the studio module functions properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

03 Oct 2022

khoros.utils.tests.test_studio.test_studio_functions()[source]

This function tests the various Studio-related functions.

New in version 5.1.2.

Return to Top


Test Tags Module (khoros.utils.tests.test_tags)

This module is used by pytest to verify that tags function properly.

Module:

khoros.utils.tests.test_tags

Synopsis:

This module is used by pytest to verify that tags function properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

03 Oct 2022

khoros.utils.tests.test_tags.get_structure_control_data(test_type)[source]

This function retrieves the control data to use in tag structure tests.

Parameters:

test_type (str) – The type of test for which to return control data

Returns:

The control data for the given test type

khoros.utils.tests.test_tags.test_add_single_tag_to_message(monkeypatch)[source]

This function tests the ability to add a single tag to a message.

New in version 5.1.2.

khoros.utils.tests.test_tags.test_failed_add_single_tag_to_message(monkeypatch)[source]

This function tests to ensure that an exception is raised properly for failed tag additions.

New in version 5.1.2.

khoros.utils.tests.test_tags.test_invalid_payload_for_single_tag()[source]

This function tests the raising of the InvalidPayloadValueError exception for a wrong tag text type.

New in version 5.1.2.

khoros.utils.tests.test_tags.test_message_structure_one_string_tag_ignore()[source]

This function tests the khoros.objects.tags.structure_tags_for_message() function with a single tag in string format and the ignore_non_strings keyword argument set to True.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_tags.test_message_structure_one_tag()[source]

This function tests the khoros.objects.tags.structure_tags_for_message() function with a single tag in string format.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_tags.test_message_structure_str_int()[source]

This function tests the khoros.objects.tags.structure_tags_for_message() function with one tag in string format and another as an integer.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_tags.test_message_structure_str_int_ignore()[source]

This function tests the khoros.objects.tags.structure_tags_for_message() function with one tag in string format and another as an integer and with ignore_non_strings set to True.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_tags.test_message_structure_two_string_tags_ignore()[source]

This function tests the khoros.objects.tags.structure_tags_for_message() function with two tags in string format and the ignore_non_strings keyword argument set to True.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_tags.test_message_structure_two_tags()[source]

This function tests the khoros.objects.tags.structure_tags_for_message() function with two tags in string format.

Changed in version 5.0.0: Removed the redundant return statement.

khoros.utils.tests.test_tags.test_single_tag_structure()[source]

This function tests the khoros.objects.tags.test_single_tag_structure() function.

Changed in version 5.0.0: Removed the redundant return statement.

Return to Top


Test Users Module (khoros.utils.tests.test_users)

This module is used by pytest to verify that the users module functions properly.

Module:

khoros.utils.tests.test_users

Synopsis:

This module is used by pytest to verify that the users module functions properly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

10 Jul 2023

khoros.utils.tests.test_users.set_package_path()[source]

This function adds the high-level khoros directory to the sys.path list.

New in version 5.1.2.

khoros.utils.tests.test_users.test_create_user(monkeypatch)[source]

This function tests the ability to create a user.

New in version 5.1.2.

khoros.utils.tests.test_users.test_failed_create_user(monkeypatch)[source]

This function verifies that the appropriate exception is raised if the user creation process fails.

New in version 5.1.2.

khoros.utils.tests.test_users.test_get_counts()[source]

This function tests the various functions that involve retrieving user-related counts.

Changed in version 5.3.0: Added assertions for the khoros.core.Khoros.User.get_users_count() method.

New in version 5.1.2.

khoros.utils.tests.test_users.test_get_user_identifiers()[source]

This function tests the ability to retrieve the identifiers for a user.

New in version 5.1.2.

khoros.utils.tests.test_users.test_impersonate_user()[source]

This function tests the ability to impersonate a user.

New in version 5.1.2.

khoros.utils.tests.test_users.test_unsupported_update_sso_id()[source]

This function tests to ensure the CurrentlyUnsupportedError exception is raised when trying to update the SSO ID of a user.

New in version 5.1.2.

khoros.utils.tests.test_users.test_users_table_query(monkeypatch)[source]

This function tests the ability to query the users table.

New in version 5.1.2.

Return to Top


Test Version Module (khoros.utils.tests.test_version)

This module is used by pytest to verify that the version module functions properly.

Module:

khoros.utils.tests.test_version

Synopsis:

This module is used by pytest to verify that the version module functions correctly

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

26 Sep 2022

khoros.utils.tests.test_version.test_full_version()[source]

This function tests to verify that the full version is defined correctly.

New in version 5.1.0.

khoros.utils.tests.test_version.test_latest_stable()[source]

This function tests to ensure that the latest stable version can be retrieved successfully.

New in version 5.1.0.

khoros.utils.tests.test_version.test_latest_version()[source]

This function tests to ensure that the check to see if the version is the latest stable works properly.

New in version 5.1.0.

khoros.utils.tests.test_version.test_major_minor_version()[source]

This function tests to ensure that the major/minor version is getting defined correctly.

New in version 5.1.0.

Return to Top


The previous page addresses the Primary Modules within the khoros package.