Primary Modules

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


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