Supporting Modules

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

• Tools and Utilities

  • Core Utilities Module (khorosjx.utils.core_utils)

  • Dataframe Utilities Module (khorosjx.utils.df_utils)

  • Helper Module (khorosjx.utils.helper)

  • Tests Module (khorosjx.utils.tests)

  • Version Module (khorosjx.utils.version)

• Classes and Exceptions

  • Classes Module (khorosjx.utils.classes)

  • Errors Module (khorosjx.errors)

    • Exceptions Module (khorosjx.errors.exceptions)

    • Handlers Module (khorosjx.errors.handlers)

Tools and Utilities

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

Core Utilities Module (khorosjx.utils.core_utils)

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

Module

khorosjx.utils.core_utils

Synopsis

Useful tools and utilities to assist in managing a Khoros JX (formerly Jive-x) or Jive-n community

Usage

import khorosjx

Example

timestamp = khorosjx.utils.core_utils.get_timestamp(time_format="delimited")

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

Dec 2019

khorosjx.utils.core_utils.add_to_master_list(single_list, master_list)

This function appends items in a list to the master list.

Parameters

• single_list (list) – List of dictionaries from the paginated query

• master_list (list) – Master list of dictionaries containing group information

Returns

The master list with the appended data

khorosjx.utils.core_utils.convert_dict_list_to_dataframe(dict_list, column_names=[])

This function converts a list of dictionaries into a pandas dataframe.

Parameters

• dict_list (list) – List of dictionaries

• column_names (list) – The column names for the dataframe (Optional)

Returns

A pandas dataframe of the data

khorosjx.utils.core_utils.convert_dict_to_json(data)

This function converts a dictionary to JSON so that it can be traversed similar to a converted requests response.

Parameters

data (dict) – Dictionary to be converted to JSON

Returns

The dictionary data in JSON format

Raises

TypeError

khorosjx.utils.core_utils.convert_single_pair_dict_list(dict_list)

This function converts a list of single-pair dictionaries into a normal list.

Parameters

dict_list (list) – A list of single-pair dictionaries

Returns

A normal list with the value from each dictionary

khorosjx.utils.core_utils.eprint(*args, **kwargs)

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

khorosjx.utils.core_utils.get_format_syntax(syntax_nickname)

This function obtains the appropriate datetime format syntax for a format nickname. (e.g. delimited)

Parameters

syntax_nickname (str) – The nickname of a datetime format

Returns

The proper datetime format as a string

khorosjx.utils.core_utils.get_timestamp(time_format='split')

This function obtains the current timestamp in the local timezone.

Parameters

time_format (str) – The format for the timestamp that will be returned (default: split)

Returns

The current timestamp in %Y-%m-%d %H:%M:%S format as a string

khorosjx.utils.core_utils.identify_dataset(query_uri)

This function identifies the appropriate field dataset by examining a query URI.

Parameters

query_uri (str) – The API query URI to be examined

Returns

The appropriate dataset name in string format

khorosjx.utils.core_utils.print_if_verbose(msg, verbose_enabled=False)

This function prints a message onscreen only if verbose mode is enabled.

Parameters

• msg (str) – The message to print onscreen

• verbose_enabled (bool) – Determines if verbose mode is enabled (False by default)

Returns

None

khorosjx.utils.core_utils.remove_comment_wrappers_from_html(html_string)

This function removes comment wrappers (i.e. <!-- and -->) from an HTML string.

New in version 2.5.1.

Parameters

html_string (str) – The HTML string from which to remove comment wrappers

Returns

The HTML string with comment wrappers removed

khorosjx.utils.core_utils.validate_timestamp(timestamp, time_format='delimited', replace_invalid=True)

This function validates a timestamp string to ensure that it matches a prescribed syntax.

Parameters

• timestamp (str) – The timestamp in string format

• time_format (str) – The format for the supplied timestamp (default: delimited)

• replace_invalid (bool) – States if an invalid timestamp should be replaced with a default value (Default: True)

Returns

A valid timestamp string, either what was provided or a default timestamp

Raises

ValueError

Return to Top

Dataframe Utilities Module (khorosjx.utils.df_utils)

This module includes various utilities to assist in creating, importing, exporting and manipulating pandas dataframes.

Module

khorosjx.utils.df_utils

Synopsis

Useful tools and utilities to assist in importing, manipulating and exporting pandas dataframes

Usage

from khorosjx import df_utils

Example

TBD

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

18 Dec 2019

khorosjx.utils.df_utils.convert_dict_list_to_dataframe(dict_list, column_names=[])

This function converts a list of dictionaries into a pandas dataframe.

Parameters

• dict_list (list) – List of dictionaries

• column_names (list) – The column names for the dataframe (Optional)

Returns

A pandas dataframe of the data

khorosjx.utils.df_utils.import_csv(file_path, delimiter=',', column_names=[], columns_to_return=[], has_headers=True)

This function imports a CSV file to generate a dataframe.

Parameters

