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
- 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
- Returns
None
- Raises
ModuleNotFoundError
,khorosjx.errors.exceptions.KhorosJXError
,khorosjx.errors.exceptions.InvalidKhorosJXModuleError
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
- 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.
- 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.
- 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.
- 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 anyNameError
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.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 toNone
and adjusted the function accordingly.Changed in version 2.6.0: Added conditional to ensure
quiet
isFalse
before calling thestderr
print statement.Changed in version 2.5.3: Fixed the
email.value
filter and added the optionalquiet
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.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 toNone
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.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
- 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
- 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
- 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
- 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
- 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
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
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
- Returns
The Content ID for the content URL
- Raises
- 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
- 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
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
- Returns
The Content ID for the content URL
- Raises
- 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 toNone
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
?
) excludingcount
andstartIndex
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 queryreturn_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
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
andtags
values toNone
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
- 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
- Returns
The API response for the DELETE request
- Raises
- 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
- 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
- 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
- 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.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
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
- 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
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
- 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
- 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
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
- 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
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
- Returns
A Boolean value indicating whether or not the video is embedded
- Raises
- 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 foundverbose (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.
- khorosjx.content.videos.get_content_id(lookup_value, lookup_type='url')[source]¶
This function obtains the Content ID for a particular video.
- Parameters
- 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.content.videos.get_video_dimensions(lookup_value, lookup_type='content_id')[source]¶
This function returns the dimensions of a given video.
- Parameters
- Returns
The video dimensions in string format
- Raises
- 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
- Returns
The Video ID for the video
- Raises
- 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
- Returns
The video information in JSON format
- Raises
- 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
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.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
oreach
)ignore_exceptions (bool) – Determines whether nor not exceptions should be ignored (Default:
False
)
- Returns
Returns a Boolean value for
any
andall
scopes, or a list of Boolean values foreach
- Raises
- 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 toNone
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.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 toNone
and adjusted the function accordingly.- Parameters
- 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
user_type (str) – Determines if the function should return
admin
ormember
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
ordataframe
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
- 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
- Returns
A list of group memberships for the user
- Raises
- 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
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.
- khorosjx.news.delete_stream(stream_id, return_json=False)[source]¶
This function deletes a stream when given its ID.
- 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
- Returns
The subscription that has the supplied subscription ID
- Raises
- 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 toNone
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.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 toNone
and adjusted the function accordingly.- Parameters
- 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 toNone
and adjusted the function accordingly.- Parameters
- 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
- Returns
A dictionary mapping the subscription IDs to the respective subscriber groups
- Raises
- 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 toNone
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 pandasdataframe
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.
- 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
- Returns
A list of subscription IDs
- Raises
- khorosjx.news.rebuild_publication(publication_id)[source]¶
This function rebuilds a publication.
- 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
- Returns
The response from the API PUT request
- Raises
- khorosjx.news.update_stream(stream_id, payload)[source]¶
This function updates a stream using the supplied JSON payload.
- Parameters
- Returns
The response from the API PUT request
- Raises
- 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
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
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.
- 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.
- 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 toNone
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
ortxt
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) orcontainer_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.
- 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
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 toNone
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
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
- 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
- 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 toNone
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
- 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
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
- Returns
The Browse ID (aka Place ID) for the space
- Raises
- 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
- 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.
- 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
- 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
ortxt
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) orplace_id
(akacontainer_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
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.
- 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
- Returns
The primary email address for the user
- Raises
- 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.
- 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.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.
- 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
- 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.
- 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