Khoros JX Python Library¶

Welcome to the official documentation for the Khoros JX Python Library.

Table of Contents¶

Introduction¶

The khorosjx library acts as a Python software development kit (SDK) to administer and manage Khoros JX (formerly Jive-x) and Jive-n online community platforms.

Installation¶

The package can be installed via pip using the syntax below.

# pip install khorosjx

You may also clone the repository and install from source using the syntax below.

# git clone git://github.com/jeffshurtliff/khorosjx.git
# cd khorosjx/
# python3 setup.py install

Change Log¶

Changes for each release can be found on the Change Log page.

Basic Usage¶

This section provides basic usage instructions for the package.

Importing the package¶

The package can be imported into a Python script using the syntax below.

import khorosjx

Initializing the modules¶

While it is certainly possible to import modules directly (e.g. from khorosjx import users), it is recommended that you instead leverage the init_module() function as shown below.

khorosjx.init_module('content', 'users')

In the example above, both the khorosjx.content and the khoros.users modules have been initiated.

Note

It is not necessary to import the khorosjx.core module as it is imported by default.

Establishing the API connection¶

Before leveraging the API in function calls, you must first establish your connection by providing the base URL for the environment (e.g. https://community.example.com) and the username and password for the unfederated service account through which the API calls will be made. This is demonstrated below.

base_url = 'https://community.example.com'
credentials = ('adminuser', 'password123!')
khorosjx.core.connect(base_url, credentials)

Note

At this time the library only allow connections using basic authentication, but there are plans to include the ability to leverage OAuth 2.0 in a future release.

Once the connection has been established, you can proceed to leverage the library of functions in the various modules as needed.

Requirements¶

The following packages are leveraged within the khorosjx package:

numpy 1.17.4
pandas-0.25.3
python-dateutil 2.8.1
pytz 2019.3
requests 2.22.0
urllib3 1.25.7

The full requirements list can be found in the requirements.txt file.

Modules¶

The KhorosJX Python Library consists of the following primary modules:

Core Module (khorosjx.core): This module contains core functions such as initializing the connection to the API, getting API version information, performing GET and PUT requests, etc.
Admin Module (khorosjx.admin): This module contains administrative functions that would only be performed by a platform administrator or a community manager.
Content Module (khorosjx.content): This module contains functions relating to content within the platform which allows for creating, editing and managing content such as documents, ideas, videos, etc.
Groups Module (khorosjx.groups): This module contains functions for working with security groups (and eventually social groups) such as obtaining and managing group membership.
Spaces Module (khorosjx.spaces): This module contains functions for working with spaces, such as identifying content within spaces, etc.
Users Module (khorosjx.users): This module contains functions for working with users, such as obtaining their account/profile information, getting a count of their created content, etc.

The library also includes some supporting modules to support the overall functionality of the primary modules, as well as modules containing global Classes and Exceptions for the library, which are listed below.

Core Utilities Module (khorosjx.utils.core_utils): This module includes various utilities to assist in converting dictionaries to JSON, formatting timestamps, etc.
Classes Module (khorosjx.utils.classes): This module contains nearly all classes utilized by other modules within the library.
Exceptions Module (khorosjx.errors.exceptions): This module contains all of the exception classes leveraged in functions throughout the library.

License¶

This package falls under the MIT License.

Reporting Issues¶

Issues can be reported within the GitHub repository.

Disclaimer¶

This package is in no way endorsed or supported by the Khoros or Aurea Software, Inc. companies.

Core Functionality¶

Warning

This page is currently in development.

This page provides instructions and examples around the core functionality of the library. This includes a review of the Basic Usage as well as base functionality such as performing generic API requests.

Getting Started
Performing GET Requests
- Using the get_data() function
  
  Optional arguments in the get_data() function
  
  Ignoring exceptions in the get_data() function
  
  Returning the get_data() response in JSON format
- Using the get_request_with_retries() function
  
  Returning the get_request_with_retries() response in JSON format
Performing POST Requests
Performing PUT Requests

Getting Started¶

The topics in this section are necessary to leverage the khorosjx library.

Importing the package¶

The package can be imported into a Python script using the syntax below.

import khorosjx

Initializing the modules¶

While it is certainly possible to import modules directly (e.g. from khorosjx import users), it is recommended that you instead leverage the init_module() function as shown below.

khorosjx.init_module('content', 'users')

In the example above, both the khorosjx.content and the khoros.users modules have been initiated.

Note

It is not necessary to import the khorosjx.core module as it is imported by default.

Establishing the API connection¶

Before leveraging the API in function calls, you must first establish your connection by providing the base URL for the environment (e.g. https://community.example.com) and the username and password for the unfederated service account through which the API calls will be made. This is demonstrated below.

base_url = 'https://community.example.com'
credentials = ('adminuser', 'password123!')
khorosjx.core.connect(base_url, credentials)

Note

At this time the library only allow connections using basic authentication, but there are plans to include the ability to leverage OAuth 2.0 in a future release.

Once the connection has been established, you can proceed to leverage the library of functions in the various modules as needed.

Performing GET Requests¶

There are two primary ways to perform GET requests against the Core API. The first is to use the get_data() function, which avoids the necessity to construct a query URI but is somewhat restrictive in what can be returned. The second is more flexible but does require the construction of API query URIs.

Both of these methods are addressed in the sections below.

Using the get_data() function¶

The get_data() function performs GET requests by requiring only two arguments: the API endpoint and a lookup value.

The API endpoints, also known as the API services in the Jive REST API documentation, are the different avenues within the API through which data can be retrieved and, in some cases, created and/or modified. The endpoints supported within the khorosjx library are listed below.

abuseReports	acclaim	actions	activities	addOns	announcements
attachments	calendar	checkpoints	collaborations	comments	contents
deletedObjects	dms	events	eventTypes	executeBatch	extprops
extstreamDefs	extstreams	ideaVotes	images	inbox	invites
members	mentions	messages	moderation	oembed	outcomes
pages	people	places	placeTemplateCategories	placeTemplates	placeTopics
profileImages	publications	questions	rsvp	search	sections
securityGroups	shares	slides	stages	statics	streamEntries
streams	tags	tileDefs	tiles	urls	versions
videos	vitals	votes	webhooks

By default, the respective ID is used as the lookup value for each endpoint. For example, when querying the people endpoint the default lookup value is the User ID, whereas when querying the contents endpoint the default lookup value is the Content ID.

The example below shows how you would use the function to retrieve data for content with 12345 as its Content ID.

api_response = khorosjx.core.get_data('contents', 12345)

Note

Because f-strings are leveraged to construct the query URIs in the function, the lookup value can be supplied as an integer or a string.

When querying against specific endpoints, other identifiers may be permitted as well. For example, if querying for user data via the people endpoint it is possible to supply a User ID, username or email address as demonstrated in the examples below.

response_from_id = khorosjx.core.get_data('people', 1234)
response_from_email = khorosjx.core.get_data('people', 'john.doe@example.com', 'email')
response_from_username = khorosjx.core.get_data('people', 'john_doe', 'username')

Optional arguments in the get_data() function¶

There are two optional arguments that may be supplied within the get_data() function which can be useful in certain circumstances. Both are addressed below.

Ignoring exceptions in the get_data() function¶

When utilizing the get_data() function multiple times, such as when looping through a list of users, it may be useful to ignore exceptions so that the entire script doesn’t fail if data for a single user cannot be returned successfully. This can be done by setting the ignore_exceptions argument to True in the function arguments, as demonstrated below.

api_response = khorosjx.core.get_data('people', 1234, ignore_exceptions=True)

Leveraging this option will result in failed responses printing an error message and then either returning the API response (which will include a status code other than 200) or an empty JSON string. (See the next section)

Returning the get_data() response in JSON format¶

Rather than having to convert the API response to JSON in your script, you can do so within the get_data() function by setting the return_json argument to True as shown in the example below.

user_json = khorosjx.core.get_data('people', 1234, return_json=True)

Note

As stated in the previous section, if the ignore_exceptions argument is also set to true then JSON data will still be returned but will simply be empty.

Using the get_request_with_retries() function¶

If you have a need to perform a less generic GET request then it will likely be better to leverage the get_request_with_retries() function instead of get_data() so that the specific query URI can be supplied.

The get_request_with_retries() function performs the GET query and will retry the operation up to five times to account for any unexpected connection aborts or timeouts, which is known to happen on occasion with the Jive APIs.

This function is demonstrated in the example below.

query_uri = f"{base_url}/people/1234/contents?count=100&startIndex=200&fields=@all"
api_response = khorosjx.core.get_request_with_retries(query_uri)

Note

Notice that the base_url global variable is being utilized above, which was defined when establishing the API connection when getting started above.

Returning the get_request_with_retries() response in JSON format¶

Similar to the get_data() function, you have the option of returning the response in JSON format by setting the return_json argument to True as shown in the example below.

get_request_json = khorosjx.core.get_request_with_retries(query_uri, return_json=True)

Performing POST Requests¶

Todo

This section is not yet written but will be at a future date.

Performing PUT Requests¶

Todo

This section is not yet written but will be at a future date.

Using the Helper Utility¶

This page provides instructions and examples around leveraging the Helper Module (khorosjx.utils.helper) which 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.

What is a helper?
The configuration file
- API Connection
  
  Supplying credentials in the config file
  
  Retrieving credentials using a script function
- Script Styling
Initializing the Helper
- Global Variables

What is a helper?¶

When talking about the KhorosJX Python Library, a helper is a configuration file which defines various settings that can be leveraged by the library to simplify the Getting Started process. It also allows additional features to be enabled in certain circumstances that may be deemed helpful.

The configuration file¶

The Helper configuration file is a YAML file that follows the formatting shown below.

# Helper configuration file for the khorosjx package

# Define how to obtain the connection information
connection:
    base_url: https://community.example.com
    credentials:
        # Uncomment the lines below to provide plaintext credentials
        #
        use_script: no
        username: exampleuser
        password: examplePWD123!

        # Uncomment the lines below to provide the credentials via module
        # for a module and function
        #
        # use_script: yes
        # module_name: jxhelper
        # function_name: get_credentials
        # function_kwargs: username='adminuser'

# Define whether or not to color-code the function output
styling:
    use_console_colors: no

Note

In a future release, you will have the ability to utilize a JSON file rather than YAML if preferred.

API Connection¶

The primary functionality of the Helper configuration file is to allow you to define the Base URL and the API credentials which are both necessary to leverage the library. (See Basic Usage)

This can be done in two different ways:

Supplying the credentials within the configuration file
Leveraging another Python module and function to retrieve the credentials.

Supplying credentials in the config file¶

If your configuration will be stored in a secure location then you have the option of storing the credentials directly within the configuration file, as demonstrated in the example above. This method requires the fields listed below to be defined, which all reside within the credentials subsection under the connection section.

use_script: This field specifies whether or not a script (i.e. module/function) will be used to retrieve the credentials and should be set to no in this situation.
username: This field is where you will store the username for the account you will utilize with the Core API.
password: This field is where you will store the corresponding password for the username above.

Retrieving credentials using a script function¶

An an alternative to providing credentials directly within the configuration file, you have the option to create a module and function (or leverage an existing module and function) to return the credentials needed for the khorosjx library.

This can be done by commenting out (or removing) the section mentioned above in the configuration file for storing credentials within the file itself and instead uncomment the other section which includes these fields:

use_script: This field specifies whether or not a script (i.e. module/function) will be used to retrieve the credentials and should be set to yes in this situation.
module_name: This field defines the name of the module that must be imported.
function_name: This field defines the name of the function within the module above that will provide the credentials.
function_kwargs: This is an optional field where you can define any keyword arguments that must be defined in order to return the appropriate data for the khorosjx library.

Note

The configuration file only supports basic keyword arguments (e.g. username=”apiuser”) with integer, string or Boolean values. Non-keyword arguments and values that are lists, tuples, dictionaries or other data types are not permitted at this time.

For example, let’s assume that you have a package entitled myutils with an underlying module entitled jxhelper which lets you return credentials for a specified user.

# Define function to return credentials for a specific user
get_credentials(username):
    # Retrieve the credentials from our SQL server database
    un, pw = get_credentials_from_sql(username)
    return un, pw

In this example, if you wanted this function to return credentials for a user with the usrename adminuser, then you would define the values below in the configuration file.

use_script: no
module_name: myutils.jxhelper
function_name: get_credentials
function_kwargs: username=’adminuser`

Script Styling¶

A secondary section in the configuration file address script styling, with a single option to enable console colors, which is not currently an enabled feature and will be available in a future release. As such, the setting in the configuration file is present for future preparation purposes and current has no effect.

Initializing the Helper¶

Once the configuration file is created, you can initialize it from the primary module with the syntax below.

khorosjx.init_helper('/path/to/khorosjx_helper.yml')

This function call will not only initialize the Helper settings as global variables to use throughout the library, but will also perform the API connection process as well so this will not need to be performed in a separate function call.

Global Variables¶

Once the Helper utility has been initialized, the following global variables become accessible:

helper_settings: A dictionary that includes all settings defined by the utility
use_console_colors: A Boolean value that defines whether console colors should be utilized throughout the library. (Currently has no effect)

Managing Users¶

Warning

This page is currently in development.

This page has instructions relating to managing users within a KhorosJX (or Jive-n) community, including tasks such as obtaining user information and statistics and other similar operations.

Leveraging the Users Module
Obtaining User Information
- Obtain the User ID of a user
- Obtain the username, email address and profile URL of a user
  
  Obtain the username
  
  Obtain the primary email address
  
  Obtain the user profile URL

Leveraging the Users Module¶

In order to leverage the Users Module (and any other module within the khorosjx library) you must first perform the following steps:

Import the high-level khorosjx package.
Initialize the users module.
Establish the connection to the environment.

This is demonstrated in the example below.

# Import the package
import khorosjx

# Initialize the users module
khorosjx.init_module('users')

# Establish a connection to the environment
environment_url = 'https://community.example.com'
api_username = 'adminuser'
api_password = 'password123$'
khorosjx.core.connect(environment_url, (api_username, api_password))

# Global variables established from the connection above
base_url            # Global variable (str) derived from the environment_url above
api_credentials     # Global variable (tuple) derived from api_username and api_password above

Warning

The API credentials were defined in the example above for the purpose of demonstrating the process. However, it is strongly recommended that you never include API credentials in plaintext within scripts or other locations that can potentially be accessed by unauthorized parties.

Obtaining User Information¶

This section addresses how you can obtain information about a user to use in other administrative functions and/or to obtain for statistical purposes.

Obtain the User ID of a user¶

The User ID value is a unique identifier within the KhorosJX / Jive environment which identifies a user and allows the platform–as well as third-party integrations via the API–to take actions against the user in various capacities.

However, sometimes the User ID for a user is not readily available and you only have their email address or username. In these situations, the get_user_id() function can be used to retrieve the needed User ID, as shown in the examples below.

user_id_from_email = khorosjx.users.get_user_id('john.doe@example.com')
user_id_from_username = khorosjx.users.get_user_id('john_doe', 'username')

Note

You will notice that, because email is the default identifier, you must supply username as a second argument if you are providing a username.

Obtain the username, email address and profile URL of a user¶

Similar to how you obtain the User ID of a user, you can also retrieve a user’s username, email address and profile URL using simple functions within the Users Module (khorosjx.users). These operations are explained in the following subsections.

Obtain the username¶

Assuming you have the User ID or email address for a user, you can quickly obtain their username via the khorosjx.users.get_username() function, as demonstrated in the examples below.

username_from_id = khorosjx.users.get_username(1234)
username_from_email = khorosjx.users.get_username('john.doe@example.com', 'email')

Note

Similar to the khorosjx.users.get_user_id() function, you must provide the lookup type (e.g. email) as a second argument if not querying with the User ID.

You may also notice that when leveraging the User ID, you can provide it as either an integer or a string value and both will be acceptable.

Obtain the primary email address¶

You can quickly retrieve the primary email address for a user by leveraging the khorosjx.users.get_primary_email() function and supplying the User ID or username of the user. This is demonstrated below.

email_address_from_id = khorosjx.users.get_primary_email(1234)
email_address_from_username = khorosjx.users.get_primary_email('john_doe', 'username')

Note

As with the other functions above, you must provide the lookup type (e.g. username) as a second argument if not querying with the User ID. Also in similar fashion, the User ID can be provided as either an integer or a string value and both will be acceptable.

Obtain the user profile URL¶

When you have the username for a user, it is easy to determine the URL of their respective profile as the URL structure is simply your base URL, the people endpoint and then the username. (e.g. https://community.example.com/people/john_doe)

However, the khorosjx.users.get_profile_url() function makes the process even easier by constructing the URL for you, and can even do so when supplied a User ID or email address rather than a username.

All three methods are demonstrated below.

profile_url_from_id = khorosjx.users.get_profile_url(1234)
profile_url_from_email = khorosjx.users.get_profile_url('john.doe@example.com', 'email')
profile_url_from_username = khorosjxusers.get_profile_url('john_doe', 'username')

Note

Despite the profile URL being constructed using the username, functions within this module will generally utilize the User ID as the primary lookup type as it is the main unique identifier leveraged within the Khoros JX / Jive platform.

Todo

The remainder of this document is still in progress. Please check back later for updates.

Primary Modules¶

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

Init Module (khorosjx)
Core Module (khorosjx.core)
Admin Module (khorosjx.admin)
Content Module (khorosjx.content)
Groups Module (khorosjx.groups)
News Module (khorosjx.news)
Places Module (khorosjx.places)
Spaces Module (khorosjx.spaces)
Users Module (khorosjx.users)

Init Module (khorosjx)¶

This module (being the primary __init__.py file for the library) contains the functions to initialize the modules and the Helper Utility.

Package: khorosjx
Synopsis: This package includes custom exceptions and a function to call them with specific error messages
Usage: import khorosjx
Example: khorosjx.init_helper('/home/user/jxhelper.yml')
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 24 Mar 2020

khorosjx.init_helper(file_path, file_type='yaml')[source]¶

This function initializes a helper configuration file to define package settings including the API connection.

Parameters

file_path (str) – Path to the helper configuration file
file_type (str) – The type of file utilized as the configuration file (Default: yaml)

Returns

None (Defines global variables and establishes API connection)

Raises

FileNotFoundError, khorosjx.errors.exceptions.CredentialsUnpackingError, khorosjx.errors.exceptions.InvalidHelperArgumentsError, khorosjx.errors.exceptions.HelperFunctionNotFoundError

khorosjx.init_module(*args)[source]¶

This function imports select modules from the library.

Parameters: args (str, tuple) – One or more module names to import
Returns: None
Raises: ModuleNotFoundError, khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.InvalidKhorosJXModuleError

Return to Top

Core Module (khorosjx.core)¶

This module contains core functions such as initializing the connection to the API, getting API version information, performing GET and PUT requests, etc.

Module: khorosjx.core
Synopsis: Collection of core functions and tools to work with the Jive Core API v3
Usage: import khorosjx.core (Imported by default in primary package)
Example: user_info = khorosjx.core.get_data('people', 'john.doe@example.com', 'email')
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 23 Sep 2021

khorosjx.core.connect(base_api_url, credentials)[source]¶

This function establishes the connection information for performing Core API queries.

Parameters

base_api_url (str) – The base URL (e.g. https://community.example.com) for for environment
credentials (tuple) – The username and password of the account to perform the API queries

Returns

None

khorosjx.core.delete(uri, return_json=False, verify_ssl=True)[source]¶

This function performs a DELETE request against the Core API.

Changed in version 3.2.0: The query URL is now made into an absolute URL as necessary before performing the API request.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

uri (str) – The URI against which the DELETE request will be issued
return_json (bool) – Determines whether or not the response should be returned in JSON format (Default: False)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

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

khorosjx.core.ensure_absolute_url(query_url)[source]¶

This function adds the base URL to the beginning of a query URL if not already present.

New in version 3.2.0.

Parameters: query_url (str) – The query URL that will be utilized in an API request
Returns: The query URL that includes a top-level domain
Raises: TypeError

khorosjx.core.get_api_info(api_filter='none', verify_ssl=True)[source]¶

This function obtains the API version information for a Jive environment.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

api_filter (str) – A filter to return a subset of API data (e.g. v3, platform, sso, etc.)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

API information in JSON, string or list format depending on the filter

khorosjx.core.get_api_version(api_name='v3', verify_ssl=True)[source]¶

This function obtains, parses and returns the current version of one of the Jive Core APIs.

Changed in version 3.1.0: Refactored the function to be more efficient.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

api_name (str) – The name of the API for which the version should be returned (Default: v3)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The API version in major.minor notation (e.g. 3.15) in string format

khorosjx.core.get_base_url(api_base=True)[source]¶

This function returns the base URL of the environment with or without the /api/core/v3/ path appended.

Changed in version 3.1.0: Refactored the function to properly utilize the base_url global variable.

Parameters: api_base (bool) – Determines if the /api/core/v3/ path should be appended (True by default)
Returns: The base URL for the Khoros JX or Jive-n environment

khorosjx.core.get_connection_info()[source]¶

This function returns the connection information (Base URL and API credentials) to use in other modules.

Returns: Base URL in string format and API credentials within a tuple

khorosjx.core.get_data(endpoint, lookup_value, identifier='id', return_json=False, ignore_exceptions=False, all_fields=False, verify_ssl=True)[source]¶

This function returns data for a specific API endpoint.

Changed in version 3.1.0: Fixed how the query_url variable is defined to proactively avoid raising any NameError exceptions.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

endpoint (str) – The API endpoint against which to request data (e.g. people, contents, etc.)
lookup_value (int, str) – The value to use to look up the endpoint data
identifier (str) – The type of lookup value used to look up the endpoint data (Default: id)
return_json (bool) – Determines if the data should be returned in default or JSON format (Default: False)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)
all_fields (bool) – Determines whether or not the fields=@all query should be included (Default: False)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The API response either as a requests response or in JSON format depending on the return_json value

Raises

khorosjx.errors.exceptions.GETRequestError

khorosjx.core.get_fields_from_api_response(json_data, dataset, return_fields=None, quiet=False)[source]¶

This function parses and retrieves fields from an API response from a specific dataset.

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Changed in version 2.6.0: Added conditional to ensure quiet is False before calling the stderr print statement.

Changed in version 2.5.3: Fixed the email.value filter and added the optional quiet argument.

Parameters

json_data (dict) – The JSON data from an API response
dataset (str) – The nickname of a dataset from which fields should be retrieved (e.g. people, group_admins)
return_fields (list, None) – The fields that should be returned from the API response (Default: all fields in dataset)
quiet (bool) – Silences any errors about being unable to locate API fields (False by default)

Returns

A dictionary with the field names and corresponding values

Raises

khorosjx.errors.exceptions.InvalidDatasetError

khorosjx.core.get_paginated_results(query, response_data_type, start_index=0, filter_info=(), query_all=True, return_fields=None, ignore_exceptions=False, quiet=False, verify_ssl=True)[source]¶

This function performs a GET request for a single paginated response up to 100 records.

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

query (str) – The API query without the query string
response_data_type (str) – The dataset of fields that will be in the API response (e.g. group_members)
start_index (int, str) – The startIndex value in the API query string (0 by default)
filter_info (tuple, list) – A tuple of list of tuples containing the filter element and criteria (Optional)
query_all (bool) – Determines if fields=@all filter should be included in the query string (Default: True)
return_fields (list, None) – The fields that should be returned from the API response (Default: all fields in dataset)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)
quiet (bool) – Silences any errors about being unable to locate API fields (False by default)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The queried data as a list comprised of dictionaries

Raises

khorosjx.errors.exceptions.GETRequestError

khorosjx.core.get_platform_version(verify_ssl=True)[source]¶

This function obtains the current Khoros JX (or Jive) version for an environment.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters: verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)
Returns: The full platform version in string format (e.g. 2018.22.0.0_jx)

khorosjx.core.get_query_url(pre_endpoint, asset_id='', post_endpoint='')[source]¶

This function constructs an API query URL excluding any query strings.

Changed in version 3.1.0: Refactored the function to be more efficient.

Parameters

pre_endpoint (str) – The endpoint portion of the URL preceding any ID numbers (e.g. places)
asset_id (str, int) – The ID for an asset (e.g. User ID, Browse ID for a space/blog, etc.)
post_endpoint (str) – Any remaining endpoints following the ID number (e.g. contents)

Returns

The fully structured query URL

khorosjx.core.get_request_with_retries(query_url, return_json=False, verify_ssl=True)[source]¶

This function performs a GET request with a total of 5 retries in case of timeouts or connection issues.

Changed in version 3.2.0: The query URL is now made into an absolute URL as necessary before performing the API request.

Changed in version 3.1.0: Refactored the function to be more efficient.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

query_url (str) – The URI to be queried
return_json (bool) – Determines whether or not the response should be returned in JSON format (Default: False)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

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

Raises

ValueError, TypeError, khorosjx.errors.exceptions.APIConnectionError

khorosjx.core.post_request_with_retries(url, json_payload, verify_ssl=True)[source]¶

This function performs a POST request with a total of 5 retries in case of timeouts or connection issues.

Changed in version 3.2.0: The query URL is now made into an absolute URL as necessary before performing the API request.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

url (str) – The URI to be queried
json_payload (dict) – The payload for the POST request in JSON format
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The API response from the POST request

Raises

ValueError, khorosjx.errors.exceptions.APIConnectionError, khorosjx.errors.exceptions.POSTRequestError

khorosjx.core.put_request_with_retries(url, json_payload, verify_ssl=True)[source]¶

This function performs a PUT request with a total of 5 retries in case of timeouts or connection issues.

Changed in version 3.2.0: The query URL is now made into an absolute URL as necessary before performing the API request.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

url (str) – The URI to be queried
json_payload (dict) – The payload for the PUT request in JSON format
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The API response from the PUT request

Raises

ValueError, khorosjx.errors.exceptions.APIConnectionError, khorosjx.errors.exceptions.PUTRequestError

khorosjx.core.set_base_url(domain_url, version=3, protocol='https', return_url=True)[source]¶

This function gets the base URL for API calls when supplied with a domain URL. (e.g. community.example.com)

Changed in version 3.2.0: Added the return_url parameter to determine if the base URL should be returned by the function.

Parameters

domain_url (str) – The domain URL of the environment, with or without the http/https prefix
version (int) – The version of the REST API to utilize (Default: 3)
protocol (str) – The protocol to leverage for the domain prefix if not already supplied (Default: https)
return_url (bool) – Determines if the base URL should be returned by the function (True by default)

Returns

The base URL for API calls in string format (e.g. https://community.example.com/api/core/v3)

Raises

TypeError, ValueError

khorosjx.core.set_credentials(credentials)[source]¶

This function defines the Core API credentials as global variables and validates them.

Changed in version 3.1.0: Parenthesis were added to the exception classes and utilized the isinstsance() builtin.

Parameters: credentials (tuple) – The username and password for the account that will be utilizing the Core API
Returns: None
Raises: khorosjx.errors.exceptions.IncompleteCredentialsError, khorosjx.errors.exceptions.CredentialsUnpackingError, khorosjx.errors.exceptions.WrongCredentialTypeError

khorosjx.core.verify_connection()[source]¶

This function verifies that the base URL and API credentials have been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Admin Module (khorosjx.admin)¶

This module contains administrative functions that would only be performed by a platform administrator or a community manager.

Module: khorosjx.admin
Synopsis: Collection of functions relating to security groups
Usage: from khorosjx import admin
Example: Coming Soon
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.admin.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.admin.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Content Module (khorosjx.content)¶

This module contains functions relating to content within the platform which allows for creating, editing and managing content such as documents, ideas, videos, etc.

Module: khorosjx.content
Synopsis: Collection of functions relating to content
Usage: from khorosjx import content
Example: content_id = content.base.get_content_id(url, 'document')
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 24 Mar 2020

khorosjx.content.get_content_id(url, content_type='document')[source]¶

This function obtains the Content ID for a particular content asset. (Supports all but blog posts)

Deprecated since version 2.0.0: The khorosjx.content.base.get_content_id() function should be used.

Parameters

url (str) – The URL to the content
content_type (str) – The content type for the URL for which to obtain the Content ID (Default: document)

Returns

The Content ID for the content URL

Raises

ValueError

khorosjx.content.get_document_attachments(lookup_value, lookup_type='doc_id', return_dataframe=False)[source]¶

This function retrieves information on any attachments associated with a document.

Deprecated since version 2.0.0: The khorosjx.content.docs.get_document_attachments() function should be used.

Parameters

lookup_value (str, int) – The value with which to look up the document
lookup_type (str) – Identifies the type of lookup value that has been provided (Default: doc_id)
return_dataframe (bool) – Determines whether or not a pandas dataframe should be returned

Returns

A list, dictionary or pandas dataframe depending on the number of attachments and/or function arguments

Raises

khorosjx.errors.exceptions.GETRequestError, khorosjx.errors.exceptions.InvalidDatasetError, khorosjx.errors.exceptions.InvalidLookupTypeError, khorosjx.errors.exceptions.LookupMismatchError

khorosjx.content.get_document_info(lookup_value, lookup_type='doc_id', return_fields=[], ignore_exceptions=False)[source]¶

This function obtains the group information for a given document.

Deprecated since version 2.0.0: The khorosjx.content.docs.get_document_info() function should be used.

Parameters

lookup_value (int, str) – The value with which to look up the document
lookup_type (str) – Identifies the type of lookup value that has been provided (Default: doc_id)
return_fields (list) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A dictionary with the group information

Raises

khorosjx.errors.exceptions.GETRequestError, khorosjx.errors.exceptions.InvalidDatasetError, khorosjx.errors.exceptions.InvalidLookupTypeError, khorosjx.errors.exceptions.LookupMismatchError

khorosjx.content.overwrite_doc_body(url, body_html, minor_edit=True, ignore_exceptions=False)[source]¶

This function overwrites the body of a document with new HTML content.

Deprecated since version 2.0.0: The khorosjx.content.docs.overwrite_doc_body() function should be used.

Parameters

url (str) – THe URL of the document to be updated
body_html – The new HTML body to replace the existing document body
minor_edit (bool) – Determines whether the Minor Edit flag should be set (Default: True)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

The response of the PUT request used to update the document

Raises

khorosjx.errors.exceptions.ContentPublishError

Return to Top

Base Content Module (khorosjx.content.base)¶

This module contains the core functions relating to content within the platform which allows for creating, editing and managing content.

Module: khorosjx.content.base
Synopsis: Collection of core functions relating to content
Usage: import khorosjx.content.base as content_core
Example: content_id = content_core.get_content_id(url, 'document')
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.content.base.get_content_id(url, content_type='document', verify_ssl=True)[source]¶

This function obtains the Content ID for a particular content asset. (Supports all but blog posts)

Changed in version 3.1.0: Made some minor syntax improvements.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

url (str) – The URL to the content
content_type (str) – The content type for the URL for which to obtain the Content ID (Default: document)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The Content ID for the content URL

Raises

ValueError, khorosjx.errors.exceptions.ContentNotFoundError

khorosjx.content.base.get_paginated_content(endpoint, query_string='', start_index=0, dataset='', all_fields=False, return_fields=None, ignore_exceptions=False)[source]¶

This function returns paginated content information. (Up to 100 records at a time)

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

endpoint (str) – The full endpoint without preceding slash (e.g. securityGroups, people/email/user_email)
query_string (str) – Any query strings to apply (without preceding ?) excluding count and startIndex
start_index (int, str) – The startIndex API value
dataset (str) – Defines the type of data returned in the API response (e.g. security_group, people, etc.)
all_fields (bool) – Determines if the fields=@all parameter should be passed in the query
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A list of dictionaries containing information for each group in the paginated query

khorosjx.content.base.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.content.base.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Documents Module (khorosjx.content.docs)¶

This module contains functions specific to handling documents.

Module: khorosjx.content.docs
Synopsis: Collection of functions relating to documents (e.g. https://community.example.com/docs/DOC-1234)
Usage: from khorosjx.content import docs
Example: content_id = docs.get_content_id(url)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.content.docs.create_document(subject, body, place_id, categories=None, tags=None, verify_ssl=True)[source]¶

This function creates a new document.

Changed in version 3.1.0: Changed the default categories and tags values to None and adjusted the function accordingly.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

subject (str) – The title/subject of the document
body (str) – The raw HTML making up the document body
place_id (int, str) – The Place ID (aka Browse ID) of the space where the document should reside
categories (list, None) – Any categories associated with the document (none by default)
tags (list, None) – Any tags associated with the document (none by default)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The API response from the POST request for the document creation

Raises

TypeError, khorosjx.errors.exceptions.POSTRequestError

khorosjx.content.docs.delete_document(lookup_value, lookup_type='content_id', return_json=False)[source]¶

This function deletes a document.

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

Parameters

lookup_value (str, int) – THe value with which to identify the document.
lookup_type (str) – Identifies the value as a content_id (default), doc_id or url
return_json (bool) – Determines if the API response should be returned in JSON format (False by default)

Returns

The API response for the DELETE request

Raises

khorosjx.errors.exceptions.InvalidLookupTypeError

khorosjx.content.docs.get_content_id(lookup_value, lookup_type='url', verify_ssl=True)[source]¶

This function obtains the Content ID for a particular document.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

lookup_value (str) – The URL of the document
lookup_type (str) – The type of value is being used for lookup (url by default)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The Content ID for the document

Raises

ValueError, khorosjx.errors.exceptions.ContentNotFoundError, khorosjx.errors.exceptions.InvalidLookupTypeError

khorosjx.content.docs.get_document_attachments(lookup_value, lookup_type='doc_id', return_dataframe=False)[source]¶

This function retrieves information on any attachments associated with a document.

Parameters

lookup_value (str, int) – The value with which to look up the document
lookup_type (str) – Identifies the type of lookup value that has been provided (Default: doc_id)
return_dataframe (bool) – Determines whether or not a pandas dataframe should be returned

Returns

A list, dictionary or pandas dataframe depending on the number of attachments and/or function arguments

Raises

khorosjx.errors.exceptions.GETRequestError, khorosjx.errors.exceptions.InvalidDatasetError, khorosjx.errors.exceptions.InvalidLookupTypeError, khorosjx.errors.exceptions.LookupMismatchError

khorosjx.content.docs.get_document_info(lookup_value, lookup_type='doc_id', return_fields=None, ignore_exceptions=False, verify_ssl=True)[source]¶

This function obtains the group information for a given document.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

lookup_value (int, str) – The value with which to look up the document
lookup_type (str) – Identifies the type of lookup value that has been provided (Default: doc_id)
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

A dictionary with the group information

Raises

khorosjx.errors.exceptions.GETRequestError, khorosjx.errors.exceptions.InvalidDatasetError, khorosjx.errors.exceptions.InvalidLookupTypeError, khorosjx.errors.exceptions.LookupMismatchError

khorosjx.content.docs.get_url_for_id(doc_id)[source]¶

This function constructs a full URL for a given Document ID.

Parameters: doc_id (int, str) – The Document ID with which to construct the URL
Returns: The fully constructed URL for the document (e.g. https://community.example.com/docs/DOC-1234)
Raises: TypeError, ValueError

khorosjx.content.docs.overwrite_doc_body(url, body_html, minor_edit=True, ignore_exceptions=False, verify_ssl=True)[source]¶

This function overwrites the body of a document with new HTML content.

Changed in version 2.6.0: Added the verify_ssl argument.

Parameters

url (str) – THe URL of the document to be updated
body_html – The new HTML body to replace the existing document body
minor_edit (bool) – Determines whether the Minor Edit flag should be set (Default: True)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)
verify_ssl (bool) – Determines if API calls should verify SSL certificates (True by default)

Returns

The response of the PUT request used to update the document

Raises

khorosjx.errors.exceptions.ContentPublishError

khorosjx.content.docs.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.content.docs.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Events Module (khorosjx.content.events)¶

This module contains functions specific to handling events.

Module: khorosjx.content.events
Synopsis: Collection of functions relating to events (e.g. https://community.example.com/event/1234)
Usage: from khorosjx.content import events
Example: content_id = events.get_content_id(url)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.content.events.get_content_id(url)[source]¶

This function obtains the Content ID for a particular event.

Parameters: url (str) – The URL of the event
Returns: The Content ID for the event
Raises: ValueError

khorosjx.content.events.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.content.events.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Ideas Module (khorosjx.content.ideas)¶

This module contains functions specific to handling ideas.

Module: khorosjx.content.ideas
Synopsis: Collection of functions relating to ideas (e.g. https://community.example.com/idea/1234)
Usage: from khorosjx.content import ideas
Example: content_id = ideas.get_content_id(url)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.content.ideas.get_content_id(url)[source]¶

This function obtains the Content ID for a particular idea.

Parameters: url (str) – The URL of the idea
Returns: The Content ID for the idea
Raises: ValueError

khorosjx.content.ideas.get_ideas_for_space(browse_id, return_type='list', ignore_exceptions=False)[source]¶

This function retrieves ideas for a given space.

Parameters

browse_id (str, int) – The Browse ID of the space to be queried
return_type (str) – Determines if the data should be returned as a list (default) or a dataframe
ignore_exceptions (bool) – Determines if exceptions encountered should be ignored (False by default)

Returns

The ideas for the given space in a list or a pandas dataframe

khorosjx.content.ideas.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.content.ideas.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Threads Module (khorosjx.content.threads)¶

This module contains functions specific to handling community discussion and question threads.

Module: khorosjx.content.threads
Synopsis: Collection of functions relating to discussion and question threads
Usage: from khorosjx.content import threads
Example: content_id = threads.get_content_id(url)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.content.threads.get_content_id(url)[source]¶

This function obtains the Content ID for a particular discussion or question thread.

Parameters: url (str) – The URL of the thread
Returns: The Content ID for the thread
Raises: ValueError

khorosjx.content.threads.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.content.threads.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Videos Module (khorosjx.content.videos)¶

This module contains functions specific to handling videos.

Module: khorosjx.content.videos
Synopsis: Collection of functions relating to videos (e.g. https://community.example.com/videos/1234)
Usage: from khorosjx.content import videos
Example: content_id = videos.get_content_id(url)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.content.videos.check_if_embedded(lookup_value, lookup_type='content_id')[source]¶

This function checks to see if a native video is embedded in a document or just a standalone video.

Parameters

lookup_value (str, int) – The value with which to look up the video
lookup_type (str) – Defines if the lookup value is a content_id (default), video_id or url

Returns

A Boolean value indicating whether or not the video is embedded

Raises

khorosjx.errors.exceptions.InvalidLookupTypeError

khorosjx.content.videos.download_video(video_url, output_path, output_name='', default_type='mp4', verbose=False)[source]¶

This function downloads a video file when provided its URLs and an output name and location.

Parameters

video_url (str) – The direct download URL with its accompanying authorization token
output_path (str) – The full path to the directory where the video file should be downloaded
output_name (str) – The name of the output file (e.g. video.mp4)
default_type (str) – Defines a default file extension (mp4 by default) if an extension is not found
verbose (bool) – Determines if verbose console output should be displayed (False by default)

Returns

None

khorosjx.content.videos.find_video_attachments(document_attachments)[source]¶

This function identifies any attached videos in a collection of document attachments.

Parameters: document_attachments (list, dict) – Attachments associated with a document
Returns: A list of dictionaries containing info on any video attachments

khorosjx.content.videos.get_content_id(lookup_value, lookup_type='url')[source]¶

This function obtains the Content ID for a particular video.

Parameters

lookup_value (str, int) – The URL or Video ID associated with the video
lookup_type – Defines the type of value given to identify the video as url (default) or id

Returns

The Content ID for the video

Raises

ValueError, khorosjx.errors.exceptions.InvalidLookupTypeError

khorosjx.content.videos.get_native_videos_for_space(browse_id, return_fields=[], return_type='list', ignore_exceptions=False)[source]¶

This function returns information on all native (i.e. non-attachment and not third party) for a given space.

Parameters

browse_id (int, str) – The Browse ID associated with the space
return_fields (list) – Specific fields to return if not all of the default fields are needed (Optional)
return_type (str) – Determines if the data should be returned in a list or a pandas dataframe (Default: list)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A list of dictionaries or a dataframe containing information for each group

Raises

khorosjx.errors.exceptions.InvalidDatasetError

khorosjx.content.videos.get_video_dimensions(lookup_value, lookup_type='content_id')[source]¶

This function returns the dimensions of a given video.

Parameters

lookup_value (str, int) – The value with which to look up the video
lookup_type (str) – Defines if the lookup value is a content_id (default), video_id or url

Returns

The video dimensions in string format

Raises

khorosjx.errors.exceptions.InvalidLookupTypeError

khorosjx.content.videos.get_video_id(lookup_value, lookup_type='url')[source]¶

This function returns the video ID for a video when given its URL or a Content ID.

Parameters

lookup_value (str, int) – The URL or Content ID with which to identify the video
lookup_type (str) – Defines the type of value given to identify the video as url (default) or content_id

Returns

The Video ID for the video

Raises

khorosjx.errors.exceptions.InvalidLookupTypeError

khorosjx.content.videos.get_video_info(lookup_value, lookup_type='content_id')[source]¶

This function retrieves information about a given video in JSON format.

Parameters

lookup_value (str, int) – The value with which to look up the video
lookup_type (str) – Defines whether the lookup value is a content_id (default), video_id or url

Returns

The video information in JSON format

Raises

khorosjx.errors.exceptions.InvalidLookupTypeError

khorosjx.content.videos.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.content.videos.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Groups Module (khorosjx.groups)¶

This module contains functions for working with security groups (and eventually social groups) such as obtaining and managing group membership.

Module: khorosjx.groups
Synopsis: Collection of functions relating to security groups
Usage: from khorosjx import groups
Example: group_info = groups.get_group_info(1051)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.groups.add_user_to_group(group_id, user_value, lookup_type='id', return_mode='none', print_results=True, ignore_exceptions=True)[source]¶

This function adds a user to a security group.

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

Parameters

group_id (int, str) – The Group ID of the security group to which the user should be added
user_value (int, str) – The value with which to look up the user (e.g. User ID, email address)
lookup_type (str) – Defines whether the user value is a User ID or an email address (Default: id)
return_mode (str) – Determines what–if anything–should be returned by the function (Default: none)
print_results (bool) – Determines whether or not all results (including success messages) should be printed onscreen
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: True)

Returns

The resulting status code, a Boolean value indicating the success of the operation, or nothing

Raises

khorosjx.errors.exceptions.POSTRequestError

khorosjx.groups.check_user_membership(user_memberships, groups_to_check, scope='any', ignore_exceptions=False)[source]¶

This function checks if a user belongs to one or more security groups.

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

Parameters

user_memberships (list, tuple) – A list of security groups to which the user belongs
groups_to_check (list, tuple, str) – One or more groups (name or ID) against which to compare the user’s memberships
scope (str) – Determines the result returned for the comparison (Options: any, all or each)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

Returns a Boolean value for any and all scopes, or a list of Boolean values for each

Raises

khorosjx.errors.exceptions.InvalidScopeError

khorosjx.groups.get_all_groups(return_fields=None, return_type='list', ignore_exceptions=False)[source]¶

This function returns information on all security groups found within the environment.

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
return_type (str) – Determines if the data should be returned in a list or a pandas dataframe (Default: list)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A list of dictionaries or a dataframe containing information for each group

Raises

khorosjx.errors.exceptions.InvalidDatasetError

khorosjx.groups.get_group_info(group_id, return_fields=None, ignore_exceptions=False)[source]¶

This function obtains the group information for a given Group ID.

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

group_id (int,str) – The Group ID of the group whose information will be requested
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A dictionary with the group information

Raises

khorosjx.errors.exceptions.GETRequestError, khorosjx.errors.exceptions.InvalidDatasetError

khorosjx.groups.get_group_memberships(group_id, user_type='member', only_id=True, return_type='list', ignore_exceptions=False, quiet=False)[source]¶

This function gets the memberships (including administrator membership) for a specific security group.

Changed in version 2.5.3: Added the optional _quiet argument to silence missing API field errors.

Changed in version 2.5.1: The ?fields=@all query string was added to the API URI to ensure all fields are retrieved.

Parameters

group_id (int, str) – The Group ID for the security group
user_type (str) – Determines if the function should return admin or member users (Default: member)
only_id (bool) – Determines if only the User ID for the members should be returned or full data (Default: True)
return_type (str) – Determines if a list or dataframe should be returned (Default: list)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: True)
quiet (bool) – Silences any errors about being unable to locate API fields (False by default)

Returns

A list or dataframe of security group memberships

Raises

ValueError

khorosjx.groups.get_user_memberships(user_lookup, return_values='name', ignore_exceptions=False)[source]¶

This function returns the security group memberships for a given user.

Changed in version 3.1.0: Refactored the function to be more efficient.

Parameters

user_lookup (int,str) – A User ID or email address that can be used to identify the user
return_values (str) – The type of values that should be returned in the membership list (Default: name)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A list of group memberships for the user

Raises

khorosjx.errors.exceptions.UserQueryError

khorosjx.groups.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.groups.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

News Module (khorosjx.news)¶

This module contains functions for working with news streams, including publications and subscriptions.

Module: khorosjx.news
Synopsis: Collection of functions relating to security groups
Usage: from khorosjx import news
Example: all_publication = khorosjx.news.get_all_publications()
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.news.delete_publication(pub_id, return_json=False)[source]¶

This function deletes a publication when given its ID.

Parameters

pub_id (int, str) – The ID of the publication
return_json (bool) – Determines if the API response should be returned in JSON format (False by default)

Returns

The API response (optionally in JSON format)

khorosjx.news.delete_stream(stream_id, return_json=False)[source]¶

This function deletes a stream when given its ID.

Parameters

stream_id (int, str) – The ID of the stream
return_json (bool) – Determines if the API response should be returned in JSON format (False by default)

Returns

The API response (optionally in JSON format)

khorosjx.news.filter_subscriptions_by_id(sub_id, subscriptions)[source]¶

This function filters the returned IDs by a supplied subscription ID when applicable.

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

Parameters

sub_id (str) – The subscription ID to use as the filter
subscriptions (list) – A list of subscriptions

Returns

The subscription that has the supplied subscription ID

Raises

khorosjx.errors.exceptions.SubscriptionNotFoundError

khorosjx.news.get_all_publications(return_fields=None, return_type='list', ignore_exceptions=False)[source]¶

This function retrieves all publications within an environment.

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
return_type (str) – Determines if the data should be returned in a list or a pandas dataframe (Default: list)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A list of dictionaries or a dataframe containing information for each publication

Raises

khorosjx.errors.exceptions.InvalidDatasetError

khorosjx.news.get_publication(pub_id, return_fields=None, ignore_exceptions=False)[source]¶

This function retrieves the information on a single publication when supplied its ID.

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

pub_id (int, str) – The ID of the publication
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A dictionary with the data for the publication

Raises

khorosjx.errors.exceptions.InvalidDatasetError, khorosjx.errors.exceptions.GETRequestError

khorosjx.news.get_stream(stream_id, return_fields=None, ignore_exceptions=False)[source]¶

This function retrieves the information on a single publication when supplied its ID.

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

stream_id (int, str) – The ID of the stream to retrieve
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A dictionary with the data for the publication

Raises

khorosjx.errors.exceptions.InvalidDatasetError, khorosjx.errors.exceptions.GETRequestError

khorosjx.news.get_subscriber_groups(publication_id, subscription_id='', full_uri=False)[source]¶

This function identifies the subscriber groups for one or more subscriptions within a publication.

Changed in version 3.1.0: Refactored the function to be more efficient.

Parameters

publication_id (int, str) – The ID of the publication
subscription_id (int, str) – The specific subscription ID for which to return subscriber groups (Optional)
full_uri (bool) – Determines whether or not to return the full URI or just the Group ID (False by default)

Returns

A dictionary mapping the subscription IDs to the respective subscriber groups

Raises

khorosjx.errors.exceptions.SubscriptionNotFoundError

khorosjx.news.get_subscriber_ids(subscribers)[source]¶

This function pulls the subscriber IDs out of dictionaries and into a single list.

Parameters: subscribers (list) – A list of dictionaries containing subscriber information from which to extract the IDs
Returns: A list of IDs for the supplied subscribers

khorosjx.news.get_subscribers(publication_id, subscription_id, return_type='list', only_id=True, return_fields=None, ignore_exceptions=False)[source]¶

This function retrieves the individual subscribers (i.e. users) for a given subscription within a publication.

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

publication_id (int, str) – The ID of the publication where the subscription resides
subscription_id (int, str) – The ID of the subscription in which to identify the subscribers
return_type (str) – Determines whether the data should be returned as a list (default) or a pandas dataframe
only_id (bool) – Determines if only the ID of each user should be returned (default) or a dict with all user data
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A list or pandas dataframe with the subscriber information

khorosjx.news.get_subscription_data(pub_id)[source]¶

This function returns the subscription data for a given publication.

Parameters: pub_id (int, str) – The ID of the publication
Returns: A list of dictionaries containing the data for each subscription

khorosjx.news.get_subscription_ids(pub_id, return_type='str')[source]¶

This function compiles a list of subscription IDs for a given publication ID.

Parameters

pub_id (int, str) – The ID of the publication
return_type – Determines if the IDs should be returned in str (default) or int format

Returns

A list of subscription IDs

Raises

ValueError

khorosjx.news.rebuild_publication(publication_id)[source]¶

This function rebuilds a publication.

Parameters: publication_id (int, str) – The ID of the publication to be rebuilt
Returns: The response from the API PUT request
Raises: khorosjx.errors.exceptions.PUTRequestError

khorosjx.news.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.news.update_publication(publication_id, payload)[source]¶

This function updates a publication using the supplied JSON payload.

Parameters

publication_id (int, str) – The ID of the publication to be updated
payload (dict) – The JSON payload with which the publication will be updated

Returns

The response from the API PUT request

Raises

khorosjx.errors.exceptions.PUTRequestError

khorosjx.news.update_stream(stream_id, payload)[source]¶

This function updates a stream using the supplied JSON payload.

Parameters

stream_id (int, str) – The ID of the stream to be updated
payload (dict) – The JSON payload with which the stream will be updated

Returns

The response from the API PUT request

Raises

khorosjx.errors.exceptions.PUTRequestError

khorosjx.news.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Places Module (khorosjx.places)¶

This module contains sub-modules containing functions for working with containers known as places, which are identified as either spaces or blogs.

Package: khorosjx.places
Synopsis: This package includes custom exceptions and accompanying function
Usage: import khorosjx.places
Example: TBD
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 14 Jan 2020

Return to Top

Base Places Module (khorosjx.places.base)¶

This module contains core functions relating to places. (i.e. spaces and blogs)

Module: khorosjx.places.base
Synopsis: Collection of core functions relating to places (i.e. spaces and blogs)
Usage: import khorosjx.places.base as places_core
Example: place_info = khorosjx.spaces.core.get_place_info(browse_id)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.places.base.get_browse_id(container_id, return_type='str')[source]¶

This function retrieves the Browse ID (aka Place ID) for a place given its Container ID.

Parameters

container_id (int, str) – The Space ID for the space to query
return_type (str) – Determines whether to return the value as a str or an int (Default: str)

Returns

The Browse ID (aka Place ID) for the place

Raises

GETRequestError

khorosjx.places.base.get_place_id(container_id, return_type='str')[source]¶

This function retrieves the Place ID (aka Browse ID) for a place given its Container ID.

Changed in version 3.1.0: Made improvements to proactively avoid raising any NameError exceptions.

Parameters

container_id (int, str) – The Container ID for the space to query
return_type (str) – Determines whether to return the value as a str or an int (Default: str)

Returns

The Place ID (aka Browse ID) for the place

Raises

GETRequestError

khorosjx.places.base.get_place_info(place_id, return_fields=None, ignore_exceptions=False)[source]¶

This function obtains the place information for a given Place ID. (aka Browse ID)

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

place_id (int, str) – The Place ID (aka Browse ID) of the place whose information will be requested
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A dictionary with the place information

Raises

GETRequestError, InvalidDatasetError

khorosjx.places.base.get_places_list_from_file(full_path, file_type='csv', has_headers=True, id_column='', id_type='browse_id', excel_sheet_name='', filter_info=None)[source]¶

This function retrieves a list of place identifiers from a file.

Parameters

full_path (str) – The full path to the file to import
file_type – Defines if the file to be imported is a csv (Default), xlsx, xls or txt file.
has_headers (bool) – Defines if the import file uses column headers (True by default)
id_column (str) – Defines the column name (if applicable) which contains the place identifier (Null by default)
id_type (str) –
Defines if the ID type is a browse_id (Default) or container_id

Todo

Add functionality for this parameter within the function
excel_sheet_name (str) – The sheet name to retrieve if an Excel file is supplied (First sheet imported by default)
filter_info (dict, None) – Dictionary used to apply any filter to the imported data if necessary (Null by default)

Returns

A list of place identifiers

Raises

InvalidFileTypeError

khorosjx.places.base.get_uri_for_id(destination_id, browse_id=True)[source]¶

This function generates the full URI for a place given an identifier.

Parameters

destination_id (int, str) – A Jive ID or Place ID (aka Browse ID) for a place
browse_id (bool) – Defines whether or not the identifier provided is a Browse ID (True by default)

Returns

The full URI in string format

khorosjx.places.base.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

New in version 3.1.0.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.places.base.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Blogs Module (khorosjx.places.blogs)¶

This module contains functions for working with blogs (meaning the containers rather than the individual blog posts) such as identifying posts within a blog, etc.

Module: khorosjx.places.blogs
Synopsis: Collection of core places functions that are specific to blogs
Usage: import khorosjx.places.blogs
Example: blog_info = khorosjx.places.blogs.get_blog_info(browse_id)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.places.blogs.get_blog_info(place_id, return_fields=None, ignore_exceptions=False)[source]¶

This function obtains the blog information for a given Place ID. (aka Browse ID)

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

place_id (int, str) – The Place ID (aka Browse ID) of the blog whose information will be requested
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A dictionary with the blog information

Raises

GETRequestError, InvalidDatasetError

khorosjx.places.blogs.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

New in version 3.1.0.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.places.blogs.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Spaces Module (khorosjx.places.spaces)¶

This module contains functions for working with spaces, such as identifying content within spaces, space permissions, permitted content types, etc.

Module: khorosjx.places.spaces
Synopsis: Collection of core places functions that are specific to spaces
Usage: import khorosjx.places.spaces
Example: space_info = khorosjx.places.spaces.get_space_info(browse_id)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.places.spaces.get_permitted_content_types(id_value, id_type='browse_id', return_type='list')[source]¶

This function returns the permitted content types for a given space.

Parameters

id_value (int, str) – The space identifier as a Browse ID (default), Place ID or Container ID
id_type (str) – Determines if the id_value is a browse_id (Default), place_id or container_id
return_type (str) – Determines if the result should be returned in list (Default), tuple or str format

Returns

The permitted content types in list, tuple or string format

Raises

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

khorosjx.places.spaces.get_space_content_permissions(id_value, id_type='browse_id', return_type='list')[source]¶

This function returns all of the defined permissions (aka appliedEntitlements) for a specific space.

Parameters

id_value (int, str) – The space identifier as a Browse ID (default), Place ID or Space ID
id_type (str) – Determines if the id_value is a browse_id (Default), place_id or space_id
return_type (str) – Determines if the result should be returned as a list (Default) or pandas dataframe

Returns

The list or dataframe with the space permissions

Raises

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

khorosjx.places.spaces.get_space_info(place_id, return_fields=None, ignore_exceptions=False)[source]¶

This function obtains the space information for a given Place ID. (aka Browse ID)

Changed in version 3.1.0: Changed the default return_fields value to None and adjusted the function accordingly.

Parameters

place_id (int, str) – The Place ID (aka Browse ID) of the space whose information will be requested
return_fields (list, None) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A dictionary with the space information

Raises

khorosjx.errors.exceptions.GETRequestError, khorosjx.errors.exceptions.InvalidDatasetError

khorosjx.places.spaces.get_space_permissions(id_value, id_type='browse_id', return_type='list')[source]¶

This deprecated function returns all of the defined permissions (aka appliedEntitlements) for a space.

Deprecated since version 2.6.0: The function has been renamed to be khorosjx.places.spaces.get_space_content_permissions().

Parameters

id_value (int, str) – The space identifier as a Browse ID (default), Place ID or Space ID
id_type (str) – Determines if the id_value is a browse_id (Default), place_id or space_id
return_type (str) – Determines if the result should be returned as a list (Default) or pandas dataframe

Returns

The list or dataframe with the space permissions

Raises

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

khorosjx.places.spaces.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.places.spaces.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Spaces Module (khorosjx.spaces)¶

This module contains functions for working with spaces, such as identifying content within spaces, etc.

Module: khorosjx.spaces
Synopsis: Collection of deprecated functions relating to spaces/places
Usage: import khorosjx.spaces
Example: space_info = khorosjx.spaces.get_space_info(1234)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 24 Mar 2020

khorosjx.spaces.get_browse_id(space_id, return_type='str')[source]¶

This function retrieves the Browse ID (aka Place ID) for a space given its ID.

Deprecated since version 2.0.0: The khorosjx.places.spaces.get_browse_id() function should be used.

Parameters

space_id (int, str) – The Space ID for the space to query
return_type (str) – Determines whether to return the value as a str or an int (Default: str)

Returns

The Browse ID (aka Place ID) for the space

Raises

khorosjx.errors.exceptions.GETRequestError

khorosjx.spaces.get_permitted_content_types(id_value, id_type='browse_id', return_type='list')[source]¶

This function returns the permitted content types for a given space.

Deprecated since version 2.0.0: The khorosjx.places.spaces.get_permitted_content_types() function should be used.

Parameters

id_value (int, str) – The space identifier as a Browse ID (default), Place ID or Space ID
id_type (str) – Determines if the id_value is a browse_id (Default), place_id or space_id
return_type (str) – Determines if the result should be returned in list (Default), tuple or str format

Returns

The permitted content types in list, tuple or string format

Raises

khorosjx.errors.exceptions.SpaceNotFountError, khorosjx.errors.exceptions.GETRequestError

khorosjx.spaces.get_place_id(space_id, return_type='str')[source]¶

This function retrieves the Place ID (aka Browse ID) for a space given its ID.

Deprecated since version 2.0.0: The khorosjx.places.spaces.get_place_id() function should be used.

Parameters

space_id (int, str) – The Space ID for the space to query
return_type (str) – Determines whether to return the value as a str or an int (Default: str)

Returns

The Place ID (aka Browse ID) for the space

Raises

GETRequestError

khorosjx.spaces.get_space_info(place_id, return_fields=[], ignore_exceptions=False)[source]¶

This function obtains the space information for a given Space ID.

Deprecated since version 2.0.0: The khorosjx.places.spaces.get_space_info() function should be used.

Parameters

place_id (int, str) – The Place ID (aka Browse ID) of the space whose information will be requested
return_fields (list) – Specific fields to return if not all of the default fields are needed (Optional)
ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default: False)

Returns

A dictionary with the space information

Raises

khorosjx.errors.exceptions.GETRequestError, khorosjx.errors.exceptions.InvalidDatasetError

khorosjx.spaces.get_space_permissions(id_value, id_type='browse_id', return_type='list')[source]¶

This function returns all of the defined permissions for a specific space.

Deprecated since version 2.0.0: The khorosjx.places.spaces.get_space_permissions() function should be used.

Parameters

id_value (int, str) – The space identifier as a Browse ID (default), Place ID or Space ID
id_type (str) – Determines if the id_value is a browse_id (Default), place_id or space_id
return_type (str) – Determines if the result should be returned as a list (Default) or pandas dataframe

Returns

The list or dataframe with the space permissions

Raises

khorosjx.errors.exceptions.SpaceNotFountError, khorosjx.errors.exceptions.GETRequestError

khorosjx.spaces.get_spaces_list_from_file(full_path, file_type='csv', has_headers=True, id_column='', id_type='browse_id', excel_sheet_name='', filter_info={})[source]¶

This function retrieves a list of space identifiers from a file.

Deprecated since version 2.0.0: The khorosjx.places.base.get_places_list_from_file() function should be used.

Parameters

full_path (str) – The full path to the file to import
file_type – Defines if the file to be imported is a csv (Default), xlsx, xls or txt file.
has_headers (bool) – Defines if the import file uses column headers (True by default)
id_column (str) – Defines the column name (if applicable) which contains the space identifier (Null by default)
id_type (str) – Defines if the ID type is a browse_id (Default) or place_id (aka container_id)
excel_sheet_name (str) – The sheet name to retrieve if an Excel file is supplied (First sheet imported by default)
filter_info (dict) – Dictionary used to apply any filter to the imported data if necessary (Null by default)

Returns

A list of space identifiers

Raises

khorosjx.errors.exceptions.InvalidFileTypeError

Return to Top

Users Module (khorosjx.users)¶

This module contains functions for working with users, such as obtaining their account/profile information, getting a count of their created content, etc.

Module: khorosjx.users
Synopsis: Collection of functions relating to user accounts and profiles
Usage: import khorosjx
Example: user_info = khorosjx.users.get_people_followed(user_id)
Created By: Jeff Shurtliff
Last Modified: Jeff Shurtliff
Modified Date: 22 Sep 2021

khorosjx.users.get_json_field(json_data, field_names)[source]¶

This function retrieves a value for a specific field from the JSON data for a user.

Changed in version 3.1.0: Refactored the function to be more efficient.

Parameters

json_data (dict) – The JSON data from which the field value must be retrieved
field_names (tuple, list) – The field name along with any parent field paths

Returns

The value for the specific field in its original format

Raises

ValueError, TypeError, KeyError

khorosjx.users.get_people_followed(user_id, ignore_exceptions=False, return_type=<class 'list'>, start_index=0)[source]¶

This function returns a list of users followed by a particular user.

Parameters

user_id (int) – The User ID for the user against which to check
ignore_exceptions (bool) – Determines whether non-200 API responses should raise an exception (Default: False)
return_type (type) – Determines whether to return a comma-separated string, tuple or list (Default: list)
start_index (int) – The startIndex for the API call (Default: 0)

Returns

The User IDs of all people followed by the queried user

khorosjx.users.get_primary_email(lookup_value, lookup_type='id')[source]¶

This function obtains the primary email address for a user by looking up their User ID or username.

Changed in version 3.1.0: Updated the khorosjx.users._validate_lookup_type() function call to use the new function name.

Parameters

lookup_value (str) – The User ID or username for which to look up the user
lookup_type (str) – Determines if the User ID or username should be used to find the user (Default: id)

Returns

The primary email address for the user

Raises

khorosjx.errors.exceptions.InvalidLookupTypeError

khorosjx.users.get_profile_url(lookup_value, lookup_type='id')[source]¶

This function constructs the URL to a user’s profile.

Changed in version 3.1.0: Removed a hardcoded URL with the interpolated base_url variable.

Parameters

lookup_value (str) – The lookup value to locate the user
lookup_type (str) – Determines if the lookup value is a User ID, email address or username (Default: id)

Returns

The URL of the user’s profile

khorosjx.users.get_recent_logins(count=100, start_index=0)[source]¶

This function returns the most recent logins that have occurred in the environment.

Parameters

count – The maximum number of results to return in the given GET request (Default: 100)
start_index – The startIndex value in the GET request (Default: 0)

Returns

The login data in JSON format

Raises

khorosjx.errors.exceptions.UserQueryError

khorosjx.users.get_user_content_count(user_id, start_index=0)[source]¶

This function obtains the number of content items created by a particular user.

Changed in version 3.1.0: Updated the khorosjx.users._get_paginated_content_count() function call to use the new function name.

Parameters

user_id (int) – The User ID of the user
start_index (int) – The startIndex value in the REST API call (Default: 0)

Returns

The count of content found for the user in integer format

khorosjx.users.get_user_id(lookup_value, lookup_type='email')[source]¶

This function obtains the User ID for a user by querying the API against the user’s email address or username.

Changed in version 3.1.0: Updated the khorosjx.users._validate_lookup_type() function call to use the new function name.

Parameters

lookup_value (str) – Email address or username of the user
lookup_type (str) – Determines if the lookup value is an email or username (Default: email)

Returns

The User ID for the user

Raises

khorosjx.errors.exceptions.InvalidLookupTypeError, khorosjx.errors.exceptions.GETRequestError

khorosjx.users.get_username(lookup_value, lookup_type='id')[source]¶

This function obtains the username for a user by looking up their User ID or email address.

Changed in version 3.1.0: Updated the khorosjx.users._validate_lookup_type() function call to use the new function name.

Parameters

lookup_value (str) – The User ID or email address for which to look up the user
lookup_type (str) – Determines if the User ID or email address should be used to find the user (Default: id)

Returns

The username for the user

khorosjx.users.parse_user_fields(json_data)[source]¶

This function populates a dictionary with the user information retrieved from the API response.

Changed in version 3.1.0: Refactored the function to be more efficient.

Parameters: json_data (dict) – The user data retrieved from the API in JSON format
Returns: Dictionary of user information that has been validated and normalized

khorosjx.users.retrieve_connection_info()[source]¶

This function initializes and defines the global variables for the connection information.

Changed in version 3.1.0: Refactored the function to be more efficient.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

khorosjx.users.verify_core_connection()[source]¶

This function verifies that the core connection information (Base URL and API credentials) has been defined.

Changed in version 3.1.0: Refactored the function to be more pythonic and to avoid depending on a try/except block.

Returns: None
Raises: khorosjx.errors.exceptions.KhorosJXError, khorosjx.errors.exceptions.NoCredentialsError

Return to Top

Supporting Modules¶

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

Tools and Utilities
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)[source]¶

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=[])[source]¶

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)[source]¶

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)[source]¶

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)[source]¶: 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)[source]¶

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')[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

This function removes comment wrappers (i.e. ) 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)[source]¶

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=[])[source]¶

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)[source]¶

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)[source]¶

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[source]¶: This class is used to help parse values imported from a YAML configuration file.

khorosjx.utils.helper.import_yaml_file(file_path)[source]¶

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')[source]¶

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()[source]¶

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()[source]¶: This function imports the primary modules for the package and returns True when successful.

khorosjx.utils.tests.test_init_module.set_package_path()[source]¶: This function adds the high-level khorosjx directory to the sys.path list.

khorosjx.utils.tests.test_init_module.test_init_module()[source]¶: 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()[source]¶

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()[source]¶

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()[source]¶

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()[source]¶

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()[source]¶

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[source]¶: This class includes content-related lists, dictionaries and other utilities.

class khorosjx.utils.classes.FieldLists[source]¶: This class provides lists of JSON fields for various API data sets.

class khorosjx.utils.classes.Groups[source]¶: This class provides various mappings to security group-related information.

class khorosjx.utils.classes.Platform[source]¶: This class provides various mappings to Jive-related information such as environments, URLs, etc.

class khorosjx.utils.classes.TimeUtils[source]¶: This class contains dictionaries and other utilities to assist with time-related function calls.

class khorosjx.utils.classes.Users[source]¶

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

class UserJSON[source]¶: 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)[source]¶: 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)[source]¶: This exception is used when the supplied API credentials are incorrect.

exception khorosjx.errors.exceptions.ContentNotFoundError(*args, **kwargs)[source]¶: This exception is used when an API query for content returns a 404 status code.

exception khorosjx.errors.exceptions.ContentPublishError(*args, **kwargs)[source]¶: This exception is used when content is unable to publish successfully.

exception khorosjx.errors.exceptions.CredentialsUnpackingError(*args, **kwargs)[source]¶: This exception is used when the tuple containing API credentials cannot be unpacked.

exception khorosjx.errors.exceptions.CurrentlyUnsupportedError(*args, **kwargs)[source]¶: This exception is used when an operation is attempted that is not yet supported.

exception khorosjx.errors.exceptions.DatasetNotFoundError(*args, **kwargs)[source]¶: This exception is used when a dataset was not provided and/or cannot be found.

exception khorosjx.errors.exceptions.GETRequestError(*args, **kwargs)[source]¶: This exception is used for generic GET request errors when there isn’t a more specific exception.

exception khorosjx.errors.exceptions.HelperFunctionNotFoundError(*args, **kwargs)[source]¶: This exception is used when a function referenced in the helper config file does not exist.

exception khorosjx.errors.exceptions.IncompleteCredentialsError(*args, **kwargs)[source]¶: This exception is used when a tuple containing API credentials is missing a username or password.

exception khorosjx.errors.exceptions.InvalidDatasetError(*args, **kwargs)[source]¶: This exception is used when a supplied dataset is invalid.

exception khorosjx.errors.exceptions.InvalidEndpointError(*args, **kwargs)[source]¶: This exception is used when an invalid API endpoint / service is provided.

exception khorosjx.errors.exceptions.InvalidFileTypeError(*args, **kwargs)[source]¶: This exception is used when a supplied file type is invalid and cannot be used.

exception khorosjx.errors.exceptions.InvalidHelperArgumentsError(*args, **kwargs)[source]¶: THis exception is used when the helper function was supplied arguments instead of keyword arguments.

exception khorosjx.errors.exceptions.InvalidKhorosJXModuleError(*args, **kwargs)[source]¶: 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)[source]¶: This exception is used when an invalid API lookup type is provided.

exception khorosjx.errors.exceptions.InvalidRequestTypeError(*args, **kwargs)[source]¶: This exception is used when an invalid API request type is provided.

exception khorosjx.errors.exceptions.InvalidScopeError(*args, **kwargs)[source]¶: This exception is used when a supplied scope is invalid and cannot be found.

exception khorosjx.errors.exceptions.KhorosJXError[source]¶: This is the base class for Khoros JX exceptions.

exception khorosjx.errors.exceptions.LookupMismatchError(*args, **kwargs)[source]¶: This exception is used when an a lookup value doesn’t match the supplied lookup type.

exception khorosjx.errors.exceptions.MissingBaseUrlError(*args, **kwargs)[source]¶: This exception is used when a valid base URL has not been defined.

exception khorosjx.errors.exceptions.NoCredentialsError(*args, **kwargs)[source]¶: This exception is used when credentials weren’t found when utilizing the core functions.

exception khorosjx.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 khorosjx.errors.exceptions.POSTRequestError(*args, **kwargs)[source]¶: This exception is used for generic POST request errors when there isn’t a more specific exception.

exception khorosjx.errors.exceptions.PUTRequestError(*args, **kwargs)[source]¶: This exception is used for generic PUT request errors when there isn’t a more specific exception.

exception khorosjx.errors.exceptions.SpaceNotFoundError(*args, **kwargs)[source]¶: This exception is used when an API query for a space returns a 404 response.

exception khorosjx.errors.exceptions.SubscriptionNotFoundError(*args, **kwargs)[source]¶: This exception is used when a subscription referenced in a function does not exist.

exception khorosjx.errors.exceptions.UserNotFoundError(*args, **kwargs)[source]¶: This exception is used when an API query for a user returns a 404 status code.

exception khorosjx.errors.exceptions.UserQueryError(*args, **kwargs)[source]¶: This exception is used when an API query returns an unidentified non-200 response.

exception khorosjx.errors.exceptions.WrongCredentialTypeError(*args, **kwargs)[source]¶: 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)[source]¶: This function raises the InvalidLookupTypeError exception and provides a custom message.

khorosjx.errors.handlers.check_api_response(response, request_type='get', ignore_exceptions=False)[source]¶

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')[source]¶

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

Change Log¶

This page documents the additions, changes, fixes, deprecations and removals made in each release.

v3.2.0¶

Release Date: 2021-09-23

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.core.ensure_absolute_url() function.

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.errors.exceptions.MissingBaseUrlError exception class.

Changed¶

Primary Modules¶

Changes to the primary modules.

Added the return_url parameter to the khorosjx.core.set_base_url() function to determine if the base URL should be returned by the function.
The following functions were updated to leverage the khorosjx.core.ensure_absolute_url() function:
- khorosjx.core.get_request_with_retries()
- khorosjx.core._api_request_with_payload()
- khorosjx.core.post_request_with_retries()
- khorosjx.core.put_request_with_retries()
- khorosjx.core.delete()

v3.1.0¶

Release Date: 2021-09-22

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.places.base.retrieve_connection_info() function.
Added the khorosjx.places.blogs.retrieve_connection_info() function.

Changed¶

Primary Modules¶

Changes to the primary modules.

Refactored the following functions to be more pythonic and to avoid depending on a try/except block, and to define the related global variables at the module level:
Refactored the following functions to be more efficient and removed one of the exception references in the docstring:
Refactored the following functions to be more efficient:
Changed the default return_fields value to None and made related adjustments in the following functions:
Changed the default categories and tags values to None in the khorosjx.content.docs.create_document() and adjusted the function accordingly.
The name of the raised exception was added to the error message in the khorosjx.core._api_request_with_payload() function.
Renamed the khorosjx.users.__validate_lookup_type() function to be khorosjx.users._validate_lookup_type() instead. (Single underscore prefix)
Renamed the khorosjx.users.__get_paginated_content_count() function to be khorosjx.users._get_paginated_content_count() instead. (Single underscore prefix)
Renamed the khorosjx.users.__get_followed() function to be khorosjx.users._get_followed() instead. (Single underscore prefix)
Updated the khorosjx.users._validate_lookup_type() function call in the following functions to use the new function name:
Updated the khorosjx.users._get_paginated_content_count() function call in khorosjx.users.get_user_content_count() to use the new function name.
Added a TODO to rename the following functions:
- khorosjx.content.base.__convert_lookup_value()
- khorosjx.content.base.__trim_attachments_info()
- khorosjx.places.base.__verify_browse_id()

Supporting Modules¶

Changes to the supporting modules.

Moved the function khoros.errors.handlers._raise_exception_for_status_code() function out to the module level from within khoros.errors.handlers.check_api_response().

Fixed¶

Primary Modules¶

Fixes in the primary modules.

Fixed how the query_url variable is defined in the khorosjx.core.get_data() function to proactively avoid raising any NameError exceptions.
Adjusted a dictionary lookup in the following functions to proactively avoid raising a KeyError exception:
- khorosjx.groups._get_paginated_groups()
- khorosjx.content.docs.get_document_attachments()
Added parenthesis to the exception classes in the following functions:
- khorosjx.core.set_credentials()
- khorosjx.content.docs.delete_document()
- khorosjx.groups.check_user_membership()
- khorosjx.groups.add_user_to_group()
- khorosjx.news.filter_subscriptions_by_id()
- khorosjx.users._get_followed()
Refactored the khorosjx.core.get_base_url() function to properly utilize the base_url global variable.
Removed a hardcoded URL in the khorosjx.users.get_profile_url() with the interpolated base_url variable.
Made some minor syntax improvements in the khorosjx.content.base.get_content_id() function.
Made improvements to the khoros.places.base.get_place_id() function to proactively avoid raising any NameError exceptions.

Supporting Modules¶

Changes to the supporting modules.

Added parenthesis to the exception classes in the following functions:
- khorosjx.errors.handlers.check_json_for_error()

v3.0.0¶

Release Date: 2021-09-20

Added¶

General¶

Added the codeql-analysis.yml workflow.
Merged dependabot pull requests to mitigate security vulnerabilities with twine dependency packages.

Changed¶

General¶

Started over with the requirements.txt file and renamed the original file to be original-requirements.txt.
Added the install_requires configuration to the setup.py file.
Added Python version 3.9 to pythonpackage.yml.

Fixed¶

General¶

Fixed a minor grammatical error in the examples/khorosjx_helper.yml file.

v2.5.3¶

Release Date: 2020-05-01

Changed¶

Primary Modules¶

Changes to the primary modules.

Added the optional quiet argument to the khorosjx.core.get_fields_from_api_response() function which silences any errors for being unable to locate API fields.
Added the optional quiet argument to the khorosjx.core.get_paginated_results() function which silences any errors for being unable to locate API fields.
Added the optional quiet argument to the khorosjx.groups.get_group_memberships() function which silences any errors for being unable to locate API fields.
Added the optional quiet argument to the khorosjx.groups._add_paginated_members() function which silences any errors for being unable to locate API fields.
Removed the unnecessary variable definition of added_to_group within the khorosjx.groups.add_user_to_group() function.
Renamed the khorosjx.core.__get_filter_syntax() function to be khorosjx.core._get_filter_syntax() instead.
Renamed the khorosjx.core.__api_request_with_payload() function to be khorosjx.core._api_request_with_payload() instead.

Documentation¶

Changes to the documentation.

Added a docstring to the khorosjx.core._get_filter_syntax() function.

Fixed¶

Primary Modules¶

Fixes to the primary modules.

Changed the filter string emails.value to be email.value in the khorosjx.core.get_fields_from_api_response() function.

v2.5.2¶

Release Date: 2020-04-29

Fixed¶

Supporting Modules¶

Fixes to the supporting modules.

Fixed the khorosjx.utils.helper._convert_yaml_to_bool() function to only perform its operations if the passed value is not a Boolean value to prevent the following AttributeError exception from occurring: AttributeError: 'bool' object has no attribute 'lower'

v2.5.1¶

Release Date: 2020-04-29

Added¶

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.utils.core_utils.remove_comment_wrappers_from_html() function.

General¶

Added PyCharm Python Security Scanner to the pythonpackage.yml file.
Updated to bleach v3.1.4 as recommended by GitHub to include some security fixes.

Changed¶

Primary Modules¶

Changes to the primary modules.

Renamed the khorosjx.places.spaces.get_space_permissions() function to be khorosjx.places.spaces.get_space_content_permissions() instead and added a DeprecationWarning to the original.
Moved the khorosjx.places.spaces.__get_paginated_content_permissions() function from within the khorosjx.places.spaces.get_space_permissions() function to the module level.
Moved the khorosjx.places.spaces.verify_core_connection.__get_info() function to the module level as khorosjx.places.spaces.retrieve_connection_info().
Renamed the khorosjx.groups.__add_paginated_members() function to be khorosjx.groups._add_paginated_members() instead.
Renamed the khorosjx.groups.__get_paginated_groups() function to be khorosjx.groups._get_paginated_groups() instead.
Added the ?fields=@all query string to the API URI in the khorosjx.groups.get_group_members() function to ensure all fields are retrieved.

Supporting Modules¶

Changes to the supporting modules.

Replaced the yaml.load() function call with yaml.safe_load() in khoros.utils.helper.import_yaml_file() as it is a better security practice.
Renamed the khorosjx.utils.helper.__get_connection_info() function to be khorosjx.utils.helper._get_connection_info() instead.
Renamed the khorosjx.utils.helper.__get_credentials_from_module() function to be khorosjx.utils.helper._get_credentials_from_module() instead.
Renamed the khorosjx.utils.helper.__parse_function_arguments() function to be khorosjx.utils.helper._parse_function_arguments() instead.
Renamed the khorosjx.utils.helper.__get_console_color_settings() function to be khorosjx.utils.helper._get_console_color_settings() instead.
Renamed the khorosjx.utils.helper.__get_modules_to_import() function to be khorosjx.utils.helper._get_modules_to_import() instead.
Renamed the khorosjx.utils.helper.__convert_yaml_to_bool() function to be khorosjx.utils.helper._convert_yaml_to_bool() instead.

Fixed¶

Primary Modules¶

Fixes to the primary modules.

Added error handling to the khorosjx.core.get_fields_from_api_response() function to prevent it from failing with an IndexError exception.

Documentation¶

Fixes to the documentation.

Fixed a typo and added hyperlinks to raised exceptions in the khorosjx.places.spaces.get_permitted_content_types() function docstring.
Fixed a typo in the docstring for the khorosjx.news.filter_subscriptions_by_id() function.

v2.5.0¶

Release Date: 2020-03-25

Changed¶

Primary Modules¶

Changes to the primary modules.

Updated the khorosjx.core.get_request_with_retries() function to raise the custom khorosjx.errors.exceptions.APIConnectionError exception class rather than the built-in ConnectionError exception class.
Removed the import warnings line from the khorosjx.core module as it was not being used.
Moved the khorosjx.admin.verify_core_connection.get_info() function to the module level as khorosjx.admin.retrieve_connection_info().
Moved the khorosjx.content.base.verify_core_connection.get_info() function to the module level as khorosjx.content.base.retrieve_connection_info().
Moved the khorosjx.content.docs.verify_core_connection.get_info() function to the module level as khorosjx.content.docs.retrieve_connection_info().
Moved the khorosjx.content.docs.__perform_overwrite_operation() function to be at the module level instead of within the khorosjx.content.docs.overwrite_doc_body() function.
Moved the khorosjx.content.events.verify_core_connection.get_info() function to the module level as khorosjx.content.events.retrieve_connection_info().
Moved the khorosjx.content.ideas.verify_core_connection.get_info() function to the module level as khorosjx.content.ideas.retrieve_connection_info().
Moved the khorosjx.content.threads.verify_core_connection.get_info() function to the module level as khorosjx.content.threads.retrieve_connection_info().
Moved the khorosjx.content.videos.verify_core_connection.get_info() function to the module level as khorosjx.content.videos.retrieve_connection_info().
Moved the khorosjx.content.videos.__append_videos() function to be at the module level instead of within the khorosjx.content.videos.get_native_videos_for_space() function.
Moved the khorosjx.groups.verify_core_connection.get_info() function to the module level as khorosjx.groups.retrieve_connection_info().
Moved the khorosjx.groups.__add_paginated_members() function to be at the module level instead of within the khorosjx.groups.get_group_memberships() function.
Moved the khorosjx.groups.__get_paginated_groups() function to be at the module level instead of within the khorosjx.groups.get_all_groups() function.
Updated the khorosjx.groups.get_group_memberships() function to leverage the khorosjx.utils.df_utils.convert_dict_list_to_dataframe() function rather than the deprecated khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function.
Moved the khorosjx.news.verify_core_connection.get_info() function to the module level as khorosjx.news.retrieve_connection_info().
Moved the khorosjx.news.get_subscriber_groups.__filter_subscriptions_by_id() function to the module level as khorosjx.news.filter_subscriptions_by_id().
Moved the khorosjx.news.get_subscriber_groups.__get_subscriber_ids() function to the module level as khorosjx.news.get_subscriber_ids().
Moved the khorosjx.users.verify_core_connection.get_info() function to the module level as khorosjx.users.retrieve_connection_info().
Moved the khorosjx.users.get_user_content_count.__get_count() function to the module level as khorosjx.users.__get_paginated_content_count().

Documentation¶

Changes to the documentation.

Updated the exception class references within docstrings to be hyperlinks to the class details in these functions:

Fixed¶

Security¶

Fixes relating to security vulnerabilities.

Updated the version of the bleach package in requirements.txt to be 3.1.2 to mitigate an identified mutation XSS vulnerability that was reported by GitHub.

Documentation¶

Fixes to the documentation.

Corrected a typo in the docstring for the khorosjx.core.get_base_url() function.

v2.4.1¶

Release Date: 2020-03-23

Fixed¶

Primary Modules¶

Additions to the primary modules.

Added the verify_core_connection() function call to the khorosjx.content.base.__convert_lookup_value() function to resolve the NameError: name 'base_url' is not defined error.
Added missing docstrings to the khorosjx.content.ideas.get_ideas_for_space() function.

v2.4.0¶

Release Date: 2020-03-16

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.content.ideas.get_ideas_for_space() function.
Added the idea_fields list to the khorosjx.utils.classes.FieldLists class.
Added the khorosjx.utils.version.warn_when_not_latest() function call in the main khorosjx module.

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.utils.version.get_latest_stable() function.
Added the khorosjx.utils.version.latest_version() function.
Added the khorosjx.utils.version.warn_when_not_latest() function.

Changed¶

Primary Modules¶

Changes to the primary modules.

Introduced the all_fields argument into the khorosjx.content.base.get_paginated_content() function.
Updated the datasets dictionary in the khorosjx.utils.classes.Content class to include the idea key value pair.
Updated the khorosjx.groups.__get_paginated_groups() function to use the khorosjx.utils.df_utils.convert_dict_list_to_dataframe() function instead of the deprecated khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function.
Removed obsolete import re statement from the khorosjx.groups.__get_paginated_groups() function.

Fixed¶

Primary Modules¶

Fixes to the primary modules.

Fixed a minor syntax issue in the khorosjx.content.base.get_content_id() function.

Documentation¶

Changes to the documentation.

Fixed a typo in the README.md file.

v2.3.1¶

Release Date: 2020-02-24

Changed¶

General¶

Adjusted the python_requires value in setup.py to reject version 3.8.1 and above as the numpy and pandas packages do not currently support that version.
Upgraded the bleach package to version 3.1.1 to mitigate a security alert for a mutation XSS vulnerability and updated the requirements.txt file accordingly.

v2.3.0¶

Release Date: 2020-02-11

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.news module with the following functions:

Supporting Modules¶

Additions to the supporting modules.

Added the publication_fields, subscription_fields and stream_fields lists to the khorosjx.utils.classes.FieldLists class.
Added the khorosjx.errors.exceptions.SubscriptionNotFoundError exception class.

Changed¶

Primary Modules¶

Changes to the primary modules.

Added the khorosjx.news module to the __all__ special variable in the primary khorosjx module.
Updated the khorosjx.init_module() function to be compatible with the khorosjx.news module.
Updated the khorosjx.core.get_data() function to include the all_fields argument. (False by default)
Referenced the khorosjx.errors.exceptions.POSTRequestError exception class in the docstring for the khorosjx.core.post_request_with_retries() function.
Referenced the khorosjx.errors.exceptions.PUTRequestError exception class in the docstring for the khorosjx.core.put_request_with_retries() function.

Supporting Modules¶

Changes to the supporting modules.

Added a DeprecationWarning to the khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function.

Fixed¶

Primary Modules¶

Fixes to the primary modules.

Changed the json_payload type to dict in the docstring for the khorosjx.core.put_request_with_retries() and khorosjx.core.post_request_with_retries() functions.

Removed¶

General¶

Removed the MANIFEST.in file as the VERSION file is no longer used.

v2.2.0¶

Release Date: 2020-01-22

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.core.get_base_url() function.
Added the khorosjx.core.get_query_url() function.
Added the khorosjx.core.__get_filter_syntax() function.
Added the khorosjx.content.videos.get_video_id() function.
Added the khorosjx.content.videos.get_native_videos_for_space() function.
Added the khorosjx.content.videos.find_video_attachments() function.
Added the khorosjx.content.videos.__construct_url_from_id() function.
Added the khorosjx.content.videos.check_if_embedded() function.
Added the khorosjx.content.videos.get_video_dimensions() function.

Supporting Modules¶

Additions to the supporting modules.

Added the video_fields list to the khorosjx.utils.classes.FieldLists class.
Added the video key value pair to the datasets dictionary within the khorosjx.utils.classes.Content class.
Added the khorosjx.errors.handlers.bad_lookup_type() function.
Added the khorosjx.errors.exceptions.ContentNotFoundError exception.

Changed¶

General¶

Updated setup.py to define version in the setuptools.setup() function using the __version__ value from khorosjx.utils.version().

Primary Modules¶

Changes to the primary modules.

Updated the khorosjx.core.get_paginated_results() function to allow additional filters to be supplied as a tuple containing the element and criteria (e.g. ('type', 'video') or a list of tuples for multiple filters.
Made minor adjustment to the khorosjx.groups.get_all_groups() function.
Updated the khorosjx.content.videos.get_content_id() function to allow a URL or Video ID to be supplied.
Updated the khorosjx.content.base.get_content_id() function to raise the khorosjx.errors.exceptions.ContentNotFoundError exception instead of a generic KeyError exception.

v2.1.0¶

Release Date: 16 Jan 2020

Added¶

General¶

Added the __version__ global variable in the khorosjx (__init__.py) module.

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.core.delete() function.
Added the khorosjx.content.docs.create_document() function.
Added the khorosjx.content.docs.delete_document() function.
Added the khorosjx.places.base.get_uri_for_id() function.
Added the khorosjx.content.docs.get_url_for_id() function.

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.utils.helper.__get_modules_to_import() function.
Added the khorosjx.errors.exceptions.DatasetNotFoundError exception class.
Added the uri_dataset_mapping and security_group_uri_map dictionaries to the khorosjx.utils.classes.Content class.
Added the khorosjx.utils.core_utils.identify_dataset() function with the accompanying internal functions:
- khorosjx.utils.core_utils.__get_security_group_dataset()
- khorosjx.utils.core_utils.__get_invite_dataset()
- khorosjx.utils.core_utils.__get_metadata_dataset()
- khorosjx.utils.core_utils.__get_moderation_dataset()
- khorosjx.utils.core_utils.__get_search_dataset()
- khorosjx.utils.core_utils.__get_support_center_dataset()
- khorosjx.utils.core_utils.__get_tile_dataset()
Added the khorosjx.utils.version module containing the source __version__ and the following functions:
- khorosjx.utils.version.get_full_version()
- khorosjx.utils.version.get_major_minor_version()

Changed¶

General¶

Updated setup.py to obtain the version value from the khorosjx.utils.version() function.
Updated docs/conf.py to obtain the version value from the khorosjx.utils.version() function.

Primary Modules¶

Changes to the primary modules.

Updated the khorosjx.places module to proactively import the khorosjx.places.base, khorosjx.places.blogs and khorosjx.places.spaces modules.
Updated the khorosjx.content.docs.get_content_id() function to accept both URLs and Document IDs.
Updated the khorosjx.init_helper() function to handle the modules section of the YAML configuration file.
Added error handling for invalid file types in the khorosjx.init_helper() function.
Updated the khorosjx.init_module() function to properly handle the all string within an iterable.
Updated the khorosjx.core.get_fields_from_api_response() to reference the datasets dictionary that was moved into the khorosjx.utils.classes.Content class.

Supporting Modules¶

Changes to the supporting modules.

Updated the khorosjx.utils.helper.parse_helper_cfg() and khorosjx.utils.helper.retrieve_helper_settings() functions to leverage the khorosjx.utils.helper.__get_modules_to_import() function.
Added the accepted_import_modules and all_modules lists to the khorosjx.utils.helper.HelperParsing class.
Moved the datasets dictionary from the khorosjx.core.get_fields_from_api_response() function into the khorosjx.utils.classes.Content class.

Documentation¶

Changes to the documentation.

Adjusted the docstring for the khorosjx.errors.exceptions.InvalidDatasetError exception class to differentiate it from the khorosjx.errors.exceptions.DatasetNotFoundError exception class.

Examples¶

Changes to the example files found in the examples directory within the GitHub repository.

Added the modules section to the khorosjx_helper.yml file.

v2.0.0¶

Release Date: 8 Jan 2020

Added¶

Primary Modules¶

Additions to the primary modules.

Created the khorosjx.places module with the following sub-modules and functions:
Created the khorosjx.content module with the following sub-modules and functions:
Added the khorosjx.content.videos.download_video() function.

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.utils.core_utils.print_if_verbose() function.
Added the permitted_video_file_types list to the khorosjx.utils.classes.Content class.

Documentation¶

Additions to the documentation.

Added “Return to Top” hyperlinks on the primary modules, supporting modules and change log pages.
Added the khorosjx.utils.df_utils and khorosjx.errors modules to the supporting modules page.

Changed¶

General¶

Changed the Development Status PyPI classifier in the setup.py file to be 5 - Production/Stable.

Primary Modules¶

Changes to the primary modules.

Included the blog and place datasets in the dictionary within the khorosjx.core.get_fields_from_api_response() function.

Supporting Modules¶

Changes to the supporting modules.

Added df_utils and helper to __all__ in the khorosjx.utils module.

Documentation¶

Changes to the documentation.

Updated the Primary Modules page to show functions within the __init__.py files.
Added deprecated directives to docstrings of deprecated functions.
Adjusted the docstrings on the khorosjx.init_helper() function.
Restructured the table of contents at the top of the Supporting Modules page.
Updated the short-term and long-term items on the Roadmap page.

Fixed¶

Primary Modules¶

Fixes applied in the primary modules.

Fixed the try/except in the khorosjx.content.docs.get_document_attachments() function to account for both KeyError and IndexError exceptions instead of just the latter.

Supporting Modules¶

Fixes applied in the supporting modules.

Fixed the khorosjx.errors.handlers.check_api_response() function so that a 502 response code displays a simple Site Temporarily Unavailable error rather than displaying the entire raw HTML response from the API.

Documentation¶

Fixes applied to the documentation.

Fixed an issue with the header block docstring for the khorosjx.utils.classes module.

Deprecated¶

Primary Modules¶

Deprecations in the primary modules.

Deprecated and moved the functions below to the khorosjx/content/__init__.py file from the removed khorosjx/content.py file. (The deprecated functions will be removed in v3.0.0.)
- khorosjx.content.get_content_id()
- khorosjx.content.overwrite_doc_body()
- khorosjx.content.__convert_lookup_value()
- khorosjx.content.get_document_info()
- khorosjx.content.__trim_attachments_info()
- khorosjx.content.get_document_attachments()
Deprecated the khorosjx.spaces.get_space_info() function.
Deprecated the khorosjx.spaces.get_place_id() function.
Deprecated the khorosjx.spaces.get_browse_id() function.
Deprecated the khorosjx.spaces.__verify_browse_id() function.
Deprecated the khorosjx.spaces.get_spaces_list_from_file() function.
Deprecated the khorosjx.spaces.get_permitted_content_types() function.
Deprecated the khorosjx.spaces.get_space_permissions() function.
Deprecated the khorosjx.spaces.__get_unique_permission_fields() function.
Deprecated the khorosjx.spaces.__generate_permissions_dataframe() function.

Removed¶

Primary Modules¶

Removals in the primary modules.

The khorosjx.content module has been removed. (See the previous sections for additional context.)

Return to Top

v1.7.0¶

Release Date: 2019-12-21

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.spaces.get_spaces_list_from_file() function.

Supporting Modules¶

Additions to the supporting modules.

Added the new khorosjx.utils.df_utils module to house all pandas-related functions and utilities.
Added the khorosjx.utils.df_utils.convert_dict_list_to_dataframe() function. (Moved from the khorosjx.utils.core_utils module.)
Added the khorosjx.utils.df_utils.import_csv() function.
Added the khorosjx.utils.df_utils.import_excel() function.
Added the khorosjx.errors.exceptions.InvalidFileTypeError exception class.

Changed¶

Primary Modules¶

Changes to the primary modules.

Updated the khorosjx.core.get_fields_from_api_response() function to handle the resources.html.ref field.

Supporting Modules¶

Changes to the supporting modules.

Updated the khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function to leverage the khorosjx.utils.df_utils.convert_dict_list_to_dataframe() function in the new module.
Updated the place_fields list in the khorosjx.utils.classes.FieldLists class to include the resources.html.ref field.

Fixed¶

Primary Modules¶

Fixes in the primary modules.

Fixed a logic error in the khorosjx.core.get_fields_from_api_response() function which was preventing custom-curated fields for nested values from returning properly.

Deprecated¶

Supporting Modules¶

Deprecations in the supporting modules.

Deprecated the khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function as it now resides in the khorosjx.utils.df_utils.convert_dict_list_to_dataframe() function within the new module.

Return to Top

v1.6.0¶

Release Date: 2019-12-17

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.spaces.get_permitted_content_types() function.
Added the internal khorosjx.spaces._verify_browse_id() function.
Added the khorosjx.spaces.get_space_permissions() function.
Added the internal khorosjx.spaces.__get_unique_permission_fields() function.
Added the internal khorosjx.spaces.__generate_permissions_dataframe() function.

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.errors.handlers.check_json_for_error() function.
Added the khorosjx.errors.exceptions.NotFoundResponseError exception class.
Added the khorosjx.errors.exceptions.SpaceNotFoundError exception class.

Documentation¶

Addition to the documentation in this release.

Added a Roadmap page to list upcoming enhancements and changes.

Changed¶

Primary Modules¶

Changes to the primary modules.

Updated the khorosjx.init_module() function to allow the all string to be passed which imports all modules.

Supporting Modules¶

Changes to the supporting modules.

Added the optional column_names keyword argument in the khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function.

Documentation¶

Changes to the documentation in this release.

Changed the project name from KhorosJX to Khoros JX Python Library in the conf.py script.
Made adjustments to the toctree directives on the index page.
Changed the Latest Release badge in the README.md file to be labeled Latest Stable Release instead.

Fixed¶

Primary Modules¶

Fixes to the primary modules.

Removed helper from __all__ in the Init Module (khorosjx).
Fixed how to query URL was generated in the khorosjx.core.get_api_info() function.
Fixed a docstring error in the khorosjx.core.put_request_with_retries() function.
Fixed a minor docstring error in khorosjx.groups.add_user_to_group() function.
Fixed a docstring error in the khorosjx.users.get_people_followed() function.
Added the missing verify_core_connection() function call in khorosjx.users.get_recent_logins() function. (See Issue #1)

Supporting Modules¶

Fixes to the supporting modules.

Removed the **kwargs argument in the super() call within all custom exceptions.

Documentation¶

Fixes in the documentation in this release.

Fixed minor typos in the README.md file.
Fixed a minor typo in the khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function docstring.

Return to Top

v1.5.0¶

Release Date: 2019-12-05

Added¶

Primary Modules¶

Additions to the primary modules.

Added to the datasets dictionary and a “field not found” error message in the khorosjx.core.get_fields_from_api_response() function.
Added the khorosjx.content.get_document_info() function.
Added the khorosjx.content.get_document_attachments() function.
Added the internal khorosjx.content.__convert_lookup_value() function.
Added the internal khorosjx.content.__trim_attachments_info() function.
Added the khorosjx.spaces.get_space_info() function.
Added the khorosjx.spaces.get_place_id() and khorosjx.spaces.get_browse_id() functions.
Added the internal khorosjx.users.__validate_lookup_type() function.

Supporting Modules¶

Additions to the supporting modules.

Added the place_fields and document_fields lists to the khorosjx.utils.classes.FieldLists class.
Added the khorosjx.errors.exceptions.LookupMismatchError exception class.
Added the khorosjx.errors.exceptions.CurrentlyUnsupportedError exception class.

Documentation¶

Added the section on how to Obtain the primary email address within the Managing Users page now that the function is available.

Changed¶

Updated the khorosjx.users.get_user_id() and khorosjx.users.get_username() functions to leverage the internal khorosjx.users.__validate_lookup_type() function.
Updated the khorosjx.users.get_user_id() function to confirm that an email address was provided if the ‘email’ lookup type is supplied.
Updated the header block docstring at the top of the khorosjx.spaces() module.
Updated the header block docstring at the top of the khorosjx.errors.exceptions() module.

Fixed¶

Fixed a variable name error in the khorosjx.users.get_username() function.

Return to Top

v1.4.0¶

Release Date: 2019-11-30

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.core.get_paginated_results() function.
Added docstrings to the khorosjx.core.get_fields_from_api_response() function.
Added the khorosjx.groups.get_group_memberships() function.

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.utils.core_utils.add_to_master_list() function.
Added the khorosjx.utils.core_utils.convert_single_pair_dict_list() function.
Added docstrings to the khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function.
Added the new khorosjx.utils.classes.Groups class which contains the membership_types and user_type_mapping dictionaries.
Added the people_fields list to the khorosjx.utils.classes.FieldLists class.

Changed¶

Supporting Modules¶

Changes in the supporting modules.

Added a TODO note to move the khorosjx.utils.core_utils.eprint() function to the khorosjx.errors.handlers module.

Documentation¶

Changed the structure of the changelog to be more concise. (i.e. less sub-sections)

Developer Changes¶

Changed the Development Status classifier from Alpha to Beta in the setup.py file.

Removed¶

Primary Modules¶

Removals in the primary modules.

Removed the nested add_to_master_list() function from within the khorosjx.groups.get_all_groups() function.

Return to Top

v1.3.0¶

Release Date: 2019-11-27

Added¶

Primary Modules¶

Additions to the primary modules.

Added the init_helper() function to the Init Module (khorosjx) to initialize a helper configuration file.

Supporting Modules¶

Additions to the supporting modules.

Added the new Helper Module (khorosjx.utils.helper) which 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.
Added the khorosjx.errors.exceptions.InvalidHelperArgumentsError exception class.
Added the khorosjx.errors.exceptions.HelperFunctionNotFoundError exception class.

Examples¶

Added a new examples directory containing the khorosjx_helper.yml file which demonstrates how the helper configuration file should be formatted.

Documentation¶

Added the Using the Helper Utility page to address the new Helper Utility that was introduced.
Added the Helper Module (khorosjx.utils.helper) to the Supporting Modules page.
Added a “See Also” section mentioning the Helper Utility on the Core Functionality page.

Return to Top

v1.2.0¶

Release Date: 2019-11-24

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.core.__api_request_with_payload() function to leverage for both POST and PUT requests.
Added the khorosjx.core.post_request_with_retries() function for POST requests, which leverages the private function above.
Added the khorosjx.groups.add_user_to_group() function.
Added the khorosjx.groups.check_user_membership() function.

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.utils.core_utils.eprint() function to print error messages to stderr and onscreen.
Added the khorosjx.errors.exceptions.POSTRequestError, khorosjx.errors.exceptions.InvalidScopeError, khorosjx.errors.exceptions.InvalidLookupTypeError, khorosjx.errors.exceptions.InvalidEndpointError, khorosjx.errors.exceptions.InvalidRequestTypeError and khorosjx.errors.exceptions.APIConnectionError exception classes.

Documentation¶

Added the Core Functionality page with instructions on leveraging the core functionality of the library. (Page is still a work in progress)
Added the Managing Users page with instructions on managing users by leveraging the library. (Page is still a work in progress)
Added the Basic Usage page with the intent of inserting it into more than one page.

Changed¶

General¶

Updated the classifiers in setup.py to specifically reference Python 3.6, 3.7 and 3.8.

Primary Modules¶

Changes to existing functions in the primary modules.

Updated the khorosjx.core.get_data() function to accept username as an identifier for the people endpoint.
Updated the khorosjx.core.get_request_with_retries() function to include the return_json optional argument. (Disabled by default)
Refactored the khorosjx.core.put_request_with_retries() function to leverage the khorosjx.core.__api_request_with_payload() function.
Updated the khorosjx.users.get_user_id() function to accept a username as well as an email address.

Supporting Modules¶

Changes to existing functions in the supporting modules.

Expanded the functionality of the khorosjx.errors.handlers.check_api_response() function.

Documentation¶

Updated the Introduction page to insert the Basic Usage content.
Added the Basic Usage page with the intent of inserting it into more than one page.

Return to Top

v1.1.1¶

Release Date: 2019-11-23

Added¶

Added default messages to all of the exception classes in the Exceptions Module (khorosjx.errors.exceptions).
Added docstrings to the khorosjx.content.overwrite_doc_body() function.

Changed¶

Updated the build workflow (pythonpackage.yml) to also test Python 3.8 for compatibility.
Changed the structure of the change log to match the best practices from keepachangelog.com.
Made minor PEP8 compliance edits to the Classes Module (khorosjx.utils.classes).

Removed¶

The khorosjx.errors.raise_exceptions() function is no longer necessary as the exception classes now have default messages and it has been removed from the khorosjx.errors module (__init__.py) and the Handlers Module (khorosjx.errors.handlers).
Removed the khorosjx.errors.exceptions.ExceptionMapping and khorosjx.errors.exceptions.ExceptionGrouping classes as they are no longer used.

Return to Top

v1.1.0¶

Release Date: 2019-11-22

Added¶

Primary Modules¶

Additions to the primary modules.

Added the khorosjx.core.put_request_with_retries() function.
Added the ignore_exceptions parameter in the khorosjx.core.get_data() function and replaced the built-in ValueError exception with the custom khorosjx.errors.exceptions.GETRequestError exception class.
Added the khorosjx.core.get_fields_from_api_response() function.
Added the khorosjx.content.overwrite_doc_body() function.
Added the khorosjx.groups.get_user_memberships() function.
Added the khorosjx.groups.get_group_info() function.
Added the khorosjx.groups.get_all_groups() function.
Added the khorosjx.users.get_recent_logins() function.

Supporting Modules¶

Additions to the supporting modules.

Added the khorosjx.utils.core_utils.convert_dict_list_to_dataframe() function.
Added the khorosjx.errors.exceptions.ContentPublishError, khorosjx.errors.exceptions.BadCredentialsError, khorosjx.errors.exceptions.GETRequestError and khorosjx.errors.exceptions.PUTRequestError exception classes.
Added the new Handlers Module (khorosjx.errors.handlers) which includes a new khorosjx.errors.handlers.check_api_response() function.
Created the new Tests Module (khorosjx.utils.tests) for unit tests to leverage with pytest.

Changed¶

Updated the Supporting Modules documentation page to reference the new modules.
Reformatted the Change Log documentation page to follow the Sphinx Style Guide.

Deprecated¶

The raise_exception() function in the khorosjx.errors module now displays a DeprecationWarning as it has been moved into the new Handlers Module (khorosjx.errors.handlers).
Added a PendingDeprecationWarning warning on the khorosjx.errors.handlers.raise_exception() function as it will be deprecated in a future release. (See v1.1.1)

Fixed¶

Added the khorosjx.core.verify_connection() function call to the khorosjx.core.get_data() function.

Return to Top

v1.0.1.post1¶

Release Date: 2019-11-19

Changed¶

Created a new Introduction page with the existing home page content and added a Navigation (i.e. Table of Contents) to the home page.
Changed all auxilliary modules references to be supporting modules instead.
Added a Reporting Issues section to the Introduction page and to the README file.

Return to Top

v1.0.1¶

Release Date: 2019-11-19

Changed¶

Removed the version from the individual module header blocks as all will adhere to the primary versioning.

Fixed¶

Added missing from . import core in the khorosjx.admin, khorosjx.groups and khorosjx.spaces modules.

Return to Top

Roadmap¶

This page lists enhancements that are planned for upcoming releases in both the short-term and long-term.

Attention

The enhancements listed on this page are subject to change without notice.

Short-Term¶

The following list includes enhancements, changes and other items currently planned for short-term release.

Create the khorosjx.content.base.get_content_info() function.
Create the khorosjx.content.base.get_content_for_space() function.
Create the khorosjx.content.base.get_content_count_for_space() function.
Create the khorosjx.content.threads.get_attachments() function.

Long-Term¶

The following list includes enhancements, changes and other items currently planned for long-term release.

Support for OAuth authentication as opposed to only basic authentication.
Integrate the library with the standard logging package.