• file_path (str) – The absolute path to the CSV file to be imported

• delimiter (str) – The column delimiter utilized in the CSV

• column_names (list) – The column names to use with the imported dataframe (Optional)

• columns_to_return – Determines which of the columns should actually be returned (Default: all columns)

• has_headers (bool) – Defines whether or not the data in the file has column headers (Default: True)

Returns

The imported data as a pandas dataframe

Raises

FileNotFoundError, TypeError

khorosjx.utils.df_utils.import_excel(file_path, excel_sheet='', use_first_sheet=False, column_names=[], columns_to_return=[], has_headers=True)

This function imports a Microsoft Excel file to generate a dataframe.

Parameters

• file_path (str) – The absolute path to the Excel file to be imported

• excel_sheet (str) – The name of the specific sheet in the file to import

• use_first_sheet (bool) – Defines whether or not the first sheet in the file should be used (Default: False)

• column_names (list) – The column names to use with the imported dataframe (Optional)

• columns_to_return – Determines which of the columns should actually be returned (Default: all columns)

• has_headers (bool) – Defines whether or not the data in the file has column headers (Default: True)

Returns

The imported data as a pandas dataframe

Raises

FileNotFoundError, TypeError

Return to Top

Helper Module (khorosjx.utils.helper)

This module includes 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

khorosjx.utils.helper

Synopsis

Module that allows the khorosjx library to leverage a helper file and/or script

Usage

from khorosjx.utils import helper

Example

helper_cfg = helper.import_yaml_file('/path/to/jxhelper.yml')

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

29 Apr 2020

class khorosjx.utils.helper.HelperParsing

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

khorosjx.utils.helper.import_yaml_file(file_path)

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

Changed in version 2.5.1: 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

Returns

The parsed configuration data

Raises

FileNotFoundError

khorosjx.utils.helper.parse_helper_cfg(helper_cfg, file_type='yaml')

This is the primary function used to parse the helper config file.

Parameters

• helper_cfg – The raw data loaded from the config file

• file_type – Indicates the type of configuration file (Default: yaml)

Returns

None (Defines global variables)

Raises

CredentialsUnpackingError, InvalidHelperArgumentsError, HelperFunctionNotFoundError

khorosjx.utils.helper.retrieve_helper_settings()

This function returns a dictionary of the defined helper settings.

Returns

Dictionary of helper variables with nicknames

Return to Top

Tests Module (khorosjx.utils.tests)

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

Test Module Import (khorosjx.utils.tests.test_init_module)

Module

khorosjx.utils.tests.test_init_module

Synopsis

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

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

22 Nov 2019

khorosjx.utils.tests.test_init_module.init_module_operation()

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

khorosjx.utils.tests.test_init_module.set_package_path()

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

khorosjx.utils.tests.test_init_module.test_init_module()

This function tests to confirm that all primary modules are able to be imported successfully.

Return to Top

Version Module (khorosjx.utils.version)

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

Module

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

23 Sep 2021

khorosjx.utils.version.get_full_version()

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

Returns

The current full version (i.e. X.Y.Z) in string format

khorosjx.utils.version.get_latest_stable()

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

Returns

The latest stable version in string format

khorosjx.utils.version.get_major_minor_version()

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

Returns

The current major.minor (i.e. X.Y) version in string format

khorosjx.utils.version.latest_version()

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

Returns

Boolean value indicating if the versions match

khorosjx.utils.version.warn_when_not_latest()

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

Returns

None

Return to Top

Classes and Exceptions

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

Classes Module (khorosjx.utils.classes)

This module contains nearly all classes utilized by other modules within the library.

Module

khorosjx.utils.classes

Synopsis

Collection of classes relating to the khorosjx library

Usage

from khorosjx.utils.classes import Users

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

06 Mar 2020

class khorosjx.utils.classes.Content

This class includes content-related lists, dictionaries and other utilities.

class khorosjx.utils.classes.FieldLists

This class provides lists of JSON fields for various API data sets.

class khorosjx.utils.classes.Groups

This class provides various mappings to security group-related information.

class khorosjx.utils.classes.Platform

This class provides various mappings to Jive-related information such as environments, URLs, etc.

class khorosjx.utils.classes.TimeUtils

This class contains dictionaries and other utilities to assist with time-related function calls.

class khorosjx.utils.classes.Users

This class includes user-related lists, dictionaries and other utilities.

class UserJSON

This class maps the field names in the users table to the JSON field names.

Return to Top

Errors Module (khorosjx.errors)

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

Package

khorosjx.errors

Synopsis

This module includes custom exceptions and accompanying function

Usage

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

Example

raise errors.exceptions.BadCredentialsError

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

08 Jan 2020

Exceptions Module (khorosjx.errors.exceptions)

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

Module

khorosjx.errors.exceptions

Synopsis

Collection of exception classes relating to the khorosjx library

Usage

import khorosjx.errors.exceptions

Example

raise khorosjx.errors.exceptions.BadCredentialsError

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

23 Sep 2021

exception khorosjx.errors.exceptions.APIConnectionError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.BadCredentialsError(*args, **kwargs)

This exception is used when the supplied API credentials are incorrect.

exception khorosjx.errors.exceptions.ContentNotFoundError(*args, **kwargs)

This exception is used when an API query for content returns a 404 status code.

exception khorosjx.errors.exceptions.ContentPublishError(*args, **kwargs)

This exception is used when content is unable to publish successfully.

exception khorosjx.errors.exceptions.CredentialsUnpackingError(*args, **kwargs)

This exception is used when the tuple containing API credentials cannot be unpacked.

exception khorosjx.errors.exceptions.CurrentlyUnsupportedError(*args, **kwargs)

This exception is used when an operation is attempted that is not yet supported.

exception khorosjx.errors.exceptions.DatasetNotFoundError(*args, **kwargs)

This exception is used when a dataset was not provided and/or cannot be found.

exception khorosjx.errors.exceptions.GETRequestError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.HelperFunctionNotFoundError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.IncompleteCredentialsError(*args, **kwargs)

This exception is used when a tuple containing API credentials is missing a username or password.

exception khorosjx.errors.exceptions.InvalidDatasetError(*args, **kwargs)

This exception is used when a supplied dataset is invalid.

exception khorosjx.errors.exceptions.InvalidEndpointError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.InvalidFileTypeError(*args, **kwargs)

This exception is used when a supplied file type is invalid and cannot be used.

exception khorosjx.errors.exceptions.InvalidHelperArgumentsError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.InvalidKhorosJXModuleError(*args, **kwargs)

This exception is used when an invalid module is attempted to be initialized from the primary __init__ file.

exception khorosjx.errors.exceptions.InvalidLookupTypeError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.InvalidRequestTypeError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.InvalidScopeError(*args, **kwargs)

This exception is used when a supplied scope is invalid and cannot be found.

exception khorosjx.errors.exceptions.KhorosJXError

This is the base class for Khoros JX exceptions.

exception khorosjx.errors.exceptions.LookupMismatchError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.MissingBaseUrlError(*args, **kwargs)

This exception is used when a valid base URL has not been defined.

exception khorosjx.errors.exceptions.NoCredentialsError(*args, **kwargs)

This exception is used when credentials weren’t found when utilizing the core functions.

exception khorosjx.errors.exceptions.NotFoundResponseError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.POSTRequestError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.PUTRequestError(*args, **kwargs)

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

exception khorosjx.errors.exceptions.SpaceNotFoundError(*args, **kwargs)

This exception is used when an API query for a space returns a 404 response.

exception khorosjx.errors.exceptions.SubscriptionNotFoundError(*args, **kwargs)

This exception is used when a subscription referenced in a function does not exist.

exception khorosjx.errors.exceptions.UserNotFoundError(*args, **kwargs)

This exception is used when an API query for a user returns a 404 status code.

exception khorosjx.errors.exceptions.UserQueryError(*args, **kwargs)

This exception is used when an API query returns an unidentified non-200 response.

exception khorosjx.errors.exceptions.WrongCredentialTypeError(*args, **kwargs)

This exception is used when a username or password is not in string format.

Return to Top

Handlers Module (khorosjx.errors.handlers)

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

Module

khorosjx.errors.handlers

Synopsis

Collection of error handler functions relating to the khorosjx library

Usage

from khorosjx.errors import handlers

Example

successful_response = check_api_response(response)

Created By

Jeff Shurtliff

Last Modified

Jeff Shurtliff

Modified Date

22 Sep 2021

khorosjx.errors.handlers.bad_lookup_type(lookup_type, good_examples)

This function raises the InvalidLookupTypeError exception and provides a custom message.

khorosjx.errors.handlers.check_api_response(response, request_type='get', ignore_exceptions=False)

This function checks an API response to determine if it was successful

Parameters

• response (class) – The API response obtained via the requests package

• request_type (str) – The type of API request that was performed. (Default: get)

• ignore_exceptions (bool) – Determines whether or not exceptions should be ignored and not raised (Default: False)

Returns

A Boolean value indicating whether or not the API request was deemed successful

Raises

khorosjx.errors.exceptions.BadCredentialsError, khorosjx.errors.exceptions.GETRequestError, khorosjx.errors.exceptions.POSTRequestError, khorosjx.errors.exceptions.PUTRequestError

khorosjx.errors.handlers.check_json_for_error(json_data, data_type='space')

This function checks to see if JSON from an API response contains an error.

Changed in version 3.1.0: Parenthesis were added to the exception classes and the function was refactored to be more efficient.

Parameters

• json_data (dict) – The API response data in JSON format

• data_type (str) – Determines what type of data was being queried (Default: space)

Returns

None

Raises

khorosjx.errors.exceptions.GETRequestError khorosjx.errors.exceptions.SpaceNotFoundError, khorosjx.errors.exceptions.NotFoundResponseError

Return to Top