Khoros Python Library Documentation

Khoros Python Library DocumentationRelease 4.5.0

Jeff Shurtliff

Apr 21, 2022

CONTENTS

1 Table of Contents 31.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Performing Community API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3 Working with Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.4 Working with Boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.5 Working with Group Hubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281.6 Managing Node Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341.7 Khoros Core Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391.8 Primary Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281.9 Supporting Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3261.10 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

2 Module Index and Search 429

Python Module Index 431

Index 433

i

ii

Khoros Python Library Documentation, Release 4.5.0

Welcome to the official documentation for the Python SDK for Khoros Communities.

CONTENTS 1

https://pypi.org/project/khoros


2 CONTENTS

CHAPTER

ONE

TABLE OF CONTENTS

1.1 Introduction

The khoros library acts as a Python software development kit (SDK) to administer and manage Khoros Communities(formerly Lithium) online community platforms.

• Installation

• Change Log

• Usage

– Importing the package

– Initializing a Khoros object instance

∗ Passing the information directly into the object

∗ Leveraging a “helper” configuration file

– Interacting with the Community APIs

• License

• Reporting Issues

• Roadmap

• Additional Resources

• Disclaimer

1.1.1 Installation

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

pip install khoros --upgrade

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

git clone git://github.com/jeffshurtliff/khoros.gitcd khoros/python3 setup.py install

Return to Top

3

https://khoros.com/platform/communities


1.1.2 Change Log

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

Return to Top

1.1.3 Usage

This section provides basic usage instructions for the package.

Return to Top

Importing the package

Rather than importing the base package, it is recommended that you import the primary khoros.Khoros class usingthe syntax below.

from khoros import Khoros

This recommendation is because the best practice is to use the name khoros when naming your object instance.

Return to Top

4 Chapter 1. Table of Contents


Initializing a Khoros object instance

The primary khoros.Khoros object serves many purposes, the most important being to establish a connection tothe Khoros Community environment with which you intend to interact. As such, when initializing an instance of thekhoros.Khoros object, you will need to pass it the community URL, the credentials it will use and related informationso that the connection can be established.

The khoros.Khoros object can be initiated in three different ways:

• Passing the information directly into the object

• Leveraging a “helper” configuration file

• Utilizing environment variables

Return to Top

Passing the information directly into the object

The community and connection information can be passed directly into the khoros.Khoros object when initializingit, as demonstrated in the example below.

khoros = Khoros(community_url='https://community.example.com',session_auth={'username': USERNAME, 'password': PASSWD}

)

Alternatively, configuration settings can be passed at once using the options argument in the khoros.Khoros class,as shown below.

my_settings = {'community_url': 'https://community.example.com','community_name': 'mycommunity','auth_type': 'session_auth','session_auth': {

'username': USERNAME,'password': PASSWD

}}

Return to Top

1.1. Introduction 5


Leveraging a “helper” configuration file

As an alternative to passing the connection information to the khoros.Khoros class in the ways demonstrated above,a “helper” configuration file in yaml or json format can be leveraged instead and passed to the khoros.Khoros classwhen initializing the object.

This is an example of how the configuration file would be written:

# Helper configuration file for the khoros package

# Define how to obtain the connection informationconnection:

community_url: https://community.example.com/tenant_id: example12345

# Define the default authentication type to usedefault_auth_type: session_auth

# Define the OAuth 2.0 credentialsoauth2:

client_id: FLFeNYob7XXXXXXXXXXXXXXXXXXXXZcWQEQHR5T6bo=client_secret: 1n0AIXXXXXXXXXXXXXXXXXXXX1udOtNaYnfJCeOszYw=redirect_url: http://redirect.community.example.com/getAccessToken

# Define the session key authorization informationsession_auth:

username: serviceaccountpassword: Ch@ng3ME!

# Define the preferred format for API responsesprefer_json: yes

# List the enabled discussion styles in the environment (blog, contest, forum, idea,␣→˓qanda, tkb)discussion_styles:

- blog- contest- forum- idea- qanda- tkb

The file can then be referenced using the helper argument when initializing the object instance, as shown below.

HELPER_FILE = "/path/to/helper.yml"khoros = Khoros(helper=HELPER_FILE)

Return to Top


https://en.wikipedia.org/wiki/YAML

https://en.wikipedia.org/wiki/JSON


Utilizing environment variables

This third method of initializing a Khoros object instance is definitely the easiest, as it allows you to call upon thekhoros.Khoros class without passing any arguments, as shown below.

from khoros import Khoroskhoros = Khoros()

This is accomplished by defining environment variables within your Operating System, either through the graphicalUI, the command-line or within the Python IDE using the os module and adding entries to the os.environ dictionary,as shown below.

import osos.environ['KHOROS_URL'] = 'https://community.example.com'

The environment variables leveraged in the khoros library are listed below.

Table 1: Khoros Environment VariablesEnvironment Variable Description ExampleKHOROS_URL The base URL of the environment https://community.example.

comKHOROS_TENANT_ID The Tenant ID associated with your

environmentabcde12345

KHOROS_DEFAULT_AUTH The default authentication method youwish to use

session_auth

KHOROS_OAUTH_ID The Client ID utilized by the OAuth2.0 authorization grant flow

FXXXXXXb7owXXXXXXo+jFlPXXXXXXjZcWQXXXXXX6bo=

KHOROS_OAUTH_SECRET The Client Secret utilized by theOAuth 2.0 authorization grant flow

1XXXXXX+/kZXXXXXXZZ9u1B5+1uXXXXXXfJCeOszYw=

KHOROS_OAUTH_REDIRECT_URLThe Redirect URL utilized by theOAuth 2.0 authorization grant flow

http://redirect.community.example.com/getAccessToken

KHOROS_SESSION_USER The username to use with Session Keyauthentication

apiuser

KHOROS_SESSION_PW The password to use with Session Keyauthentication

Ch@ng3M3!

KHOROS_PREFER_JSON Boolean string indicating if JSON re-sponses are preferred

True

KHOROS_LIQL_PRETTY Boolean string indicating if reader-friendly formatting should be used

False

KHOROS_LIQL_TRACK_LSI Boolean string indicating if queriesshould be captured in Community An-alytics search reports

False

KHOROS_LIQL_ALWAYS_OK Boolean string indicating if all re-sponses should return a 200 OK statuscode

False

KHOROS_TRANSLATE_ERRORSBoolean string indicating if errors inAPI responses should be made morerelevant where possible

True

If you are leveraging this library on a macOS or Linux operating system (e.g. Ubuntu Server) then you can simply addthe environment variables you wish to define to either the /etc/environment file if you wish to apply them to allusers, or to your user’s ~/.bashrc file for them to only apply to your user.

1.1. Introduction 7

https://www.techjunkie.com/environment-variables-windows-10/

https://www.techjunkie.com/environment-variables-windows-10/

https://docs.python.org/3/library/os.html#module-os

https://able.bio/rhett/how-to-set-and-get-environment-variables-in-python--274rgt5

https://developer.khoros.com/khoroscommunitydevdocs/docs/oauth-authorization-grant





https://developer.khoros.com/khoroscommunitydevdocs/docs/session-key

https://developer.khoros.com/khoroscommunitydevdocs/docs/session-key


# Define environment variables for KhorosKHOROS_URL='https://community.example.com'

Note: You will generally need to log out and log back in for the changes to take effect.

If you are leveraging this library on a Windows operating system (e.g. Windows 10) then you can add environmentvariables for your user via the Command Prompt (i.e. cmd.exe) or PowerShell.

Note: Using either of these two methods, you can add the environment variables using an interactive terminal windowor using a batch/script file. (Files should use the .bat or .cmd extension for the Command Prompt and .ps1 forPowerShell.)

Command Prompt

@echo offecho Defining the KHOROS_URL environment variable...setx KHOROS_URL https://community.example.comecho.

PowerShell

"Defining the KHOROS_URL environment variable..."[Environment]::SetEnvironmentVariable("KHOROS_URL", "https://community.example.com/",→˓"User")

Return to Top

Interacting with the Community APIs

Once the khoros.Khoros object instance has been initialized, it can be leveraged to interact with a Khoros Commu-nity environment in many ways, which will be fully documented shortly in the documentation. The example belowdemonstrates how a search can be performed using LiQL to return information from the environment in JSON format.

response_json = khoros.search(select_fields=('id', 'view_href'),from_source='messages',where_filter=('style', 'tkb'),order_by='last_post_time',limit=5

)

Return to Top


https://khoros.readthedocs.io/en/latest/

https://en.wikipedia.org/wiki/JSON


1.1.4 License

This package falls under the MIT License.

Return to Top

1.1.5 Reporting Issues

Issues can be reported within the GitHub repository.

Return to Top

1.1.6 Roadmap

Upcoming improvements to the library can be found in the following locations:

• 2020 Roadmap on GitHub

• 2021 Roadmap on GitHub

Return to Top

1.1.7 Additional Resources

Additional resources for leveraging the Community APIs can be found in the official Khoros Developer Documentation.

Return to Top

1.1. Introduction 9

https://github.com/jeffshurtliff/khoros/blob/master/LICENSE

https://github.com/jeffshurtliff/khoros/issues

https://github.com/jeffshurtliff/khoros/projects/1

https://github.com/jeffshurtliff/khoros/projects/2

https://developer.khoros.com/khoroscommunitydevdocs


1.1.8 Disclaimer

This package is considered unofficial and is in no way endorsed or supported by Khoros, LLC.

Return to Top

1.2 Performing Community API Calls

Warning: This page is still in progress and sections may be missing or unfinished.

Using the Khoros Python API to perform Community API calls is easier than doing so manually with the requestslibrary for several reasons, including:

• It is unnecessary to pass the entire URL as the base URL is stored in the khoros.core.Khoros object. Thismeans the relative URL passed in functions is generally the same that would be passed to the rest or restadminFreeMarker directives in components, macros or endpoints.

• The authorization token (e.g. li-api-session-key) is automatically included in the request header for all API calls.

• Errors and exceptions are more intuitive with Khoros-specific messages.

There are three types of API calls that can be made using the khoros.core.Khoros object:

• Community API v1 calls

• Community API v2 calls

• Generic API calls

Note: This guide assumes that the khoros.core.Khoros object has been instantiated with the khoros variablename, as illustrated in the snippet below.

>>> from khoros import Khoros>>> khoros = Khoros(helper='helper.yml')

1.2.1 Community API v1 calls

You can perform Khoros Community API v1 calls using the methods contained within the khoros.core.Khoros.V1class:

• Use the khoros.core.Khoros.V1.get() method to perform GET requests.

• Use the khoros.core.Khoros.V1.post() method to perform POST requests.

• Use the khoros.core.Khoros.V1.search() method to perform searches using the v1 API.


https://www.khoros.com

https://2.python-requests.org/en/master/

https://developer.khoros.com/khoroscommunitydevdocs/reference/rest

https://developer.khoros.com/khoroscommunitydevdocs/reference/restadmin

https://developer.khoros.com/khoroscommunitydevdocs/docs/getting-started-with-api-1


Performing a v1 GET request

When performing a GET request using the Community API v1, you can simply pass the relative URI of the endpointyou wish to query.

Although API v1 responses are in XML format by default, this library converts the responses to JSON format by default,converts the JSON string to a Python dictionary and prunes the response to the value you need so that it is not requiredto do so manually.

>>> khoros.v1.get('/users/online/count'){'response': {'status': 'success', 'value': {'type': 'int', '$': 544}}}

However, if you prefer to receive your responses in XML format, you need only pass the keyword argumentreturn_json=False in the method call. The response will be a requests.models.Response object and including .text will provide the actual XML response.

>>> response = khoros.v1.get('/users/online/count', return_json=False)>>> type(response)<class 'requests.models.Response'>>>> response<Response [200]>>>> response.text'<response status="success">\n <value type="int">551</value>\n</response>\n'

Return to Top

Performing a v1 POST request

Performing Community API v1 POST requests using the library are also very simple, requiring only a relative URIand a dictionary of query parameters and their respective values.

>>> khoros.v1.post('/users/id/216/profiles/name/signature/set',... {'value': 'Joe Customer, PMP '}){'response': {'status': 'success'}}

As with the GET requests, the response will be returned in JSON format by default unless the return_json=Falseargument is passed in the method.

>>> khoros.v1.post('/users/id/216/profiles/name/signature/set',... {'value': 'Joe Customer, PMP'}, return_json=False).text'<response status="success"/>\n'

Note: In order to avoid exceeding URI limits when passing large query parameters in a POST request, which wouldresult in responses with 413 or 414 status codes, by default the query parameters are passed as a URL-encoded stringin the message body rather than in the URI.

However, you can still pass the query parameters in the URI if desired by passing the keyword argumentparams_in_uri=True in the method.

Return to Top

1.2. Performing Community API Calls 11

https://2.python-requests.org/en/master/user/advanced/#id2


1.2.2 Community API v2 calls

The primary benefit introduced with the Khoros Community API v2 is the ability to leverage the Lithium Query Lan-guage (LiQL) to perform GET requests.

This Python library provides two options for performing LiQL queries. The first is to provide the full LiQL query as astring argument using the khoros.core.Khoros.query() method, and the second is to pass separate arguments forthe LiQL elements into the khoros.core.Khoros.search() method which constructs the LiQL query for you.

Using LiQL queries and the query method

If you are familiar and comfortable with the LiQL syntax then you may prefer to construct your own LiQL querieswhen performing v2 GET requests.

This can be done by leveraging the khoros.core.Khoros.query()method in the core object, as demonstrated below.

>>> query = "SELECT login FROM users WHERE id = '216'">>> khoros.query(query){'status': 'success', 'message': '', 'http_code': 200,'data': {'type': 'users', 'list_item_type': 'user', 'size': 1,'items': [{'type': 'user', 'login': 'joeCustomer'}]}, 'metadata': {}}

Because the Community API v2 returns data in JSON format by default, the same can be said for this library.

Return to Top

Passing search parameters to the search method

If you are not very comfortable with LiQL syntax (or just want an easy way to perform LiQL queries) then you can usethe khoros.core.Khoros.search()method to pass LiQL elements and allow the LiQL query to be constructed foryou behind-the-scenes.

The arguments that can be utilized in the method to construct the LiQL query are listed in the table below.

Argument Data Type(s) Descriptionselect_fields str, tuple, list, set One or more fields to be selected within the SELECT statement (e.g. id)from_source str The source of the data to use in the FROM statement (e.g. messages)where_filter str, tuple, list, dict,

setThe filters (if any) to use in the WHERE clause (e.g. id = '2')

order_by str, tuple, set, dict,list

The field(s) by which to order the response data (optional)

order_desc bool Defines if the ORDER BY directionality is DESC (default) or ASClimit int Allows an optional limit to be placed on the response items (ignored by

default)


https://developer.khoros.com/khoroscommunitydevdocs/docs/getting-started-with-community-api-2-1

https://developer.khoros.com/khoroscommunitydevdocs/docs/using-liql




In addition to the arguments above, you can also utilize the optional arguments below to further customize the requestand/or response.

Argument DataType(s)

Description

return_json bool Setting to False will return the requests.models.Response objectpretty_print bool Defines if the response should be “pretty printed” (False by default)track_in_lsi bool Defines if the query should be tracked within LSI, aka Khoros Community Ana-

lytics (False by default)always_ok bool Ensures that the API response always returns a 200 OK status code even when the

request fails (False by default)error_code str Allows an error code to optionally be supplied for testing purposes (ignored by

default)format_statementsbool Determines if statements (e.g. SELECT, FROM, et.) should be formatted to be in all

caps (True by default)

Note: These arguments above are also available in the khoros.core.Khoros.query() method.

To demonstrate how this method works, let us consider the LiQL query SELECT login FROM users WHERE id ='216' that was used in the example for the khoros.core.Khoros.query() method. The code snippet below showshow the same query could be performed using the khoros.core.Khoros.search() method.

>>> khoros.search('login', 'users', 'id = "216"'){'status': 'success', 'message': '', 'http_code': 200,'data': {'type': 'users', 'list_item_type': 'user', 'size': 1,'items': [{'type': 'user', 'login': 'joeCustomer'}]}, 'metadata': {}}

Return to Top

1.2.3 Generic API calls

If you need to perform a more generic API call (as opposed to an API call to the v1 or v2 Community API) for anyreason but which still includes the authorization header automatically, such as to query a custom endpoint, then youcan leverage the base methods below from the khoros.core.Khoros object.

• khoros.core.Khoros.get()

• khoros.core.Khoros.post()

• khoros.core.Khoros.put()

1.2. Performing Community API Calls 13



Performing a GET request

The method for making a generic GET request is similar to the khoros.core.Khoros.V1.get()method in structure,but with a few key differences:

• You have the ability to leverage an absolute or relative URI.

• Query parameters cannot be passed as a Python dictionary and must be included in the URI.

Note: This second item above may change in a future release.

Warning: Also similar to the v1 GET request method, the response attempts to return in JSON format by default.Therefore, if your custom endpoint (or wherever else is being queried) is not returning in JSON format then youwill need to ensure that the keyword argument return_json=False is passed when calling the method. This willresult in the method returning the response as a requests.models.Response object instead.

Below are some simple examples of how this method might be used.

>>> khoros.get('/plugins/custom/example/example/hello_world'){'response': 'Hello World!'}>>> khoros.get('/plugins/custom/example/example/say_hello?name=John',... return_json=False).text'Hello, John!'

Note: You may notice that relative URIs are expected by default. If you wish to supply an absolute URI then you willneed to pass the keyword argument relative_url=False when calling the method.

Return to Top

Performing a POST request

Todo: Coming soon!

Return to Top




Performing a PUT request

Todo: Coming soon!

Return to Top

1.3 Working with Messages

Caution: This page is currently a work-in-progress and is subject to change without warning.

This page provides instructions on how to create, update and perform other operations relating to messages.

• Introduction

• Prerequisites

• Creating new messages

1.3.1 Introduction

A message is arguably the most important object within a Khoros Community, as a message is the base object repre-senting all user-created assets (i.e. content) in the environment.

Messages represent multiple discussion styles (i.e. content types) depending on the board in which it is published,including:

• blog posts (aka blog articles)

• forum/discussion threads

• knowledge articles (aka TKB articles)

• contests

• ideas

• Q&A articles

This page explains how to work with message via the khoros Python library.

1.3. Working with Messages 15


1.3.2 Prerequisites

As with most other methods and functions, the core Khoros object must be instantiated so that it can be leveraged toperform the authenticated and authorized API calls.

Performing this task is covered in detail on the Introduction page, and is demonstrated briefly in the examples below.

Instantiation using environment variables

If you have defined environment variables for your Khoros Community environment on your system from which youare leveraging the library then it is very eaay to instantiate the core Khoros object as shown below.

from khoros import Khoroskhoros = Khoros()

Note: As mentioned on other pages, it is recommended that you use khoros as the identifier for the instantiated object.

Instantiation using a helper file

If environment variables are not configured, the next simplest option is to use a helper file as demonstrated below.

from khoros import Khoroskhoros = Khoros(helper='path/to/helper.yml')

Manual instantiation

In the absence of environment variables or a helper file, the core Khoros object can be instantiated manually using thekhoros.core.Khoros __init__ method arguments. This is illustrated in the sample code found on the Introductionpage.



1.3.3 Creating new messages

Creating new messages can be done using the khoros.core.Khoros.Message.create() method within the coreKhoros object, which can be called using the khoros.messsages.create` method, assuming ``khoros is thename of the instantiated core object per the recommended practice.

At a minimum, creating a new message requires the following elements:

• Subject (i.e. title)

• Destination (i.e. board in which it will be published)

Note: It is interesting to note that, unlike other community platforms (including Khoros JX), the content body is nota required field.

However, in the examples within this tutorial a message body will be provided to further clarify the process.

Defining the node

Todo: Coming Soon!

1.4 Working with Boards

Boards are the primary residence of all content in a Khoros Community environment, and they can be created, queried,manipulated and even deleted using the Khoros Community APIs.

This section addresses how the Khoros Community Python library leverages these APIs to harness these boards.

• Overview

• Creating a New Board

– Return Options

∗ Simple Boolean Response (Default)

∗ Full API Response

∗ Return the Board ID

∗ Return the Board URL

∗ Return the Board API URL

∗ Return the API response HTTP Code

∗ Return the API response status

∗ Return Any Error Messages

∗ Return Multiple Types

– Creating a New Forum

– Creating a New Blog

– Creating a New Tribal Knowledge Base (TKB)

1.4. Working with Boards 17

https://khorosjx.rtfd.io


– Creating a New Q&A Board

– Creating a New Idea Exchange

– Creating a New Contest

– Optional Configuration Items

∗ Adding a Description

∗ Defining the Parent Category

∗ Creating a Hidden Board

∗ Configuring Label Settings

• Retrieving a Board ID

1.4.1 Overview

All of the board-specific functions reside within the khoros.structures.boards module. However, they are alsofully integrated into the khoros.core.Khoros object by way of the khoros.core.Khoros.Board subclass and theassociated khoros.core.Khoros.boards object class.

After initializing the core object, the functions covered in the following sections can be leveraged for board-relatedoperations.

Caution: This tutorial assumes that the core object has been initialized as khoros per the naming convention bestpractices defined on the Introduction page.

Return to Top

1.4.2 Creating a New Board

A new board can be created using the boards.create() function via the initiated core object, as demonstrated below.

>>> khoros.boards.create('my-board', 'My Board', 'forum', return_status=True)'success'

The table below lists the arguments that can/must be used in the function, which leverages the khoros.structures.boards.create() function.

Argument Type Descriptionboard_id* string The board IDboard_title* string The board title/namediscussion_style* string The type of discussion style (e.g. blog, contest, forum, idea, qanda or tkb)description string The description of the boardparent_category_id string The ID of the parent category (if applicable)hidden boolean Defines whether or not the new board should be hidden from lists and menusallowed_labels string Type of labels permitted (freeform-only, predefined-only or freeform or pre-defined)use_freeform_labels boolean Indicates that only freeform labels should be permitted

continues on next page



Table 2 – continued from previous pageArgument Type Descriptionuse_predefined_labels boolean Indicates that only predefined labels should be permittedpredefined_labels list The list of predefined labels that are permittedmedia_type string The media type associated with a contest (image, video or story meaning text)blog_authors list The approved blog authors in a blog board as a list of user data dictionariesblog_author_ids list A list of User IDs representing the approved blog authors in a blog boardblog_author_logins list A list of logins (i.e. usernames) representing the approved blog authors in a blog boardblog_comments_enabled boolean Indicates that comments should be enabled on blog posts within a blog boardblog_moderators list The designated moderators in a blog board as a list of user data dictionariesblog_moderator_ids list A list of User IDs representing the blog moderators in a blog boardblog_moderator_logins list A list of logins (i.e. usernames) representing the moderators in a blog boardone_entry_per_contest boolean Indicates whether or not a user can only submit one entry to a single contestone_kudo_per_contest boolean Indicates whether or not a user can vote only once per contestposting_date_end datetime The date/time a contest is closed to submissionsposting_date_start datetime The date/time when the submission period for a contest beginsvoting_date_end datetime The date/time when the voting period for a contest endsvoting_date_start datetime The date/time when the voting period for a contest beginswinner_announced_date datetime The date/time the contest winner will be announcedfull_response boolean Indicates whether the full, raw API response should be returnedreturn_id boolean Indicates whether the Board ID should be returnedreturn_url boolean Indicates whether the Board URL should be returnedreturn_api_url boolean Indicates whether the API URL (i.e. URI) of the board should be returnedreturn_http_code boolean Indicates whether the HTTP Code of the API response should be returnedreturn_status boolean Indicates whether the status of the API response should be returnedreturn_error_messages boolean Indicates whether the Developer Response Message (if any) should be returned

Note: The fields labeled with an asterisk (*) are required.

Return to Top

Return Options

There are multiple ways to return data when creating a board, which can be explicitly defined using one or more of thefollowing function arguments:

• full_response

• return_id

• return_url

• return_api_url

• return_http_code

• return_status

• return_error_messages

These arguments are explained in more detail within the sub-sections below.

Return to Top



Simple Boolean Response (Default)

Unless explicitly defined, the function will return a simple Boolean response (i.e. True or False) indicating whetheror not the operation was successful.

>>> def create_and_check():... successful = khoros.boards.create('my-new-forum', 'My New Forum', 'forum')... result = "It worked!" if successful else "It failed!"... print(result)...

>>> create_and_check()'It worked!'

Return to Top

Full API Response

If you’d rather return the full, raw response from the API request in order to parse it later at your convenience, then thiscan be done by setting the full_response argument to True in the function call as shown below.

>>> response = khoros.boards.create('my-new-forum', 'My New Forum', 'forum', full_→˓response=True)>>> if response.status_code != 404:... response = response.json()... print(response['status'])'success'

Return to Top

Return the Board ID

If it makes sense for you to return the ID of the board you just created then you can do so by defining the return_idargument as True as seen below.

>>> forums_to_create = [('first-board', 'My First Board'), ('second-board', 'My Second␣→˓Board')]>>> for forum in forums_to_create:... board_id, board_title = forum... forum_id = khoros.boards.create(board_id, board_title, 'forum', return_id=True)... print("Forum Created:", forum_id)

(continues on next page)



(continued from previous page)

'Forum Created: first-board''Forum Created: second-board'

Return to Top

Return the Board URL

Very likely the most popular return option for this function, defining the return_url argument as True will returnthe URL of the newly created board, as shown below.

>>> khoros.boards.create('python-lovers', 'The Python Lovers Blog', \... 'blog', return_url=True)'https://stage.example.com/t5/The-Python-Lovers-Blog/bg-p/python-lovers'

Return to Top

Return the Board API URL

If additional API calls will be immediately performed following the creation of a board, it may be useful to return theAPI URL (i.e. URI) for the new board by defining the return_api_url argument as True, as shown below.

>>> khoros.boards.create('python-lovers', 'The Python Lovers Blog', \... 'blog', return_api_url=True)'/boards/python-lovers'

Return to Top

Return the API Response HTTP Code

Another potentially useful return option is to define the return_http_code argument as True, which will return theHTTP status code for the API response, as demonstrated below.

>>> khoros.boards.create('python-lovers', 'The Python Lovers Blog', \... 'blog', return_http_code=True)200

Return to Top


https://en.wikipedia.org/wiki/List_of_HTTP_status_codes


Return the API Response Status

Alternatively, it is possible to return the status of the API response (as defined by Khoros in the JSON response) bydefining the return_status argument as True, as shown below.

>>> khoros.boards.create('my-first-blog', 'My First Blog', 'blog', \... return_status=True)'success'

>>> khoros.boards.create('my-first-blog', 'My First Blog', 'blog', \... return_status=True)'error'

Return to Top

Return Any Error Messages

If you want to ensure that you see any error messages when applicable but don’t want to return the full API response,you can define the return_error_messages argument as True, as shown below.

>>> khoros.boards.create('my-first-blog', 'My First Blog', \... 'blog', return_error_messages=True)"An object of type blog-board already exists with the 'id' property value 'my-first-blog'→˓"

This argument captures both the message value and the occasionally populated developer_message value. If oneof the values is blank or if they are exactly the same, such as in the example above, then only one of the values willbe displayed. Otherwise, if both values are defined and do not match then they will be returned in the {message} -{developer_message} format. (i.e. The two values will be separated by spaces and a hyphen.)

If you wish to return both fields regardless of their values then you can define the optional split_errors argumentas True as well to return a tuple containing both values, as shown below.

>>> khoros.boards.create('my-first-blog', 'My First Blog', 'blog', \... return_error_messages=True, split_errors=True)("An object of type blog-board already exists with the 'id' property value 'my-first-blog→˓'", "An object of type blog-board already exists with the 'id' property value 'my-→˓first-blog'")

Return to Top



Return Multiple Types

You are not restricted to choosing only one of the return options. You can enable as many options as needed and ifmultiple types are detected by the function then they will be returned as a tuple with those values, as demonstrated inthe example below.

>>> response = khoros.boards.create('my-first-blog', 'My First Blog', 'blog', \... return_http_code=True, return_status=True, return_error_messages=True)

>>> if response[1] == 'success':... print(f"The board creation was successful with the HTTP code {response[0]}.")... else:... print(f"The board creation failed with the following error:\n{response[2]}")...The board creation failed with the following error:An object of type blog-board already exists with the 'id' property value 'my-first-blog'

Note: The tuple will return the values in the order they are listed as function arguments.

Return to Top

Creating a New Forum

To create a new forum, it is necessary to set the discussion_style argument equal to forum when calling theboards.create() function. All other arguments, with the exception of the board_id and board_title arguments,are optional.

>>> khoros.boards.create('my-new-forum', 'My New Forum', 'forum')

Return to Top

Creating a New Blog

To create a new forum, it is necessary to set the discussion_style argument equal to blogwhen calling the boards.create() function, in addition to defining the board_id and board_title.

Blog boards also have the option of explicitly defining approved blog authors and/or designated blog moderators at thetime of the board creation. The easiest way of doing this is by supplying a list of User IDs (via the blog_author_idsand blog_moderator_ids arguments) or by supplying a list of logins (i.e. usernames) via the blog_author_loginsand blog_moderator_logins arguments. These options are demonstrated below.

This example shows how to define authors and moderators using the User ID values.



>>> authors = ['23', '44', '67']>>> mods = ['5', '19']>>> board_id, board_title, discussion_style = 'my-first-blog', 'My First Blog', 'blog'>>> khoros.boards.create(board_id, board_title, discussion_style, \

blog_author_ids=authors, blog_moderator_ids=mods)

This example shows how to define authors and moderators using the user login values.

>>> authors = ['Ron Weasley', 'Neville Longbottom']>>> mods = ['Hermione Granger']>>> board_id, board_title, discussion_style = 'my-first-blog', 'My First Blog', 'blog'>>> khoros.boards.create(board_id, board_title, discussion_style, \... blog_author_logins=authors, blog_moderator_logins=mods)

Alternatively, if you happen to already have the fully formatted authors and moderators fields for the API request,which would be a list of dictionaries containing user data, then they can be used instead via the blog_authors andblog_moderators function arguments, as demonstrated below.

>>> authors = [{"id": "45"}, {"id": "57"}]>>> mods = [{"id": "12"}]>>> board_id, board_title, discussion_style = 'my-first-blog', 'My First Blog', 'blog'>>> khoros.boards.create(board_id, board_title, discussion_style, \... blog_authors=authors, blog_moderators=mods)

Return to Top

Creating a New Tribal Knowledge Base (TKB)

Creating a new Tribal Knowledge Base, or TKB, is very similar to creating a forum, except that the discussion_styleargument will be defined as tkb as shown in the example below.

>>> khoros.boards.create('product-knowledge-base', 'Product Knowledge Base', \... 'tkb', return_status=True)'success'

Return to Top



Creating a New Q&A Board

Creating a new Q&A board is also similar to creatinga forum, except that the discussion_style argument will bedefined as qanda sa shown below.

>>> khoros.boards.create('product-questions', 'Product Questions', \... 'qanda', return_status=True)'success'

Return to Top

Creating a New Idea Exchange

Idea Exchange boards (used for ideation) can be created by defining the discussion_style argument as idea, asshown below.

>>> khoros.boards.create('product-idea-exchange', 'Product Idea Exchange', \... 'idea', one_entry_per_contest=False, \... one_kudo_per_contest=True, return_status=True)'success'

Return to Top

Creating a New Contest

Contest boards can be created by defining the discussion_style argument as contest. Contests also have severalunique optional arguments that can be used, which are listed in the table earlier in this tutorial and again below.

Argument Type Descriptionmedia_type string The media type associated with a contest (image, video or story meaning

text)one_entry_per_contest boolean Indicates whether or not a user can only submit one entry to a single contestone_kudo_per_contest boolean Indicates whether or not a user can vote only once per contestposting_date_end date-

timeThe date/time a contest is closed to submissions

posting_date_start date-time

The date/time when the submission period for a contest begins

voting_date_end date-time

The date/time when the voting period for a contest ends

voting_date_start date-time

The date/time when the voting period for a contest begins

win-ner_announced_date

date-time

The date/time the contest winner will be announced

A function call using some of these arguments is shown below.


https://community.khoros.com/t5/Ideas/Fostering-a-flourishing-ideation-process/ta-p/404636


>>> khoros.boards.create('product-innovation-contest', 'Product Innovation Contest', \... 'contest', one_entry_per_contest=False, \... one_kudo_per_contest=True, media_type='story', return_→˓status=True)'success'

Return to Top

Optional Configuration Items

There are several other optional arguments that may also be passed in the function call to define other elements of thenew board, which are addressed in the sub-sections below.

Return to Top

Adding a Description

As it is an SEO best practice to include a description when creating a new board, it is recommended that you de-fine the optional description argument whenever using the khoros.structures.boards.create() function, asdemonstrated below.

>>> khoros.boards.create('upcoming-events', 'Upcoming Events', 'blog', \... 'Get the details on our upcoming events and product releases.')True

Note: As the description argument immediately follows the three required arguments in the function call, it is notnecessary to define it using a keyword argument. (e.g. description='Get the details...')

Return to Top

Defining the Parent Category

By default, a new board will be created at the top-most level of the community environment. However, if you intendto create the board below a specific category then this can easily be done by supplying the ID of said category via theparent_category_id argument, as demonstrated below.

>>> khoros.boards.create('upcoming-events', 'Upcoming Events', 'blog', \... 'Get the details on our upcoming events and product releases.',␣→˓\





... parent_category_id='products')True

Return to Top

Creating a Hidden Board

If you do not want your new board to appear in lists or menus then you can flag it as a “hidden” board by defining thehidden argument as True in the function call, as shown below.

>>> khoros.boards.create('tkb-archive', 'Archived TKB Articles', 'tkb', hidden=True)True

Return to Top

Configuring Label Settings

While creating a board, you can configure the label settings up front via the function call if desired, rather than config-uring them later in the Community Admin UI or via separate API requests.

The first setting you can configure is whether or not the board will allow freeform labels (i.e. where users can createtheir own labels), predefined labels (i.e. where community managers define the labels and users can only select them)or both.

There are two ways to do this:

• The first method is to define the allowed_labels argument as either freeform-only, predefined-only orfreeform or pre-defined.

>>> khoros.boards.create('product-discussions', 'Product Discussions', 'forum', \... allowed_labels='freeform-only')True

• The second method is to define the Boolean arguments use_freeform_labels and/oruse_predefined_labels as True.

>>> khoros.boards.create('product-discussions', 'Product Discussions', 'forum', \... use_freeform_labels=True)True

Note: Defining both use_freeform_labels and use_predefined_labels as True is the equivalent of definingthe allowed_labels argument as freeform or pre-defined.

Return to Top



1.4.3 Retrieving a Board ID

The majority of Khoros Community API calls–and therefore the majority of functions and methods in this li-brary–relating to boards require a board ID to be provided. As such, it will often be necessary for you to quicklyretrieve a board ID, which is easy to do via the khoros.core.Khoros.Board.get_board_id() function.

This function requires only the URL of the board and can be called from within the core object (i.e. khoros.core.Khoros) using the khoros.core.Khoros.boards.get_board_id() method call as demonstrated below.

>>> from khoros import Khoros>>> khoros = Khoros(helper='~/helper.yml')>>> khoros.boards.get_board_id('https://community.example.com/t5/example-board/tkb-p/→˓example-board')'example-board'

>>>

Note: This function will work with boards for all discussion styles.

The retrieved board ID can then be used in other functions and methods to perform any necessary tasks.

1.5 Working with Group Hubs

Group Hubs are nodes with unique capabilities that can be leveraged in ways unlike any other board within the KhorosCommunity platform. This section addresses how the Khoros Community Python library leverages the API to harnessthese nodes.

• Overview

• Creating a New Group Hub

– Return Options

∗ Simple Boolean Response (Default)

∗ Full API Response

∗ Return the ID

∗ Return the URL

∗ Return the API URL

∗ Return the API Response HTTP Code

∗ Return the API Response Status

∗ Return Any Error Messages

∗ Return Multiple Types

– Defining the ID and Title



1.5.1 Overview

Group Hubs are one of the newer features (as of May 2020) in the Khoros Community platform, with their generalavailability and Khoros Community API v2 support for them having been introduced as part of the Khoros Communities20.1 Release in January 2020.

This node, which behaves in similar ways to a Facebook group, has a few key differences compared to other boards,including the following:

• Group hubs can include any discussion type

• Group hubs can be Open, Closed or Hidden• Users can be granted the ability to create their own groups if desired

1.5.2 Creating a New Group Hub

Creating a new Group Hub is similar to creating a new board except with fewer configuration options during the actualcreation. For example, you are not able to specify in the API request to create a group hub who its members should be,how labels should be leveraged, who its moderators will be, etc. However, you will be able to define the following:

• Node ID *

• Title *

• Description

• Membership Type*

• Discussion Styles

• Parent Category ID

• Avatar Image

Note: The fields labeled with an asterisk (*) are required.

Return to Top

Return Options

There are multiple ways to return data when creating a group hub, which can be explicitly defined using one or moreof the following function arguments:

• full_response

• return_id

• return_url

• return_api_url

• return_http_code

• return_status

• return_error_messages

1.5. Working with Group Hubs 29

https://community.khoros.com/t5/Khoros-Community-Release-Notes/Khoros-Communities-20-1-Release-Notes/ba-p/565249

https://community.khoros.com/t5/Khoros-Community-Release-Notes/Khoros-Communities-20-1-Release-Notes/ba-p/565249

https://www.facebook.com/help/1629740080681586

https://community.khoros.com/t5/Khoros-Community-Blog/Group-Hubs-Overview-and-Use-Cases/ba-p/561969


These arguments are explained in more detail within the sub-sections below.

Return to Top

Simple Boolean Response (Default)

Unless explicitly defined, the function will return a simple Boolean response (i.e. True or False) indicating whetheror not the operation was successful.

>>> def create_and_check():... successful = khoros.grouphubs.create('my-new-group', 'My New Group', open_→˓group=True)... result = "It worked!" if successful else "It failed!"... print(result)...

>>> create_and_check()'It worked!'

Return to Top

Full API Response

If you’d rather return the full, raw response from the API request in order to parse it later at your convenience, then thiscan be done by setting the full_response argument to True in the function call as shown below.

>>> response = khoros.grouphubs.create('my-new-group', 'My New Group', open_group=True,␣→˓full_response=True)>>> if response.status_code != 404:... response = response.json()... print(response['status'])'success'

Return to Top



Return the ID

If it makes sense for you to return the ID of the group hub you just created then you can do so by defining the return_idargument as True as seen below.

>>> groups_to_create = [('first-group', 'My First Group'), ('second-group', 'My Second␣→˓Group')]>>> for group in groups_to_create:... group_id, group_title = group... group_id = khoros.grouphubs.create(group_id, group_title, open_group=True,␣→˓return_id=True)... print("Group Hub Created:", group_id)'Group Hub Created: first-group''Group Hub Created: second-group'

Return to Top

Return the URL

Very likely the most popular return option for this function, defining the return_url argument as True will returnthe URL of the newly created group hub, as shown below.

>>> khoros.grouphubs.create('python-lovers', 'The Python Lovers Group', \... open_group=True, return_url=True)'https://stage.example.com/t5/the-python-lovers-group/gh-p/python-lovers'

Return to Top

Return the API URL

If additional API calls will be immediately performed following the creation of a board, it may be useful to return theAPI URL (i.e. URI) for the new board by defining the return_api_url argument as True, as shown below.

>>> khoros.grouphubs.create('python-lovers', 'The Python Lovers Group', \... open_group=True, return_api_url=True)'/grouphubs/python-lovers'

Return to Top



Return the API Response HTTP Code

Another potentially useful return option is to define the return_http_code argument as True, which will return theHTTP status code for the API response, as demonstrated below.

>>> khoros.grouphubs.create('python-lovers', 'The Python Lovers Group', \... open_group=True, return_http_code=True)200

Return to Top

Return the API Response Status

Alternatively, it is possible to return the status of the API response (as defined by Khoros in the JSON response) bydefining the return_status argument as True, as shown below.

>>> khoros.grouphubs.create('my-first-group', 'My First Group', \... open_group=True, return_status=True)'success'

>>> khoros.grouphubs.create('my-first-group', 'My First Group', \... open_group=True, return_status=True)'error'

Return to Top

Return Any Error Messages

If you want to ensure that you see any error messages when applicable but don’t want to return the full API response,you can define the return_error_messages argument as True, as shown below.

>>> khoros.grouphubs.create('my-first-group', 'My First group', \... open_group=True, return_error_messages=True)"An object of type grouphub already exists with the 'id' property value 'my-first-group'"

This argument captures both the message value and the occasionally populated developer_message value. If oneof the values is blank or if they are exactly the same, such as in the example above, then only one of the values willbe displayed. Otherwise, if both values are defined and do not match then they will be returned in the {message} -{developer_message} format. (i.e. The two values will be separated by spaces and a hyphen.)

If you wish to return both fields regardless of their values then you can define the optional split_errors argumentas True as well to return a tuple containing both values, as shown below.

>>> khoros.grouphubs.create('my-first-blog', 'My First Blog', open_group=True, \... return_error_messages=True, split_errors=True)("An object of type grouphub already exists with the 'id' property value 'my-first-group'→˓", "An object of type grouphub already exists with the 'id' property value 'my-first-→˓group'")



https://en.wikipedia.org/wiki/List_of_HTTP_status_codes



Return to Top

Return Multiple Types

You are not restricted to choosing only one of the return options. You can enable as many options as needed and ifmultiple types are detected by the function then they will be returned as a tuple with those values, as demonstrated inthe example below.

>>> response = khoros.grouphubs.create('my-first-group', 'My First group', open_→˓group=True, \... return_http_code=True, return_status=True, return_error_messages=True)

>>> if response[1] == 'success':... print(f"The group hub creation was successful with the HTTP code {response[0]}.")... else:... print(f"The group hub creation failed with the following error:\n{response[2]}")...The group hub creation failed with the following error:An object of type grouphub already exists with the 'id' property value 'my-first-group'

Note: The tuple will return the values in the order they are listed as function arguments.

Return to Top

Defining the ID and Title

The ID and Title for the new group hub are defined using the group_hub_id and group_hub_title arguments,respectively, as demonstrated in the example below.

>>> khoros.grouphubs.create('this-is-the-id', 'This is the Group Title', open_group=True)

Note: Because group_hub_id is the first argument and group_hub_title is the second argument in the func-tion/method, it is not necessary to use keyword arguments (e.g. group_hub_id='this-is-the-id') to designateeach argument.

Return to Top



Todo: This page is currently being developed. Please check back later for more information.

1.6 Managing Node Settings

You can manage the settings on any node (including categories, boards and grouphubs) using the khoros.core.Khoros.Settings subclass, which leverages the khoros.objects.settings module.

This guide demonstrates various ways that you can retrieve, define and update the node settings within your KhorosCommunities environment.

• Prerequisites

• Retrieving node settings

– Retrieving board settings

– Retrieving category settings

– Retrieving group hub settings

• Defining node settings

• Working with JSON strings

• Troubleshooting

– An unexpected error has occurred when defining a node setting

– Unable to define node settings using the API v2 field name

– No board with the specified dispid error

1.6.1 Prerequisites

Throughout this guide we will assume that the Khoros core object has already been instantiated as khoros as shownbelow.

>>> from khoros import Khoros>>> khoros = Khoros(helper='/Users/example/helper.yml')

1.6.2 Retrieving node settings

This section demonstrates how easy it is to retrieve a specific setting value from a node.

Caution: These methods and functions assume you are querying a board by default. An additional parametermust be passed in order to query a category or grouphub node, as will be explained.



Retrieving board settings

A specific setting for a board can be retrieved using the khoros.core.Khoros.Settings.get_node_setting()method, which leverages the underlying khoros.objects.settings.get_node_setting() function.

In this method, the first parameter is the name of the setting to retrieve and the second parameter is the Node ID forthe node to be queried. Depending on the field name, the method (and underlying function) will attempt to select theappropriate Community API for the job.

For example, because most–if not all–custom settings set up by Khoros within the v2 API begin with the c_ prefix(with the c implying custom), if a setting with the name c_primary_moderator was provided as the first parameterthen the v2 API will automatically be selected and a LiQL query will be utilized to retrieve the value.

Alternatively, as API v1 values are generally defined in namespace notation, a field with the name custom.primary_moderator would leverage the v1 API within the method/function to retrieve the value.

>>> khoros.settings.get_node_setting('c_primary_moderator',... 'product-blog')'cmmgr123'>>> khoros.settings.get_node_setting('custom.primary_moderator',... 'product-blog')'cmmgr123'

However, if you want to ensure that the appropriate API version is leveraged then you can explicitly define it using thev1 parameter by defining it as either True or False.

>>> khoros.settings.get_node_setting('c_primary_moderator',... 'product-blog',... v1=False)'cmmgr123'>>> khoros.settings.get_node_setting('custom.primary_moderator',... 'product-blog',... v1=True)'cmmgr123'

Retrieving category settings

Retrieving a node setting from a category is nearly identical to retrieving board settings, with the one caveat that youmust explicitly define the node type in the third parameter, as illustrated below.

>>> khoros.settings.get_node_setting('c_primary_moderator',... 'our-awesome-product',... 'category')'cmmgr123'>>> khoros.settings.get_node_setting('custom.primary_moderator',... 'our-awesome-product',... 'category')'cmmgr123'

1.6. Managing Node Settings 35

https://en.wikipedia.org/wiki/Namespace


Caution: It is important to note that the node type should be defined in singular form rather than in plural. Thismeans that category, board and grouphub are the three acceptable values.

Retrieving group hub settings

Similar to retrieving category settings, you must explicitly define the node type using the grouphub value to success-fully retrieve the value, as demonstrated below.

>>> khoros.settings.get_node_setting('c_primary_moderator',... 'api-users-group',... 'grouphub')'cmmgr123'>>> khoros.settings.get_node_setting('custom.primary_moderator',... 'api-users-group',... 'grouphub')'mgr123'

1.6.3 Defining node settings

It is just as easy to define or update node settings with this library, which is done using the khoros.core.Khoros.Settings.define_node_setting() method and the underlying function khoros.objects.settings.define_node_setting().

The primary difference is that you will obviously need to specify the value of the metadata field when invoking themethod. This value will always be a string for custom metadata as this is how said fields are always configured. Assuch, it is always a good idea to leverage literal string interpolation when there is any uncertainty about the data type.

With the khoros.core.Khoros.Settings.define_node_setting() method, the first parameter is the name ofthe custom field, the second parameter is the value to write to said field, the third parameter is the Node ID of theaffected node and the fourth parameter is the node type.

You will know your operation was successful when the standard success response is received as a JSON string or object,as shown in the examples below.

>>> khoros.settings.define_node_setting('custom.primary_moderator',... 'johnDoe',... 'product-blog')'{"status": "success"}'>>> khoros.settings.define_node_setting('custom.primary_moderator',... 'johnDoe',... 'our-awesome-product',... 'category')'{"status": "success"}'>>> khoros.settings.define_node_setting('custom.primary_moderator',... 'johnDoe',



https://www.python.org/dev/peps/pep-0498/



... 'api-users-group',

... 'grouphub')'{"status": "success"}'

1.6.4 Working with JSON strings

Utilizing JSON objects in custom metadata can add many opportunities for customization and automation with yourcommunity. Rather than just storing a basic text string value in your metadata, you could store multiple values bytreating the string as a JSON object.

For example, instead of just tracking the username of the node’s primary moderator as was done in the examples above,you may wish to keep other relevant data in the same field. This could be accomplished with a JSON object similar tothe following:

{"primary_moderator": {"full_name": "John Doe","login": "johnDoe","email": "[email protected]"

}}

By converting the JSON object to a string, you can pass it as the metadata value as shown in the example below.

>>> import json>>>>>> # Store the metadata>>> moderator_info = {... 'primary_moderator': {... 'full_name': 'John Doe',... 'login': 'johnDoe',... 'email': '[email protected]'... }... }>>> khoros.settings.define_node_setting('custom.moderator_info',... json.dumps(moderator_info),... 'product-blog')'{"status": "success"}'>>>>>> # Retrieve the metadata>>> data = khoros.settings.get_node_setting('custom.moderator_info',... 'product-blog')>>> moderator_info = json.loads(data)>>> print(f'The primary moderator is ${moderator_info["primary_moderator"]["full_name"]}.→˓')The primary moderator is John Doe.

You also have the option of using the convert_json Boolean parameter in the khoros.settings.get_node_setting() method to automatically convert the JSON string to a Python dictionary to save yourself the

1.6. Managing Node Settings 37


step of converting it manually with the json.loads() function.

>>> data = khoros.settings.get_node_setting('custom.moderator_info',... 'product-blog',... convert_json=True)>>> print(f'The primary moderator is ${data["primary_moderator"]["full_name"]}.')The primary moderator is John Doe.

Note: A future release will introduce the ability to dump JSON to a string when defining node settings.

1.6.5 Troubleshooting

This section addresses some of the most commonly experienced issues when managing node settings.

An unexpected error has occurred when defining a node setting

Whenever an attempt is made to define a custom metadata field that does not exist, an Unexpected Error messagewill be returned, as shown below.

>>> khoros.settings.define_node_setting('custom.fake_field',... 'John Doe',... 'product-blog'){'status': 'error', 'error': {'code': 100, 'message': 'An Unexpected Error has occurred.→˓'}}

Unable to define node settings using the API v2 field name

Community API v2 metadata field names are considered read-only and have the sole purpose of allowing you to retrievethe data with a LiQL query. Therefore, it is by design that you are unable to write to said field. Attempting to do sowill likely return an Unexpected Error message, as shown below.

>>> khoros.settings.define_node_setting('c_primary_moderator',... 'johnDoe',... 'product-blog'){'status': 'error', 'error': {'code': 100, 'message': 'An Unexpected Error has occurred.→˓'}}


https://docs.python.org/3/library/json.html#json.loads


No board with the specified dispid error

When a Node ID is not recognized in the Khoros Communities environment, the error message No board with thespecified dispid will be returned in the API response, as shown below.

>>> khoros.settings.get_node_setting('custom.primary_moderator', 'api-users-group')Traceback (most recent call last):File "<stdin>", line 1, in <module>File "/Users/johndoe/Development/khoros/khoros/core.py", line 3605, in get_node_settingreturn objects_module.settings.get_node_setting(self.khoros_object, setting_name,␣

→˓node_id, node_type, v1,File "/Users/johndoe/Development/khoros/khoros/objects/settings.py", line 58, in get_

→˓node_settingsetting_value = _get_v1_node_setting(khoros_object, setting_name, node_id, node_type)

File "/Users/johndoe/Development/khoros/khoros/objects/settings.py", line 125, in _get_→˓v1_node_settingraise errors.exceptions.GETRequestError(status_code=_settings_data['error']['code'],

khoros.errors.exceptions.GETRequestError: The GET request returned the 101 status code␣→˓with the following message: No board with the specified dispid.

When this error message is received, you should first ask yourself if the node being queried matches the node typedefined in the parameter. For example, the query above does not have a node type defined in the parameter, whichmeans it is defaulting to the board type. However, the node in question in this circumstance is a group hub, whichwould explain the error.

1.7 Khoros Core Object

This section provides details around the core module and the methods used within the core object for the khorospackage, which are listed below.

• Init Module (khoros)

• Core Module (khoros.core)

– Core Functionality Subclasses (khoros.core.Khoros)

∗ V1 Subclass (khoros.core.Khoros.V1)

– Core Object Subclasses (khoros.core.Khoros)

∗ Album Subclass (khoros.core.Khoros.Album)

∗ Archives Subclass (khoros.core.Khoros.Archives)

∗ Message Subclass (khoros.core.Khoros.Message)

∗ Role Subclass (khoros.core.Khoros.Role)

∗ Settings Subclass (khoros.core.Khoros.Settings)

∗ User Subclass (khoros.core.Khoros.User)

– Core Structure Subclasses (khoros.core.Khoros)

∗ Board Subclass (khoros.core.Khoros.Board)

1.7. Khoros Core Object 39


∗ Category Subclass (khoros.core.Khoros.Category)

∗ Community Subclass (khoros.core.Khoros.Community)

∗ Group Hub Subclass (khoros.core.Khoros.GroupHub)

∗ Node Subclass (khoros.core.Khoros.Node)

– Studio Subclass (khoros.core.Khoros.Studio)

1.7.1 Init Module (khoros)

This module (being the primary __init__.py file for the library) provides a “jumping-off-point” to initialize theprimary khoros.core.Khoros object.

Package khoros

Synopsis This is the __init__ module for the khoros package

Usage from khoros import Khoros

Example khoros = Khoros(community_url='https://community.example.com',helper='path/to/helper_file.yml')

Created By Jeff Shurtliff

Last Modified Jeff Shurtliff

Modified Date 15 Sep 2021

class khoros.Khoros(defined_settings=None, community_url=None, tenant_id=None, community_name=None,auth_type=None, session_auth=None, oauth2=None, sso=None, helper=None,env_variables=None, auto_connect=True, use_community_name=False,prefer_json=True, debug_mode=False, skip_env_variables=False, empty=False,ssl_verify=None)

This is the class for the core object leveraged in this library.

class Album(khoros_object)This class includes methods for interacting with the albums collection.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Album inner class object.

Parameters khoros_object (class[khoros.Khoros]) – The core khoros.Khoros ob-ject

create(title=None, description=None, owner_id=None, hidden=False, default=False,full_response=False)

This method creates a new image album for a user.

New in version 2.3.0.Parameters

• title (str, None) – The title of the album to be created• description (str, None) – The description of the album• owner_id (str, int, None) – The User ID of the album owner


https://rsa.im/2WAewBP

https://docs.python.org/3/library/stdtypes.html#str



https://docs.python.org/3/library/functions.html#int


Note: If not defined, the owner will be the user performing the API call.

• hidden (bool) – Defines if the album should be public (default) or hidden• default (bool) – Defines if this will be the default album for the user (False by default)• full_response (bool) – Defines if the full response should be returned instead of the

outcome (False by default)Returns Boolean value indicating a successful outcome (default) or the full API response

get_albums_for_user(user_id=None, login=None, public=None, private=None,verify_success=False, allow_exceptions=True)

This method returns data for the albums owned by a given user.


• user_id (str, int) – The User ID for the album owner• login (str) – The username of the album owner• public (bool) – Indicates that public albums should be returned (all albums returned

by default)• private (bool) – Indicates that private albums should be returned (all albums returned

by default)• verify_success (bool) – Optionally check to confirm that the API query was success-

ful (False by default)• allow_exceptions (bool) – Defines whether or not exceptions can be raised for re-

sponses returning errors

Caution: This does not apply to exceptions for missing required data.

Returns A list of dictionaries representing each albumRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

class Archives(khoros_object)This class includes methods for archiving content.

New in version 4.1.0.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Archives inner class object.

New in version 4.1.0.Parameters khoros_object (class[khoros.Khoros]) – The core khoros.Khoros ob-

ject

static aggregate_results(results, include_raw=False)This method aggregates the results of an archive/unarchive operation into an easy-to-parse dictionary.


• results (list, dict) – The results from an archive or unarchive operation• include_raw (bool) – Includes the raw API response in the aggregated data dictionary

under the raw key (False by default)Returns A dictionary with fields for status, archived, unarchived, failed andunknown or the raw response when the API call completely fails, with the optional rawdata when requested


https://docs.python.org/3/library/functions.html#bool










https://docs.python.org/3/library/stdtypes.html#list

https://docs.python.org/3/library/stdtypes.html#dict



archive(message_id=None, message_url=None, suggested_url=None, archive_entries=None,aggregate_results=False, include_raw=False)

This method archives one or more messages while providing an optional suggested URL as a place-holder.


• message_id (str, int, None) – The message ID for the content to be archived• message_url (str, None) – The URL of the message to be archived (as an alternative

to the message_id argument)• suggested_url (str, None) – The full URL to suggest to the user when navigating

to the archived message• archive_entries (dict, list, tuple, set, None) – A dictionary mapping one

or more message IDs with accompanying suggested URLs

Note: Alternatively, a list, tuple or set of message IDs can be supplied which will beconverted into a dictionary with blank suggested URLs.

• aggregate_results (bool) – Aggregates the operation results into an easy-to-parsedictionary (False by default)

• include_raw (bool) – Includes the raw API response in the aggregated data dictionaryunder the raw key (False by default)

Note: This parameter is only relevant when the aggregate_results parameter isTrue.

Returns Boolean value indicating a successful outcome (default), the full API response orone or more specific fields defined by function arguments

Raises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

unarchive(message_id=None, message_url=None, new_board_id=None, archive_entries=None,aggregate_results=False, include_raw=False)

This method unarchives one or more messages and moves them to a given board.


• message_id (str, int, None) – The message ID for the content to be archived• message_url (str, None) – The URL of the message to be archived (as an alternative

to the message_id argument)• new_board_id (str, None) – The board ID of what will be the new parent board of a

message getting unarchived• archive_entries (dict, list, tuple, set, None) – A dictionary mapping one

or more message IDs with accompanying board IDs

Note: Alternatively, a list, tuple or set of message IDs can be supplied which will beconverted into a dictionary with blank board IDs.










https://docs.python.org/3/library/stdtypes.html#tuple

https://docs.python.org/3/library/stdtypes.html#set

















class Board(khoros_object)This class includes methods for interacting with boards.


__init__(khoros_object)This method initializes the khoros.core.Khoros.Board inner class object.


ject

board_exists(board_id=None, board_url=None)This method checks to see if a board (i.e. blog, contest, forum, idea exchange, Q&A or TKB) exists.


• board_id (str, None) – The ID of the board to check• board_url (str, None) – The URL of the board to check

Returns Boolean value indicating whether or not the board already existsRaises khoros.errors.exceptions.MissingRequiredDataError

create(board_id, board_title, discussion_style, description=None, parent_category_id=None,hidden=None, allowed_labels=None, use_freeform_labels=None, use_predefined_labels=None,predefined_labels=None, media_type=None, blog_authors=None, blog_author_ids=None,blog_author_logins=None, blog_comments_enabled=None, blog_moderators=None,blog_moderator_ids=None, blog_moderator_logins=None, one_entry_per_contest=None,one_kudo_per_contest=None, posting_date_end=None, posting_date_start=None,voting_date_end=None, voting_date_start=None, winner_announced_date=None,full_response=None, return_id=None, return_url=None, return_api_url=None,return_http_code=None, return_status=None, return_error_messages=None,split_errors=False)

This method creates a new board within a Khoros Community environment.

Changed in version 2.5.2: Changed the functionality around the return_error_messages argumentand added the split_errors argument.


• board_id (str) – The unique identifier (i.e. id field) for the new board (Required)• board_title (str) – The title of the new board (Required)• discussion_style (str) – Defines the board as a blog, contest, forum, idea,qanda or tkb (Required)

• description (str, None) – A brief description of the board• parent_category_id (str, None) – The ID of the parent category (if applicable)• hidden (bool, None) – Defines whether or not the new board should be hidden from

lists and menus (disabled by default)











• allowed_labels (str, None) – The type of labels allowed on the board(freeform-only, predefined-only or freeform and pre-defined)

• use_freeform_labels (bool, None) – Determines if freeform labels should be uti-lized

• use_predefined_labels (bool, None) – Determines if pre-defined labels should beutilized

• predefined_labels (list, None) – The pre-defined labels to utilized on the boardas a list of dictionaries

Todo: The ability to provide labels as a simple list and optionally standardize theirformat (e.g. Pascal Case, etc.) will be available in a future release.

• media_type (str, None) – The media type associated with a contest. (image, videoor story meaning text)

• blog_authors (list, None) – The approved blog authors in a blog board as a list ofuser data dictionaries

• blog_author_ids (list, None) – A list of User IDs representing the approved blogauthors in a blog board

• blog_author_logins (list, None) – A list of User Logins (i.e. usernames) repre-senting approved blog authors in a blog board

• blog_comments_enabled (bool, None) – Determines if comments should be enabledon blog posts within a blog board

• blog_moderators (list, None) – The designated blog moderators in a blog board asa list of user data dictionaries

• blog_moderator_ids (list, None) – A list of User IDs representing the blog mod-erators in a blog board

• blog_moderator_logins (list, None) – A list of User Logins (i.e. usernames) rep-resenting blog moderators in a blog board

• one_entry_per_contest (bool, None) – Defines whether a user can submit only oneentry to a single contest

• one_kudo_per_contest (bool, None) – Defines whether a user can vote only onceper contest

• posting_date_end (type[datetime.datetime], None) – The date/time when thecontest is closed to submissions

• posting_date_start (type[datetime.datetime], None) – The date/time whenthe voting period for a contest begins

• voting_date_end (type[datetime.datetime], None) – The date/time when thevoting period for a contest ends

• voting_date_start (type[datetime.datetime], None) – The date/time whenthe voting period for a contest begins

• winner_announced_date (type[datetime.datetime], None) – The date/time thecontest winner will be announced

• full_response (bool, None) – Determines whether the full, raw API response shouldbe returned by the function

• return_id (bool, None) – Determines if the ID of the new board should be returnedby the function

• return_url (bool, None) – Determines if the URL of the new board should be re-turned by the function

• return_api_url (bool, None) – Determines if the API URL of the new board shouldbe returned by the function

• return_http_code (bool, None) – Determines if the HTTP Code of the API re-sponse should be returned by the function

• return_status (bool, None) – Determines if the Status of the API response should
















https://docs.python.org/3/library/functions.html#type

https://docs.python.org/3/library/datetime.html#datetime.datetime
















be returned by the function• return_error_messages (bool, None) – Determines if the Developer Response

Message (if any) associated with the API response should be returned by the function• split_errors (bool) – Defines whether or not error messages should be merged when

applicableReturns Boolean value indicating a successful outcome (default), the full API response or

one or more specific fields defined by function argumentsRaises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError, ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

static get_board_id(url)This method retrieves the Board ID for a given board when provided its URL.

New in version 2.6.0.Parameters url (str) – The URL from which to parse out the Board IDReturns The Board ID retrieved from the URLRaises khoros.errors.exceptions.InvalidURLError

structure_payload(board_id, board_title, discussion_style, description=None,parent_category_id=None, hidden=None, allowed_labels=None,use_freeform_labels=None, use_predefined_labels=None,predefined_labels=None, media_type=None, blog_authors=None,blog_author_ids=None, blog_author_logins=None,blog_comments_enabled=None, blog_moderators=None,blog_moderator_ids=None, blog_moderator_logins=None,one_entry_per_contest=None, one_kudo_per_contest=None,posting_date_end=None, posting_date_start=None, voting_date_end=None,voting_date_start=None, winner_announced_date=None)

This method structures the payload to use in a Community API v2 request involving a board.


• board_id (str) – The unique identifier (i.e. id field) for the new board (Required)• board_title (str) – The title of the new board (Required)• discussion_style (str) – Defines the board as a blog, contest, forum, idea,qanda or tkb (Required)

• description (str, None) – A brief description of the board• parent_category_id (str, None) – The ID of the parent category (if applicable)• hidden (bool, None) – Defines whether or not the new board should be hidden from

lists and menus (disabled by default)• allowed_labels (str, None) – The type of labels allowed on the board

(freeform-only, predefined-only or freeform and pre-defined)• use_freeform_labels (bool, None) – Determines if freeform labels should be uti-

lized• use_predefined_labels (bool, None) – Determines if pre-defined labels should be

utilized• predefined_labels (list, None) – The pre-defined labels to utilized on the board

as a list of dictionaries


• media_type (str, None) – The media type associated with a contest. (image, videoor story i.e. text)




https://docs.python.org/3/library/exceptions.html#ValueError




























Returns The full and properly formatted payload for the API requestRaises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError

class Category(khoros_object)This class includes methods for interacting with categories.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Category inner class object.


category_exists(category_id=None, category_url=None)This method checks to see if a category exists.


• category_id (str, None) – The ID of the category to check• category_url (str, None) – The URL of the category to check

Returns Boolean value indicating whether or not the category already existsRaises khoros.errors.exceptions.MissingRequiredDataError

create(category_id, category_title, parent_id=None, return_json=True)This method creates a new category.


• category_id (str) – The Category ID of the new category (e.g. video-games)

























• category_title (str) – The title of the new category (e.g. Video Games)• parent_id (str, None) – The Category ID of the parent category (optional)• return_json (bool) – Determines whether or not the response should be returned in

JSON format (True by default)Returns The response from the API callRaises ValueError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.APIConnectionError

friendly_date_enabled(identifier=None, category_details=None)This method identifies if friendly dates are enabled for a given category.


• identifier (str, None) – The Category ID or Category URL with which to identifythe category

• category_details (dict, None) – Dictionary containing community details (op-tional)

Returns Boolean indicating if friendly dates are enabledRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_active_skin(identifier=None, category_details=None)This method retrieves the skin being used with a given category.




Returns The name of the active skin in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_category_details(identifier, first_item=True)This method returns a dictionary of community configuration settings.


• identifier (str) – The Category ID or Category URL with which to identify thecategory

• first_item (bool) – Filters the response data to the first item returned (True by default)Returns The community details within a dictionaryRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_category_field(field, identifier=None, category_details=None)This method returns a specific community field from the Khoros Community API.














• field (str) – The field whose value to return from the khoros.structures.base.Mapping class


• category_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns The requested field in its native formatRaises khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

static get_category_id(url)This method retrieves the Category ID for a given category when provided its URL.

Parameters url (str) – The URL from which to parse out the Category IDReturns The Category ID retrieved from the URLRaises khoros.errors.exceptions.InvalidURLError

get_creation_date(identifier=None, category_details=None)This method retrieves the creation date of a given category.




Returns The creation of the category in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_depth(identifier=None, category_details=None)This method retrieves the depth of a given category.




Returns The depth of the category as an integerRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_description(identifier=None, category_details=None)This method retrieves the description for a given category.




Returns The description in string format













Raises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_friendly_date_max_age(identifier=None, category_details=None)This method retrieves the maximum age where friendly dates should be used (if enabled) for a category.




Returns Integer representing the number of days the friendly date feature should be leveragedif enabled


get_language(identifier=None, category_details=None)This method retrieves the defined language for a given category.




Returns The language (e.g. en) in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_id(identifier=None, category_details=None)This method retrieves the parent ID for a given category.




Returns The parent ID in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_type(identifier=None, category_details=None)This method retrieves the parent type for a given category.












Returns The parent type in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_parent_url(identifier=None, category_details=None)This method retrieves the parent URL for a given category.




Returns The parent URL in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_position(identifier=None, category_details=None)This method retrieves the position of a given category.




Returns The position of the category as an integerRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_id(identifier=None, category_details=None)This method retrieves the root category ID for a given category.




Returns The root category ID in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_type(identifier=None, category_details=None)This method retrieves the root category type for a given category.














Returns The root category type in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_root_url(identifier=None, category_details=None)This method retrieves the root category URL for a given category.




Returns The root category URL in string formatRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_title(identifier=None, full_title=True, short_title=False, category_details=None)This method retrieves the full and/or short title of the category.



• full_title (bool) – Return the full title of the environment (True by default)• short_title (bool) – Return the short title of the environment (False by default)• category_details (dict, None) – Dictionary containing community details (op-

tional)Returns The title(s) of the environment as a string or a tuple of stringsRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_total_category_count()

This method returns the total number of categories within the Khoros Community environment.

Changed in version 3.3.2: Added logging for the DeprecationWarning.

Deprecated since version 2.6.0: Use the khoros.core.Khoros.Category.get_total_count()method instead.

Returns The total number of categories as an integerRaises khoros.errors.exceptions.GETRequestError

get_total_count()












https://docs.python.org/3/library/exceptions.html#DeprecationWarning


Returns The total number of categories as an integerRaises khoros.errors.exceptions.GETRequestError

get_url(category_id=None, category_details=None)This method retrieves the URL of a given category.


• category_id (str, None) – The ID of the category to be evaluated (optional ifcategory_details provided)


Returns The full URL of the categoryRaises khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_views(identifier=None, category_details=None)This method retrieves the total view count for a given category.




Returns The total number of viewsRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

is_hidden(identifier=None, category_details=None)This method identifies whether or not a given category is hidden.




Returns Boolean value indicating if the category is hiddenRaises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

class Community(khoros_object)This class includes methods for interacting with the overall Khoros Community.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Community inner class object.


ject









email_confirmation_required_to_post(community_details=None)This method identifies if an email configuration is required before posting in the environment.

New in version 2.1.0.Parameters community_details (dict, None) – Dictionary containing community de-

tails (optional)Returns Boolean value indicating if email configuration is required before postingRaises khoros.errors.exceptions.GETRequestError

friendly_date_enabled(community_details=None)This method if the friendly date functionality is utilized within the environment.


tails (optional)Returns Boolean value indicating if the feature is enabledRaises khoros.errors.exceptions.GETRequestError

get_active_skin(community_details=None)This method retrieves the primary active skin that is utilized within the environment.


tails (optional)Returns The skin name as a stringRaises khoros.errors.exceptions.GETRequestError

get_community_details()

This method returns a dictionary of community configuration settings.

New in version 2.1.0.Returns The community details within a dictionaryRaises khoros.errors.exceptions.GETRequestError

get_community_field(field, community_details=None)This method retrieves a particular field from the community collection in the API.


• field (str) – The field whose value to return from the khoros.structures.base.Mapping class

• community_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

Returns The requested field in its native formatRaises khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

get_creation_date(community_details=None)This method retrieves the timestamp for the initial creation of the environment.


tails (optional)Returns The creation date as a string (e.g. 2020-02-03T22:41:36.408-08:00)Raises khoros.errors.exceptions.GETRequestError









get_date_pattern(community_details=None)This method retrieves the date pattern (e.g. yyyy-MM-dd) utilized within the environment.


tails (optional)Returns The date pattern in string formatRaises khoros.errors.exceptions.GETRequestError

get_description(community_details=None)This method retrieves the description of the environment.


tails (optional)Returns The description in string formatRaises khoros.errors.exceptions.GETRequestError

get_friendly_date_max_age(community_details=None)This method identifies if the friendly date functionality is utilized within the environment.


tails (optional)Returns Boolean value indicating if the feature is enabledRaises khoros.errors.exceptions.GETRequestError

get_language(community_details=None)This method retrieves the language (e.g. en) utilized in the environment.


tails (optional)Returns The language code as a stringRaises khoros.errors.exceptions.GETRequestError

get_max_attachments(community_details=None)This method retrieves the maximum number of attachments permitted per message within the envi-ronment.


tails (optional)Returns The value as an integerRaises khoros.errors.exceptions.GETRequestError

get_ooyala_player_branding_id(community_details=None)This method retrieves the branding ID for the Ooyala Player utilized within the environment.


tails (optional)Returns The branding ID in string formatRaises khoros.errors.exceptions.GETRequestError

get_permitted_attachment_types(community_details=None)This method retrieves the attachment file types permitted within the environment.










Parameters community_details (dict, None) – Dictionary containing community de-tails (optional)

Returns The permitted file types within a listRaises khoros.errors.exceptions.GETRequestError

get_primary_url(community_details=None)This method retrieves the primary URL of the environment.


tails (optional)Returns The primary URL in string formatRaises khoros.errors.exceptions.GETRequestError

get_sign_out_url(community_details=None)This method retrieves the Sign Out URL for the environment.


tails (optional)Returns The Sign Out URL as a stringRaises khoros.errors.exceptions.GETRequestError

get_tenant_id(community_details=None)This method retrieves the tenant ID of the environment.


tails (optional)Returns The tenant ID in string formatRaises khoros.errors.exceptions.GETRequestError

get_title(full_title=True, short_title=False, community_details=None)This method retrieves the full and/or short title of the environment.


• full_title (bool) – Return the full title of the environment (True by default)• short_title (bool) – Return the short title of the environment (False by default)• community_details (dict, None) – Dictionary containing community details (op-

tional)Returns The title(s) of the environment as a string or a tuple of stringsRaises khoros.errors.exceptions.GETRequestError

show_breadcrumb_at_top_level(community_details=None)This method identifies if breadcrumbs should be shown at the top level of the environment.


tails (optional)Returns Boolean value indicating if breadcrumbs are displayed at the top level of the envi-

ronmentRaises khoros.errors.exceptions.GETRequestError

show_community_node_in_breadcrumb(community_details=None)This method identifies if the community node should be shown in breadcrumbs.












Parameters community_details (dict, None) – Dictionary containing community de-tails (optional)

Returns Boolean value indicating if the community node is displayed in bredcrumbsRaises khoros.errors.exceptions.GETRequestError

top_level_categories_enabled(community_details=None)This method identifies if top level categories are enabled within the environment.


tails (optional)Returns Boolean value indicating if top level categories are enabledRaises khoros.errors.exceptions.GETRequestError

top_level_categories_on_community_page(community_details=None)This method identifies if top level categories are enabled on community pages.


tails (optional)Returns Boolean value indicating if top level categories are enabled on community pagesRaises khoros.errors.exceptions.GETRequestError

class GroupHub(khoros_object)This class includes methods for interacting with group hubs.

__init__(khoros_object)This method initializes the khoros.core.Khoros.GroupHub inner class object.


create(group_id, group_title, description=None, membership_type=None, open_group=None,closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None,enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None,enable_tkb=None, all_styles_default=True, parent_category_id=None,avatar_image_path=None, full_response=None, return_id=None, return_url=None,return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False)

This method creates a new group hub within a Khoros Community environment.


• group_id (str, int) – The unique identifier (i.e. id field) for the new group hub(Required)

• group_title (str) – The title of the group hub (Required)• description (str, None) – A brief description of the group hub• membership_type (dict, None) – The membership_type value (open, closed orclosed_hidden)

• open_group (bool, None) – Defines the group hub as an open group• closed_group (bool, None) – Defines the group hub as a closed group• hidden_group (bool, None) – Defines the group hub as a closed and hidden group• discussion_styles (list, None) – A list of discussion styles that will be permitted

in the group hub• enable_blog (bool, None) – Defines that the blog discussion style should be enabled

for the group hub• enable_contest (bool, None) – Defines that the contest discussion style should be

enabled for the group hub

















• enable_forum (bool, None) – Defines that the forum discussion style should be en-abled for the group hub

• enable_idea (bool, None) – Defines that the idea discussion style should be enabledfor the group hub

• enable_qanda (bool, None) – Defines that the Q&A (qanda) discussion style shouldbe enabled for the group hub

• enable_tkb (bool, None) – Defines that the TKB (tkb) discussion style should beenabled for the group hub

• all_styles_default (bool) – Enables all discussion styles if not otherwise specified• parent_category_id (str, int, None) – The parent category identifier (if applica-

ble)• avatar_image_path (str, None) – The file path to the avatar image to be uploaded

(if applicable)• full_response (bool, None) – Determines whether the full, raw API response should

be returned by the function

Caution: This argument overwrites the return_id, return_url,return_api_url, return_http_code, return_status andreturn_error_messages arguments.

• return_id (bool, None) – Determines if the ID of the new group hub should be re-turned by the function

• return_url (bool, None) – Determines if the URL of the new group hub should bereturned by the function

• return_api_url (bool, None) – Determines if the API URL of the new group hubshould be returned by the function


• return_status (bool, None) – Determines if the Status of the API response shouldbe returned by the function

• return_error_messages (bool, None) – Determines if any error messages associ-ated with the API response should be returned by the function

• split_errors (bool) – Defines whether or not error messages should be merged whenapplicable


Raises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError

get_total_count()

This method returns the total number of group hubs within the Khoros Community environment.Returns The total number of group hubs as an integer

grouphub_exists(grouphub_id=None, grouphub_url=None)This method checks to see if a group hub exists.


• grouphub_id (str, None) – The ID of the group hub to check• grouphub_url (str, None) – The URL of the group hub to check

Returns Boolean value indicating whether or not the group hub already existsRaises khoros.errors.exceptions.MissingRequiredDataError





















structure_payload(group_id, group_title, description=None, membership_type=None,open_group=None, closed_group=None, hidden_group=None,discussion_styles=None, enable_blog=None, enable_contest=None,enable_forum=None, enable_idea=None, enable_qanda=None,enable_tkb=None, all_styles_default=True, parent_category_id=None)

This method structures the payload to use in a Group Hub API request.


• group_id (str, int) – The unique identifier (i.e. id field) for the new group hub(Required)

• group_title (str) – The title of the group hub (Required)• description (str, None) – A brief description of the group hub• membership_type (dict, None) – The membership_type value (open, closed orclosed_hidden)

• open_group (bool, None) – Defines the group hub as an open group• closed_group (bool, None) – Defines the group hub as a closed group• hidden_group (bool, None) – Defines the group hub as a closed and hidden group• discussion_styles (list, None) – A list of discussion styles that will be permitted

in the group hub• enable_blog (bool, None) – Defines if the blog discussion style should be enabled

for the group hub• enable_contest (bool, None) – Defines if the contest discussion style should be

enabled for the group hub• enable_forum (bool, None) – Defines if the forum discussion style should be enabled

for the group hub• enable_idea (bool, None) – Defines if the idea discussion style should be enabled

for the group hub• enable_qanda (bool, None) – Defines if the Q&A (qanda) discussion style should

be enabled for the group hub• enable_tkb (bool, None) – Defines if the TKB (tkb) discussion style should be en-

abled for the group hub• all_styles_default (bool) – Defines if all discussion styles should be enabled if not

otherwise specified• parent_category_id (str, int, None) – The parent category identifier (if applica-

ble)Returns The properly formatted payload for the API requestRaises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError

update_title(new_title, group_hub_id=None, group_hub_url=None, full_response=None,return_id=None, return_url=None, return_api_url=None, return_http_code=None,return_status=None, return_error_messages=None, split_errors=False)

This method updates the title of an existing group hub.


• new_title (str) – The new title for the group hub• group_hub_id (str, None) – The group hub ID that identifies the group hub to update

(necessary if URL not provided)• group_hub_url (str, None) – The group hub URL that identifies the group hub to

update (necessary if ID not provided)• full_response (bool, None) – Determines whether the full, raw API response should

be returned by the function































• return_error_messages (bool, None) – Determines if any error messages associ-ated with the API response should be returned by the function



Raises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError

class Message(khoros_object)This class includes methods for interacting with messages.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Message inner class object.


create(subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None,context_id=None, context_url=None, cover_image=None, images=None, is_answer=None,is_draft=None, labels=None, product_category=None, products=None, read_only=None,seo_title=None, seo_description=None, tags=None, ignore_non_string_tags=False,teaser=None, topic=None, videos=None, attachment_file_paths=None, full_payload=None,full_response=None, return_id=None, return_url=None, return_api_url=None,return_http_code=None, return_status=None, return_error_messages=None,split_errors=False, proxy_user_object=None)

This method creates a new message within a given node.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to becreated on behalf of other users.

Changed in version 4.3.0: It is now possible to pass the pre-constructed full JSON payload into thefunction via the full_payload parameter as an alternative to defining each field individually.

Changed in version 2.8.0: The ignore_non_string_tags, return_status,return_error_messages and split_errors arguments were introduced.


• subject (str, None) – The title or subject of the message• body (str, None) – The body of the message in HTML format












• node (dict, None) – A dictionary containing the id key and its associated value indi-cating the destination

• node_id (str, None) – The ID of the node in which the message will be published• node_url (str, None) – The URL of the node in which the message will be published

Note: This argument is necessary in the absence of the node and node_id arguments.

• canonical_url (str, None) – The search engine-friendly URL to the message• context_id (str, None) – Metadata on a message to identify the message with an

external identifier of your choice• context_url (str, None) – Metadata on a message representing a URL to associate

with the message (external identifier)• cover_image (dict, None) – The cover image set for the message• images (dict, None) – The query to retrieve images uploaded to the message• is_answer (bool, None) – Designates the message as an answer on a Q&A board• is_draft (bool, None) – Indicates whether or not the message is still a draft (i.e.

unpublished)• labels (dict, None) – The query to retrieve labels applied to the message• product_category (dict, None) – The product category (i.e. container forproducts) associated with the message

• products (dict, None) – The product in a product catalog associated with the message• read_only (bool, None) – Indicates whether or not the message should be read-only

or have replies/comments blocked• seo_title (str, None) – The title of the message used for SEO purposes• seo_description (str, None) – A description of the message used for SEO purposes• tags (dict, None) – The query to retrieve tags applied to the message• ignore_non_string_tags (bool) – Determines if non-strings (excluding iterables)

should be ignored rather than converted to strings (False by default)• teaser (str, None) – The message teaser (used with blog articles)• topic (dict, None) – The root message of the conversation in which the message

appears• videos (dict, None) – The query to retrieve videos uploaded to the message• attachment_file_paths (str, tuple, list, set, None) – The full path(s) to

one or more attachment (e.g. path/to/file1.pdf)• full_payload (dict, str, None) – Pre-constructed full JSON payload as a dictio-

nary (preferred) or a JSON string with the following syntax:

{"data": {"type": "message",

}}

Note: The type field shown above is essential for the payload to be valid.

• full_response (bool, None) – Defines if the full response should be returned insteadof the outcome (False by default)

Caution: This argument overwrites the return_id, return_url,return_api_url and return_http_code arguments.































• return_id (bool, None) – Indicates that the Message ID should be returned (Falseby default)

• return_url (bool, None) – Indicates that the Message URL should be returned(False by default)

• return_api_url (bool, None) – Indicates that the API URL of the message shouldbe returned (False by default)

• return_http_code (bool, None) – Indicates that the HTTP status code of the re-sponse should be returned (False by default)


• return_error_messages (bool, None) – Determines if the Developer ResponseMessage (if any) associated with the API response should be returned by the function


• proxy_user_object (class[khoros.objects.users.ImpersonatedUser],None) – Instantiated khoros.objects.users.ImpersonatedUser object to createthe message on behalf of a secondary user.

Returns Boolean value indicating a successful outcome (default) or the full API responseRaises TypeError, ValueError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

format_content_mention(content_info=None, content_id=None, title=None, url=None)This method formats the <li-message> HTML tag for a content @mention.


Parameters• content_info (dict, None) – A dictionary containing the 'id' and/or 'login'

key(s) with the user data

Note: This argument is necessary if the Title and URL are not explicitly passedusing the title and url function arguments.

• content_id (str, int, None) – The Message ID (aka Content ID) associatedwith the content mention

Note: This is an optional argument as the ID can be retrieved from the URL.

• title (str, None) – The display title for the content mention (e.g. "Click Here")

• url (str, None) – The fully-qualified URL of the message being mentioned

Returns The properly formatted <li-message> HTML tag in string format

Raises khoros.errors.exceptions.MessageTypeNotFoundError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.MessageTypeNotFoundError, khoros.errors.exceptions.InvalidURLError

format_user_mention(user_info=None, user_id=None, login=None)This method formats the <li-user> HTML tag for a user @mention.


Parameters









https://docs.python.org/3/library/exceptions.html#TypeError








• user_info (dict, None) – A dictionary containing the 'id' and/or 'login'key(s) with the user information

Note: This argument is necessary if the User ID and/or Login are not explicitlypassed using the user_id and/or login function arguments.

• user_id (str, int, None) – The unique user identifier (i.e. User ID) for the user

• login (str, None) – The login (i.e. username) for the user

Returns The properly formatted <li-user> HTML tag in string format

Raises khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

get_metadata(msg_id, metadata_key)This method retrieves the value for a specific metadata key associated with a given message.


Parameters• msg_id (str, int) – The ID of the message for which the metadata will be retrieved

• metadata_key (str) – The metadata key for which the value will be retrieved

Returns The metadata value

Raises khoros.errors.exceptions.MissingRequiredDataError',:py:exc:`khoros.errors.exceptions.InvalidMetadataError, khoros.errors.exceptions.GETRequestError

static parse_v2_response(json_response, return_dict=False, status=False, response_msg=False,http_code=False, message_id=False, message_url=False,message_api_uri=False, v2_base='')

This method parses an API response for a message operation (e.g. creating a message) and returnsdata.


Changed in version 3.2.0: The lower-level function call now utilizes keyword arguments to fix anargument mismatch issue.

Deprecated since version 2.5.0: Use the khoros.core.Khoros.parse_v2_response() functioninstead.


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

• return_dict (bool) – Defines if the parsed data should be returned within a dictio-nary

• status (bool) – Defines if the status value should be returned

• response_msg (bool) – Defines if the developer response message should be re-turned

• http_code (bool) – Defines if the HTTP status code should be returned

• message_id (bool) – Defines if the message ID should be returned

















• message_url (bool) – Defines if the message URL should be returned

• message_api_uri (bool) – Defines if the ** message API URI** should be re-turned

• v2_base (str) – The base URL for the API v2

Returns A string, tuple or dictionary with the parsed data

Raises khoros.errors.exceptions.MissingRequiredDataErrorupdate(msg_id=None, msg_url=None, subject=None, body=None, node=None, node_id=None,

node_url=None, canonical_url=None, context_id=None, context_url=None,cover_image=None, is_draft=None, labels=None, moderation_status=None, parent=None,product_category=None, products=None, read_only=None, topic=None, status=None,seo_title=None, seo_description=None, tags=None, overwrite_tags=False,ignore_non_string_tags=False, teaser=None, attachments_to_add=None,attachments_to_remove=None, full_response=None, return_id=None, return_url=None,return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False, proxy_user_object=None)

This method updates one or more elements of an existing message.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to beupdated on behalf of other users.


Parameters• msg_id (str, int, None) – The ID of the existing message

• msg_url (str, None) – The URL of the existing message

• subject (str, None) – The title or subject of the message

• body (str, None) – The body of the message in HTML format

• node (dict, None) – A dictionary containing the id key and its associated valueindicating the destination

• node_id (str, None) – The ID of the node in which the message will be published

• node_url (str, None) – The URL of the node in which the message will be pub-lished

Note: This argument is necessary in the absence of the node and node_id argu-ments.

• canonical_url (str, None) – The search engine-friendly URL to the message

• context_id (str, None) – Metadata on a message to identify the message with anexternal identifier of your choosing

• context_url (str, None) – Metadata on a message representing a URL to asso-ciate with the message (external identifier)

• cover_image (dict, None) – The cover image set for the message

• is_draft (bool, None) – Indicates whether or not the message is still a draft (i.e.unpublished)

• labels (dict, None) – The query to retrieve labels applied to the message




















• moderation_status (str, None) – The moderation status of the message

Note: Acceptable values are unmoderated, approved, rejected,marked_undecided, marked_approved and marked_rejected.

• parent (str, None) – The parent of the message

• product_category (dict, None) – The product category (i.e. container forproducts) associated with the message

• products (dict, None) – The product in a product catalog associated with themessage

• read_only (bool, None) – Indicates whether or not the message should be read-only or have replies/comments blocked

• topic (dict, None) – The root message of the conversation in which the messageappears

• status (dict, None) – The message status for messages where conversation.styleis idea or contest

Caution: This property is not returned if the message has the defaultUnspecified status assigned. It will only be returned for ideas with a statusof Completed or with a custom status created in Community Admin.

• seo_title (str, None) – The title of the message used for SEO purposes

• seo_description (str, None) – A description of the message used for SEO pur-poses

• tags (dict, None) – The query to retrieve tags applied to the message

• overwrite_tags (bool) – Determines if tags should overwrite any existing tags(where applicable) or if the tags should be appended to the existing tags (default)

• ignore_non_string_tags (bool) – Determines if non-strings (excluding iter-ables) should be ignored rather than converted to strings (False by default)

• teaser (str, None) – The message teaser (used with blog articles)

• attachments_to_add (str, tuple, list, set, None) – The full path(s) toone or more attachments (e.g. path/to/file1.pdf) to be added to the message

• attachments_to_remove (str, tuple, list, set, None) – One or more at-tachments to remove from the message

Note: Each attachment should specify the attachment id of the attachment to remove,which begins with m#_. (e.g. m283_file1.pdf)

• full_response (bool, None) – Defines if the full response should be returnedinstead of the outcome (False by default)


























• return_id (bool, None) – Indicates that the Message ID should be returned(False by default)


• return_api_url (bool, None) – Indicates that the API URL of the messageshould be returned (False by default)

• return_http_code (bool, None) – Indicates that the HTTP status code of theresponse should be returned (False by default)

• return_status (bool, None) – Determines if the Status of the API responseshould be returned by the function


• split_errors (bool) – Defines whether or not error messages should be mergedwhen applicable

• proxy_user_object (class[khoros.objects.users.ImpersonatedUser],None) – Instantiated khoros.objects.users.ImpersonatedUser object to cre-ate the message on behalf of a secondary user.

Returns Boolean value indicating a successful outcome (default) or the full API response

Raises TypeError, ValueError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

static validate_message_payload(payload)This method validates the payload for a message to ensure that it can be successfully utilized.


Parameters payload (dict, str) – The message payload to be validated as a dictionary(preferred) or a JSON string.

Returns The payload as a dictionary

Raises khoros.errors.exceptions.InvalidMessagePayloadErrorclass Node(khoros_object)

This class includes methods for interacting with nodes.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Node inner class object.

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

get_avatar_url(identifier, node_details=None, original=True, tiny=False, small=False,medium=False, large=False)

This method retrieves one or more avatar URLs for a given node.


Parameters• identifier (str, None) – The Node ID or Node URL with which to identify the

node















• node_details (dict, None) – The data captured from the khoros.structures.base.get_details() function

• original (bool) – Indicates if the URL for the original-size image should be re-turned (True by default)

• tiny (bool) – Indicates if the URL for the image in a tiny size should be returned(False by default)

• small (bool) – Indicates if the URL for the image in a small size should be returned(False by default)

• medium (bool) – Indicates if the URL for the image in a medium size should bereturned (False by default)

• large (bool) – Indicates if the URL for the image in a large size should be returned(False by default)

Returns A single URL as a string (default) or a dictionary of multiple URLs by size


get_creation_date(identifier, node_details=None, friendly=False)This method returns the creation date of a given node.



node


• friendly (bool) – Defines if the “friendly” date (e.g. Friday) should be returned(False by default)

Returns The creation date as a string


get_depth(identifier, node_details=None)This method returns the depth of a given node.



node


Returns The depth as an integer















get_description(identifier, node_details=None)This method returns the description of a given node.



node


Returns The node description as a string


get_discussion_style(identifier, node_details=None)This method returns the full URL of a given Node ID.


Parameters• identifier (str, None) – The Node ID with which to identify the node


Returns The node URl as a string


get_node_details(identifier, first_item=True)This method returns a dictionary of node configuration settings.


Parameters• identifier (str) – The Node ID or Node URL with which to identify the node

• first_item (bool) – Filters the response data to the first item returned (True bydefault)

Returns The node details within a dictionary

Raises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError









get_node_field(field, identifier=None, node_details=None)This method returns a specific node field from the Khoros Community API.


Parameters• field (str) – The field to return from the khoros.structures.base.Mapping

class

• identifier (str, None) – The Node ID or Node URL with which to identify thenode


Returns The requested field in its native format


static get_node_id(url, node_type=None)This method retrieves the Node ID for a given node within a URL.

Parameters• url (str) – The URL from which to parse out the Node ID

• node_type (str, None) – The node type (e.g. blog, tkb, message, etc.) for theobject in the URL

Returns The Node ID retrieved from the URL

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

static get_node_type_from_url(url)This method attempts to retrieve a node type by analyzing a supplied URL.

Parameters url (str) – The URL from which to extract the node type

Returns The node type based on the URL provided

Raises khoros.errors.exceptions.NodeTypeNotFoundErrorget_parent_id(identifier, node_details=None, include_prefix=False)

This method returns the Parent ID of a given node.



node


• include_prefix (bool) – Determines if the prefix (e.g. category:) should beincluded (Default: False)

Returns The Parent ID as a string













get_parent_type(identifier, node_details=None)This method returns the parent type of a given node.



node


Returns The parent type as a string


get_parent_url(identifier, node_details=None)This method returns the parent URL of a given node.



node


Returns The parent URL as a string


get_position(identifier, node_details=None)This method returns the position of a given node.



node


Returns The position as an integer










get_root_id(identifier, node_details=None, include_prefix=False)This method returns the Root Category ID of a given node.



node


• include_prefix (bool) – Defines if the prefix (e.g. category:) should be in-cluded (False by default)

Returns The Root Category ID as a string


get_root_type(identifier, node_details=None)This method returns the root category type of a given node.



node


Returns The root category type as a string


get_root_url(identifier, node_details=None)This method returns the root category URL of a given node.



node


Returns The root category URL as a string











get_title(identifier=None, full_title=True, short_title=False, node_details=None)This method retrieves the full and/or short title of the node.



node

• full_title (bool) – Determines if the full title of the node should be returned(True by default)

• short_title (bool) – Determines if the short title of the node should be returned(False by default)

• node_details (dict, None) – Dictionary containing node details (optional)

Returns The node title(s) as a string or a tuple of strings


get_total_node_count()

This method returns the total number of nodes within the Khoros Community environment.

Returns The total number of nodes as an integer

Raises khoros.errors.exceptions.GETRequestErrorget_type(identifier, node_details=None)

This method returns the full URL of a given Node ID.






get_url(node_id=None, node_details=None)This method returns the full URL of a given Node ID.


Parameters• node_id (str, None) – The Node ID with which to identify the node














get_views(identifier, node_details=None)This method returns the views for a given node.



node


Returns The views as an integer


is_hidden(identifier, node_details=None)This method identifies whether or not a given node is hidden.



node


Returns Boolean indicating whether or not the node is hidden


node_exists(node_id=None, node_url=None)This method checks to see if a node exists.


Parameters• node_id (str, None) – The ID of the node to check

• node_url (str, None) – The URL of the node to check

Returns Boolean value indicating whether or not the node already exists

Raises khoros.errors.exceptions.MissingRequiredDataErrorclass Role(khoros_object)

This class includes methods relating to roles and permissions.









__init__(khoros_object)This method initializes the khoros.core.Khoros.Role inner class object.



assign_roles_to_user(user, lookup_type='id', roles_to_add=None, node=None,node_type='board', v1=False, return_json=True)

This method assigns a user to one or more roles.


Parameters• user (str) – The identifier (i.e. ID, login or email) of the user to be assigned to the

role

• lookup_type (str) – The lookup type for the user identifier (id, login or email)

• roles_to_add (str, list, tuple, set) – One or more roles (Role IDs or RoleNames) to which the user will be assigned

• node (str, None) – The Node ID of the node to which the role is scoped whenapplicable

• node_type (str) – The type of node to which the role is scoped (e.g. board (de-fault), category, etc.)

• v1 (bool) – Determines if the Community API v1 should be used to perform theoperation (False by default)

• return_json (bool) – Determines if the response should be returned as JSONrather than XML (True by default)

Returns The response from the API request

Raises ValueError, khoros.errors.exceptions.APIConnectionError,khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.UnsupportedNodeTypeError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.POSTRequestError,khoros.errors.exceptions.PUTRequestError

static get_role_id(role_name, scope='community', node_id=None)This method constructs and returns the Role ID associated with a given role name and scope.


Parameters• role_name (str) – The name of the role (e.g. Administrator, Moderator,Owner, etc.)

• scope (str) – The scope of the role (community by default)

• node_id (str, None) – The associated Node ID for any role that does not have aglobal/community scope.

Returns The properly constructed Role ID where applicable

Raises khoros.errors.exceptions.InvalidRoleError, khoros.errors.exceptions.MissingRequiredDataError

















get_roles_for_user(user_id, fields=None)This method returns all roles associated with a given User ID.

Changed in version 4.1.0: The docstring has been updated to reference the correct exception raisedby this method.

Changed in version 3.5.0: Fields to return in the LiQL query can now be explicitly defined.


Parameters• user_id (str) – The User ID for which to retrieve the roles data

• fields (str, list, tuple, set, None) – The field(s) to retrieve from theLiQL query as a string or list

Note: All fields (i.e. SELECT *) are returned unless fields are explicitly defined.

Returns A dictionary with data for each role associated with the given User ID

Raises khoros.errors.exceptions.GETRequestErrorget_total_role_count(return_dict=False, total=True, top_level=False, board=False,

category=False, group_hub=False)This method retrieves the total role count for one or more role type(s).


Parameters• return_dict (bool) – Determines if the data should be returned as a dictionary

(False by default)

• total (bool) – Indicates that the total overall role count should be returned (Trueby default)

• top_level (bool) – Indicates that the total top-level role count should be returned(False by default)

• board (bool) – Indicates that the total board-level role count should be returned(False by default)

• category (bool) – Indicates that the total category-level role count should be re-turned (False by default)

• group_hub (bool) – Indicates that the total group hub-level role count should bereturned (False by default)

Returns The role count(s) as an integer, tuple or dictionary, depending on the argumentssupplied

Raises khoros.objects.roles.InvalidRoleTypeError

get_users_with_role(fields='login', role_id=None, role_name=None, scope=None, node_id=None,limit_per_query=1000, simple=False)

This method retrieves a list of all users that have a specific role.


Parameters














• fields (str, tuple, list, set) – One or more fields from the Users objectto return (login field by default)

• role_id (str, None) – The identifier for the role innode_type:node_id:role_name format

• role_name (str, None) – The simple role name (e.g. Administrator)

Caution: This option should only be used when the role name is unique withinthe community at all node levels.

• scope (str, None) – The scope of the role (e.g. board, category, community,grouphub)

Note: If a value is not supplied and only a role name is defined then the role scopeis assumed to be at the community level. (i.e. global)

• node_id (str, None) – The Node ID associated with the role (where applicable)


• limit_per_query (int, str) – Defines a LIMIT constraint other than the default1000 limit per LiQL query

Note: Unless modified by Khoros Support or Professional Services, 1000 is themaximum number of entries that can be returned in a single LiQL query.

• simple (bool) – Returns a simple list of the strings or tuples of the value(s) for eachuser (False by default)

Returns A list of users as strings, tuples or dictionaries depending if simple mode isenabled

Raises khoros.errors.exceptions.DataMismatchError, khoros.errors.exceptions.MissingRequiredDataError

class SAML(khoros_object)This class includes methods relating to SAML 2.0 authentication and user provisioning.


__init__(khoros_object)This method initializes the khoros.core.Khoros.SAML inner class object.


static import_assertion(file_path, base64_encode=True, url_encode=True)This method imports an XML SAML assertion as a string and optionally base64- and/or URL-encodes it.















Parameters• file_path (str) – The file path to the XML file to import

• base64_encode (bool) – Determines if the assertion should be base64-encoded(True by default)

• url_encode (bool) – Determines if the assertion should be URL-encoded (Trueby default)

Returns The SAML assertion string

Raises FileNotFoundError

send_assertion(assertion=None, file_path=None, base64_encode=True, url_encode=True)This method sends a SAML assertion as a POST request in order to provision a new user.


Parameters• assertion (str, None) – The SAML assertion in string format and optionally

base64- and/or URL-encoded

• file_path (str, None) – The file path to the XML file to import that contains theSAML assertion



Returns The API response from the POST request

Raises khoros.errors.exceptions.MissingRequiredDataErrorclass Settings(khoros_object)

This class includes methods relating to the retrieval and defining of various settings.


__init__(khoros_object)This method initializes the khoros.core.Khoros.Settings inner class object.


define_node_setting(setting_name, setting_val, node_id, node_type='board', return_json=True)This method defines a particular setting value for a given node.

Changed in version 4.0.0: The default value for the return_json parameter is now True.

Changed in version 3.3.2: The return_json parameter has been introduced which returns a simpleJSON object (as a dict) indicating whether or not the operation was successful. (Currently Falseby default)


Parameters• setting_name (str) – The name of the setting field for which to retrieve the value

• setting_val (str) – The value of the setting to be defined

• node_id (str) – The ID of the node associated with the setting to retrieve





https://docs.python.org/3/library/exceptions.html#FileNotFoundError









• node_type (str) – Defines the node as a board (default), category or grouphub

• return_json (bool) – Returns a simple JSON dictionary indicating the operationresult (False by default)

Caution: An unsuccessful REST call will result in the raising of the khoros.errors.exceptions.PostRequestError exception if the return_json pa-rameter is set to False.

Returns None

Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError,khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.PayloadMismatchError

get_node_setting(setting_name, node_id, node_type='board', v1=None, convert_json=False)This method retrieves the value of a specific node setting.

Changed in version 3.3.2: The convert_json parameter has been introduced which optionally con-verts a JSON string into a dictionary.





• v1 (bool, None) – Optionally defines a specific Community API version to usewhen retrieving the value

• convert_json (bool) – Optionally converts a JSON string into a Python dictionary(False by default)

Returns The value of the setting for the node

Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError,khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.LiQLParseError

class Studio(khoros_object)This class includes methods relating to the Lithium SDK and Studio Plugin.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Studio inner class object.


static get_node_version()

This method identifies and returns the installed Node.js version.


Returns The version as a string or None if not installed














static get_npm_version()

This method identifies and returns the installed npm version.



static get_sdk_version()

This method identifies the currently installed version of the Lithium SDK.


Returns The SDK version in string format or None if not installed

static node_installed()

This method checks whether or not Node.js is installed.


Returns Boolean value indicating whether or not Node.js is installed

static npm_installed()

This method checks whether or not npm is installed.


Returns Boolean value indicating whether or not npm is installed

static sdk_installed()

This method checks to see if the Lithium SDK is installed.


Returns Boolean value indicating whether or not the Lithium SDK is installed

class Subscription(khoros_object)This class includes methods relating to subscriptions.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Subscription inner class object.


add_subscription(target_id, target_type='board', payload=None, included_boards=None,excluded_boards=None, proxy_user_object=None)

This method adds a subscription to a given target for the current user.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests tobe performed on behalf of other users.


Parameters• target_id (str, int) – The unique identifier for the target (e.g. Node ID, Mes-

sage ID, etc.)

• target_type – The target type such as board (default), message, category, etc.

• payload (dict, None) – Pre-constructed payload to use in the API call

• included_boards (list, tuple, set, str, None) – One or more boards(represented by Node ID) to be included in the partial subscription










• excluded_boards (list, tuple, set, str, None) – One or more boards(represented by Node ID) to be excluded from the partial subscription

• proxy_user_object (class[khoros.objects.users.ImpersonatedUser],None) – Instantiated khoros.objects.users.ImpersonatedUser object to per-form the API request on behalf of a secondary user.

Returns The API response in JSON format

Raises ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PayloadMismatchError

get_subscription_uri()

This method returns the subscriptions URI for the v2 API to perform API calls.


Returns The full (absolute) URI for the subscriptions v2 API endpoint

subscribe_to_board(node_id, proxy_user_object=None)This method subscribes the current user to an individual message.



Parameters• node_id (str) – The unique identifier for a board (i.e. Board ID)




subscribe_to_category(node_id, included_boards=None, excluded_boards=None,proxy_user_object=None)

This method subscribes the current user to a full or partial category.



Parameters• node_id (str) – The unique identifier (i.e. Node ID) for the category
























subscribe_to_label(label, board_id, proxy_user_object=None)This method subscribes the current user to label found on a board.



Parameters• label (str, int) – The label to which to subscribe

• board_id (str) – The unique identifier (i.e. Node ID) for the board where the labelis found




subscribe_to_message(msg_id, proxy_user_object=None)This method subscribes the current user to an individual message.



Parameters• msg_id (str, int) – The unique identifier for an individual message




subscribe_to_product(product_id, proxy_user_object=None)This method subscribes the current user to a product.



Parameters• product_id (str, int) – The unique identifier for a product
















class Tag(khoros_object)This class includes methods relating to the tagging of content.


__init__(khoros_object)This method initializes the khoros.core.Khoros.Tag inner class object.



add_single_tag_to_message(tag, msg_id, allow_exceptions=False)This method adds a single tag to an existing message.


Parameters• tag (str) – The tag value to be added

• msg_id (str, int) – The unique identifier for the message

• allow_exceptions (bool) – Determines if exceptions are permitted to be raised(False by default)

Returns None

Raises khoros.errors.exceptions.POSTRequestErroradd_tags_to_message(tags, msg_id, allow_exceptions=False)

This method adds one or more tags to an existing message.


..caution:: This function is not the most effective way to add multiple tags to a message. It is recommendedthat the khoros.core.Khoros.messages.update() method be used instead with its tagsargument, which is more efficient and performance-conscious.

Parameters• tags (str, tuple, list, set) – One or more tags to be added to the message



Returns None

Raises khoros.errors.exceptions.POSTRequestError















get_tags_for_message(msg_id)This method retrieves the tags for a given message.


Parameters msg_id (str, int) – The Message ID for the message from which to retrievetags

Returns A list of tags associated with the message

static structure_single_tag_payload(tag_text)This method structures the payload for a single tag.


Parameters tag_text (str) – The tag to be included in the payload


Raises khoros.errors.exceptions.InvalidPayloadValueErrorstructure_tags_for_message(*tags, msg_id=None, overwrite=False, ignore_non_strings=False,

wrap_json=False)This method structures tags to use within the payload for creating or updating a message.

Changed in version 4.3.0: Introduced the wrap_json parameter to wrap the tags in a dictionarywithin the items key.


Parameters• tags (str, list, tuple, set) – One or more tags or list of tags to be structured

• msg_id (str, int, None) – Message ID of an existing message so that its existingtags can be retrieved (optional)

• overwrite (bool) – Determines if tags should overwrite any existing tags (whereapplicable) or if the tags should be appended to the existing tags (default)

• ignore_non_strings (bool) – Determines if non-strings (excluding iterables)should be ignored rather than converted to strings (False by default)

• wrap_json (bool) – Determines if the list of tags should be wrapped in the{"items": []} JSON structure – In other words, a dictionary rather than a list(False by default)

Returns A list of properly formatted tags to act as the value for the tags field in the mes-sage payload

class User(khoros_object)This class includes methods for interacting with users.

__init__(khoros_object)This method initializes the khoros.core.Khoros.User inner class object.


create(user_settings=None, login=None, email=None, password=None, first_name=None,last_name=None, biography=None, sso_id=None, web_page_url=None, cover_image=None,ignore_exceptions=False)















This method creates a new user in the Khoros Community environment.

Changed in version 4.0.0: This function now returns the API response and the ignore_exceptionsparameter has been introduced.

Changed in version 3.5.0: The unnecessary return statement at the end of the method has beenremoved.

Parameters• user_settings (dict, None) – Allows all user settings to be passed to the func-

tion within a single dictionary

• login (str, None) – The username (i.e. login) for the user (required)

• email (str, None) – The email address for the user (required)

• password (str, None) – The password for the user

• first_name (str, None) – The user’s first name (i.e. given name)

• last_name (str, None) – The user’s last name (i.e. surname)

• biography (str, None) – The user’s biography for their profile

• sso_id (str, None) – The Single Sign-On (SSO) ID for the user

• web_page_url (str, None) – The URL to the user’s website

• cover_image (str, None) – The cover image to be used on the user’s profile

• ignore_exceptions (bool) – Defines whether to raise the khoros.errors.exceptions.UserCreationError exception if the creation attempt fails (Falseby default)

Returns The response to the user creation API request

Raises khoros.errors.exceptions.UserCreationErrordelete(user_id, return_json=False)

This method deletes a user from the Khoros Community environment.

Parameters• user_id (str, int) – The User ID of the user to be deleted

• return_json (bool) – Determines if the API response should be returned in JSONformat (False by default)

Returns The API response (optionally in JSON format)

Raises khoros.errors.exceptions.FeatureNotConfiguredErrorget_album_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the number of albums for a user.

Parameters• user_settings (dict, None) – A dictionary containing all relevant user settings

supplied in the parent function

• user_id (int, str, None) – The User ID associated with the user

• login (str, None) – The username of the user

• email (str, None) – The email address of the user






















Returns The number of albums found for the user as an integer

Raises khoros.errors.exceptions.GETRequestErrorget_email(user_settings=None, user_id=None, login=None, first_name=None, last_name=None,

allow_multiple=False, display_warnings=True)This method retrieves the email address for a user by leveraging supplied user information.

Note: The priority of supplied fields are as follows: User ID, username, first and last name, lastname, first name



• user_id (str, None) – The User ID of the user


• first_name (str, None) – The first name (i.e. given name) of the user

• last_name (str, None) – The last name (i.e. surname) of the user

• allow_multiple (bool) – Allows a list of email addresses to be returned if multipleresults are found

• display_warnings (bool) – Determines if warning messages should be displayed(True by default)

Returns The email address of the user as a string or a list of emails if allow_multipleis True

get_followers_count(user_settings=None, user_id=None, login=None, email=None)This method gets the count of community members who have added the user as a friend in the com-munity.






Returns The number of community members who have added the user as a friend in integerformat

Raises khoros.errors.exceptions.GETRequestErrorget_following_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of community members the user has added as a friend in the community.























Returns The number of community members the user has added as a friend in integerformat

Raises khoros.errors.exceptions.GETRequestErrorget_ids_from_login_list(login_list, return_type='list')

This method identifies the User IDs associated with a list of user logins. (i.e. usernames)

Parameters• login_list (list, tuple) – List of user login (i.e. username) values in string

format

• return_type (str) – Determines if the data should be returned as a list (default)or a dict

Returns A list or dictionary with the User IDs

Raises khoros.errors.exceptions.GETRequestErrorget_images_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of images uploaded by the user.






Returns The number of images uploaded by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorget_kudos_given_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of kudos a user has given.






Returns The number of kudos given by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorget_kudos_received_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of kudos a user has received.
























Returns The number of kudos received by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorget_last_visit_timestamp(user_settings=None, user_id=None, login=None, email=None)

This method retrieves the timestamp for the last time the user logged into the community.






Returns The last visit timestamp in string format

Raises khoros.errors.exceptions.GETRequestErrorget_login(user_settings=None, user_id=None, email=None, first_name=None, last_name=None,

allow_multiple=False, display_warnings=True)This is an alternative method name for the khoros.core.Khoros.User.get_username()method.

get_messages_count(user_settings=None, user_id=None, login=None, email=None)This method gets the count of messages (topics and replies) posted by the user.






Returns The number of messages (topics and replies) posted by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorget_online_user_count()

This method retrieves the number of users currently online.

Returns The user count for online users as an integer

Raises khoros.errors.exceptions.GETRequestErrorget_public_images_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of public images uploaded by the user.

























Returns The number of public images uploaded by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorget_registration_data(user_settings=None, user_id=None, login=None, email=None)

This method retrieves the registration data for a given user.






Returns A dictionary containing the registration data for the user

Raises khoros.errors.exceptions.GETRequestErrorget_registration_status(user_settings=None, user_id=None, login=None, email=None)

This method retrieves the registration status for a given user.






Returns The registration status in string format

Raises khoros.errors.exceptions.GETRequestErrorget_registration_timestamp(user_settings=None, user_id=None, login=None, email=None)

This method retrieves the timestamp for when a given user registered for an account.






Returns The registration timestamp in string format

Raises khoros.errors.exceptions.GETRequestErrorget_replies_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of replies posted by the user.

Parameters




















• user_settings (dict, None) – A dictionary containing all relevant user settingssupplied in the parent function




Returns The number of replies posted by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorget_roles_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of roles applied to the user.






Returns The number of roles applied to the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorget_solutions_authored_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of messages created by the user that are marked as accepted solutions.






Returns The number of messages created by the user that are marked as accepted solutionsin integer format

Raises khoros.errors.exceptions.GETRequestErrorget_topics_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of topic messages (excluding replies) posted by the user.






Returns The number of topic messages (excluding replies) posted by the user in integerformat

Raises khoros.errors.exceptions.GETRequestError























get_user_data(user_settings=None, user_id=None, login=None, email=None)This method retrieves all user data for a given user.






Returns A dictionary containing the user data for the user

Raises khoros.errors.exceptions.GETRequestErrorget_user_id(user_settings=None, login=None, email=None, first_name=None, last_name=None,

allow_multiple=False, display_warnings=True)This method looks up and retrieves the User ID for a user by leveraging supplied user information.

Note: The priority of supplied fields are as follows: login, email, first and last name, last name, firstname







• allow_multiple (bool) – Allows a list of User IDs to be returned if multiple resultsare found


Returns The User ID of the user as an integer or a list of User IDs if allow_multiple isTrue

get_username(user_settings=None, user_id=None, email=None, first_name=None, last_name=None,allow_multiple=False, display_warnings=True)

This method looks up and retrieves the username for a user by leveraging supplied user information.

Note: The priority of supplied fields are as follows: User ID, email, first and last name, last name,first name






















• allow_multiple (bool) – Allows a list of usernames to be returned if multipleresults are found


Returns The username (i.e. login) of the user or a list of usernames if allow_multipleis True

get_videos_count(user_settings=None, user_id=None, login=None, email=None)This method gets the count of videos uploaded by the user.






Returns The number of videos uploaded by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorimpersonate_user(user_login)

This method instantiates and returns the :py:class`khoros.objects.users.ImpersonatedUser` object whichcan then be passed to other methods and functions to perform operations as a secondary user.

Note: The authenticated user must have the Administrator role and/or have the Switch Userpermission enabled.


Parameters user_login (str) – The username (i.e. login) of the user to be impersonated

Returns The instantiated :py:class`khoros.objects.users.ImpersonatedUser` object

query_users_table_by_id(select_fields, user_id)This method queries the users table for one or more given SELECT fields for a specific User ID.

Parameters• select_fields (str, tuple, list, set) – One or more SELECT field (e.g.login, messages.count(*), etc.) to query

• user_id (int, str) – The User ID associated with the user

Returns The API response for the performed LiQL query






















update_sso_id(new_sso_id, user_id=None, user_login=None)This method updates the SSO ID for a user.


Parameters• new_sso_id (str) – The new SSO ID for the user

• user_id (str, int, None) – The numeric User ID that identifies the user

• user_login (str, None) – The username that identifies the user

Returns The API response

Raises py:exc:khoros.errors.exceptions.MissingRequiredDataError

class V1(khoros_object)This class includes methods for performing base Community API v1 requests.

__init__(khoros_object)This method initializes the khoros.core.Khoros.V1 inner class object.



get(endpoint, query_params=None, return_json=True, proxy_user_object=None)This method makes a Community API v1 GET request.



Parameters• endpoint (str) – The API endpoint to be queried

• query_params (dict) – The field and associated values to be leveraged in the querystring

• return_json (bool) – Determines if the response should be returned in JSON for-mat rather than the default



Raises ValueError, TypeError, khoros.errors.exceptions.GETRequestError,khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError

post(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False,proxy_user_object=None)

This method makes a Community API v1 POST request.













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





• params_in_uri (bool) – Determines if query parameters should be passed in theURI rather than in the request body (False by default)

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

Caution: This is not yet fully supported and therefore should not be used at thistime.



Raises ValueError, TypeError, khoros.errors.exceptions.POSTRequestError,khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

put(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False,proxy_user_object=None)This method makes a Community API v1 PUT request.




Caution: While PUT requests are technically supported in this library, at this time they are notyet supported by the Khoros Community API v1 endpoints.




















Raises ValueError, TypeError, khoros.errors.exceptions.PUTRequestError,khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

search(endpoint, filter_field, filter_value, return_json=False, fail_on_no_results=False,proxy_user_object=None)

This method performs a search for a particular field value using a Community API v1 call.



Parameters• endpoint (str) – The API v1 endpoint against which to perform the search query

• filter_field (str) – The name of the field being queried within the API v1 end-point

• filter_value (str, int) – The value associated with the field being queried

• return_json (bool) – Determines if the response should be returned in JSON for-mat (False by default)

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



Raises khoros.errors.exceptions.GETRequestErrorclass V2(khoros_object)

This class includes methods for performing base Community API v2 requests.

















get(endpoint, return_json=True, headers=None, proxy_user_object=None)This method performs a Community API v2 GET request that leverages the Khoros authorizationheaders.


Parameters• endpoint (str) – The API v2 endpoint aginst which to query

• return_json (bool) – Determines if the API response should be converted intoJSON format (True by default)

• headers (dict, None) – Allows the API call headers to be manually defined ratherthan using only the core object


Returns The API response from the GET request

Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError

post(endpoint, payload=None, return_json=True, content_type=None, headers=None,multipart=False, proxy_user_object=None)

This method performs a Community API v2 POST request that leverages the Khoros authorizationheaders.


Parameters• endpoint (str) – The relative (default) or fully-qualified URL for the API call

• payload (dict, str, None) – The JSON or plaintext payload (if any) to be sup-plied with the API request

Todo: Add support for other payload formats such as binary, etc.


• content_type (str, None) – Allows the content-type value to be explicitlydefined if necessary

Note: If this parameter is not defined then the content type will be identified basedon the payload format and/or type of request.















• multipart (bool) – Defines whether or not the query is a multipart/form-dataquery (False by default)




put(endpoint, payload=None, return_json=True, content_type=None, headers=None, multipart=False,proxy_user_object=None)This method performs a Community API v2 PUT request that leverages the Khoros authorizationheaders.











Returns The API response from the PUT request

Raises ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.PayloadMismatchError

__init__(defined_settings=None, community_url=None, tenant_id=None, community_name=None,auth_type=None, session_auth=None, oauth2=None, sso=None, helper=None,env_variables=None, auto_connect=True, use_community_name=False, prefer_json=True,debug_mode=False, skip_env_variables=False, empty=False, ssl_verify=None)













This method instantiates the core Khoros object.

Changed in version 4.3.0: Fixed an issue where the ssl_verify parameter was being mostly disregarded.

Changed in version 4.2.0: Introduced support for LithiumSSO Token authentication and made some gen-eral code improvements.

Changed in version 3.4.0: Introduced the ssl_verify parameter and established a key-value pair for it inthe core_settings dictionary for the object.

Changed in version 3.3.2: Method arguments are no longer ignored if they are implicitly False and insteadonly the arguments that explicitly have a None value are ignored. The skip_env_variables argumenthas also been introduced to explicitly ignore any valid environment variables, as well as the empty argu-ment to optionally instantiate an empty instantiated object. Logging was also added in various locationsthroughout the method.

Changed in version 3.3.0: Changed settings to defined_settings and _settings to_core_settings.

Parameters• defined_settings (dict, None) – Predefined settings that the object should use

• community_url (str, None) – The base URL of the Khoros community instance(e.g. community.khoros.com)

• tenant_id (str, None) – The tenant ID for the Khoros community instance (e.g.lithosphere)

• community_name (str, None) – The community name (e.g. community-name) forthe Khoros community instance

• auth_type (str, None) – The authentication type to use when connecting to theinstance (session_auth by default)

• session_auth (dict, None) – The username and password values for session keyauthentication

• oauth2 (dict, None) – The client_id, client_secret and redirect_url val-ues for OAuth 2.0 authentication

• sso (dict, None) – The values for single sign-on (SSO) authentication

• helper (str, tuple, list, dict, None) – The path (and optional file type) tothe YAML or JSON helper configuration file

• env_variables (dict, str, None) – A dictionary (or file path to a YAML orJSON file) that maps environment variable names

• auto_connect (bool) – Determines if a connection should be established when ini-tialized (True by default)

• use_community_name (bool) – Defines if the community name should be used inthe API URLs (False by default)

• prefer_json (bool) – Defines preference that API responses be returned in JSONformat (True by default)

• debug_mode (bool) – Determines if Debug Mode should be enabled for developmentpurposes (False by default)

• skip_env_variables (bool) – Explicitly ignores any valid environment variables(False by default)






















• empty (bool) – Instantiates an empty object to act as a placeholder with default values(False by default)

• ssl_verify (bool, None) – Determines whether or not to verify the server’s TLScertificate (True by default)

Raises khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.SessionAuthenticationError

close()

This core method destroys the instance.

Changed in version 3.5.0: The unnecessary pass statement at the end of the method has been removed.

connect(connection_type=None)This method establishes a connection to the environment using a specified authentication type.

Changed in version 4.2.0: Introduced support for LithiumSSO Token authentication and made generalcode improvements to avoid unnecessary KeyError exceptions. Also fixed an issue with the exceptionerror message.

Changed in version 3.3.2: Added logging for the khoros.errors.exceptions.CurrentlyUnsupportedError exception.

Parameters connection_type (str, None) – The type of authentication method (e.g.session_auth)

Returns None

Raises khoros.errors.exceptions.CurrentlyUnsupportedErrorget(query_url, relative_url=True, return_json=True, headers=None, proxy_user_object=None)

This method performs a simple GET request that leverages the Khoros authorization headers.

Changed in version 4.2.0: Resolved an issue that caused errors with absolute URLs, and made generalcode improvements were made to avoid unnecessary KeyError exceptions.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to beperformed on behalf of other users.

Parameters• query_url (str) – The relative (default) or fully-qualified URL for the API call

• relative_url (bool) – Determines if the URL should be appended to the commu-nity domain (True by default)



• proxy_user_object (class[khoros.objects.users.ImpersonatedUser],None) – Instantiated khoros.objects.users.ImpersonatedUser object toperform the API request on behalf of a secondary user.


Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError,khoros.errors.exceptions.GETRequestError




https://docs.python.org/3/library/exceptions.html#KeyError










get_platform_version(full_release=False, simple=False, commit_id=False, timestamp=False)This method retrieves the Khoros Community platform version information for a given environment.


Parameters• full_release (bool) – Defines if the full platform release version should be returned

Note: If none of the options are enabled then the full_release option will beenabled by default.

• simple (bool) – Defines if the simple X.Y version (e.g. 20.6) should be returned(False by default)

• commit_id (bool) – Defines if the Commit ID (i.e. hash) for the release should bereturned (False by default)

• timestamp (bool) – Defines if the timestamp of the release (e.g. 2007092156) shouldbe returned (False by default)

Returns One or more string with version information

Raises khoros.errors.exceptions.GETRequestErrorget_session_key(username=None, password=None)

This method retrieves the session key for an authentication session.


Parameters• username (str, None) – The username (i.e. login) of a secondary user to authenti-

cate (optional)

• password (str, None) – The password of a secondary user to authenticate (optional)

Caution: It is recommended that the khoros.core.Khoros.users.impersonate_user`() method be used instead of authenticating as a secondaryuser with this method.

Returns The session key in string format

Raises khoros.errors.exceptions.SessionAuthenticationErrorget_total_count(collection, where_filter='', verify_success=True)

This method retrieves the total asset count from a given collection (e.g. categories).

Parameters• collection (str) – The collection object to use in the FROM clause of the LiQL

query (e.g. users)

• where_filter (str) – An optional filter to use as the WHERE clause in the LiQLquery

• verify_success (bool) – Determines if the API query should be verified as suc-cessful (True by default)

Returns The total count as an integer












Raises khoros.errors.exceptions.GETRequestErrorstatic parse_v2_response(json_response, return_dict=False, status=False, error_msg=False,

http_code=False, data_id=False, data_url=False, data_api_uri=False,v2_base='')

This method parses an API response for a Community API v2 operation and returns parsed data.

Changed in version 3.2.0: The lower-level function call now utilizes keyword arguments to fix an argumentmismatch issue.





• error_msg (bool) – Defines if the error message (and developer response message)should be returned


• data_id (bool) – Defines if the ID should be returned

• data_url (bool) – Defines if the URL should be returned

• data_api_uri (bool) – Defines if the API URI should be returned



Raises khoros.errors.exceptions.MissingRequiredDataErrorperform_v1_search(endpoint, filter_field, filter_value, return_json=False, fail_on_no_results=False)



Deprecated since version 3.0.0: Use the khoros.core.Khoros.V1.search() method instead.




• return_json (bool) – Determines if the response should be returned in JSON format(False by default)

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





















post(query_url, payload=None, relative_url=True, return_json=True, content_type=None, headers=None,multipart=False, proxy_user_object=None)This method performs a simple POST request that leverages the Khoros authorization headers.



Changed in version 3.5.0: The query_url no longer gets prefixed with a slash (/) if relative_url isset to False.

Changed in version 3.1.1: The content_type parameter now gets defined as an empty string prior tocalling the sub-function.



• payload (dict, str, None) – The JSON or plaintext payload (if any) to be suppliedwith the API request




• content_type (str, None) – Allows the content-type value to be explicitly de-fined if necessary







put(query_url, payload=None, relative_url=True, return_json=True, content_type=None, headers=None,multipart=False, proxy_user_object=None)This method performs a simple PUT request that leverages the Khoros authorization headers.





























query(query, return_json=True, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='',format_statements=True, return_items=False)

This method performs a Community API v2 query using LiQL with the full LiQL syntax.

Changed in version 4.1.0: The JSON response can now be reduced to just the returned items by passingreturn_items=True.

Parameters• query (str) – The full LiQL query in its standard syntax (not URL-encoded)














• return_json (bool) – Determines if the API response should be returned in JSONformat (True by default)

• pretty_print (bool) – Defines if the response should be “pretty printed” (Falseby default)

• track_in_lsi (bool) – Defines if the query should be tracked within LSI (Falseby default)

• always_ok (bool) – Defines if the HTTP response should always be 200 OK (Falseby default)

• error_code (str) – Allows an error code to optionally be supplied for testing pur-poses (ignored by default)

• format_statements (bool) – Determines if statements (e.g. SELECT, FROM, et.)should be formatted to be in all caps (True by default)

• return_items (bool) – Reduces the JSON response to be only the list of items re-turned from the LiQL response (False by default)

Note: If an error response is returned then an empty list will be returned.

Returns The query response from the API in JSON format (unless defined otherwise)

Raises khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.GETRequestError

search(select_fields, from_source, where_filter='', order_by=None, order_desc=True, limit=0,return_json=True, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='',format_statements=True)

This method performs a LiQL query in the Community API v2 by specifying the query elements.

Parameters• select_fields (str, tuple, list, set) – One or more fields to be selected

within the SELECT statement (e.g. id)

• from_source (str) – The source of the data to use in the FROM statement (e.g.messages)

• where_filter (str, tuple, list, dict, set) – The filters (if any) to use inthe WHERE clause (e.g. id = '2')

• order_by (str, tuple, set, dict, list) – The field(s) by which to order theresponse data (optional)

• order_desc (bool) – Defines if the ORDER BY directionality is DESC (default) orASC

• limit (int) – Allows an optional limit to be placed on the response items (ignoredby default)





































Raises khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.OperatorMismatchError, khoros.errors.exceptions.InvalidOperatorError

signout()

This method invalidates the active session key or SSO authentication session.

Changed in version 3.5.0: The unnecessary return statement at the end of the method has been removed.

Changed in version 3.3.2: Logging was introduced to report the successful session invalidation.

Return to Top

1.7.2 Core Module (khoros.core)

This module contains the core object and functions to establish the connection to the API and leverage it to performvarious actions.

Module khoros.core

Synopsis Collection of core functions and tools to work with the Khoros Community APIs

Usage import khoros.core (Imported by default in primary package)

Example khoros = Khoros(helper='helper.yml')



Modified Date 13 Nov 2021

class khoros.core.Khoros(defined_settings=None, community_url=None, tenant_id=None,community_name=None, auth_type=None, session_auth=None, oauth2=None,sso=None, helper=None, env_variables=None, auto_connect=True,use_community_name=False, prefer_json=True, debug_mode=False,skip_env_variables=False, empty=False, ssl_verify=None)

This is the class for the core object leveraged in this library.

class Album(khoros_object)This class includes methods for interacting with the albums collection.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Album inner class object.








create(title=None, description=None, owner_id=None, hidden=False, default=False,full_response=False)

This method creates a new image album for a user.


Parameters• title (str, None) – The title of the album to be created

• description (str, None) – The description of the album

• owner_id (str, int, None) – The User ID of the album owner


• hidden (bool) – Defines if the album should be public (default) or hidden

• default (bool) – Defines if this will be the default album for the user (False bydefault)

• full_response (bool) – Defines if the full response should be returned instead ofthe outcome (False by default)


get_albums_for_user(user_id=None, login=None, public=None, private=None,verify_success=False, allow_exceptions=True)



Parameters• user_id (str, int) – The User ID for the album owner

• login (str) – The username of the album owner

• public (bool) – Indicates that public albums should be returned (all albums re-turned by default)

• private (bool) – Indicates that private albums should be returned (all albumsreturned by default)

• verify_success (bool) – Optionally check to confirm that the API query wassuccessful (False by default)

• allow_exceptions (bool) – Defines whether or not exceptions can be raised forresponses returning errors


Returns A list of dictionaries representing each album

Raises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError

















class Archives(khoros_object)This class includes methods for archiving content.


__init__(khoros_object)This method initializes the khoros.core.Khoros.Archives inner class object.





Parameters• results (list, dict) – The results from an archive or unarchive operation

• include_raw (bool) – Includes the raw API response in the aggregated data dic-tionary under the raw key (False by default)

Returns A dictionary with fields for status, archived, unarchived, failed andunknown or the raw response when the API call completely fails, with the optionalraw data when requested


This method archives one or more messages while providing an optional suggested URL as a place-holder.


Parameters• message_id (str, int, None) – The message ID for the content to be archived

• message_url (str, None) – The URL of the message to be archived (as an alter-native to the message_id argument)

• suggested_url (str, None) – The full URL to suggest to the user when navigat-ing to the archived message

• archive_entries (dict, list, tuple, set, None) – A dictionary mappingone or more message IDs with accompanying suggested URLs

Note: Alternatively, a list, tuple or set of message IDs can be supplied which willbe converted into a dictionary with blank suggested URLs.

• aggregate_results (bool) – Aggregates the operation results into an easy-to-parse dictionary (False by default)
























• message_url (str, None) – The URL of the message to be archived (as an alter-native to the message_id argument)

• new_board_id (str, None) – The board ID of what will be the new parent boardof a message getting unarchived

• archive_entries (dict, list, tuple, set, None) – A dictionary mappingone or more message IDs with accompanying board IDs

Note: Alternatively, a list, tuple or set of message IDs can be supplied which willbe converted into a dictionary with blank board IDs.

• aggregate_results (bool) – Aggregates the operation results into an easy-to-parse dictionary (False by default)





class Board(khoros_object)This class includes methods for interacting with boards.


__init__(khoros_object)This method initializes the khoros.core.Khoros.Board inner class object.

















Parameters• board_id (str, None) – The ID of the board to check

• board_url (str, None) – The URL of the board to check

Returns Boolean value indicating whether or not the board already exists

Raises khoros.errors.exceptions.MissingRequiredDataErrorcreate(board_id, board_title, discussion_style, description=None, parent_category_id=None,

hidden=None, allowed_labels=None, use_freeform_labels=None,use_predefined_labels=None, predefined_labels=None, media_type=None,blog_authors=None, blog_author_ids=None, blog_author_logins=None,blog_comments_enabled=None, blog_moderators=None, blog_moderator_ids=None,blog_moderator_logins=None, one_entry_per_contest=None, one_kudo_per_contest=None,posting_date_end=None, posting_date_start=None, voting_date_end=None,voting_date_start=None, winner_announced_date=None, full_response=None,return_id=None, return_url=None, return_api_url=None, return_http_code=None,return_status=None, return_error_messages=None, split_errors=False)


Changed in version 2.5.2: Changed the functionality around the return_error_messages argu-ment and added the split_errors argument.


Parameters• board_id (str) – The unique identifier (i.e. id field) for the new board (Required)• board_title (str) – The title of the new board (Required)• discussion_style (str) – Defines the board as a blog, contest, forum, idea,qanda or tkb (Required)

• description (str, None) – A brief description of the board

• parent_category_id (str, None) – The ID of the parent category (if applicable)

• hidden (bool, None) – Defines whether or not the new board should be hiddenfrom lists and menus (disabled by default)


• use_freeform_labels (bool, None) – Determines if freeform labels should beutilized

• use_predefined_labels (bool, None) – Determines if pre-defined labelsshould be utilized

• predefined_labels (list, None) – The pre-defined labels to utilized on theboard as a list of dictionaries
















• media_type (str, None) – The media type associated with a contest. (image,video or story meaning text)

• blog_authors (list, None) – The approved blog authors in a blog board as a listof user data dictionaries

• blog_author_ids (list, None) – A list of User IDs representing the approvedblog authors in a blog board

• blog_author_logins (list, None) – A list of User Logins (i.e. usernames) rep-resenting approved blog authors in a blog board

• blog_comments_enabled (bool, None) – Determines if comments should be en-abled on blog posts within a blog board

• blog_moderators (list, None) – The designated blog moderators in a blogboard as a list of user data dictionaries

• blog_moderator_ids (list, None) – A list of User IDs representing the blogmoderators in a blog board

• blog_moderator_logins (list, None) – A list of User Logins (i.e. usernames)representing blog moderators in a blog board

• one_entry_per_contest (bool, None) – Defines whether a user can submit onlyone entry to a single contest

• one_kudo_per_contest (bool, None) – Defines whether a user can vote onlyonce per contest

• posting_date_end (type[datetime.datetime], None) – The date/time whenthe contest is closed to submissions

• posting_date_start (type[datetime.datetime], None) – The date/timewhen the voting period for a contest begins

• voting_date_end (type[datetime.datetime], None) – The date/time whenthe voting period for a contest ends

• voting_date_start (type[datetime.datetime], None) – The date/timewhen the voting period for a contest begins

• winner_announced_date (type[datetime.datetime], None) – Thedate/time the contest winner will be announced

• full_response (bool, None) – Determines whether the full, raw API responseshould be returned by the function

• return_id (bool, None) – Determines if the ID of the new board should be re-turned by the function

• return_url (bool, None) – Determines if the URL of the new board should bereturned by the function

• return_api_url (bool, None) – Determines if the API URL of the new boardshould be returned by the function

• return_http_code (bool, None) – Determines if the HTTP Code of the APIresponse should be returned by the function






























• return_error_messages (bool, None) – Determines if the Developer Re-sponse Message (if any) associated with the API response should be returned bythe function



Raises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError, ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError



Parameters url (str) – The URL from which to parse out the Board ID

Returns The Board ID retrieved from the URL

Raises khoros.errors.exceptions.InvalidURLErrorstructure_payload(board_id, board_title, discussion_style, description=None,

parent_category_id=None, hidden=None, allowed_labels=None,use_freeform_labels=None, use_predefined_labels=None,predefined_labels=None, media_type=None, blog_authors=None,blog_author_ids=None, blog_author_logins=None,blog_comments_enabled=None, blog_moderators=None,blog_moderator_ids=None, blog_moderator_logins=None,one_entry_per_contest=None, one_kudo_per_contest=None,posting_date_end=None, posting_date_start=None, voting_date_end=None,voting_date_start=None, winner_announced_date=None)






• hidden (bool, None) – Defines whether or not the new board should be hiddenfrom lists and menus (disabled by default)

















• use_predefined_labels (bool, None) – Determines if pre-defined labelsshould be utilized

• predefined_labels (list, None) – The pre-defined labels to utilized on theboard as a list of dictionaries


• media_type (str, None) – The media type associated with a contest. (image,video or story i.e. text)


• blog_author_ids (list, None) – A list of User IDs representing the approvedblog authors in a blog board



• blog_moderators (list, None) – The designated blog moderators in a blogboard as a list of user data dictionaries

• blog_moderator_ids (list, None) – A list of User IDs representing the blogmoderators in a blog board



• one_kudo_per_contest (bool, None) – Defines whether a user can vote onlyonce per contest




• voting_date_start (type[datetime.datetime], None) – The date/timewhen the voting period for a contest begins

• winner_announced_date (type[datetime.datetime], None) – Thedate/time the contest winner will be announced

Returns The full and properly formatted payload for the API request

Raises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidNodeTypeError

class Category(khoros_object)This class includes methods for interacting with categories.

























__init__(khoros_object)This method initializes the khoros.core.Khoros.Category inner class object.




Parameters• category_id (str, None) – The ID of the category to check

• category_url (str, None) – The URL of the category to check

Returns Boolean value indicating whether or not the category already exists

Raises khoros.errors.exceptions.MissingRequiredDataErrorcreate(category_id, category_title, parent_id=None, return_json=True)

This method creates a new category.


Parameters• category_id (str) – The Category ID of the new category (e.g. video-games)

• category_title (str) – The title of the new category (e.g. Video Games)

• parent_id (str, None) – The Category ID of the parent category (optional)

• return_json (bool) – Determines whether or not the response should be returnedin JSON format (True by default)

Returns The response from the API call

Raises ValueError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.APIConnectionError



Parameters• identifier (str, None) – The Category ID or Category URL with which to iden-

tify the category

• category_details (dict, None) – Dictionary containing community details(optional)

Returns Boolean indicating if friendly dates are enabled
















tify the category


Returns The name of the active skin in string format




Parameters• identifier (str) – The Category ID or Category URL with which to identify the

category


Returns The community details within a dictionary




Parameters• field (str) – The field whose value to return from the khoros.structures.base.Mapping class

• identifier (str, None) – The Category ID or Category URL with which to iden-tify the category



Raises khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError


Parameters url (str) – The URL from which to parse out the Category ID

Returns The Category ID retrieved from the URL

Raises khoros.errors.exceptions.InvalidURLError











get_creation_date(identifier=None, category_details=None)This method retrieves the creation date of a given category.



tify the category


Returns The creation of the category in string format





tify the category


Returns The depth of the category as an integer





tify the category




get_friendly_date_max_age(identifier=None, category_details=None)This method retrieves the maximum age where friendly dates should be used (if enabled) for a cate-gory.











tify the category


Returns Integer representing the number of days the friendly date feature should be lever-aged if enabled





tify the category


Returns The language (e.g. en) in string format





tify the category


Returns The parent ID in string format




Parameters











Returns The parent type in string format





tify the category


Returns The parent URL in string format





tify the category


Returns The position of the category as an integer





tify the category











Returns The root category ID in string format





tify the category


Returns The root category type in string format





tify the category


Returns The root category URL in string format





tify the category

• full_title (bool) – Return the full title of the environment (True by default)

• short_title (bool) – Return the short title of the environment (False by default)












Returns The title(s) of the environment as a string or a tuple of strings






Returns The total number of categories as an integer

Raises khoros.errors.exceptions.GETRequestErrorget_total_count()




Raises khoros.errors.exceptions.GETRequestErrorget_url(category_id=None, category_details=None)

This method retrieves the URL of a given category.


Parameters• category_id (str, None) – The ID of the category to be evaluated (optional ifcategory_details provided)


Returns The full URL of the category





tify the category


Returns The total number of views













tify the category


Returns Boolean value indicating if the category is hidden


class Community(khoros_object)This class includes methods for interacting with the overall Khoros Community.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Community inner class object.





Parameters community_details (dict, None) – Dictionary containing communitydetails (optional)

Returns Boolean value indicating if email configuration is required before posting

Raises khoros.errors.exceptions.GETRequestErrorfriendly_date_enabled(community_details=None)

This method if the friendly date functionality is utilized within the environment.



Returns Boolean value indicating if the feature is enabled

Raises khoros.errors.exceptions.GETRequestErrorget_active_skin(community_details=None)

This method retrieves the primary active skin that is utilized within the environment.









Returns The skin name as a string

Raises khoros.errors.exceptions.GETRequestErrorget_community_details()




Raises khoros.errors.exceptions.GETRequestErrorget_community_field(field, community_details=None)

This method retrieves a particular field from the community collection in the API.









Returns The creation date as a string (e.g. 2020-02-03T22:41:36.408-08:00)

Raises khoros.errors.exceptions.GETRequestErrorget_date_pattern(community_details=None)

This method retrieves the date pattern (e.g. yyyy-MM-dd) utilized within the environment.



Returns The date pattern in string format

Raises khoros.errors.exceptions.GETRequestErrorget_description(community_details=None)

This method retrieves the description of the environment.












Raises khoros.errors.exceptions.GETRequestErrorget_friendly_date_max_age(community_details=None)

This method identifies if the friendly date functionality is utilized within the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_language(community_details=None)

This method retrieves the language (e.g. en) utilized in the environment.



Returns The language code as a string

Raises khoros.errors.exceptions.GETRequestErrorget_max_attachments(community_details=None)

This method retrieves the maximum number of attachments permitted per message within the envi-ronment.



Returns The value as an integer

Raises khoros.errors.exceptions.GETRequestErrorget_ooyala_player_branding_id(community_details=None)

This method retrieves the branding ID for the Ooyala Player utilized within the environment.



Returns The branding ID in string format

Raises khoros.errors.exceptions.GETRequestErrorget_permitted_attachment_types(community_details=None)

This method retrieves the attachment file types permitted within the environment.



Returns The permitted file types within a list









get_primary_url(community_details=None)This method retrieves the primary URL of the environment.



Returns The primary URL in string format

Raises khoros.errors.exceptions.GETRequestErrorget_sign_out_url(community_details=None)

This method retrieves the Sign Out URL for the environment.



Returns The Sign Out URL as a string

Raises khoros.errors.exceptions.GETRequestErrorget_tenant_id(community_details=None)

This method retrieves the tenant ID of the environment.



Returns The tenant ID in string format

Raises khoros.errors.exceptions.GETRequestErrorget_title(full_title=True, short_title=False, community_details=None)

This method retrieves the full and/or short title of the environment.


Parameters• full_title (bool) – Return the full title of the environment (True by default)


• community_details (dict, None) – Dictionary containing community details(optional)


Raises khoros.errors.exceptions.GETRequestErrorshow_breadcrumb_at_top_level(community_details=None)

This method identifies if breadcrumbs should be shown at the top level of the environment.



Returns Boolean value indicating if breadcrumbs are displayed at the top level of the en-vironment











show_community_node_in_breadcrumb(community_details=None)This method identifies if the community node should be shown in breadcrumbs.



Returns Boolean value indicating if the community node is displayed in bredcrumbs

Raises khoros.errors.exceptions.GETRequestErrortop_level_categories_enabled(community_details=None)

This method identifies if top level categories are enabled within the environment.



Returns Boolean value indicating if top level categories are enabled

Raises khoros.errors.exceptions.GETRequestErrortop_level_categories_on_community_page(community_details=None)

This method identifies if top level categories are enabled on community pages.



Returns Boolean value indicating if top level categories are enabled on community pages

Raises khoros.errors.exceptions.GETRequestErrorclass GroupHub(khoros_object)

This class includes methods for interacting with group hubs.

__init__(khoros_object)This method initializes the khoros.core.Khoros.GroupHub inner class object.


create(group_id, group_title, description=None, membership_type=None, open_group=None,closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None,enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None,enable_tkb=None, all_styles_default=True, parent_category_id=None,avatar_image_path=None, full_response=None, return_id=None, return_url=None,return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False)



Parameters• group_id (str, int) – The unique identifier (i.e. id field) for the new group hub

(Required)• group_title (str) – The title of the group hub (Required)• description (str, None) – A brief description of the group hub










• membership_type (dict, None) – The membership_type value (open, closedor closed_hidden)

• open_group (bool, None) – Defines the group hub as an open group

• closed_group (bool, None) – Defines the group hub as a closed group

• hidden_group (bool, None) – Defines the group hub as a closed and hidden group

• discussion_styles (list, None) – A list of discussion styles that will be per-mitted in the group hub

• enable_blog (bool, None) – Defines that the blog discussion style should be en-abled for the group hub

• enable_contest (bool, None) – Defines that the contest discussion style shouldbe enabled for the group hub

• enable_forum (bool, None) – Defines that the forum discussion style should beenabled for the group hub

• enable_idea (bool, None) – Defines that the idea discussion style should be en-abled for the group hub

• enable_qanda (bool, None) – Defines that the Q&A (qanda) discussion styleshould be enabled for the group hub

• enable_tkb (bool, None) – Defines that the TKB (tkb) discussion style shouldbe enabled for the group hub

• all_styles_default (bool) – Enables all discussion styles if not otherwise spec-ified

• parent_category_id (str, int, None) – The parent category identifier (if ap-plicable)

• avatar_image_path (str, None) – The file path to the avatar image to be up-loaded (if applicable)



• return_id (bool, None) – Determines if the ID of the new group hub should bereturned by the function

• return_url (bool, None) – Determines if the URL of the new group hub shouldbe returned by the function

• return_api_url (bool, None) – Determines if the API URL of the new grouphub should be returned by the function


























• return_error_messages (bool, None) – Determines if any error messages as-sociated with the API response should be returned by the function




get_total_count()

This method returns the total number of group hubs within the Khoros Community environment.

Returns The total number of group hubs as an integer



Parameters• grouphub_id (str, None) – The ID of the group hub to check

• grouphub_url (str, None) – The URL of the group hub to check

Returns Boolean value indicating whether or not the group hub already exists

Raises khoros.errors.exceptions.MissingRequiredDataErrorstructure_payload(group_id, group_title, description=None, membership_type=None,

open_group=None, closed_group=None, hidden_group=None,discussion_styles=None, enable_blog=None, enable_contest=None,enable_forum=None, enable_idea=None, enable_qanda=None,enable_tkb=None, all_styles_default=True, parent_category_id=None)









• discussion_styles (list, None) – A list of discussion styles that will be per-mitted in the group hub
















• enable_blog (bool, None) – Defines if the blog discussion style should be en-abled for the group hub

• enable_contest (bool, None) – Defines if the contest discussion style shouldbe enabled for the group hub

• enable_forum (bool, None) – Defines if the forum discussion style should beenabled for the group hub

• enable_idea (bool, None) – Defines if the idea discussion style should be en-abled for the group hub

• enable_qanda (bool, None) – Defines if the Q&A (qanda) discussion styleshould be enabled for the group hub

• enable_tkb (bool, None) – Defines if the TKB (tkb) discussion style should beenabled for the group hub

• all_styles_default (bool) – Defines if all discussion styles should be enabledif not otherwise specified


Returns The properly formatted payload for the API request

Raises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.InvalidPayloadValueError

update_title(new_title, group_hub_id=None, group_hub_url=None, full_response=None,return_id=None, return_url=None, return_api_url=None, return_http_code=None,return_status=None, return_error_messages=None, split_errors=False)



Parameters• new_title (str) – The new title for the group hub

• group_hub_id (str, None) – The group hub ID that identifies the group hub toupdate (necessary if URL not provided)

• group_hub_url (str, None) – The group hub URL that identifies the group hubto update (necessary if ID not provided)





• return_api_url (bool, None) – Determines if the API URL of the new grouphub should be returned by the function





















• return_error_messages (bool, None) – Determines if any error messages as-sociated with the API response should be returned by the function




class Message(khoros_object)This class includes methods for interacting with messages.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Message inner class object.


create(subject=None, body=None, node=None, node_id=None, node_url=None,canonical_url=None, context_id=None, context_url=None, cover_image=None, images=None,is_answer=None, is_draft=None, labels=None, product_category=None, products=None,read_only=None, seo_title=None, seo_description=None, tags=None,ignore_non_string_tags=False, teaser=None, topic=None, videos=None,attachment_file_paths=None, full_payload=None, full_response=None, return_id=None,return_url=None, return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False, proxy_user_object=None)


Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to becreated on behalf of other users.

Changed in version 4.3.0: It is now possible to pass the pre-constructed full JSON payload into thefunction via the full_payload parameter as an alternative to defining each field individually.



Parameters• subject (str, None) – The title or subject of the message


















• context_id (str, None) – Metadata on a message to identify the message withan external identifier of your choice



• images (dict, None) – The query to retrieve images uploaded to the message

• is_answer (bool, None) – Designates the message as an answer on a Q&A board












• videos (dict, None) – The query to retrieve videos uploaded to the message

• attachment_file_paths (str, tuple, list, set, None) – The full path(s)to one or more attachment (e.g. path/to/file1.pdf)

• full_payload (dict, str, None) – Pre-constructed full JSON payload as a dic-tionary (preferred) or a JSON string with the following syntax:


}}












































Note: This argument is necessary if the Title and URL are not explicitly passedusing the title and url function arguments.

• content_id (str, int, None) – The Message ID (aka Content ID) associatedwith the content mention

















• title (str, None) – The display title for the content mention (e.g. "ClickHere")






Parameters• user_info (dict, None) – A dictionary containing the 'id' and/or 'login'

key(s) with the user information

Note: This argument is necessary if the User ID and/or Login are not explicitlypassed using the user_id and/or login function arguments.







Parameters• msg_id (str, int) – The ID of the message for which the metadata will be re-

trieved





This method parses an API response for a message operation (e.g. creating a message) and returnsdata.













Changed in version 3.2.0: The lower-level function call now utilizes keyword arguments to fix anargument mismatch issue.

Deprecated since version 2.5.0: Use the khoros.core.Khoros.parse_v2_response() functioninstead.



• return_dict (bool) – Defines if the parsed data should be returned within a dic-tionary






• message_api_uri (bool) – Defines if the ** message API URI** should be re-turned



Raises khoros.errors.exceptions.MissingRequiredDataErrorupdate(msg_id=None, msg_url=None, subject=None, body=None, node=None, node_id=None,

node_url=None, canonical_url=None, context_id=None, context_url=None,cover_image=None, is_draft=None, labels=None, moderation_status=None, parent=None,product_category=None, products=None, read_only=None, topic=None, status=None,seo_title=None, seo_description=None, tags=None, overwrite_tags=False,ignore_non_string_tags=False, teaser=None, attachments_to_add=None,attachments_to_remove=None, full_response=None, return_id=None, return_url=None,return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False, proxy_user_object=None)


Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to beupdated on behalf of other users.





























• context_id (str, None) – Metadata on a message to identify the message withan external identifier of your choosing













Caution: This property is not returned if the message has the defaultUnspecified status assigned. It will only be returned for ideas with a statusof Completed or with a custom status created in Community Admin.






























Note: Each attachment should specify the attachment id of the attachment to re-move, which begins with m#_. (e.g. m283_file1.pdf)









































Raises khoros.errors.exceptions.InvalidMessagePayloadErrorclass Node(khoros_object)

This class includes methods for interacting with nodes.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Node inner class object.


get_avatar_url(identifier, node_details=None, original=True, tiny=False, small=False,medium=False, large=False)




node


• original (bool) – Indicates if the URL for the original-size image should be re-turned (True by default)



• medium (bool) – Indicates if the URL for the image in a medium size should bereturned (False by default)







node




















node







node



























class


























node








node







node

















node







node


• include_prefix (bool) – Defines if the prefix (e.g. category:) should be in-cluded (False by default)






node
















node







node

• full_title (bool) – Determines if the full title of the node should be returned(True by default)











Parameters









• identifier (str, None) – The Node ID with which to identify the node













node







node



















Raises khoros.errors.exceptions.MissingRequiredDataErrorclass Role(khoros_object)

This class includes methods relating to roles and permissions.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Role inner class object.



assign_roles_to_user(user, lookup_type='id', roles_to_add=None, node=None,node_type='board', v1=False, return_json=True)




role




• node_type (str) – The type of node to which the role is scoped (e.g. board (de-fault), category, etc.)


• return_json (bool) – Determines if the response should be returned as JSONrather than XML (True by default)



















Parameters• role_name (str) – The name of the role (e.g. Administrator, Moderator,Owner, etc.)






Changed in version 4.1.0: The docstring has been updated to reference the correct exception raisedby this method.




• fields (str, list, tuple, set, None) – The field(s) to retrieve from theLiQL query as a string or list



Raises khoros.errors.exceptions.GETRequestErrorget_total_role_count(return_dict=False, total=True, top_level=False, board=False,

category=False, group_hub=False)This method retrieves the total role count for one or more role type(s).



(False by default)

• total (bool) – Indicates that the total overall role count should be returned (Trueby default)


















Returns The role count(s) as an integer, tuple or dictionary, depending on the argumentssupplied





Parameters• fields (str, tuple, list, set) – One or more fields from the Users object

to return (login field by default)









Note: Unless modified by Khoros Support or Professional Services, 1000 is themaximum number of entries that can be returned in a single LiQL query.



















Returns A list of users as strings, tuples or dictionaries depending if simple mode isenabled


class SAML(khoros_object)This class includes methods relating to SAML 2.0 authentication and user provisioning.


__init__(khoros_object)This method initializes the khoros.core.Khoros.SAML inner class object.


static import_assertion(file_path, base64_encode=True, url_encode=True)This method imports an XML SAML assertion as a string and optionally base64- and/or URL-encodes it.







send_assertion(assertion=None, file_path=None, base64_encode=True, url_encode=True)This method sends a SAML assertion as a POST request in order to provision a new user.


Parameters• assertion (str, None) – The SAML assertion in string format and optionally

base64- and/or URL-encoded





Raises khoros.errors.exceptions.MissingRequiredDataErrorclass Settings(khoros_object)

This class includes methods relating to the retrieval and defining of various settings.












__init__(khoros_object)This method initializes the khoros.core.Khoros.Settings inner class object.




Changed in version 3.3.2: The return_json parameter has been introduced which returns a simpleJSON object (as a dict) indicating whether or not the operation was successful. (Currently Falseby default)








Returns None

Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError,khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.PayloadMismatchError


Changed in version 3.3.2: The convert_json parameter has been introduced which optionally con-verts a JSON string into a dictionary.





• v1 (bool, None) – Optionally defines a specific Community API version to usewhen retrieving the value

















Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError,khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.LiQLParseError

class Studio(khoros_object)This class includes methods relating to the Lithium SDK and Studio Plugin.

__init__(khoros_object)This method initializes the khoros.core.Khoros.Studio inner class object.


























class Subscription(khoros_object)This class includes methods relating to subscriptions.





__init__(khoros_object)This method initializes the khoros.core.Khoros.Subscription inner class object.






Parameters• target_id (str, int) – The unique identifier for the target (e.g. Node ID, Mes-

sage ID, etc.)



















































































class Tag(khoros_object)This class includes methods relating to the tagging of content.


__init__(khoros_object)This method initializes the khoros.core.Khoros.Tag inner class object.




















Returns None




..caution:: This function is not the most effective way to add multiple tags to a message. It is recommendedthat the khoros.core.Khoros.messages.update() method be used instead with its tagsargument, which is more efficient and performance-conscious.




Returns None












Changed in version 4.3.0: Introduced the wrap_json parameter to wrap the tags in a dictionarywithin the items key.


























Returns A list of properly formatted tags to act as the value for the tags field in the mes-sage payload

class User(khoros_object)This class includes methods for interacting with users.

__init__(khoros_object)This method initializes the khoros.core.Khoros.User inner class object.





Changed in version 3.5.0: The unnecessary return statement at the end of the method has beenremoved.

Parameters• user_settings (dict, None) – Allows all user settings to be passed to the func-

tion within a single dictionary










• ignore_exceptions (bool) – Defines whether to raise the khoros.errors.exceptions.UserCreationError exception if the creation attempt fails (Falseby default)




Parameters
















• user_id (str, int) – The User ID of the user to be deleted













Note: The priority of supplied fields are as follows: User ID, username, first and last name, lastname, first name









Returns The email address of the user as a string or a list of emails if allow_multipleis True

get_followers_count(user_settings=None, user_id=None, login=None, email=None)This method gets the count of community members who have added the user as a friend in the com-munity.

Parameters























Raises khoros.errors.exceptions.GETRequestErrorget_following_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of community members the user has added as a friend in the community.






Returns The number of community members the user has added as a friend in integerformat




format
































get_kudos_given_count(user_settings=None, user_id=None, login=None, email=None)This method gets the count of kudos a user has given.
























allow_multiple=False, display_warnings=True)This is an alternative method name for the khoros.core.Khoros.User.get_username()method.





























Raises khoros.errors.exceptions.GETRequestErrorget_public_images_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of public images uploaded by the user.
































































































Returns The number of messages created by the user that are marked as accepted solutionsin integer format








Returns The number of topic messages (excluding replies) posted by the user in integerformat

Raises khoros.errors.exceptions.GETRequestErrorget_user_data(user_settings=None, user_id=None, login=None, email=None)

This method retrieves all user data for a given user.









Note: The priority of supplied fields are as follows: login, email, first and last name, last name, firstname






























Note: The priority of supplied fields are as follows: User ID, email, first and last name, last name,first name







• allow_multiple (bool) – Allows a list of usernames to be returned if multipleresults are found


Returns The username (i.e. login) of the user or a list of usernames if allow_multipleis True


























Note: The authenticated user must have the Administrator role and/or have the Switch Userpermission enabled.





Parameters• select_fields (str, tuple, list, set) – One or more SELECT field (e.g.login, messages.count(*), etc.) to query



Raises khoros.errors.exceptions.GETRequestErrorupdate_sso_id(new_sso_id, user_id=None, user_login=None)

This method updates the SSO ID for a user.







class V1(khoros_object)This class includes methods for performing base Community API v1 requests.



























post(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False,proxy_user_object=None)

This method makes a Community API v1 POST request.






























Caution: While PUT requests are technically supported in this library, at this time they are notyet supported by the Khoros Community API v1 endpoints.



























• return_json (bool) – Determines if the response should be returned in JSON for-mat (False by default)

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



Raises khoros.errors.exceptions.GETRequestErrorclass V2(khoros_object)

This class includes methods for performing base Community API v2 requests.




get(endpoint, return_json=True, headers=None, proxy_user_object=None)This method performs a Community API v2 GET request that leverages the Khoros authorizationheaders.


Parameters• endpoint (str) – The API v2 endpoint aginst which to query





Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.GETRequestError

post(endpoint, payload=None, return_json=True, content_type=None, headers=None,multipart=False, proxy_user_object=None)

This method performs a Community API v2 POST request that leverages the Khoros authorizationheaders.


Parameters













• endpoint (str) – The relative (default) or fully-qualified URL for the API call











put(endpoint, payload=None, return_json=True, content_type=None, headers=None, multipart=False,proxy_user_object=None)This method performs a Community API v2 PUT request that leverages the Khoros authorizationheaders.




























__init__(defined_settings=None, community_url=None, tenant_id=None, community_name=None,auth_type=None, session_auth=None, oauth2=None, sso=None, helper=None,env_variables=None, auto_connect=True, use_community_name=False, prefer_json=True,debug_mode=False, skip_env_variables=False, empty=False, ssl_verify=None)

This method instantiates the core Khoros object.

Changed in version 4.3.0: Fixed an issue where the ssl_verify parameter was being mostly disregarded.

Changed in version 4.2.0: Introduced support for LithiumSSO Token authentication and made some gen-eral code improvements.

Changed in version 3.4.0: Introduced the ssl_verify parameter and established a key-value pair for it inthe core_settings dictionary for the object.

Changed in version 3.3.2: Method arguments are no longer ignored if they are implicitly False and insteadonly the arguments that explicitly have a None value are ignored. The skip_env_variables argumenthas also been introduced to explicitly ignore any valid environment variables, as well as the empty argu-ment to optionally instantiate an empty instantiated object. Logging was also added in various locationsthroughout the method.

Changed in version 3.3.0: Changed settings to defined_settings and _settings to_core_settings.

Parameters• defined_settings (dict, None) – Predefined settings that the object should use

• community_url (str, None) – The base URL of the Khoros community instance(e.g. community.khoros.com)

• tenant_id (str, None) – The tenant ID for the Khoros community instance (e.g.lithosphere)

• community_name (str, None) – The community name (e.g. community-name) forthe Khoros community instance

• auth_type (str, None) – The authentication type to use when connecting to theinstance (session_auth by default)

• session_auth (dict, None) – The username and password values for session keyauthentication












• oauth2 (dict, None) – The client_id, client_secret and redirect_url val-ues for OAuth 2.0 authentication

• sso (dict, None) – The values for single sign-on (SSO) authentication

• helper (str, tuple, list, dict, None) – The path (and optional file type) tothe YAML or JSON helper configuration file

• env_variables (dict, str, None) – A dictionary (or file path to a YAML orJSON file) that maps environment variable names

• auto_connect (bool) – Determines if a connection should be established when ini-tialized (True by default)

• use_community_name (bool) – Defines if the community name should be used inthe API URLs (False by default)

• prefer_json (bool) – Defines preference that API responses be returned in JSONformat (True by default)

• debug_mode (bool) – Determines if Debug Mode should be enabled for developmentpurposes (False by default)

• skip_env_variables (bool) – Explicitly ignores any valid environment variables(False by default)

• empty (bool) – Instantiates an empty object to act as a placeholder with default values(False by default)

• ssl_verify (bool, None) – Determines whether or not to verify the server’s TLScertificate (True by default)

Raises khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.SessionAuthenticationError

close()

This core method destroys the instance.

Changed in version 3.5.0: The unnecessary pass statement at the end of the method has been removed.

connect(connection_type=None)This method establishes a connection to the environment using a specified authentication type.

Changed in version 4.2.0: Introduced support for LithiumSSO Token authentication and made generalcode improvements to avoid unnecessary KeyError exceptions. Also fixed an issue with the exceptionerror message.

Changed in version 3.3.2: Added logging for the khoros.errors.exceptions.CurrentlyUnsupportedError exception.

Parameters connection_type (str, None) – The type of authentication method (e.g.session_auth)

Returns None

Raises khoros.errors.exceptions.CurrentlyUnsupportedErrorget(query_url, relative_url=True, return_json=True, headers=None, proxy_user_object=None)

This method performs a simple GET request that leverages the Khoros authorization headers.






























get_platform_version(full_release=False, simple=False, commit_id=False, timestamp=False)This method retrieves the Khoros Community platform version information for a given environment.


Parameters• full_release (bool) – Defines if the full platform release version should be returned

Note: If none of the options are enabled then the full_release option will beenabled by default.

• simple (bool) – Defines if the simple X.Y version (e.g. 20.6) should be returned(False by default)

• commit_id (bool) – Defines if the Commit ID (i.e. hash) for the release should bereturned (False by default)

• timestamp (bool) – Defines if the timestamp of the release (e.g. 2007092156) shouldbe returned (False by default)


Raises khoros.errors.exceptions.GETRequestErrorget_session_key(username=None, password=None)

This method retrieves the session key for an authentication session.


Parameters• username (str, None) – The username (i.e. login) of a secondary user to authenti-

cate (optional)

• password (str, None) – The password of a secondary user to authenticate (optional)















Caution: It is recommended that the khoros.core.Khoros.users.impersonate_user`() method be used instead of authenticating as a secondaryuser with this method.


Raises khoros.errors.exceptions.SessionAuthenticationErrorget_total_count(collection, where_filter='', verify_success=True)

This method retrieves the total asset count from a given collection (e.g. categories).

Parameters• collection (str) – The collection object to use in the FROM clause of the LiQL

query (e.g. users)

• where_filter (str) – An optional filter to use as the WHERE clause in the LiQLquery

• verify_success (bool) – Determines if the API query should be verified as suc-cessful (True by default)


Raises khoros.errors.exceptions.GETRequestErrorstatic parse_v2_response(json_response, return_dict=False, status=False, error_msg=False,

http_code=False, data_id=False, data_url=False, data_api_uri=False,v2_base='')

This method parses an API response for a Community API v2 operation and returns parsed data.






• error_msg (bool) – Defines if the error message (and developer response message)should be returned







Raises khoros.errors.exceptions.MissingRequiredDataError















perform_v1_search(endpoint, filter_field, filter_value, return_json=False, fail_on_no_results=False)This method performs a search for a particular field value using a Community API v1 call.


Deprecated since version 3.0.0: Use the khoros.core.Khoros.V1.search() method instead.







Raises khoros.errors.exceptions.GETRequestErrorpost(query_url, payload=None, relative_url=True, return_json=True, content_type=None, headers=None,

multipart=False, proxy_user_object=None)This method performs a simple POST request that leverages the Khoros authorization headers.



Changed in version 3.5.0: The query_url no longer gets prefixed with a slash (/) if relative_url isset to False.































put(query_url, payload=None, relative_url=True, return_json=True, content_type=None, headers=None,multipart=False, proxy_user_object=None)This method performs a simple PUT request that leverages the Khoros authorization headers.






























query(query, return_json=True, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='',format_statements=True, return_items=False)

This method performs a Community API v2 query using LiQL with the full LiQL syntax.


Parameters• query (str) – The full LiQL query in its standard syntax (not URL-encoded)







• return_items (bool) – Reduces the JSON response to be only the list of items re-turned from the LiQL response (False by default)



Raises khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.GETRequestError

search(select_fields, from_source, where_filter='', order_by=None, order_desc=True, limit=0,return_json=True, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='',format_statements=True)

This method performs a LiQL query in the Community API v2 by specifying the query elements.

Parameters













• select_fields (str, tuple, list, set) – One or more fields to be selectedwithin the SELECT statement (e.g. id)


• where_filter (str, tuple, list, dict, set) – The filters (if any) to use inthe WHERE clause (e.g. id = '2')

• order_by (str, tuple, set, dict, list) – The field(s) by which to order theresponse data (optional)

• order_desc (bool) – Defines if the ORDER BY directionality is DESC (default) orASC

• limit (int) – Allows an optional limit to be placed on the response items (ignoredby default)








Raises khoros.errors.exceptions.MissingAuthDataError, khoros.errors.exceptions.OperatorMismatchError, khoros.errors.exceptions.InvalidOperatorError

signout()

This method invalidates the active session key or SSO authentication session.


Changed in version 3.3.2: Logging was introduced to report the successful session invalidation.

Return to Top


























Core Functionality Subclasses (khoros.core.Khoros)

These classes below are inner/nested classes within the core khoros.core.Khoros class.

Note: The classes themselves are PascalCase format and singular (e.g. Node, Category, etc.) whereas the namesused to call the inner class methods are all lowercase (or snake_case) and plural. (e.g. core_object.nodes.get_node_id(), core_object.categories.get_category_id(), etc.)

Studio Subclass (khoros.core.Khoros.Studio)

class Khoros.Studio(khoros_object)This class includes methods relating to the Lithium SDK and Studio Plugin.

























Return to Top



V1 Subclass (khoros.core.Khoros.V1)

class Khoros.V1(khoros_object)This class includes methods for performing base Community API v1 requests.






• return_json (bool) – Determines if the response should be returned in JSON formatrather than the default




post(endpoint, query_params=None, return_json=True, params_in_uri=False, json_payload=False,proxy_user_object=None)This method makes a Community API v1 POST request.


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

























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


Caution: While PUT requests are technically supported in this library, at this time they are not yetsupported by the Khoros Community API v1 endpoints.






























Raises khoros.errors.exceptions.GETRequestErrorReturn to Top

Core Structure Subclasses (khoros.core.Khoros)

The classes below are inner/nested classes within the core khoros.core.Khoros class.

Note: The classes themselves are PascalCase format and singular (e.g. Node, Category, etc.) whereas the namesused to call the inner class methods are all lowercase (or snake_case) and plural. (e.g. core_object.nodes.get_node_id(), core_object.categories.get_category_id(), etc.)











Board Subclass (khoros.core.Khoros.Board)

class Khoros.Board(khoros_object)This class includes methods for interacting with boards.




Parameters• board_id (str, None) – The ID of the board to check



Raises khoros.errors.exceptions.MissingRequiredDataErrorcreate(board_id, board_title, discussion_style, description=None, parent_category_id=None, hidden=None,

allowed_labels=None, use_freeform_labels=None, use_predefined_labels=None,predefined_labels=None, media_type=None, blog_authors=None, blog_author_ids=None,blog_author_logins=None, blog_comments_enabled=None, blog_moderators=None,blog_moderator_ids=None, blog_moderator_logins=None, one_entry_per_contest=None,one_kudo_per_contest=None, posting_date_end=None, posting_date_start=None,voting_date_end=None, voting_date_start=None, winner_announced_date=None,full_response=None, return_id=None, return_url=None, return_api_url=None,return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)


Changed in version 2.5.2: Changed the functionality around the return_error_messages argument andadded the split_errors argument.





• hidden (bool, None) – Defines whether or not the new board should be hidden fromlists and menus (disabled by default)



• use_predefined_labels (bool, None) – Determines if pre-defined labels shouldbe utilized
















• media_type (str, None) – The media type associated with a contest. (image,video or story meaning text)





• blog_moderators (list, None) – The designated blog moderators in a blog boardas a list of user data dictionaries









• winner_announced_date (type[datetime.datetime], None) – The date/timethe contest winner will be announced



• return_url (bool, None) – Determines if the URL of the new board should bereturned by the function

• return_api_url (bool, None) – Determines if the API URL of the new boardshould be returned by the function
































Returns Boolean value indicating a successful outcome (default), the full API response or oneor more specific fields defined by function arguments






Raises khoros.errors.exceptions.InvalidURLErrorstructure_payload(board_id, board_title, discussion_style, description=None, parent_category_id=None,

hidden=None, allowed_labels=None, use_freeform_labels=None,use_predefined_labels=None, predefined_labels=None, media_type=None,blog_authors=None, blog_author_ids=None, blog_author_logins=None,blog_comments_enabled=None, blog_moderators=None, blog_moderator_ids=None,blog_moderator_logins=None, one_entry_per_contest=None,one_kudo_per_contest=None, posting_date_end=None, posting_date_start=None,voting_date_end=None, voting_date_start=None, winner_announced_date=None)

























• use_predefined_labels (bool, None) – Determines if pre-defined labels shouldbe utilized



• media_type (str, None) – The media type associated with a contest. (image,video or story i.e. text)





• blog_moderators (list, None) – The designated blog moderators in a blog boardas a list of user data dictionaries









• winner_announced_date (type[datetime.datetime], None) – The date/timethe contest winner will be announced



Return to Top

























Category Subclass (khoros.core.Khoros.Category)

class Khoros.Category(khoros_object)This class includes methods for interacting with categories.



Parameters• category_id (str, None) – The ID of the category to check



Raises khoros.errors.exceptions.MissingRequiredDataErrorcreate(category_id, category_title, parent_id=None, return_json=True)

This method creates a new category.


Parameters• category_id (str) – The Category ID of the new category (e.g. video-games)



• return_json (bool) – Determines whether or not the response should be returnedin JSON format (True by default)






tify the category


















tify the category






Parameters• identifier (str) – The Category ID or Category URL with which to identify the

category























Raises khoros.errors.exceptions.InvalidURLErrorget_creation_date(identifier=None, category_details=None)

This method retrieves the creation date of a given category.



tify the category







tify the category







tify the category













get_friendly_date_max_age(identifier=None, category_details=None)This method retrieves the maximum age where friendly dates should be used (if enabled) for a category.



tify the category


Returns Integer representing the number of days the friendly date feature should be leveragedif enabled





tify the category







tify the category















tify the category







tify the category







tify the category















tify the category







tify the category







tify the category







tify the category




















Raises khoros.errors.exceptions.GETRequestErrorget_total_count()




Raises khoros.errors.exceptions.GETRequestErrorget_url(category_id=None, category_details=None)

This method retrieves the URL of a given category.


Parameters• category_id (str, None) – The ID of the category to be evaluated (optional ifcategory_details provided)







tify the category

















tify the category




Return to Top

Community Subclass (khoros.core.Khoros.Community)

class Khoros.Community(khoros_object)This class includes methods for interacting with the overall Khoros Community.



Parameters community_details (dict, None) – Dictionary containing community details(optional)


Raises khoros.errors.exceptions.GETRequestErrorfriendly_date_enabled(community_details=None)

This method if the friendly date functionality is utilized within the environment.











get_active_skin(community_details=None)This method retrieves the primary active skin that is utilized within the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_community_details()




Raises khoros.errors.exceptions.GETRequestErrorget_community_field(field, community_details=None)

This method retrieves a particular field from the community collection in the API.










Raises khoros.errors.exceptions.GETRequestErrorget_date_pattern(community_details=None)

This method retrieves the date pattern (e.g. yyyy-MM-dd) utilized within the environment.












get_description(community_details=None)This method retrieves the description of the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_friendly_date_max_age(community_details=None)

This method identifies if the friendly date functionality is utilized within the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_language(community_details=None)

This method retrieves the language (e.g. en) utilized in the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_max_attachments(community_details=None)

This method retrieves the maximum number of attachments permitted per message within the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_ooyala_player_branding_id(community_details=None)

This method retrieves the branding ID for the Ooyala Player utilized within the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_permitted_attachment_types(community_details=None)

This method retrieves the attachment file types permitted within the environment.











Raises khoros.errors.exceptions.GETRequestErrorget_primary_url(community_details=None)

This method retrieves the primary URL of the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_sign_out_url(community_details=None)

This method retrieves the Sign Out URL for the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_tenant_id(community_details=None)

This method retrieves the tenant ID of the environment.




Raises khoros.errors.exceptions.GETRequestErrorget_title(full_title=True, short_title=False, community_details=None)

This method retrieves the full and/or short title of the environment.


Parameters• full_title (bool) – Return the full title of the environment (True by default)


• community_details (dict, None) – Dictionary containing community details (op-tional)


Raises khoros.errors.exceptions.GETRequestErrorshow_breadcrumb_at_top_level(community_details=None)

This method identifies if breadcrumbs should be shown at the top level of the environment.












Returns Boolean value indicating if breadcrumbs are displayed at the top level of the environ-ment

Raises khoros.errors.exceptions.GETRequestErrorshow_community_node_in_breadcrumb(community_details=None)

This method identifies if the community node should be shown in breadcrumbs.




Raises khoros.errors.exceptions.GETRequestErrortop_level_categories_enabled(community_details=None)

This method identifies if top level categories are enabled within the environment.




Raises khoros.errors.exceptions.GETRequestErrortop_level_categories_on_community_page(community_details=None)

This method identifies if top level categories are enabled on community pages.





Group Hub Subclass (khoros.core.Khoros.GroupHub)

class Khoros.GroupHub(khoros_object)This class includes methods for interacting with group hubs.

create(group_id, group_title, description=None, membership_type=None, open_group=None,closed_group=None, hidden_group=None, discussion_styles=None, enable_blog=None,enable_contest=None, enable_forum=None, enable_idea=None, enable_qanda=None,enable_tkb=None, all_styles_default=True, parent_category_id=None, avatar_image_path=None,full_response=None, return_id=None, return_url=None, return_api_url=None,return_http_code=None, return_status=None, return_error_messages=None, split_errors=False)















• discussion_styles (list, None) – A list of discussion styles that will be permit-ted in the group hub

• enable_blog (bool, None) – Defines that the blog discussion style should be en-abled for the group hub

• enable_contest (bool, None) – Defines that the contest discussion style shouldbe enabled for the group hub

• enable_forum (bool, None) – Defines that the forum discussion style should beenabled for the group hub

• enable_idea (bool, None) – Defines that the idea discussion style should be en-abled for the group hub

• enable_qanda (bool, None) – Defines that the Q&A (qanda) discussion styleshould be enabled for the group hub


• all_styles_default (bool) – Enables all discussion styles if not otherwise speci-fied


• avatar_image_path (str, None) – The file path to the avatar image to be uploaded(if applicable)































• return_error_messages (bool, None) – Determines if any error messages asso-ciated with the API response should be returned by the function




get_total_count()

This method returns the total number of group hubs within the Khoros Community environment.




Parameters• grouphub_id (str, None) – The ID of the group hub to check



Raises khoros.errors.exceptions.MissingRequiredDataErrorstructure_payload(group_id, group_title, description=None, membership_type=None, open_group=None,

closed_group=None, hidden_group=None, discussion_styles=None,enable_blog=None, enable_contest=None, enable_forum=None, enable_idea=None,enable_qanda=None, enable_tkb=None, all_styles_default=True,parent_category_id=None)
























• discussion_styles (list, None) – A list of discussion styles that will be permit-ted in the group hub

• enable_blog (bool, None) – Defines if the blog discussion style should be enabledfor the group hub

• enable_contest (bool, None) – Defines if the contest discussion style should beenabled for the group hub

• enable_forum (bool, None) – Defines if the forum discussion style should be en-abled for the group hub

• enable_idea (bool, None) – Defines if the idea discussion style should be enabledfor the group hub

• enable_qanda (bool, None) – Defines if the Q&A (qanda) discussion style shouldbe enabled for the group hub

• enable_tkb (bool, None) – Defines if the TKB (tkb) discussion style should beenabled for the group hub

• all_styles_default (bool) – Defines if all discussion styles should be enabled ifnot otherwise specified




update_title(new_title, group_hub_id=None, group_hub_url=None, full_response=None, return_id=None,return_url=None, return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False)



Parameters• new_title (str) – The new title for the group hub

• group_hub_id (str, None) – The group hub ID that identifies the group hub toupdate (necessary if URL not provided)

• group_hub_url (str, None) – The group hub URL that identifies the group hub toupdate (necessary if ID not provided)



























• return_error_messages (bool, None) – Determines if any error messages asso-ciated with the API response should be returned by the function




Return to Top

Node Subclass (khoros.core.Khoros.Node)

class Khoros.Node(khoros_object)This class includes methods for interacting with nodes.

get_avatar_url(identifier, node_details=None, original=True, tiny=False, small=False, medium=False,large=False)




node


• original (bool) – Indicates if the URL for the original-size image should be returned(True by default)

















• medium (bool) – Indicates if the URL for the image in a medium size should be re-turned (False by default)







node








node






Parameters





























class




























node








node
















node







node







node











• include_prefix (bool) – Defines if the prefix (e.g. category:) should be included(False by default)






node







node







node

• full_title (bool) – Determines if the full title of the node should be returned (Trueby default)

































node
















node









Raises khoros.errors.exceptions.MissingRequiredDataErrorReturn to Top

Core Object Subclasses (khoros.core.Khoros)

The classes below are inner/nested classes within the core khoros.core.Khoros class.

Note: The classes themselves are CamelCase format and singular (e.g. Role, User, etc.) whereas the namesused to call the inner class methods are all lowercase (or snake_case) and plural. (e.g. core_object.roles.get_role_id(), core_object.users.create(), etc.)








Album Subclass (khoros.core.Khoros.Album)

class Khoros.Album(khoros_object)This class includes methods for interacting with the albums collection.

create(title=None, description=None, owner_id=None, hidden=False, default=False, full_response=False)This method creates a new image album for a user.







• default (bool) – Defines if this will be the default album for the user (False bydefault)

• full_response (bool) – Defines if the full response should be returned instead ofthe outcome (False by default)


get_albums_for_user(user_id=None, login=None, public=None, private=None, verify_success=False,allow_exceptions=True)



Parameters• user_id (str, int) – The User ID for the album owner


• public (bool) – Indicates that public albums should be returned (all albums returnedby default)

• private (bool) – Indicates that private albums should be returned (all albums re-turned by default)

• verify_success (bool) – Optionally check to confirm that the API query was suc-cessful (False by default)

• allow_exceptions (bool) – Defines whether or not exceptions can be raised forresponses returning errors





















Return to Top

Archives Subclass (khoros.core.Khoros.Archives)

class Khoros.Archives(khoros_object)This class includes methods for archiving content.





• include_raw (bool) – Includes the raw API response in the aggregated data dictio-nary under the raw key (False by default)

Returns A dictionary with fields for status, archived, unarchived, failed and unknownor the raw response when the API call completely fails, with the optional raw data whenrequested


This method archives one or more messages while providing an optional suggested URL as a placeholder.



• message_url (str, None) – The URL of the message to be archived (as an alterna-tive to the message_id argument)

• suggested_url (str, None) – The full URL to suggest to the user when navigatingto the archived message

• archive_entries (dict, list, tuple, set, None) – A dictionary mappingone or more message IDs with accompanying suggested URLs

























• message_url (str, None) – The URL of the message to be archived (as an alterna-tive to the message_id argument)

• new_board_id (str, None) – The board ID of what will be the new parent board ofa message getting unarchived

• archive_entries (dict, list, tuple, set, None) – A dictionary mappingone or more message IDs with accompanying board IDs







Return to Top














Message Subclass (khoros.core.Khoros.Message)

class Khoros.Message(khoros_object)This class includes methods for interacting with messages.

create(subject=None, body=None, node=None, node_id=None, node_url=None, canonical_url=None,context_id=None, context_url=None, cover_image=None, images=None, is_answer=None,is_draft=None, labels=None, product_category=None, products=None, read_only=None,seo_title=None, seo_description=None, tags=None, ignore_non_string_tags=False, teaser=None,topic=None, videos=None, attachment_file_paths=None, full_payload=None, full_response=None,return_id=None, return_url=None, return_api_url=None, return_http_code=None,return_status=None, return_error_messages=None, split_errors=False, proxy_user_object=None)


Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be createdon behalf of other users.

Changed in version 4.3.0: It is now possible to pass the pre-constructed full JSON payload into the functionvia the full_payload parameter as an alternative to defining each field individually.










• context_id (str, None) – Metadata on a message to identify the message with anexternal identifier of your choice

• context_url (str, None) – Metadata on a message representing a URL to associatewith the message (external identifier)























• products (dict, None) – The product in a product catalog associated with the mes-sage





• ignore_non_string_tags (bool) – Determines if non-strings (excluding iterables)should be ignored rather than converted to strings (False by default)




• attachment_file_paths (str, tuple, list, set, None) – The full path(s)to one or more attachment (e.g. path/to/file1.pdf)

• full_payload (dict, str, None) – Pre-constructed full JSON payload as a dic-tionary (preferred) or a JSON string with the following syntax:


}}


• full_response (bool, None) – Defines if the full response should be returned in-stead of the outcome (False by default)







































Note: This argument is necessary if the Title and URL are not explicitly passed usingthe title and url function arguments.

• content_id (str, int, None) – The Message ID (aka Content ID) associated withthe content mention








Parameters• user_info (dict, None) – A dictionary containing the 'id' and/or 'login' key(s)

with the user information

Note: This argument is necessary if the User ID and/or Login are not explicitly passedusing the user_id and/or login function arguments.





















Parameters• msg_id (str, int) – The ID of the message for which the metadata will be retrieved





This method parses an API response for a message operation (e.g. creating a message) and returns data.



Deprecated since version 2.5.0: Use the khoros.core.Khoros.parse_v2_response() function in-stead.









• message_api_uri (bool) – Defines if the ** message API URI** should be returned




















update(msg_id=None, msg_url=None, subject=None, body=None, node=None, node_id=None,node_url=None, canonical_url=None, context_id=None, context_url=None, cover_image=None,is_draft=None, labels=None, moderation_status=None, parent=None, product_category=None,products=None, read_only=None, topic=None, status=None, seo_title=None, seo_description=None,tags=None, overwrite_tags=False, ignore_non_string_tags=False, teaser=None,attachments_to_add=None, attachments_to_remove=None, full_response=None, return_id=None,return_url=None, return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False, proxy_user_object=None)


Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be updatedon behalf of other users.







































• products (dict, None) – The product in a product catalog associated with the mes-sage




Caution: This property is not returned if the message has the defaultUnspecified status assigned. It will only be returned for ideas with a status ofCompleted or with a custom status created in Community Admin.










• full_response (bool, None) – Defines if the full response should be returned in-stead of the outcome (False by default)









































Raises khoros.errors.exceptions.InvalidMessagePayloadErrorReturn to Top

Role Subclass (khoros.core.Khoros.Role)

class Khoros.Role(khoros_object)This class includes methods relating to roles and permissions.

assign_roles_to_user(user, lookup_type='id', roles_to_add=None, node=None, node_type='board',v1=False, return_json=True)




role




• node_type (str) – The type of node to which the role is scoped (e.g. board (default),category, etc.)



















• return_json (bool) – Determines if the response should be returned as JSON ratherthan XML (True by default)





Parameters• role_name (str) – The name of the role (e.g. Administrator, Moderator, Owner,

etc.)






Changed in version 4.1.0: The docstring has been updated to reference the correct exception raised by thismethod.




• fields (str, list, tuple, set, None) – The field(s) to retrieve from the LiQLquery as a string or list



Raises khoros.errors.exceptions.GETRequestErrorget_total_role_count(return_dict=False, total=True, top_level=False, board=False, category=False,

group_hub=False)This method retrieves the total role count for one or more role type(s).
















(False by default)

• total (bool) – Indicates that the total overall role count should be returned (True bydefault)





Returns The role count(s) as an integer, tuple or dictionary, depending on the arguments sup-plied





Parameters• fields (str, tuple, list, set) – One or more fields from the Users object to

return (login field by default)





Note: If a value is not supplied and only a role name is defined then the role scope isassumed to be at the community level. (i.e. global)






















Note: Unless modified by Khoros Support or Professional Services, 1000 is the max-imum number of entries that can be returned in a single LiQL query.


Returns A list of users as strings, tuples or dictionaries depending if simple mode is enabled


Return to Top

Settings Subclass (khoros.core.Khoros.Settings)

class Khoros.Settings(khoros_object)This class includes methods relating to the retrieval and defining of various settings.




Changed in version 3.3.2: The return_json parameter has been introduced which returns a simple JSONobject (as a dict) indicating whether or not the operation was successful. (Currently False by default)








Returns None

Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError,khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.PayloadMismatchError












Changed in version 3.3.2: The convert_json parameter has been introduced which optionally convertsa JSON string into a dictionary.





• v1 (bool, None) – Optionally defines a specific Community API version to use whenretrieving the value



Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError,khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.LiQLParseError

Return to Top

Subscription Subclass (khoros.core.Khoros.Subscription)

class Khoros.Subscription(khoros_object)This class includes methods relating to subscriptions.





Parameters• target_id (str, int) – The unique identifier for the target (e.g. Node ID, Message

ID, etc.)



• included_boards (list, tuple, set, str, None) – One or more boards (rep-resented by Node ID) to be included in the partial subscription

• excluded_boards (list, tuple, set, str, None) – One or more boards (rep-resented by Node ID) to be excluded from the partial subscription








































• included_boards (list, tuple, set, str, None) – One or more boards (rep-resented by Node ID) to be included in the partial subscription

• excluded_boards (list, tuple, set, str, None) – One or more boards (rep-resented by Node ID) to be excluded from the partial subscription




















































Return to Top

Tag Subclass (khoros.core.Khoros.Tag)

class Khoros.Tag(khoros_object)This class includes methods relating to the tagging of content.







Returns None




..caution:: This function is not the most effective way to add multiple tags to a message. It is recommendedthat the khoros.core.Khoros.messages.update() method be used instead with its tags argu-ment, which is more efficient and performance-conscious.




Returns None


























Changed in version 4.3.0: Introduced the wrap_json parameter to wrap the tags in a dictionary within theitems key.







Returns A list of properly formatted tags to act as the value for the tags field in the messagepayload

Return to Top















User Subclass (khoros.core.Khoros.User)

class Khoros.User(khoros_object)This class includes methods for interacting with users.





Parameters• user_settings (dict, None) – Allows all user settings to be passed to the function

within a single dictionary










• ignore_exceptions (bool) – Defines whether to raise the khoros.errors.exceptions.UserCreationError exception if the creation attempt fails (False bydefault)




Parameters• user_id (str, int) – The User ID of the user to be deleted





Parameters
























Note: The priority of supplied fields are as follows: User ID, username, first and last name, last name,first name









Returns The email address of the user as a string or a list of emails if allow_multiple isTrue

get_followers_count(user_settings=None, user_id=None, login=None, email=None)This method gets the count of community members who have added the user as a friend in the community.



























get_following_count(user_settings=None, user_id=None, login=None, email=None)This method gets the count of community members the user has added as a friend in the community.






Returns The number of community members the user has added as a friend in integer format




format











Raises khoros.errors.exceptions.GETRequestErrorget_kudos_given_count(user_settings=None, user_id=None, login=None, email=None)

This method gets the count of kudos a user has given.












































allow_multiple=False, display_warnings=True)This is an alternative method name for the khoros.core.Khoros.User.get_username() method.





























get_public_images_count(user_settings=None, user_id=None, login=None, email=None)This method gets the count of public images uploaded by the user.












































































Returns The number of messages created by the user that are marked as accepted solutions ininteger format


























Returns The number of topic messages (excluding replies) posted by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorget_user_data(user_settings=None, user_id=None, login=None, email=None)

This method retrieves all user data for a given user.









Note: The priority of supplied fields are as follows: login, email, first and last name, last name, first name






























Note: The priority of supplied fields are as follows: User ID, email, first and last name, last name, firstname







• allow_multiple (bool) – Allows a list of usernames to be returned if multiple re-sults are found


Returns The username (i.e. login) of the user or a list of usernames if allow_multiple isTrue










Note: The authenticated user must have the Administrator role and/or have the Switch User per-mission enabled.





Parameters
















• select_fields (str, tuple, list, set) – One or more SELECT field (e.g.login, messages.count(*), etc.) to query



Raises khoros.errors.exceptions.GETRequestErrorupdate_sso_id(new_sso_id, user_id=None, user_login=None)

This method updates the SSO ID for a user.







Return to Top

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

1.8 Primary Modules

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

• Init Module (khoros)

• Core Module (khoros.core)

• API Module (khoros.api)

• Auth Module (khoros.auth)

• LiQL Module (khoros.liql)

• Objects Module (khoros.objects)

– Base Objects Module (khoros.objects.base)

– Albums Module (khoros.objects.albums)

– Archives Module (khoros.objects.archives)

– Attachments Module (khoros.objects.attachments)

– Labels Module (khoros.objects.labels)

– Messages Module (khoros.objects.messages)

– Roles Module (khoros.objects.roles)













– Settings Module (khoros.objects.settings)

– Subscriptions Module (khoros.objects.subscriptions)

– Tags Module (khoros.objects.tags)

– Users Module (khoros.objects.users)

• SAML Module (khoros.saml)

• Structures Module (khoros.structures)

– Base Structures Module (khoros.structures.base)

– Boards Module (khoros.structures.boards)

– Categories Module (khoros.structures.categories)

– Communities Module (khoros.structures.communities)

– Group Hubs Module (khoros.structures.grouphubs)

– Nodes Module (khoros.structures.nodes)

• Studio Module (khoros.studio)

– Base Studio Module (khoros.studio.base)

1.8.1 Init Module (khoros)

The Init Module is covered on this page.

1.8.2 Core Module (khoros.core)

The Core Module is covered on this page.

1.8.3 API Module (khoros.api)

This module handles interactions with the Khoros Community REST APIs.

Module khoros.api

Synopsis This module handles interactions with the Khoros Community REST APIs

Usage import khoros.api

Example json_response = khoros.api.get_request_with_retries(url,auth_dict=khoros.auth)


1.8. Primary Modules 229



Modified Date 02 Oct 2021

khoros.api.combine_json_and_avatar_payload(json_payload, avatar_image_path)This function combines JSON payload with an uploaded avatar image (binary file) for a multipart API request.


Parameters• json_payload (dict) – The JSON payload for the API request

• avatar_image_path (str) – The full path to the avatar image to use

Returns The full multipart payload for the API request


khoros.api.define_headers(khoros_object=None, auth_dict=None, params=None, accept=None,content_type=None, multipart=False, default_content_type=False,proxy_user_object=None)

This function defines the headers to use in an API call.

Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performedon behalf of other users.

Changed in version 3.5.0: An unnecessary else statement after the khoros.errors.exceptions.MissingAuthDataError exception is raised has been removed.

Changed in version 2.7.5: Added the default_content_type argument which is defined as False by default.

Changed in version 2.7.4: The HTTP headers were changed to be all lowercase in order to be standardized acrossthe library. A function call for khoros.api._normalize_headers() was also introduced.

Changed in version 2.3.0: Added the multipart Boolean argument to remove the content-type key valuepair when appropriate.

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

quired if the auth_dict parameter is not supplied)

• auth_dict (dict, None) – The auth dictionary within the khoros.Khoros class ob-ject

• params (dict, None) – Header parameters in a dictionary format

• accept (str, None) – The accept header value (e.g. application/json)

• content_type (str, None) – The content-type header value (e.g. application/json)

• multipart (bool) – Defines whether or not the query is a multipart/form-data query(False by default)

• default_content_type (bool) – Determines if application/json should be usedas the default content-type value if the key does not exist (False by default)

• proxy_user_object (class[khoros.objects.users.ImpersonatedUser],None) – Instantiated khoros.objects.users.ImpersonatedUser object to performthe API request on behalf of a secondary user.

Returns A dictionary with the header fields and associated values

Raises khoros.errors.exceptions.MissingAuthDataError












khoros.api.delete(url, return_json=False, khoros_object=None, auth_dict=None, headers=None,proxy_user_object=None, verify=None)

This function performs a DELETE request against the Core API.

Changed in version 4.3.0: An issue has been fixed that prevented SSL verification from being disabled by thehelper file setting.


Changed in version 3.4.0: Support has been introduced for the ssl_verify core setting in the khoros.core.Khoros object.

Parameters• url (str) – The URI against which the DELETE request will be issued

• return_json (bool) – Determines whether or not the response should be returned inJSON format (Default: False)

• khoros_object (class[khoros.Khoros], None) – The core Khoros object (Re-quired if the auth_dict parameter is not supplied)


• headers (dict, None) – Any header values (in dictionary format) to pass in the APIcall (optional)


• verify (bool, None) – Determines whether or not to verify the server’s TLS certificate(True by default)

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

khoros.api.deliver_v2_results(response, full_response=None, return_id=None, return_url=None,return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False, khoros_object=None)

This function parses a Community API v2 response and returned specific data based on the function arguments.

Changed in version 2.8.0: Introduced the ability for error messages to be translated where possible to be morerelevant, and added the optional khoros_object argument to facilitate this.

Changed in version 2.5.2: Replaced the return_developer_message argument withreturn_error_messages.

New in version 2.5.0: The code for this function was extracted from the khoros.objects.messages.create() function.

Parameters• response – The API response to be parsed

• full_response (bool, None) – Determines if the full raw API response should bereturned

• return_id (bool, None) – Determines if the id field value should be returned

• return_url (bool, None) – Determines if the view_href field value should be re-turned











• return_api_url (bool, None) – Determines if the href field value should be returned

• return_http_code (bool, None) – Determines if the http_code field value shouldbe returned

• return_status (bool, None) – Determines if the http_code field value should bereturned

• return_error_messages (bool, None) – Determines if error messages should be re-turned when applicable

• split_errors (bool) – Determines if error messages should be split into separate valuesor merged when applicable

• khoros_object – The core khoros.Khoros object

Returns Boolean value indicating a successful outcome (default), the full API response or one ormore specific fields defined by function arguments

khoros.api.encode_multipart_data(data_fields)This function uses the Streaming Multipart Data Encoder to encode the payload for a multipart/form-data APIcall.

Changed in version 3.5.0: This function now import the requests_toolbelt module locally to avoid depen-dency errors during installation.


See also:This function follows the requests_toolbelt documentation.

Parameters data_fields (dict) – A dictionary with the data to be encoded

Returns The encoded data for use by the requests library

khoros.api.encode_payload_values(payload_dict)This function URL-encoded any string-formatted payload values.


Parameters payload_dict (dict) – The JSON payload for an API call in dictionary format

Returns The JSON payload with URL-encoded string values

khoros.api.encode_v1_query_string(query_dict, return_json=True, json_payload=False)This function formats and URL-encodes a Community API v1 query string.

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


Parameters• query_dict (dict) – A dictionary with the query fields and associated values

• return_json (bool) – Determines if JSON should be returned rather than XML (default:True)

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

Returns The properly formatted and encoded query string







https://rsa.im/3dg7QiZ


https://2.python-requests.org/en/master/api/#module-requests






khoros.api.format_avatar_payload(avatar_image_path)This function structures and formats the avatar payload to be used in a multipart API request.


Parameters avatar_image_path (str) – The file path to the avatar image to use

Returns The payload dictionary containing the binary file


khoros.api.get_items_list(api_response)This function returns the list of items dictionaries within a response from the Community API.

Parameters api_response (dict) – The response to an API query in JSON format

Returns List of items dictionaries from the API response

khoros.api.get_platform_version(base_url, full_release=False, simple=False, commit_id=False,timestamp=False, khoros_object=None, verify=None)

This function retrieves the Khoros Community platform version information for a given environment.




Parameters• base_url (str) – The base URL (i.e. top-level domain) of the Khoros Community en-

vironment

• full_release (bool) – Defines if the full platform release version should be returned

Note: If none of the options are enabled then the full_release option will be enabledby default.

• simple (bool) – Defines if the simple X.Y version (e.g. 20.6) should be returned

• commit_id (bool) – Defines if the Commit ID (i.e. hash) for the release should be re-turned

• timestamp (bool) – Defines if the timestamp of the release (e.g. 2007092156) shouldbe returned

• khoros_object (class[khoros.Khoros], None) – The core Khoros object (Optionalunless needing to determine SSL certificate verification)



Raises khoros.errors.exceptions.GETRequestErrorkhoros.api.get_request_with_retries(query_url, return_json=True, khoros_object=None, auth_dict=None,

headers=None, verify=None, proxy_user_object=None)This function performs a GET request with a total of 5 retries in case of timeouts or connection issues.












Changed in version 4.0.0: Introduced the proxy_user_object parameter to allow API requests to be performedon behalf of other users. A function call was also introduced to ensure that v1 requests that should return JSONresponses are formatted correctly.

Changed in version 3.4.0: Removed an unnecessary pass statement and initially defined the response variablewith a NoneType value to prevent a linting error from being reported. Also leveraged the ssl_verify coresetting.

Changed in version 2.5.0: Leverages new private functions and has improved error handling of JSON conversionattempts.

Parameters• query_url (str) – The URI to be queried

• return_json (bool) – Determines whether or not the response should be returned inJSON format (Default: True)






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


khoros.api.get_results_count(api_response)This function returns the number of results within a response from the Community API.

Parameters api_response (dict) – The response to an API query in JSON format

Returns The number of results in the API response as an integer

khoros.api.get_v1_node_collection(node_type)This function retrieves the appropriate API v1 collection name for a given node type.

Changed in version 4.0.0: Group Hubs are now supported by the function by passing the grouphub or grouphub string.


Parameters node_type (str) – The node type for which to retrieve the collection (e.g. board,category)

Returns The associated API v2 collection for the node type

Raises khoros.errors.exceptions.InvalidNodeTypeErrorkhoros.api.get_v1_user_path(user_id=None, user_email=None, user_login=None, user_sso_id=None,

user_and_type=None, trailing_slash=False)












This function returns the segment of an API v1 endpoint that is the path to define a user.

New in version 4.0.0: Introduced the user_and_type parameter that can be passed instead of a parameter for aspecific type.


Parameters• user_id (str, int, None) – The numeric User ID associated with a user

• user_email (str, None) – The email address associated with a user

• user_login (str, None) – The username (i.e. login) associated with a user

• user_sso_id (str, None) – The Single Sign-On (SSO) ID associated with a user

• user_and_type (tuple, None) – A tuple with the first value being the user value andthe second being the user type. (Accepted types: id, email, login and sso_id)

• trailing_slash (bool) – Determines if the returned path should end with a slash(False by default)

Returns The API user path (e.g. /users/id/1234)

Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.api.make_v1_request(khoros_object, endpoint, query_params=None, request_type='GET',

return_json=True, params_in_uri=False, json_payload=False,proxy_user_object=None, verify=None)

This function makes a Community API v1 request.



Changed in version 3.2.0: Introduced the new default ability to pass the query parameters as payload to avoidURI length limits, and fixed an issue with GET requests not returning JSON responses even when requested.

Changed in version 3.0.0: The query_params argument has been updated to be optional and a full query stringcan now be passed within the endpoint argument.

Changed in version 2.7.4: The HTTP headers were changed to be all lowercase in order to be standardized acrossthe library.

Changed in version 2.7.1: Fixed a syntax error in raising the the khoros.errors.exceptions.CurrentlyUnsupportedError exception class and removed unnecessary print debugging.

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

• endpoint (str) – The API endpoint to be queried

• query_params (dict, None) – The field and associated values to be leveraged in thequery string

• request_type (str) – Determines which type of API request to perform (e.g. GET orPOST)













Caution: While PUT requests are technically supported in this library, at this timethey are not yet supported by the Khoros Community API v1 endpoints.


• params_in_uri (bool) – Determines if query parameters should be passed in the URIrather than in the request body (False by default)


Caution: This is not yet fully supported and therefore should not be used at this time.




Raises ValueError, TypeError, khoros.errors.exceptions.GETRequestError,khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PUTRequestError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

khoros.api.parse_v2_response(json_response, return_dict=False, status=False, error_msg=False,dev_msg=False, split_errors=False, http_code=False, data_id=False,data_url=False, data_api_uri=False, v2_base='', khoros_object=None)

This function parses an API response for a Community API v2 operation and returns parsed data.

Changed in version 2.8.0: Introduced the ability for error messages to be translated where possible to be morerelevant, and added the optional khoros_object argument to facilitate this.

Changed in version 2.5.2: Replaced the developer_msg argument with error_msg and added the dev_msgand split_error arguments with their accompanying functionality. (See Change Log for more details.)

Changed in version 2.5.0: Moved from the khoros.objects.messages module to khoros.api and expandedthe scope to apply to most Community API v2 API responses.



• return_dict (bool) – Defines if the parsed data should be returned within a dictionary


• error_msg (bool) – Defines if any error messages should be returned when applicable

• dev_msg (bool) – Defines if the developer message should be returned when applicable

• split_errors (bool) – Defines if error messages should be returned as separate valueswhen applicable



















• v2_base (str, None) – The base URL for the API v2

• khoros_object – The core khoros.Khoros object


Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.api.payload_request_with_retries(url, request_type, json_payload=None,

plaintext_payload=None, url_encoded_payload=None,return_json=True, khoros_object=None, auth_dict=None,headers=None, multipart=False, content_type=None,verify=None, proxy_user_object=None)

This function performs an API request that includes a payload with up to three reties as necessary.



Changed in version 3.2.0: Support has been introduced for URL-encoded string payloads in POST and PUTrequests.

Parameters• url (str) – The URI to be queried

• request_type (str) – Defines the API call as a POST or PUT request

• json_payload (dict, None) – The payload for the POST or PUT request in JSONformat

• plaintext_payload (str, None) – The payload for the POST or PUT request in plain-text (i.e. text/plain) format

• url_encoded_payload (str, None) – The payload for the POST or PUT request as aURL-encoded string






• content_type (str, None) – Allows the content-type value to be explicitly definedif necessary


















Note: If this parameter is not defined then the content type will be identified based onthe payload format and/or type of request.



Returns The API response from the API request

Raises ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PUTRequestError,khoros.errors.exceptions.InvalidRequestTypeError, khoros.errors.exceptions.PayloadMismatchError

khoros.api.perform_v1_search(khoros_object, endpoint, filter_field, filter_value, return_json=False,fail_on_no_results=False, proxy_user_object=None, verify=None)

This function performs a search for a particular field value using a Community API v1 call.



Changed in version 3.5.0: The typecheck was updated to utilize isinstance() instead of type().



• endpoint (str) – The API v1 endpoint against which to perform the search query

• filter_field (str) – The name of the field being queried within the API v1 endpoint



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
















khoros.api.post_request_with_retries(url, json_payload=None, plaintext_payload=None,url_encoded_payload=None, return_json=True,khoros_object=None, auth_dict=None, headers=None,multipart=False, content_type=None, verify=None,proxy_user_object=None)

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: Support has been introduced for URL-encoded string payloads in POST requests.

Changed in version 3.1.1: The content_type parameter now gets defined as an empty string prior to callingthe sub-function.

Changed in version 3.1.0: The function can now accept plaintext payloads and now leverages the:py:func:payload_request_with_retries function. The content_type parameter has also been introduced.

Changed in version 2.5.0: The function can now be called without supplying a JSON payload.

Changed in version 2.3.0: Added the ability to perform multipart/form-data queries.


• json_payload (dict, None) – The payload for the POST request in JSON format

• plaintext_payload (str, None) – The payload for the POST request in plaintext (i.e.text/plain) format

• url_encoded_payload (str, None) – The payload for the POST request as a URL-encoded string
























khoros.api.put_request_with_retries(url, json_payload=None, plaintext_payload=None, return_json=True,url_encoded_payload=None, khoros_object=None, auth_dict=None,headers=None, multipart=False, content_type=None, verify=None,proxy_user_object=None)

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: Support has been introduced for URL-encoded string payloads in PUT requests.

Changed in version 3.1.1: The content_type parameter now gets defined as an empty string prior to callingthe sub-function.

Changed in version 3.1.0: The function can now accept plaintext payloads and now leverages the:py:func:payload_request_with_retries function. The content_type parameter has also been introduced.

Changed in version 2.5.0: The function can now be called without supplying a JSON payload.

Changed in version 2.3.0: Added the ability to perform multipart/form-data queries.


• json_payload (dict, None) – The payload for the PUT request in JSON format

• plaintext_payload (str, None) – The payload for the POST request in plaintext (i.e.text/plain) format

• url_encoded_payload (str, None) – The payload for the POST request as a URL-encoded string
























khoros.api.query_successful(api_response)This function reviews the API response from the Community API to verify whether or not the call was successful.

Parameters api_response (dict) – The response from the API in JSON format

Returns Boolean indicating whether or not the API call was successful

khoros.api.should_verify_tls(khoros_object=None)This function determines whether or not to verify the server’s TLS certificate. (True by default)

Changed in version 4.3.0: Introduced the ssl_verify_disabled global variable to allow this check to beperformed even when the core object is not passed to the function.

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

Returns Boolean value indicating if the verification should occur

Return to Top

1.8.4 Auth Module (khoros.auth)

This module contains functions that facilitate authenticating to Khoros Community environments.

Module khoros.auth

Synopsis This module handles authentication-related tasks and operations for the Khoros CommunityAPIs

Usage import khoros.auth

Example session_key = khoros.auth(KhorosObject)



Modified Date 28 Aug 2021






khoros.auth.get_oauth_authorization_url(khoros_object)This function constructs the authorization URL needed for the OAuth 2.0 Web Application Flow.

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

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

Returns The properly encoded authorization URL in string format

khoros.auth.get_oauth_callback_url_from_user(khoros_object)This function instructs the end-user to visit the authorization URL and provide the full callback URL.


Returns The callback URL supplied by the end-user

khoros.auth.get_session_header(session_key)This function constructs and returns a proper API header containing the session key for authorization.

Parameters session_key (str) – The session key for the authorization session

Returns The API in dictionary format

khoros.auth.get_session_key(khoros_object, username=None, password=None)This function retrieves the session key for an authentication session.

Changed in version 4.2.0: The URI is now generated utilizing the khoros.auth._get_khoros_login_url()function.

Changed in version 3.5.0: This function can now be used to authenticate secondary users with either a user-name and password or with only a username if calling the function with a previously authenticated user withAdministrator privileges.




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

• username (str, None) – The username (i.e. login) of a secondary user to authenticate(optional)

• password – The password of a secondary user to authentication (optional)


Raises khoros.errors.exceptions.SessionAuthenticationErrorkhoros.auth.get_sso_key(khoros_object)

This function retrieves the session key for a LithiumSSO session.




Raises khoros.errors.exceptions.SsoAuthenticationError





khoros.auth.invalidate_session(khoros_object, user_id=None, sso_id=None)This function invalidates an active authentication session.



• user_id (str, int, None) – The User ID of the service account (Lithium Registration)

• sso_id (str, int, None) – The SSO ID of the service account (Single Sign-On)

Returns Boolean value defining if the session was invalidated successfully


Return to Top

1.8.5 LiQL Module (khoros.liql)

This module contains functions that enable API queries using the LiQL syntax.

Module khoros.liql

Synopsis Collection of functions and classes to leverage the Community API v2 and LiQL for searches

Usage from khoros import liql (Imported by default in khoros.core package)

Example query_url = liql.format_query("SELECT * FROM messages WHERE id = '2'LIMIT 1")



Modified Date 02 Oct 2021

class khoros.liql.LiQLSyntax

This class defines lists of syntax elements for use in LiQL queries.

khoros.liql.format_query(query, pretty_print=False, track_in_lsi=False, always_ok=False, error_code='',format_statements=True)

This function formats and URL-encodes a raw LiQL query to be able to use it within a Community v2 API URL.

Changed in version 2.1.0: Queries ending in a semicolon (;) will have that character stripped to avoid syntaxerrors.

Changed in version 2.0.0: Added URL-encoding support for several additional characters.

Parameters• query (str) – The LiQL query to be formatted and url-encoded

• pretty_print (bool) – Defines if the response should be “pretty printed” (False bydefault)










• track_in_lsi (bool) – Defines if the query should be tracked within LSI (False bydefault)

• always_ok (bool) – Defines if the HTTP response should always be 200 OK (False bydefault)

• error_code (str) – Allows an error code to optionally be supplied for testing purposes(ignored by default)

• format_statements (bool) – Determines if statements (e.g. SELECT, FROM, et.) shouldbe formatted to be in all caps (True by default)

Returns The properly formatted query to be inserted in the URL

khoros.liql.get_query_url(core_dict, query, pretty_print=False, track_in_lsi=False, always_ok=False,error_code='', format_statements=True)

This function defines the full Community API v2 query URL for the LiQL query.

Parameters• core_dict (dict) – The core dictionary defined in the khoros.core.Khoros object

• query (str) – The LiQL query to be encoded and embedded in the URL

• pretty_print (bool) – Defines if the response should be “pretty printed” (False bydefault)

• track_in_lsi (bool) – Defines if the query should be tracked within LSI (False bydefault)

• always_ok (bool) – Defines if the HTTP response should always be 200 OK (False bydefault)

• error_code (str) – Allows an error code to optionally be supplied for testing purposes(ignored by default)

• format_statements (bool) – Determines if statements (e.g. SELECT, FROM, et.) shouldbe formatted to be in all caps (True by default)

Returns The full Community API v2 URL in string format

khoros.liql.get_returned_items(liql_response, only_first=False)This function prunes a full LiQL API response down to only the returned item(s).

Changed in version 3.3.2: The error handling has been improved to avoid IndexError exceptions from beingraised when no items were found in the LiQL response.


Parameters• liql_response (dict) – The full JSON response from the LiQL query as a dictionary

• only_first (bool) – Returns only the first item found rather than a list of items (Falseby default)

Returns A list of items (or a single item) found within the LiQL response

Raises khoros.errors.exceptions.LiQLParseErrorkhoros.liql.get_total_count(khoros_object, collection, where_filter='', verify_success=True)

This function retrieves the total asset count from a given collection (e.g. categories).

Parameters













https://docs.python.org/3/library/exceptions.html#IndexError




• khoros_object (class[khoros.Khoros]) – The Khoros object initialized via thekhoros.core module

• collection (str) – The collection object to use in the FROM clause of the LiQL query(e.g. users)

• where_filter (str) – An optional filter to use as the WHERE clause in the LiQL query

• verify_success (bool) – Determines if the API query should be verified as successful(True by default)


Raises khoros.errors.exceptions.GETRequestErrorkhoros.liql.parse_query_elements(select_fields, from_source, where_filter='', order_by=None,

order_desc=True, limit=0)This function parses query elements to construct a full LiQL query in the appropriate syntax.

Parameters• select_fields (str, tuple, list, set) – One or more fields to be selected within

the SELECT statement (e.g. id)


• where_filter (str, tuple, list, dict, set) – The filters (if any) to use in theWHERE clause (e.g. id = '2')

• order_by (str, tuple, set, dict, list) – The field(s) by which to order the re-sponse data (optional)

• order_desc (bool) – Defines if the ORDER BY directionality is DESC (default) or ASC

• limit (int) – Allows an optional limit to be placed on the response items (ignored bydefault)

Returns The query response in JSON format

Raises khoros.errors.exceptions.OperatorMismatchError, khoros.errors.exceptions.InvalidOperatorError

khoros.liql.parse_select_fields(_select_fields)This function parses the fields to be used in the SELECT statement of the LiQL query.

Changed in version 3.5.0: Refactored the function to leverage the isinstance() built-in function.

Changed in version 3.4.0: Renamed the function to adhere to PEP8 guidelines.

Parameters _select_fields (str, tuple, list, set) – The field(s) to be used in the SE-LECT statement

Returns The properly formatted SELECT fields in string format (comma-separated)

Raises khoros.errors.exceptions.InvalidFieldErrorkhoros.liql.parse_where_clause(where, join_logic='AND')

This function parses the data supplied for the WHERE clause of a LiQL query.

Changed in version 4.3.0: Refactored the function to be more efficient and Pythonic, and added missing paren-thesis on the exception classes.

Changed in version 3.4.0: Renamed the function to adhere to PEP8 guidelines and converted from a private to apublic function.






















https://docs.python.org/3/library/functions.html#isinstance






Parameters• where (str, tuple, list, set, dict) – The WHERE clause information

• join_logic (str, tuple, list) – The logic to use

Returns A properly formatted WHERE clause (excluding the WHERE statement at the beginning)

Raises khoros.errors.exceptions.InvalidOperatorError, khoros.errors.exceptions.OperatorMismatchError

khoros.liql.perform_query(khoros_object, query_url=None, liql_query=None, return_json=True,verify_success=False, allow_exceptions=True, verify=None, return_items=False)

This function performs a LiQL query using full Community API v2 URL containing the query.”


Changed in version 3.4.0: Support has been introduced for the verify parameter to determine if SSL certificateverification is needed.

Changed in version 2.3.0: Added the allow_exceptions argument (True by default) to allow exceptions to bedisabled and updated the error/exception message to be more specific.

Changed in version 2.0.0: Added the ability for a raw LiQL query to be passed to this function rather than onlya formatted query URL, and included the optional verify_success Boolean argument to verify a successfulresponse.

Parameters• khoros_object (class[khoros.Khoros]) – The Khoros object initialized via thekhoros.core module

• query_url (str, None) – The full Khoros Community API v2 URL for the query

• liql_query (str, None) – The LiQL query to be performed, not yet embedded in thequery URL

• return_json (bool) – Determines if the response should be returned in JSON format(True by default)

• verify_success (bool) – Optionally check to confirm that the API query was successful(False by default)

• allow_exceptions (bool) – Defines whether or not exceptions can be raised for re-sponses returning errors



• return_items (bool) – Reduces the JSON response to be only the list of items returnedfrom the LiQL response (False by default)


Returns The API response (in JSON format by default)



















khoros.liql.structure_cursor_clause(cursor=None, liql_response=None)This function structures the CURSOR clause for a LiQL query.

Changed in version 4.0.0: The cursor string has been wrapped in single quotes to prevent the khoros.errors.exceptions.LiQLParseError exception from being raised.


Parameters• cursor (str, None) – A cursor value from the next_cursor key in a LiQL response

• liql_response (dict, None) – A full LiQL query response in dictionary format

Returns The properly formatted CURSOR clause for use in a new LiQL query

Raises khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.MissingRequiredDataError

Return to Top

1.8.6 Objects Module (khoros.objects)

This module contains sub-modules that are specific to the various Community API objects.

Module khoros.objects

Synopsis This module contains sub-modules that are specific to the various Community API objects.

Usage from khoros import objects

Example objects.archives.archive(khoros_obj, '123', suggested_url,return_status=True)




Return to Top





Base Objects Module (khoros.objects.base)

This module contains functions that relate to the various Community API objects but which are object-agnostic.

Module khoros.objects.base

Synopsis This module handles general (i.e. object-agnostic) functions relating to API objects.

Usage from khoros.objects import base

Example node_id = base.get_node_id('https://community.khoros.com/t5/Khoros-Blog/bg-p/relnote', 'blog')



Modified Date 17 Jul 2020

class khoros.objects.base.Mapping

This class includes dictionaries that map API fields and values to those used in this SDK.

Deprecated since version 2.1.0: Use khoros.structures.nodes.Mapping instead.

khoros.objects.base.get_node_id(url, node_type=None)This deprecated function retrieves the Node ID for a given node within a URL.

Deprecated since version 2.1.0: Use khoros.structures.nodes.get_node_id() instead.


• node_type (str, NoneType) – The node type (e.g. blog, tkb, message, etc.) for theobject in the URL



khoros.objects.base.get_node_type_from_url(url)This function attempts to retrieve a node type by analyzing a supplied URL.

Deprecated since version 2.1.0: Use khoros.structures.nodes.get_node_type_from_url() instead.



Raises khoros.errors.exceptions.NodeTypeNotFoundErrorReturn to Top






Albums Module (khoros.objects.albums)

This module includes functions that handle albums that contain images.

Module khoros.objects.albums

Synopsis This module includes functions that handle albums that contain images

Usage from khoros.objects import albums

Example response = albums.create_album(khoros_obj, title='My Album',hidden=True)




khoros.objects.albums.create(khoros_object, title=None, description=None, owner_id=None, hidden=False,default=False, full_response=False)

This function creates a new image album for a user.



• title (str, None) – The title of the album to be created





• default (bool) – Defines if this will be the default album for the user (False by default)

• full_response (bool) – Defines if the full response should be returned instead of theoutcome (False by default)


khoros.objects.albums.format_album_json(title=None, description=None, owner_id=None, hidden=None,default=False)

This function formats the JSON payload for the API call.





















• default (bool) – Defines if this will be the default album for the user (False by default)

Returns The JSON payload for the album API call

khoros.objects.albums.get_albums_for_user(khoros_object, user_id=None, login=None, public=None,private=None, verify_success=False,allow_exceptions=True)

This function returns data for the albums owned by a given user.



• user_id (str, int) – The User ID for the album owner


• public (bool) – Indicates that public albums should be returned (all albums returnedby default)

• private (bool) – Indicates that private albums should be returned (all albums returnedby default)

• verify_success (bool) – Optionally check to confirm that the API query was successful(False by default)

• allow_exceptions (bool) – Defines whether or not exceptions can be raised for re-sponses returning errors




Return to Top

Archives Module (khoros.objects.archives)

This module includes functions that handle the archiving of messages.

Module khoros.objects.archives

Synopsis This module includes functions that handle archiving messages.

Usage from khoros.objects import archives

Example archives.archive(khoros_obj, '123', suggested_url, return_status=True)



Modified Date 05 Aug 2021











khoros.objects.archives.aggregate_results_data(results, include_raw=False)This function aggregates the results of an archive/unarchive operation into an easy-to-parse dictionary.

Changed in version 4.1.1: This function can now properly handle the ARCHIVED status when returned.




Returns A dictionary with fields for status, archived, unarchived, failed and unknown orthe raw response when the API call completely fails, with the optional raw data when requested

khoros.objects.archives.archive(khoros_object, message_id=None, message_url=None,suggested_url=None, archive_entries=None, aggregate_results=False,include_raw=False)

This function archives one or more messages while providing an optional suggested URL as a placeholder.

Changed in version 4.1.0: Made some minor docstring and code adjustments and also removed the followingparameters due to the unique response format: full_response, return_id, return_url, return_api_url,return_http_code, return_status, return_error_messages and split_errors

An issue with the khoros.objects.archives.structure_archive_payload() function call was also re-solved.

The optional aggregate_results parameter has also been introduced.



• message_id (str, int, None) – The message ID for the content to be archived

• message_url (str, None) – The URL of the message to be archived (as an alternativeto the message_id argument)

• suggested_url (str, None) – The full URL to suggest to the user when navigating tothe archived message

• archive_entries (dict, list, tuple, set, None) – A dictionary mapping oneor more message IDs with accompanying suggested URLs




Note: This parameter is only relevant when the aggregate_results parameter is True.


















khoros.objects.archives.structure_archive_payload(message_id, suggested_url=None,new_board_id=None, archive_entries=None,unarchiving=False)

This function structures the payload for an archive-related API call.



• suggested_url (str, None) – The full URL to suggest to the user if the user tries toaccess the archived message

• new_board_id (str, None) – The board ID of what will be the new parent board of amessage getting unarchived

• archive_entries (dict, list, tuple, set, None) – A dictionary mapping oneor more message IDs with accompanying suggested URLs (archiving) or new board IDs(unarchiving)

Note: Alternatively, a list, tuple or set of message IDs can be supplied which will beconverted into a dictionary with blank suggested URLs (archiving) or blank new boardIDs (unarchiving).

• unarchiving (bool) – Indicates that the payload is for an unarchive task (False bydefault)

Returns The payload for the API call as a list of dictionaries containing message IDs and/or sug-gested URLs

Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.objects.archives.unarchive(khoros_object, message_id=None, message_url=None,

new_board_id=None, archive_entries=None, aggregate_results=False,include_raw=False)

This function unarchives one or more messages and moves them to a given board.

Changed in version 4.1.0: Made some minor docstring and code adjustments and also removed the followingparameters due to the unique response format: full_response, return_id, return_url, return_api_url,return_http_code, return_status, return_error_messages and split_errors

The optional aggregate_results parameter has also been introduced.



• message_id (str, int, None) – The message ID for the content to be archived

• message_url (str, None) – The URL of the message to be archived (as an alternativeto the message_id argument)















• new_board_id (str, None) – The board ID of what will be the new parent board of amessage getting unarchived

• archive_entries (dict, list, tuple, set, None) – A dictionary mapping oneor more message IDs with accompanying board IDs




Note: This parameter is only relevant when the aggregate_results parameter is True.



Return to Top

Attachments Module (khoros.objects.attachments)

This module includes functions that handle attachments for messages.

Module khoros.objects.attachments

Synopsis This module includes functions that handle attachments for messages

Usage from khoros.objects import attachments

Example payload = format_attachment_payload(titles, file_paths)




khoros.objects.attachments.construct_multipart_payload(message_json, file_paths, action='create')This function constructs the full multipart payload for a message with one or more attachment.

Changed in version 2.8.0: Support was added for updating existing messages.


Parameters• message_json (dict) – The message information in JSON format

• file_paths (str, tuple, list, set) – The full path(s) to one or more attachment(e.g. path/to/file1.pdf)















• action (str) – Indicates if the payload will be used to create (default) or update amessage

ReturnsThe full payload for the multipart API call as a dictionary

Note: See the Requests Documentation for added context on the return data.

Raises khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.DataMismatchError

khoros.objects.attachments.format_attachment_payload(file_paths, action='create')This function formats the JSON payload for attachments to be used in an API call.

Changed in version 2.8.0: Support was added for updating existing messages.


Parameters• file_paths (str, tuple, list, set) – The full path(s) to one or more attachment

(e.g. path/to/file1.pdf)


Returns The list of items (in list format) that represent the items API value


khoros.objects.attachments.get_file_upload_info(file_paths, action='create')This function constructs the binary file(s) portion of the multipart API call.

Changed in version 2.8.0: Support was added for updating an existing message.


Parameters• file_paths (str, tuple, list, set) – The full path(s) to one or more attachment

(e.g. path/to/file1.pdf)


Returns A dictionary with the file upload information for the API call

khoros.objects.attachments.get_list_items(file_paths)This function constructs the items field for the attachments API call.


Parameters file_paths (str, tuple, list, set) – The full path(s) to one or more attach-ment (e.g. path/to/file1.pdf)

Returns The list of items (in list format) that represent the items API value


Return to Top



https://rsa.im/2SvMsya
















Labels Module (khoros.objects.labels)

This module includes functions that handle labels within a Khoros Community environment.

Module khoros.objects.labels

Synopsis This module includes functions that handle labels within a Khoros Community environment

Usage from khoros.objects import labels

Example TBD




Return to Top

Messages Module (khoros.objects.messages)

This module includes functions that handle messages within a Khoros Community environment.

Module khoros.objects.messages

Synopsis This module includes functions that handle messages within a Khoros Community environment

Usage from khoros.objects import messages

Example response = messages.create_message(khoros_obj, 'My First Message','Hello World', node_id='support-tkb')



Modified Date 10 Jan 2022

khoros.objects.messages.construct_payload(subject=None, body=None, node=None, node_id=None,node_url=None, canonical_url=None, context_id=None,context_url=None, is_answer=None, is_draft=None,read_only=None, seo_title=None, seo_description=None,teaser=None, tags=None, cover_image=None, images=None,labels=None, product_category=None, products=None,topic=None, videos=None, parent=None, status=None,moderation_status=None, attachments_to_add=None,attachments_to_remove=None, overwrite_tags=False,ignore_non_string_tags=False, msg_id=None,khoros_object=None, action='create')

This function constructs and properly formats the JSON payload for a messages API request.



Todo: Add support for the following parameters which are currently present but unsupported: cover_image,images, labels, product_category, products, topic, videos, parent, status, attachments_to_addand attachments to remove

Changed in version 2.8.0: Added the parent, status, moderation_status, attachments_to_add,attachments_to_remove, overwrite_tags, ignore_non_string_tags, msg_id, khoros_object andaction arguments, and added the raises section to the docstring.






• node_url (str, None) – The URL of the node in which the message will be published






• is_draft (bool, None) – Indicates whether or not the message is still a draft (i.e. un-published)

• read_only (bool, None) – Indicates whether or not the message should be read-onlyor have replies/comments blocked


• seo_description (str, None) – A description of the message used for SEO purposes







• products (dict, None) – The product in a product catalog associated with the message

• topic (dict, None) – The root message of the conversation in which the message ap-pears


























• status (dict, None) – The message status for messages where conversation.style isidea or contest

Caution: This property is not returned if the message has the default Unspecifiedstatus assigned. It will only be returned for ideas with a status of Completed or witha custom status created in Community Admin.



• attachments_to_add (str, tuple, list, set, None) – The full path(s) to one ormore attachments (e.g. path/to/file1.pdf) to be added to the message

• attachments_to_remove (str, tuple, list, set, None) – One or more attach-ments to remove from the message


• overwrite_tags (bool) – Determines if tags should overwrite any existing tags (whereapplicable) or if the tags should be appended to the existing tags (default)


• msg_id (str, int, None) – Message ID of an existing message so that its existing tagscan be retrieved (optional)

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

Note: The core object is only necessary when providing a Message ID as it will be neededto retrieve the existing tags from the message.

• action (str) – Defines if the payload will be used to create (default) or update amessage

Returns The properly formatted JSON payload























khoros.objects.messages.create(khoros_object, subject=None, body=None, node=None, node_id=None,node_url=None, canonical_url=None, context_id=None, context_url=None,cover_image=None, images=None, is_answer=None, is_draft=None,labels=None, product_category=None, products=None, read_only=None,seo_title=None, seo_description=None, tags=None,ignore_non_string_tags=False, teaser=None, topic=None, videos=None,attachment_file_paths=None, full_payload=None, full_response=False,return_id=False, return_url=False, return_api_url=False,return_http_code=False, return_status=None,return_error_messages=None, split_errors=False,proxy_user_object=None)

This function creates a new message within a given node.

Changed in version 4.5.0: The Content-Type header is now explicitly defined as application/json whenhandling non-multipart requests.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be created onbehalf of other users.

Changed in version 4.3.0: It is now possible to pass the pre-constructed full JSON payload into the function viathe full_payload parameter as an alternative to defining each field individually.

Changed in version 2.8.0: The ignore_non_string_tags, return_status, return_error_messages andsplit_errors arguments were introduced.










































• attachment_file_paths (str, tuple, list, set, None) – The full path(s) toone or more attachment (e.g. path/to/file1.pdf)

• full_payload (dict, str, None) – Pre-constructed full JSON payload as a dictio-nary (preferred) or a JSON string with the following syntax:


}}


• full_response (bool) – Defines if the full response should be returned instead of theoutcome (False by default)


• return_id (bool) – Indicates that the Message ID should be returned (False by default)

• return_url (bool) – Indicates that the Message URL should be returned (False bydefault)

• return_api_url (bool) – Indicates that the API URL of the message should be returned(False by default)

• return_http_code (bool) – Indicates that the HTTP status code of the responseshould be returned (False by default)































khoros.objects.messages.format_content_mention(khoros_object=None, content_info=None,content_id=None, title=None, url=None)

This function formats the <li-message> HTML tag for a content @mention.


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

Note: This argument is necessary if the URL (i.e. url argument) is not an absolute URL,as the base community URL will need to be retrieved from the object.

• content_info (dict, None) – A dictionary containing the 'id' and/or 'login'key(s) with the user information

Note: This argument is necessary if the Title and URL are not explicitly passed usingthe title and url function arguments.

• content_id (str, int, None) – The Message ID (aka Content ID) associated withthe content mention






khoros.objects.messages.format_user_mention(khoros_object=None, user_info=None, user_id=None,login=None)

This function formats the <li-user> HTML tag for a user @mention.


Parameters













Note: This argument is necessary if only one of the user values (i.e. user_id or login)are passed in the function, as a lookup will need to be performed to define the missingvalue.

• user_info (dict, None) – A dictionary containing the 'id' and/or 'login' key(s)with the user information

Note: This argument is necessary if the User ID and/or Login are not explicitly passedusing the user_id and/or login function arguments.





khoros.objects.messages.get_id_from_url(url)This function retrieves the message ID from a given URL.


Parameters url (str) – The URL from which the ID will be parsed

Returns The ID associated with the message in string format

Raises khoros.errors.exceptions.MessageTypeNotFoundErrorkhoros.objects.messages.get_metadata(khoros_object, msg_id, metadata_key)

This function retrieves the value for a specific metadata key associated with a given message.



• msg_id (str, int) – The ID of the message for which the metadata will be retrieved



Raises khoros.errors.exceptions.MissingRequiredDataError', :py:exc:`khoros.errors.exceptions.InvalidMetadataError, khoros.errors.exceptions.GETRequestError

khoros.objects.messages.is_read_only(khoros_object=None, msg_id=None, msg_url=None,api_response=None)

This function checks to see whether or not a message is read-only.


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

• msg_id (str, int, None) – The unique identifier for the message













• msg_url (str, None) – THe URL of the message

• api_response (dict, None) – The JSON data from an API response

Returns Boolean value indicating whether or not the message is read-only

Raises errors.exceptions.MissingRequiredDataError, errors.exceptions.MessageTypeNotFoundError

khoros.objects.messages.parse_v2_response(json_response, return_dict=False, status=False,response_msg=False, http_code=False, message_id=False,message_url=False, message_api_uri=False, v2_base='')

This function parses an API response for a message operation (e.g. creating a message) and returns parsed data.

Deprecated since version 2.5.0: Use the khoros.api.parse_v2_response() function instead.



• return_dict (bool) – Defines if the parsed data should be returned within a dictionary


• response_msg (bool) – Defines if the developer response message should be returned




• message_api_uri (bool) – Defines if the ** message API URI** should be returned



Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.objects.messages.set_read_only(khoros_object, enable=True, msg_id=None, msg_url=None,

suppress_warnings=False)This function sets (i.e. enables or disables) the read-only flag for a given message.


• enable (bool) – Determines if the read-only flag should be enabled (True by default)

• msg_id (str, int, None) – The unique identifier for the message

• msg_url (str, None) – The URL for the message

• suppress_warnings (bool) – Determines whether or not warning messages should besuppressed (False by default)

Returns None




















khoros.objects.messages.update(khoros_object, msg_id=None, msg_url=None, subject=None, body=None,node=None, node_id=None, node_url=None, canonical_url=None,context_id=None, context_url=None, cover_image=None, is_draft=None,labels=None, moderation_status=None, parent=None,product_category=None, products=None, read_only=None, topic=None,status=None, seo_title=None, seo_description=None, tags=None,overwrite_tags=False, ignore_non_string_tags=False, teaser=None,attachments_to_add=None, attachments_to_remove=None,full_response=None, return_id=None, return_url=None,return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False,proxy_user_object=None)

This function updates one or more elements of an existing message.

Changed in version 4.4.0: Introduced the proxy_user_object parameter to allow messages to be updated onbehalf of other users.



• msg_id (str, int, None) – The ID of the existing message






































• status (dict, None) – The message status for messages where conversation.style isidea or contest

Caution: This property is not returned if the message has the default Unspecifiedstatus assigned. It will only be returned for ideas with a status of Completed or with acustom status created in Community Admin.




• overwrite_tags (bool) – Determines if tags should overwrite any existing tags (whereapplicable) or if the tags should be appended to the existing tags (default)



• attachments_to_add (str, tuple, list, set, None) – The full path(s) to one ormore attachments (e.g. path/to/file1.pdf) to be added to the message

• attachments_to_remove (str, tuple, list, set, None) – One or more attach-ments to remove from the message


• full_response (bool, None) – Defines if the full response should be returned insteadof the outcome (False by default)































• return_http_code (bool, None) – Indicates that the HTTP status code of the re-sponse should be returned (False by default)




• proxy_user_object (class[khoros.objects.users.ImpersonatedUser],None) – Instantiated khoros.objects.users.ImpersonatedUser object to updatethe message on behalf of a secondary user.



khoros.objects.messages.validate_message_payload(payload)This function validates the payload for a message to ensure that it can be successfully utilized.


Parameters payload (dict, str) – The message payload to be validated as a dictionary (pre-ferred) or a JSON string.


Raises khoros.errors.exceptions.InvalidMessagePayloadErrorReturn to Top

Roles Module (khoros.objects.roles)

This module includes functions that handle roles and permissions.

Module khoros.objects.roles

Synopsis This module includes functions that handle roles and permissions.

Usage from khoros.objects import roles

Example count = roles.get_total_role_count()




khoros.objects.roles.assign_roles_to_user(khoros_object, user, lookup_type='id', roles_to_add=None,node=None, node_type='board', v1=False,return_json=True)

This function assigns a user to one or more roles.












Parameters• khoros_object:_khoros_object – The core khoros.Khoros object

• user (str) – The identifier (i.e. ID, login or email) of the user to be assigned to the role



• node (str, None) – The Node ID of the node to which the role is scoped when applicable

• node_type (str) – The type of node to which the role is scoped (e.g. board (default),category, etc.)

• v1 (bool) – Determines if the Community API v1 should be used to perform the operation(False by default)

• return_json (bool) – Determines if the response should be returned as JSON ratherthan XML (True by default)


Raises ValueError, khoros.errors.exceptions.APIConnectionError, khoros.errors.exceptions.CurrentlyUnsupportedError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.UnsupportedNodeTypeError, khoros.errors.exceptions.InvalidNodeTypeError,khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.PUTRequestError

khoros.objects.roles.count_role_types(role_type, roles_dict)This function returns the total count for a specific role type.


Parameters• role_type (str) – The role type for which to return the count (e.g. board, category,

etc.)

• roles_dict (dict) – Dictionary of the roles for a given Khoros Community environment

Returns The total count for the role type as an integer

Raises khoros.errors.exceptions.InvalidRoleTypeErrorkhoros.objects.roles.get_role_id(role_name, scope='community', node_id=None)

This function constructs and returns the Role ID associated with a given role name and scope.


Parameters• role_name (str) – The name of the role (e.g. Administrator, Moderator, Owner,

etc.)























khoros.objects.roles.get_roles_for_user(khoros_object, user_id, fields=None)This function returns all roles associated with a given User ID.




• user_id (str, int) – The User ID for which to retrieve the roles data

• fields (str, list, tuple, set, None) – The field(s) to retrieve from the LiQLquery as a string or list



Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.roles.get_total_role_count(khoros_object, return_dict=False, total=True,

top_level=False, board=False, category=False,group_hub=False)

This function retrieves the total role count for one or more role type(s).



• return_dict (bool) – Determines if the data should be returned as a dictionary (Falseby default)

• total (bool) – Indicates that the total overall role count should be returned (True bydefault)


• board (bool) – Indicates that the total board-level role count should be returned (Falseby default)

• category (bool) – Indicates that the total category-level role count should be returned(False by default)

• group_hub (bool) – Indicates that the total group hub-level role count should be returned(False by default)

Returns The role count(s) as an integer, tuple or dictionary, depending on the arguments supplied

Raises khoros.errors.exceptions.InvalidRoleTypeErrorkhoros.objects.roles.get_users_with_role(khoros_object, fields='login', role_id=None, role_name=None,

scope=None, node_id=None, limit_per_query=1000,cursor=None, where_clause=None, users_list=None,simple=False)

This function retrieves a list of all users that have a specific role.

Changed in version 4.0.0: The function now leverages a while loop instead of recursion in order to avoid raisinga RecursionError exception with larger queries.














https://docs.python.org/3/library/exceptions.html#RecursionError




• fields (str, tuple, list, set) – One or more fields from the Users object to re-turn (login field by default)

• role_id (str, None) – The identifier for the role in node_type:node_id:role_nameformat


Caution: This option should only be used when the role name is unique within thecommunity.





• limit_per_query (int, str) – Defines a LIMIT constraint other than the default 1000limit per LiQL query

Note: Unless modified by Khoros Support or Professional Services, 1000 is the maxi-mum number of entries that can be returned in a single LiQL query.

• cursor (str, None) – Specifies a cursor to be referenced in a LiQL query

Note: This parameter is intended for use by the function when calling itself recursively toretrieve users that exceed the limit_per_query value and will not be leveraged directlyin standalone function calls.

• where_clause (str, None) – Specifies an exact WHERE clause for the query to beperformed

Note: While technically possible to leverage this parameter in function calls, its pri-mary use is by the function when calling itself recursively to retrieve users that exceed thelimit_per_query value.

• users_list (list, None) – Provides an existing list of users that is leveraged when thefunction is called recursively
















• simple (bool) – Returns a simple list of the strings or tuples of the value(s) for each user(False by default)

Returns A list of users as strings, tuples or dictionaries depending if simple mode is enabled


Return to Top

Settings Module (khoros.objects.settings)

This module includes functions that handle community, node and user settings.

Module khoros.objects.settings

Synopsis This module contains functions specific to settings for various structures and objects

Usage from khoros.objects import settings

Example value = settings.get_node_settings(khoros_object, 'custom.purpose','my-board')



Modified Date 20 May 2021

khoros.objects.settings.define_node_setting(khoros_object, setting_name, setting_val, node_id,node_type='board', return_json=True)

This function defines a particular setting value for a given node.

Changed in version 4.0.0: The default value for the return_json parameter is now True and group hubs arenow supported.

Changed in version 3.3.2: The return_json parameter has been introduced which returns a simple JSON object(as a dict) indicating whether or not the operation was successful. (Currently False by default)

Changed in version 3.3.1: A minor fix was made to the docstring to correct a Sphinx parsing issue. The functionitself was not changed.



• setting_name (str) – The name of the setting field for which to retrieve the value




• return_json (bool) – Returns a simple JSON dictionary indicating the operation result(False by default)









Caution: An unsuccessful REST call will result in the raising of the khoros.errors.exceptions.PostRequestError exception if the return_json param-eter is set to False.

Returns None (or a dictionary if function call includes the return_json=True kwarg)

Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError,khoros.errors.exceptions.POSTRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.PayloadMismatchError

khoros.objects.settings.get_node_setting(khoros_object, setting_name, node_id, node_type='board',v1=None, convert_json=False)

This function retrieves the value of a specific node setting.

Changed in version 4.0.0: The node type validation has been moved form this function to the lower-level privatefunctions.

Changed in version 3.3.2: The convert_json parameter has been introduced which optionally converts a JSONstring into a dictionary.



• setting_name (str) – The name of the setting field for which to retrieve the value



• v1 (bool, None) – Optionally defines a specific Community API version to use whenretrieving the value



Raises ValueError, TypeError, khoros.errors.exceptions.APIConnectionError,khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.LiQLParseError

Return to Top

Subscriptions Module (khoros.objects.subscriptions)

This module includes functions that handle subscriptions.

Module khoros.objects.sub

Synopsis This module includes functions that handle tags within a Khoros Community environment

Usage from khoros.objects import subscriptions

Example response = subscribe_to_board(khoros_object, 'my-forum')














Modified Date 07 Apr 2021

khoros.objects.subscriptions.add_subscription(khoros_object, target_id, target_type='board',payload=None, included_boards=None,excluded_boards=None, label_board=None,proxy_user_object=None)

This function adds a subscription to a given target for the current user.




• target_id (str, int) – The unique identifier for the target (e.g. Node ID, Message ID,etc.)



• included_boards (list, tuple, set, str, None) – One or more boards (repre-sented by Node ID) to be included in the partial subscription

• excluded_boards (list, tuple, set, str, None) – One or more boards (repre-sented by Node ID) to be excluded from the partial subscription

• label_board (str, int, None) – The Board ID associated with a label (required forlabel subscriptions)




khoros.objects.subscriptions.get_subscription_uri(khoros_object)This function returns the subscriptions URI for the v2 API to perform API calls.




khoros.objects.subscriptions.subscribe_to_board(khoros_object, node_id, proxy_user_object=None)This function subscribes the current user to an individual message.



Parameters

















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

• node_id (str) – The unique identifier for a board (i.e. Board ID)




khoros.objects.subscriptions.subscribe_to_category(khoros_object, node_id, included_boards=None,excluded_boards=None,proxy_user_object=None)

This function subscribes the current user to a full or partial category.




• node_id (str) – The unique identifier (i.e. Node ID) for the category

• included_boards (list, tuple, set, str, None) – One or more boards (repre-sented by Node ID) to be included in the partial subscription

• excluded_boards (list, tuple, set, str, None) – One or more boards (repre-sented by Node ID) to be excluded from the partial subscription




khoros.objects.subscriptions.subscribe_to_label(khoros_object, label, board_id,proxy_user_object=None)

This function subscribes the current user to label found on a board.




• label (str, int) – The label to which to subscribe

• board_id (str) – The unique identifier (i.e. Node ID) for the board where the label isfound





















khoros.objects.subscriptions.subscribe_to_message(khoros_object, msg_id, proxy_user_object=None)This function subscribes the current user to an individual message.




• msg_id (str, int) – The unique identifier for an individual message




khoros.objects.subscriptions.subscribe_to_product(khoros_object, product_id,proxy_user_object=None)

This function subscribes the current user to a product.




• product_id (str, int) – The unique identifier for a product




Return to Top










Tags Module (khoros.objects.tags)

This module includes functions that handle tags within a Khoros Community environment.

Module khoros.objects.tags

Synopsis This module includes functions that handle tags within a Khoros Community environment

Usage from khoros.objects import tags

Example tags.add_single_tag_to_message('tutorial', 123)



Modified Date 28 Jun 2021

khoros.objects.tags.add_single_tag_to_message(khoros_object, tag, msg_id, allow_exceptions=False)This function adds a single tag to an existing message.



• tag (str) – The tag value to be added


• allow_exceptions (bool) – Determines if exceptions are permitted to be raised (Falseby default)

Returns None

Raises khoros.errors.exceptions.POSTRequestErrorkhoros.objects.tags.add_tags_to_message(khoros_object, tags, msg_id, allow_exceptions=False)

This function adds one or more tags to an existing message.


..caution:: This function is not the most effective way to add multiple tags to a message. It is recommendedthat the khoros.objects.messages.update() function be used instead with its tags argument, whichis more efficient and performance-conscious.


• tags (str, tuple, list, set) – One or more tags to be added to the message


• allow_exceptions (bool) – Determines if exceptions are permitted to be raised (Falseby default)

Returns None


khoros.objects.tags.get_tags_for_message(khoros_object, msg_id)This function retrieves the tags for a given message.
















• msg_id (str, int) – The Message ID for the message from which to retrieve tags


khoros.objects.tags.structure_single_tag_payload(tag_text)This function structures the payload for a single tag.




Raises khoros.errors.exceptions.InvalidPayloadValueErrorkhoros.objects.tags.structure_tags_for_message(*tags, khoros_object=None, msg_id=None,

overwrite=False, ignore_non_strings=False,wrap_json=False)

This function structures tags to use within the payload for creating or updating a message.

Changed in version 4.3.0: Introduced the wrap_json parameter to wrap the tags in a dictionary within the itemskey.

Changed in version 4.1.0: The missing type declaration for the overwrite parameter has been added to thedocstring.




Note: The core object is only necessary when providing a Message ID as it will be neededto retrieve the existing tags from the message.

• msg_id (str, int, None) – Message ID of an existing message so that its existing tagscan be retrieved (optional)

• overwrite (bool) – Determines if tags should overwrite any existing tags (where appli-cable) or if the tags should be appended to the existing tags (default)

• ignore_non_strings (bool) – Determines if non-strings (excluding iterables) shouldbe ignored rather than converted to strings (False by default)

• wrap_json (bool) – Determines if the list of tags should be wrapped in the {"items":[]} JSON structure – In other words, a dictionary rather than a list (False by default)

Returns A list of properly formatted tags to act as the value for the tags field in the message payload
















Users Module (khoros.objects.users)

This module includes functions that handle user-related operations.

Module khoros.objects.users

Synopsis This module includes functions that handle user-related operations.

Usage from khoros.objects import users

Example khoros.users.create(username='john_doe', email='[email protected]')




class khoros.objects.users.ImpersonatedUser(user_login=None, admin_object=None)This class is used for impersonating another user when performing other functions throughout the library.

Changed in version 4.2.0: Added support for user impersonation with LithiumSSO token authentication.


close()

This method destroys the instance.


khoros.objects.users.create(khoros_object, user_settings=None, login=None, email=None, password=None,first_name=None, last_name=None, biography=None, sso_id=None,web_page_url=None, cover_image=None, ignore_exceptions=False)

This function creates a new user in the Khoros Community environment.

Changed in version 4.0.0: This function now returns the API response and the ignore_exceptions parameterhas been introduced.




• user_settings (dict, None) – Allows all user settings to be passed to the functionwithin a single dictionary






















• ignore_exceptions (bool) – Defines whether to raise the khoros.errors.exceptions.UserCreationError exception if the creation attempt fails (False by de-fault)


Raises KeyError, khoros.errors.exceptions.UserCreationError

khoros.objects.users.delete(khoros_object, user_id, return_json=False)This function deletes a user from the Khoros Community environment.



• user_id (str, int) – The User ID of the user to be deleted

• return_json (bool) – Determines if the API response should be returned in JSON for-mat (False by default)


Raises khoros.errors.exceptions.FeatureNotConfiguredErrorkhoros.objects.users.get_album_count(khoros_object, user_settings=None, user_id=None, login=None,

email=None)This function gets the number of albums for a user.


• user_settings (dict, None) – A dictionary containing all relevant user settings sup-plied in the parent function





Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_email(khoros_object, user_settings=None, user_id=None, login=None,

first_name=None, last_name=None, allow_multiple=False,display_warnings=True)

This function looks up and retrieves the email address for a user by leveraging supplied user information.

Note: The priority of supplied fields are as follows: User ID, username, first and last name, last name, firstname























Returns The email address of the user as a string or a list of email addresses if allow_multipleis True

khoros.objects.users.get_followers_count(khoros_object, user_settings=None, user_id=None,login=None, email=None)

This function gets the count of community members who have added the user as a friend in the community.






Returns The number of community members who have added the user as a friend in integer format

Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_following_count(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function gets the count of community members the user has added as a friend in the community.






Returns The number of community members the user has added as a friend in integer format

Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_ids_from_login_list(khoros_object, login_list, return_type='list')

This function identifies the User IDs associated with a list of user logins. (i.e. usernames)


• login_list (list, tuple) – List of user login (i.e. username) values in string format




















• return_type (str) – Determines if the data should be returned as a list (default) or adict


Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_images_count(khoros_object, user_settings=None, user_id=None, login=None,

email=None)This function gets the count of images uploaded by the user.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_kudos_given_count(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function gets the count of kudos a user has given.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_kudos_received_count(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function gets the count of kudos a user has received.

























Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_last_visit_timestamp(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function retrieves the timestamp for the last time the user logged into the community.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_login(khoros_object, user_settings=None, user_id=None, email=None,

first_name=None, last_name=None, allow_multiple=False,display_warnings=True)

This is an alternative function name for the khoros.objects.users.get_username() function.

khoros.objects.users.get_messages_count(khoros_object, user_settings=None, user_id=None, login=None,email=None)

This function gets the count of messages (topics and replies) posted by the user.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_online_user_count(khoros_object)

This function retrieves the number of users currently online.

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


Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_public_images_count(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function gets the count of public images uploaded by the user.



















Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_registration_data(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function retrieves the registration data for a given user.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_registration_status(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function retrieves the registration status for a given user.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_registration_timestamp(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function retrieves the timestamp for when a given user registered for an account.



























Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_replies_count(khoros_object, user_settings=None, user_id=None, login=None,

email=None)This function gets the count of replies posted by the user.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_roles_count(khoros_object, user_settings=None, user_id=None, login=None,

email=None)This function gets the count of roles applied to the user.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_solutions_authored_count(khoros_object, user_settings=None, user_id=None,

login=None, email=None)This function gets the count of messages created by the user that are marked as accepted solutions.

























Returns The number of messages created by the user that are marked as accepted solutions ininteger format

Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_topics_count(khoros_object, user_settings=None, user_id=None, login=None,

email=None)This function gets the count of topic messages (excluding replies) posted by the user.






Returns The number of topic messages (excluding replies) posted by the user in integer format

Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_user_data(khoros_object, user_settings=None, user_id=None, login=None,

email=None)This function retrieves all user data for a given user.

Parameters• khoros_object (class[khoros.Khoros]) – he core khoros.Khoros object






Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.get_user_data_with_v1(khoros_object, return_field, filter_value, filter_field='email',

fail_on_no_results=False)This function retrieves user data using a Community API v1 call.


• return_field (str) – The field being retrieved by the function (e.g. id, login, etc.)

• filter_value (str, int) – The value for which to filter the user data being queried

• filter_field (str) – The field by which the API call should be filtered (email bydefault)


Returns The value of the return field for the user being queried


















khoros.objects.users.get_user_id(khoros_object, user_settings=None, login=None, email=None,first_name=None, last_name=None, allow_multiple=False,display_warnings=True, fail_on_no_results=False)

This function looks up and retrieves the User ID for a user by leveraging supplied user information.

Note: The priority of supplied fields are as follows: login, email, first and last name, last name, first name







• allow_multiple (bool) – Allows a list of User IDs to be returned if multiple results arefound (False by default)



Returns The username of the user as a string or a list of usernames if allow_multiple is True

khoros.objects.users.get_username(khoros_object, user_settings=None, user_id=None, email=None,first_name=None, last_name=None, allow_multiple=False,display_warnings=True, fail_on_no_results=False)

This function looks up and retrieves the username for a user by leveraging supplied user information.

Note: The priority of supplied fields are as follows: User ID, email, first and last name, last name, first name







• allow_multiple (bool) – Allows a list of usernames to be returned if multiple resultsare found



















Returns The User ID of the user as an integer or a list of User IDs if allow_multiple is True

khoros.objects.users.get_videos_count(khoros_object, user_settings=None, user_id=None, login=None,email=None)

This function gets the count of videos uploaded by the user.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.impersonate_user(khoros_object, user_login)

This function instantiates and returns the :py:class`khoros.objects.users.ImpersonatedUser` object whichcan then be passed to other methods and functions to perform operations as a secondary user.



Note: The authenticated user must have the Administrator role and/or have the SwitchUser permission enabled.

• user_login (str) – The username (i.e. login) of ther user to be impersonated












khoros.objects.users.process_user_settings(user_settings=None, user_id=None, albums=None,avatar=None, banned=None, biography=None,bonus_points=None, cover_image=None, deleted=None,email=None, email_excluded=None, first_name=None,followers=None, following=None, href=None,images=None, kudos_given=None, kudos_received=None,kudos_weight=None, language=None, last_name=None,last_visit_time=None, location=None, login=None,messages=None, metrics=None, online_status=None,password=None, personal_data=None,public_images=None, rank=None, registration_data=None,reviews=None, roles=None, signature_topics=None,solutions_authored=None, sso_id=None,threads_participated=None, topics=None,user_badges=None, videos=None, view_href=None,web_page_url=None)

This function processes the user_settings for functions and formats them into a normalized dictionary.



• user_id (int, str, None) – The unique User ID associated with the user

• albums (dict, None) – The image albums associated with the user’s profile

• avatar (str, None) – The avatar (profile image) of the user

• banned (bool, None) – Defines whether or not the user is banned (True if banned)


• bonus_points (int, None) – Bonus points that an admin has assigned to the user


• deleted (bool, None) – Defines whether or not the user’s account is deleted. (True ifdeleted)

• email (str, None) – The email address for the user

• email_excluded (bool, None) – Defines whether or not the user has selected the “don’tsend me any community emails” option


• followers (dict, None) – The community members who are subscribed to the user(i.e. “friends”)

• following (dict, None) – The community members who the user follows (i.e.“friends”)

• href (str, None) – Relative href to the user resource (i.e. canonical path to the resourcerelative to the API root)

• images (dict, None) – Images uploaded by the user

• kudos_given (dict, None) – The kudos given to the user by other community members

• kudos_received (dict, None) – The kudos received by the user from other communitymembers

• kudos_weight (int, None) – The weight of the kudos awarded























• language (str, None) – The default language selected by the user


• last_visit_time (type[datetime.datetime], None) – The date/time the user waslast active on the community

• location (str, None) – The user’s location

• login (str, None) – The username (i.e. login) for the user

• messages (dict, None) – The messages (topics and replies) posted by the user

• metrics – The metrics of the user activity

• online_status (str, None) – The status of the user (ONLINE or OFFLINE)


• personal_data – The personal_data object associated with the user account contain-ing PII about the user

• public_images (dict, None) – Images uploaded by the user that the user has madepublic

• rank (dict, None) – The rank of the user in the community (Value is -1 if no rank hasbeen achieved)

• registration_data (dict, None) – Registration information about the user

• reviews (dict, None) – Product reviews written by the user

• roles (dict, None) – The roles that have been assigned to the user

• signature_topics – Topics of interest associated with this user account that the userhas selected to display

• solutions_authored (dict, None) – The solutions authored by the user (i.e postsselected as an accepted solutions)


• threads_participated (list, None) – The topic IDs of message threads in whichthe user has participated

• topics (dict, None) – Topic messages (i.e the root message of a conversation) authoredby the user

• user_badges – Badges earned by the user (as well as visible but unearned badges de-pending on admin settings)

• videos (dict, None) – Videos uploaded by the user

• view_href (str, None) – The fully-qualified href to the user resource in the Web UI(i.e. the URI of the ViewProfile page)


Returns The dictionary containing the user settings

khoros.objects.users.query_users_table_by_id(khoros_object, select_fields, user_id, first_item=False)This function queries the users table for one or more given SELECT fields for a specific User ID using LiQL.

























• select_fields (str, tuple, list, set) – One or more SELECT field (e.g.login, messages.count(*), etc.) to query


• first_item (bool) – Determines if only the first item should be returned (False bydefault)


Raises khoros.errors.exceptions.GETRequestErrorkhoros.objects.users.structure_payload(user_settings=None, login=None, email=None, password=None,

first_name=None, last_name=None, biography=None,sso_id=None, web_page_url=None, cover_image=None)

This function properly structures the payload to be passed when creating or manipulating users via the API.

Changed in version 4.0.0: Fixed an issue that was resulting in a KeyError exception potentially getting raised,and added the missing type key that was preventing users from getting created successfully.












Returns The properly formatted payload within a dictionary

khoros.objects.users.structure_user_dict_list(khoros_object=None, user_dicts=None, id_list=None,login_list=None)

This function structures a list of user data dictionaries for use in various API request payloads.


• user_dicts (list, dict, None) – A list of dictionaries (or single dictionary) con-taining user data (id at a minimum)

• id_list (list, tuple, set, None) – A list of user IDs to be converted into user datadictionaries

• login_list (list, tuple, set, None) – A list of usernames (i.e. logins) to be con-verted into user data dictionaries

Returns The properly formatted list of user data dictionaries for the supplied users

Raises TypeError, khoros.errors.exceptions.MissingRequiredDataError






























khoros.objects.users.update_sso_id(khoros_object, new_sso_id, user_id=None, user_login=None)This function updates the SSO ID for a user.


Caution: This functionality is currently unsupported directly via REST API. It is recommended thatFreeMarker and a custom endpoint be leveraged instead. See Khoros Atlas for more details.


• new_sso_id (str) – The new SSO ID for the user





Return to Top

1.8.7 SAML Module (khoros.saml)

This module includes functions that relate to SAML Single Sign-On (SSO).

Module khoros.objects.saml

Synopsis This module includes functions that relate to SAML SSO.

Usage from khoros import saml

Example assertion = saml.import_assertion(file_path)




khoros.saml.import_assertion(file_path, base64_encode=True, url_encode=True)This function imports an XML SAML assertion as a string and optionally base64- and/or URL-encodes it.



• base64_encode (bool) – Determines if the assertion should be base64-encoded (Trueby default)

• url_encode (bool) – Determines if the assertion should be URL-encoded (True bydefault)



https://bit.ly/33iGZmW










khoros.saml.send_assertion(khoros_object, assertion=None, file_path=None, base64_encode=True,url_encode=True)

This function sends a SAML assertion as a POST request in order to provision a new user.



• assertion (str, None) – The SAML assertion in string format and optionally base64-and/or URL-encoded


• base64_encode (bool) – Determines if the assertion should be base64-encoded (Trueby default)

• url_encode (bool) – Determines if the assertion should be URL-encoded (True bydefault)



1.8.8 Structures Module (khoros.structures)

This module contains sub-modules that are specific to the various Community structures.

Module khoros.structures

Synopsis This module contains sub-modules that are specific to the various Community structures.

Usage from khoros import structures




Return to Top








Base Structures Module (khoros.structures.base)

This module contains functions relating to structures. (i.e. categories, nodes and tenants/communities)

Module khoros.structures.communities

Synopsis This module contains functions relating to structures (i.e. categories, nodes and tenants)

Usage from khoros.structures import base

Example details = base.get_details(khoros_object, 'category', 'category-id')



Modified Date 10 Mar 2021

class khoros.structures.base.Mapping

This class contains lists and dictionaries used to map structure data.

khoros.structures.base.get_details(khoros_object, identifier='', structure_type=None, first_item=None,community=False)

This function retrieves all details for a structure type via LiQL.



• identifier (str) – The identifier (Category/Node ID or URL) by which to filter theresults in the WHERE clause.

• structure_type – Designates the structure as a category, node or community

Note: Optional if the identifier is a URL or the community Boolean is True

• first_item (bool) – Filters the response data to the first item returned (True by default)

• community (bool) – Alternate way of defining the structure type as a community (Falseby default)

Returns The details for the structure type as a dictionary


khoros.structures.base.get_structure_field(khoros_object, field, identifier='', details=None,structure_type=None, first_item=True, community=False)

This function returns a specific API field value for a community, category or node collection.



• field (str) – The field from the khoros.structures.base.Mapping class whosevalue should be returned

• identifier (str) – The identifier (Category/Node ID or URL) by which to filter theresults in the WHERE clause.








• structure_type (str, None) – Designates the structure as a category, node orcommunity




Returns The API field value in its appropriate format


khoros.structures.base.get_structure_id(url)This function retrieves the Node ID from a full URL.

Changed in version 2.6.0: The function was renamed from _get_node_id to get_structure_id and convertedfrom private to public.


Parameters url (str) – The full URL of the node

Returns The ID in string format

khoros.structures.base.get_structure_type_from_url(url, ignore_exceptions=False)This function determines if a URL is for a category or node (or neither).


Parameters• url (str) – The URL to be evaluated

• ignore_exceptions (bool) – Determines if exceptions should not be raised

Returns A string with category or node, or a blank string if neither

khoros.structures.base.is_category_url(url, ignore_exceptions=False)This function identifies if a provided URL is for a category in the environment.




Returns Boolean value indicating if the URL is associated with a category

Raises khoros.errors.exceptions.InvalidStructureTypeErrorkhoros.structures.base.is_node_url(url, ignore_exceptions=False)

This function identifies if a provided URL is for a node in the environment.















Returns Boolean value indicating if the URL is associated with a node

Raises khoros.errors.exceptions.InvalidStructureTypeErrorkhoros.structures.base.limit_to_first_child(structure_data)

This function limits structure data to be only for the first child.


Parameters structure_data (dict) – The data captured from the khoros.structures.base.get_details() function

Returns The data dictionary that has been restricted to the first child

Raises TypeError, KeyError

khoros.structures.base.structure_exists(khoros_object, structure_type, structure_id=None,structure_url=None)

This function checks to see if a structure (i.e. node, board, category or group hub) exists.



• structure_type (str) – The type of structure (e.g. board, category, node orgrouphub) .. note:: The group hub value (as two words) is also acceptable.

• structure_id (str, None) – The ID of the structure to check

• structure_url (str, None) – The URL of the structure to check

Returns Boolean value indicating whether or not the structure already exists

Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.structures.base.verify_structure_type(identifier, structure_type, community=False)

This function verifies the structure type by examining the identifier(s) and provided structure type value.


Parameters• identifier (str) – The identifier (Category/Node ID or URL) by which to filter the

results in the parent function

• structure_type (str) – Designates the structure as a category, node or community



Returns The appropriately labeled and verified structure type

Raises khoros.errors.exceptions.InvalidStructureTypeError, khoros.errors.exceptions.MissingRequiredDataError

Return to Top













Boards Module (khoros.structures.boards)

This module contains functions specific to boards within the Khoros Community platform.

Module khoros.structures.boards

Synopsis This module contains functions specific to boards within the Khoros Community platform

Usage from khoros.structures import boards

Example board_url = boards.create(khoros_object, 'my-board', 'My Board','forum', return_url=True)




khoros.structures.boards.board_exists(khoros_object, board_id=None, board_url=None)This function checks to see if a board (i.e. blog, contest, forum, idea exchange, Q&A or TKB) exists.



• board_id (str, None) – The ID of the board to check



Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.structures.boards.create(khoros_object, board_id, board_title, discussion_style, description=None,

parent_category_id=None, hidden=None, allowed_labels=None,use_freeform_labels=None, use_predefined_labels=None,predefined_labels=None, media_type=None, blog_authors=None,blog_author_ids=None, blog_author_logins=None,blog_comments_enabled=None, blog_moderators=None,blog_moderator_ids=None, blog_moderator_logins=None,one_entry_per_contest=None, one_kudo_per_contest=None,posting_date_end=None, posting_date_start=None,voting_date_end=None, voting_date_start=None,winner_announced_date=None, full_response=None, return_id=None,return_url=None, return_api_url=None, return_http_code=None,return_status=None, return_error_messages=None, split_errors=False)

This function creates a new board within a Khoros Community environment.

Changed in version 2.5.2: Changed the functionality around the return_error_messages argument and addedthe split_errors argument.



• board_id (str) – The unique identifier (i.e. id field) for the new board (Required)






• board_title (str) – The title of the new board (Required)• discussion_style (str) – Defines the board as a blog, contest, forum, idea, qanda

or tkb (Required)• description (str, None) – A brief description of the board






• predefined_labels (list, None) – The pre-defined labels to utilized on the board asa list of dictionaries

Todo: The ability to provide labels as a simple list and optionally standardize their format(e.g. Pascal Case, etc.) will be available in a future release.







• blog_moderator_ids (list, None) – A list of User IDs representing the blog moder-ators in a blog board
































• voting_date_start (type[datetime.datetime], None) – The date/time when thevoting period for a contest begins





• return_url (bool, None) – Determines if the URL of the new board should be re-turned by the function

• return_api_url (bool, None) – Determines if the API URL of the new board shouldbe returned by the function

• return_http_code (bool, None) – Determines if the HTTP Code of the API responseshould be returned by the function






khoros.structures.boards.get_board_id(url)This function retrieves the Board ID for a given board when provided its URL.























khoros.structures.boards.structure_payload(khoros_object, board_id, board_title, discussion_style,description=None, parent_category_id=None,hidden=None, allowed_labels=None,use_freeform_labels=None, use_predefined_labels=None,predefined_labels=None, media_type=None,blog_authors=None, blog_author_ids=None,blog_author_logins=None, blog_comments_enabled=None,blog_moderators=None, blog_moderator_ids=None,blog_moderator_logins=None,one_entry_per_contest=None,one_kudo_per_contest=None, posting_date_end=None,posting_date_start=None, voting_date_end=None,voting_date_start=None, winner_announced_date=None)

This function structures the payload to use in a Community API v2 request involving a board.



• board_id (str) – The unique identifier (i.e. id field) for the new board (Required)• board_title (str) – The title of the new board (Required)• discussion_style (str) – Defines the board as a blog, contest, forum, idea, qanda

or tkb (Required)• description (str, None) – A brief description of the board






• predefined_labels (list, None) – The pre-defined labels to utilized on the board asa list of dictionaries

Todo: The ability to provide labels as a simple list and optionally standardize their format(e.g. Pascal Case, etc.) will be available in a future release.























• blog_moderator_ids (list, None) – A list of User IDs representing the blog moder-ators in a blog board







• voting_date_start (type[datetime.datetime], None) – The date/time when thevoting period for a contest begins




Return to Top

Categories Module (khoros.structures.categories)

This module contains functions specific to categories within the Khoros Community platform.

Module khoros.structures.categories

Synopsis This module contains functions specific to categories within the Khoros Community platform

Usage from khoros.structures import categories

Example category_id = categories.get_category_id(url)






















khoros.structures.categories.category_exists(khoros_object, category_id=None, category_url=None)This function checks to see if a category exists.



• category_id (str, None) – The ID of the category to check



Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.structures.categories.create(khoros_object, category_id, category_title, parent_id=None,

return_json=True)This function creates a new category.



• category_id (str) – The Category ID of the new category (e.g. video-games)



• return_json (bool) – Determines whether or not the response should be returned inJSON format (True by default)



khoros.structures.categories.friendly_date_enabled(khoros_object, identifier=None,category_details=None)

This function identifies if friendly dates are enabled for a given category.






Raises khoros.errors.exceptions.GETRequestError, khoros.errors.exceptions.InvalidFieldError, khoros.errors.exceptions.InvalidStructureTypeError,khoros.errors.exceptions.MissingRequiredDataError












khoros.structures.categories.get_active_skin(khoros_object, identifier=None, category_details=None)This function retrieves the skin being used with a given category.







khoros.structures.categories.get_category_details(khoros_object, identifier, first_item=True)This function returns a dictionary of category configuration settings.



• identifier (str) – The Category ID or Category URL with which to identify the cat-egory


Returns The category details within a dictionary


khoros.structures.categories.get_category_field(khoros_object, field, identifier=None,category_details=None)

This function returns a specific category field from the Khoros Community API.

















khoros.structures.categories.get_category_id(url)This function retrieves the Category ID for a given category when provided its URL.

Changed in version 2.6.0: The function was refactored to leverage the khoros.structures.base.get_structure_id() function.



Raises khoros.errors.exceptions.InvalidURLErrorkhoros.structures.categories.get_creation_date(khoros_object, identifier=None,

category_details=None)This function retrieves the creation date of a given category.







khoros.structures.categories.get_depth(khoros_object, identifier=None, category_details=None)This function retrieves the depth of a given category.







khoros.structures.categories.get_description(khoros_object, identifier=None, category_details=None)This function retrieves the description for a given category.














khoros.structures.categories.get_friendly_date_max_age(khoros_object, identifier=None,category_details=None)

This function retrieves the maximum age where friendly dates should be used (if enabled) for a given category.





Returns Integer representing the number of days the friendly date feature should be leveraged ifenabled


khoros.structures.categories.get_language(khoros_object, identifier=None, category_details=None)This function retrieves the defined language for a given category.







khoros.structures.categories.get_parent_id(khoros_object, identifier=None, category_details=None)This function retrieves the parent ID for a given category.















khoros.structures.categories.get_parent_type(khoros_object, identifier=None, category_details=None)This function retrieves the parent type for a given category.







khoros.structures.categories.get_parent_url(khoros_object, identifier=None, category_details=None)This function retrieves the parent URL for a given category.







khoros.structures.categories.get_position(khoros_object, identifier=None, category_details=None)This function retrieves the position of a given category.
















khoros.structures.categories.get_root_id(khoros_object, identifier=None, category_details=None)This function retrieves the root category ID for a given category.







khoros.structures.categories.get_root_type(khoros_object, identifier=None, category_details=None)This function retrieves the root category type for a given category.







khoros.structures.categories.get_root_url(khoros_object, identifier=None, category_details=None)This function retrieves the root category URL for a given category.
















khoros.structures.categories.get_title(khoros_object, identifier=None, full_title=True,short_title=False, category_details=None)

This function retrieves the full and/or short title of the category.




• full_title (bool) – Return the full title of the category (True by default)

• short_title (bool) – Return the short title of the category (False by default)

• category_details (dict, None) – Dictionary containing category details (optional)

Returns The category title(s) as a string or a tuple of strings


khoros.structures.categories.get_total_category_count(khoros_object)This function returns the total number of categories within the Khoros Community environment.

Deprecated since version 2.6.0: Use the khoros.structures.categories.get_total_count() functioninstead.



Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.categories.get_total_count(khoros_object)

This function returns the total number of categories within the Khoros Community environment.




Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.categories.get_url(khoros_object, category_id=None, category_details=None)

This function retrieves the URL of a given category.



• category_id (str, None) – The ID of the category to be evaluated (optional ifcategory_details dictionary is provided)











khoros.structures.categories.get_views(khoros_object, identifier=None, category_details=None)This function retrieves the total view count for a given category.







khoros.structures.categories.is_hidden(khoros_object, identifier=None, category_details=None)This function identifies whether or not a given category is hidden.







Return to Top








Communities Module (khoros.structures.communities)

This module contains functions specific to the high-level community configuration.

Module khoros.structures.communities

Synopsis This module contains functions specific to the high-level community configuration

Usage from khoros.structures import communities

Example details = get_community_details(khoros_object)




khoros.structures.communities.email_confirmation_required_to_post(khoros_object,community_details=None)

This function identifies if an email configuration is required before posting in the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.friendly_date_enabled(khoros_object, community_details=None)

This function if the friendly date functionality is utilized within the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_active_skin(khoros_object, community_details=None)

This function retrieves the primary active skin that is utilized within the environment.











khoros.structures.communities.get_community_details(khoros_object)This function returns a dictionary of community configuration settings.




Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_community_field(khoros_object, field, community_details=None)

This function returns a specific community field from the Khoros Community API.







khoros.structures.communities.get_creation_date(khoros_object, community_details=None)This function retrieves the timestamp for the initial creation of the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_date_pattern(khoros_object, community_details=None)

This function retrieves the date pattern (e.g. yyyy-MM-dd) utilized within the environment.












khoros.structures.communities.get_description(khoros_object, community_details=None)This function retrieves the description of the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_friendly_date_max_age(khoros_object, community_details=None)

This function identifies if the friendly date functionality is utilized within the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_language(khoros_object, community_details=None)

This function retrieves the language (e.g. en) utilized in the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_max_attachments(khoros_object, community_details=None)

This function retrieves the maximum number of attachments permitted per message within the environment.












khoros.structures.communities.get_ooyala_player_branding_id(khoros_object,community_details=None)

This function retrieves the branding ID for the Ooyala Player utilized within the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_permitted_attachment_types(khoros_object,

community_details=None)This function retrieves the attachment file types permitted within the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_primary_url(khoros_object, community_details=None)

This function retrieves the primary URL of the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_sign_out_url(khoros_object, community_details=None)

This function retrieves the Sign Out URL for the environment.












khoros.structures.communities.get_tenant_id(khoros_object, community_details=None)This function retrieves the tenant ID of the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.get_title(khoros_object, full_title=True, short_title=False,

community_details=None)This function retrieves the full and/or short title of the environment.







Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.show_breadcrumb_at_top_level(khoros_object,

community_details=None)This function identifies if breadcrumbs should be shown at the top level of the environment.




Returns Boolean value indicating if breadcrumbs are displayed at the top level of the environment

Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.show_community_node_in_breadcrumb(khoros_object,

community_details=None)This function identifies if the community node should be shown in breadcrumbs.













Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.top_level_categories_enabled(khoros_object,

community_details=None)This function identifies if top level categories are enabled within the environment.





Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.communities.top_level_categories_on_community_page(khoros_object, commu-

nity_details=None)This function identifies if top level categories are enabled on community pages.






Group Hubs Module (khoros.structures.grouphubs)

This module contains functions specific to group hubs within the Khoros Community platform.

Module khoros.structures.grouphubs

Synopsis This module contains functions specific to group hubs within the Khoros Community platform

Usage from khoros.structures import grouphubs

Example group_hub_url = grouphubs.create(khoros_object, gh_id, gh_title,disc_styles, return_url=True)



Modified Date 26 Dec 2020





khoros.structures.grouphubs.create(khoros_object, group_id, group_title, description=None,membership_type=None, open_group=None, closed_group=None,hidden_group=None, discussion_styles=None, enable_blog=None,enable_contest=None, enable_forum=None, enable_idea=None,enable_qanda=None, enable_tkb=None, all_styles_default=True,parent_category_id=None, avatar_image_path=None,full_response=None, return_id=None, return_url=None,return_api_url=None, return_http_code=None, return_status=None,return_error_messages=None, split_errors=False)

This function creates a new group hub within a Khoros Community environment.

Changed in version 2.7.2: Changed the data type for membership_type from dict to str in the docstring.



• group_id (str, int) – The unique identifier (i.e. id field) for the new group hub (Re-quired)

• group_title (str) – The title of the group hub (Required)• description (str, None) – A brief description of the group hub

• membership_type (str, None) – The membership_type value (open, closed orclosed_hidden)




• discussion_styles (list, None) – A list of discussion styles that will be permittedin the group hub

• enable_blog (bool, None) – Defines that the blog discussion style should be enabledfor the group hub

• enable_contest (bool, None) – Defines that the contest discussion style should beenabled for the group hub





• all_styles_default (bool) – Defines that all discussion styles should be enabled ifnot otherwise specified

• parent_category_id (str, int, None) – The parent category identifier (if applica-ble)

• avatar_image_path (str, None) – The file path to the avatar image to be uploaded (ifapplicable)





























• return_error_messages (bool, None) – Determines if any error messages associatedwith the API response should be returned by the function




khoros.structures.grouphubs.get_grouphub_id(url)This function retrieves the Group Hub ID for a given group hub when provided its URL.


Parameters url (str) – The URL from which to parse out the Group Hub ID

Returns The Group Hub ID retrieved from the URL

Raises khoros.errors.exceptions.InvalidURLErrorkhoros.structures.grouphubs.get_total_count(khoros_object)

This function returns the total number of group hubs within the Khoros Community environment.




khoros.structures.grouphubs.grouphub_exists(khoros_object, grouphub_id=None, grouphub_url=None)This function checks to see if a group hub exists.


Parameters












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

• grouphub_id (str, None) – The ID of the group hub to check



Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.structures.grouphubs.refresh_enabled_discussion_styles(khoros_object)

This function refreshes the all_discussion_styles global variable to match what is in the core objectsettings when applicable.




Returns None

khoros.structures.grouphubs.structure_payload(khoros_object, group_id, group_title, description=None,membership_type=None, open_group=None,closed_group=None, hidden_group=None,discussion_styles=None, enable_blog=None,enable_contest=None, enable_forum=None,enable_idea=None, enable_qanda=None,enable_tkb=None, all_styles_default=True,parent_category_id=None)

This function structures the payload to use in a Group Hub API request.

Changed in version 2.7.3: Changed the grouphub value in the initial payload definition to be a dictionary ratherthan a string to mitigate a TypeError exception getting raised.

Changed in version 2.7.2: Changed the data type for membership_type from dict to str in the docstring andfixed some bad logic raising false positive exceptions.



• group_id (str, int) – The unique identifier (i.e. id field) for the new group hub (Re-quired)

• group_title (str) – The title of the group hub (Required)• description (str, None) – A brief description of the group hub

• membership_type (str, None) – The membership_type value (open, closed orclosed_hidden)




• discussion_styles (list, None) – A list of discussion styles that will be permittedin the group hub

• enable_blog (bool, None) – Defines that the blog discussion style should be enabledfor the group hub
















• enable_contest (bool, None) – Defines that the contest discussion style should beenabled for the group hub





• all_styles_default (bool) – Defines that all discussion styles should be enabled ifnot otherwise specified

• parent_category_id (str, int, None) – The parent category identifier (if applica-ble)



khoros.structures.grouphubs.update_title(khoros_object, new_title, group_hub_id=None,group_hub_url=None, full_response=None, return_id=None,return_url=None, return_api_url=None,return_http_code=None, return_status=None,return_error_messages=None, split_errors=False)

This function updates the title of an existing group hub.



• new_title (str) – The new title for the group hub

• group_hub_id (str, None) – The group hub ID that identifies the group hub to update(necessary if URL not provided)

• group_hub_url (str, None) – The group hub URL that identifies the group hub toupdate (necessary if ID not provided)
























• return_error_messages (bool, None) – Determines if any error messages associatedwith the API response should be returned by the function




Return to Top

Nodes Module (khoros.structures.nodes)

This module contains functions specific to nodes within the Khoros Community platform.

Module khoros.structures.nodes

Synopsis This module contains functions specific to nodes within the Khoros Community platform

Usage from khoros.structures import nodes

Example node_id = nodes.get_id(url)




class khoros.structures.nodes.Mapping

This class includes dictionaries that map API fields and values to those used in this SDK.

khoros.structures.nodes.get_avatar_url(khoros_object, identifier, node_details=None, original=True,tiny=False, small=False, medium=False, large=False)

This function retrieves one or more avatar URLs for a given node.



• identifier (str, None) – The Node ID or Node URL with which to identify the node











• original (bool) – Indicates if the URL for the image in its original size should be re-turned (True by default)

• tiny (bool) – Indicates if the URL for the image in a tiny size should be returned (Falseby default)


• medium (bool) – Indicates if the URL for the image in a medium size should be returned(False by default)




khoros.structures.nodes.get_creation_date(khoros_object, identifier, node_details=None,friendly=False)

This function returns the creation date of a given node.





• friendly (bool) – Determines whether to return the “friendly” date (e.g. Friday) in-stead (False by default)



khoros.structures.nodes.get_depth(khoros_object, identifier, node_details=None)This function returns the depth of a given node.



















khoros.structures.nodes.get_description(khoros_object, identifier, node_details=None)This function returns the description of a given node.







khoros.structures.nodes.get_discussion_style(khoros_object, identifier, node_details=None)This function returns the full URL of a given Node ID.







khoros.structures.nodes.get_node_details(khoros_object, identifier, first_item=True)This function returns a dictionary of node configuration settings.



• identifier (str) – The Node ID or Node URL with which to identify the node




khoros.structures.nodes.get_node_field(khoros_object, field, identifier=None, node_details=None)This function returns a specific node field from the Khoros Community API.


Parameters









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






khoros.structures.nodes.get_node_id(url=None, node_type=None, node_details=None)This function retrieves the Node ID for a given node within a URL.

Parameters• url (str, None) – The URL from which to parse out the Node ID

• node_type (str, None) – The node type (e.g. blog, tkb, message, etc.) for the objectin the URL



Raises khoros.errors.exceptions.InvalidNodeTypeError, khoros.errors.exceptions.MissingRequiredDataError, khoros.errors.exceptions.NodeIDNotFoundError, khoros.errors.exceptions.NodeTypeNotFoundError

khoros.structures.nodes.get_node_type_from_url(url)This function attempts to retrieve a node type by analyzing a supplied URL.



Raises khoros.errors.exceptions.NodeTypeNotFoundErrorkhoros.structures.nodes.get_parent_id(khoros_object, identifier, node_details=None,

include_prefix=False)This function returns the Parent ID of a given node.





• include_prefix (bool) – Determines if the prefix (e.g. category:) should be in-cluded (False by default)















khoros.structures.nodes.get_parent_type(khoros_object, identifier, node_details=None)This function returns the parent type of a given node.







khoros.structures.nodes.get_parent_url(khoros_object, identifier, node_details=None)This function returns the parent URL of a given node.







khoros.structures.nodes.get_position(khoros_object, identifier, node_details=None)This function returns the position of a given node.















khoros.structures.nodes.get_root_id(khoros_object, identifier, node_details=None, include_prefix=False)This function returns the Root Category ID of a given node.





• include_prefix (bool) – Determines if the prefix (e.g. category:) should be in-cluded (False by default)



khoros.structures.nodes.get_root_type(khoros_object, identifier, node_details=None)This function returns the root category type of a given node.







khoros.structures.nodes.get_root_url(khoros_object, identifier, node_details=None)This function returns the root category URL of a given node.
















khoros.structures.nodes.get_title(khoros_object, identifier=None, full_title=True, short_title=False,node_details=None)

This function retrieves the full and/or short title of the node.




• full_title (bool) – Determines if the full title of the node should be returned (Trueby default)

• short_title (bool) – Determines if the short title of the node should be returned (Falseby default)




khoros.structures.nodes.get_total_node_count(khoros_object)This function returns the total number of nodes within the Khoros Community environment.



Raises khoros.errors.exceptions.GETRequestErrorkhoros.structures.nodes.get_type(khoros_object, identifier, node_details=None)

This function returns the full URL of a given Node ID.







khoros.structures.nodes.get_url(khoros_object, node_id=None, node_details=None)This function returns the full URL of a given Node ID.



• node_id (str, None) – The Node ID with which to identify the node













khoros.structures.nodes.get_views(khoros_object, identifier, node_details=None)This function returns the views for a given node.







khoros.structures.nodes.is_hidden(khoros_object, identifier, node_details=None)This function identifies whether or not a given node is hidden.







khoros.structures.nodes.node_exists(khoros_object, node_id=None, node_url=None)This function checks to see if a node exists.



• node_id (str, None) – The ID of the node to check













1.8.9 Studio Module (khoros.studio)

This module contains sub-modules that relate to the Lithium SDK and the Khoros Community Studio Plugin.

Module khoros.studio

Synopsis This module performs tasks that relate to the Lithium SDK and the Khoros Community StudioPlugin.

Usage from khoros import studio




Return to Top

Base Studio Module (khoros.studio.base)

This module contains functions that handle the base functionality of the khoros.studio module.

Module khoros.studio.base

Synopsis This module handles the base functionality of the studio module.

Usage import khoros.studio.base as studio_base




khoros.studio.base.get_node_version()

This function identifies and returns the installed Node.js version.



khoros.studio.base.get_npm_version()

This function identifies and returns the installed npm version.



khoros.studio.base.get_sdk_version()

This function identifies the currently installed version of the Lithium SDK.





khoros.studio.base.node_installed()

This function checks whether or not Node.js is installed.



khoros.studio.base.npm_installed()

This function checks whether or not npm is installed.



khoros.studio.base.sdk_installed()

This function checks to see if the Lithium SDK is installed.



Return to Top

The previous page addresses Khoros Core Object within the khoros package. The next page addresses the SupportingModules within the khoros package.

1.9 Supporting Modules

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

• Classes & Exceptions

– Errors Module (khoros.errors)

∗ Exceptions Module (khoros.errors.exceptions)

∗ Handlers Module (khoros.errors.handlers)

∗ Translations Module (khoros.errors.translations)

• Tools & Utilities

– Core Utilities Module (khoros.utils.core_utils)

– Logging Utilities Module (khoros.utils.log_utils)

– Environment Module (khoros.utils.environment)

– Helper Module (khoros.utils.helper)

– Version Module (khoros.utils.version)

• Unit Testing

– Tests Module (khoros.utils.tests)

∗ Resources Modules (khoros.utils.tests.resources)



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

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

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

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

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

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

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

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

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

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

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

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

1.9.1 Classes & Exceptions

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

Errors Module (khoros.errors)

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

Package khoros.errors

Synopsis This module includes custom exceptions

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

Example raise errors.exceptions.MissingAuthDataError




Return to Top

1.9. Supporting Modules 327


Exceptions Module (khoros.errors.exceptions)

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

Module khoros.errors.exceptions

Synopsis Collection of exception classes relating to the khoros library

Usage import khoros.errors.exceptions

Example raise khoros.errors.exceptions.BadCredentialsError()




exception khoros.errors.exceptions.APIConnectionError(*args, **kwargs)This exception is used when the API query could not be completed due to connection aborts and/or timeouts.

exception khoros.errors.exceptions.APIRequestError(*args, **kwargs)This exception is used for generic API request errors when there isn’t a more specific exception.

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

exception khoros.errors.exceptions.CurrentlyUnsupportedError(*args, **kwargs)This exception is used when a feature or functionality being used is currently unsupported.

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

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

exception khoros.errors.exceptions.DELETERequestError(*args, **kwargs)This exception is used for generic DELETE request errors when there isn’t a more specific exception.

exception khoros.errors.exceptions.DataMismatchError(*args, **kwargs)This exception is used when there is a mismatch between two data sources.


exception khoros.errors.exceptions.FeatureNotConfiguredError(*args, **kwargs)This exception is used when an API request fails because a feature is not configured.


exception khoros.errors.exceptions.GETRequestError(*args, **kwargs)This exception is used for generic GET request errors when there isn’t a more specific exception.

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

exception khoros.errors.exceptions.HelperFunctionNotFoundError(*args, **kwargs)This exception is used when a function referenced in the helper config file does not exist.

exception khoros.errors.exceptions.InvalidCallbackURLError(*args, **kwargs)This exception is used when an invalid Callback URL for OAuth 2.0 was not provided.

exception khoros.errors.exceptions.InvalidEndpointError(*args, **kwargs)This exception is used when an invalid API endpoint / service is provided.



exception khoros.errors.exceptions.InvalidFieldError(*args, **kwargs)This exception is used when an invalid field is provided.


exception khoros.errors.exceptions.InvalidHelperArgumentsError(*args, **kwargs)This exception is used when the helper function was supplied arguments instead of keyword arguments.

exception khoros.errors.exceptions.InvalidHelperFileTypeError(*args, **kwargs)This exception is used when an invalid file type is provided for the helper file.

exception khoros.errors.exceptions.InvalidLookupTypeError(*args, **kwargs)This exception is used when an invalid API lookup type is provided.

exception khoros.errors.exceptions.InvalidMessagePayloadError(*args, **kwargs)This exception is used when the payload for creating a message is invalid.

exception khoros.errors.exceptions.InvalidMetadataError(*args, **kwargs)This exception is used when there is an issue involving message metadata.


exception khoros.errors.exceptions.InvalidNodeTypeError(*args, **kwargs)This exception is used when an invalid node type is provided.

exception khoros.errors.exceptions.InvalidOperatorError(*args, **kwargs)This exception is used when an invalid operator is provided for the LiQL query.

exception khoros.errors.exceptions.InvalidPayloadValueError(*args, **kwargs)This exception is used when an invalid value is provided for a payload field.


exception khoros.errors.exceptions.InvalidRequestTypeError(*args, **kwargs)This exception is used when an invalid API request type is provided.

exception khoros.errors.exceptions.InvalidRoleError(*args, **kwargs)This exception is used when an invalid role is provided.

exception khoros.errors.exceptions.InvalidRoleTypeError(*args, **kwargs)This exception is used when an invalid role type is provided.

exception khoros.errors.exceptions.InvalidStructureTypeError(*args, **kwargs)This exception is used when an invalid node type is provided.


exception khoros.errors.exceptions.InvalidURLError(*args, **kwargs)This exception is used when a provided URL is invalid.


exception khoros.errors.exceptions.KhorosError

This is the base class for Khoros exceptions.

exception khoros.errors.exceptions.LiQLParseError(*args, **kwargs)This exception is used when a function is unable to successfully parse a LiQL response.




exception khoros.errors.exceptions.LookupMismatchError(*args, **kwargs)This exception is used when an a lookup value doesn’t match the supplied lookup type.

exception khoros.errors.exceptions.MessageTypeNotFoundError(*args, **kwargs)This exception is used when a message type cannot be identified from a given URL.

exception khoros.errors.exceptions.MissingAuthDataError(*args, **kwargs)This exception is used when authentication data is not supplied and therefore a connection cannot occur.

exception khoros.errors.exceptions.MissingRequiredDataError(*args, **kwargs)This exception is used when a function or method is missing one or more required arguments.

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


exception khoros.errors.exceptions.NodeIDNotFoundError(*args, **kwargs)This exception is used when a valid Node ID could not be found in a provided URL.

exception khoros.errors.exceptions.NodeTypeNotFoundError(*args, **kwargs)This exception is used when a valid node type could not be found in a provided URL.

exception khoros.errors.exceptions.NotFoundResponseError(*args, **kwargs)This exception is used when an API query returns a 404 response and there isn’t a more specific class.

exception khoros.errors.exceptions.OperatorMismatchError(*args, **kwargs)This exception is used when the number of operators in the LiQL query does not match the number of fields.

exception khoros.errors.exceptions.POSTRequestError(*args, **kwargs)This exception is used for generic POST request errors when there isn’t a more specific exception.


exception khoros.errors.exceptions.PUTRequestError(*args, **kwargs)This exception is used for generic PUT request errors when there isn’t a more specific exception.


exception khoros.errors.exceptions.PayloadMismatchError(*args, **kwargs)This exception is used when more than one payload is supplied for an API request.


exception khoros.errors.exceptions.SessionAuthenticationError(*args, **kwargs)This exception is used when the session key authentication attempt failed.

exception khoros.errors.exceptions.SsoAuthenticationError(*args, **kwargs)This exception is used when the SSO authentication attempt failed.


exception khoros.errors.exceptions.TooManyResultsError(*args, **kwargs)This exception is used when more results are returned than were expected in a LiQL query.

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




exception khoros.errors.exceptions.UnknownFileTypeError(*args, **kwargs)This exception is used when a file type of a given file cannot be identified.


exception khoros.errors.exceptions.UnsupportedNodeTypeError(*args, **kwargs)This exception is used when an unsupported node type has been provided.


exception khoros.errors.exceptions.UserCreationError(*args, **kwargs)This exception is used when an attempt to create a user fails.

Return to Top

Handlers Module (khoros.errors.handlers)

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

Module khoros.errors.handlers

Synopsis Functions that handle various error situations within the namespace

Usage from khoros.errors import handlers

Example error_msg = handlers.get_error_from_html(html_string)




khoros.errors.handlers.eprint(*args, **kwargs)This function behaves the same as the print() function but is leveraged to print errors to sys.stderr.

khoros.errors.handlers.get_error_from_html(html_error, v1=False)This function parses an error message from Khoros displayed in HTML format.

Changed in version 2.0.0: Added the v1 Boolean argument

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

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

Returns The concise error message parsed from the HTML

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

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

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

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



https://2.python-requests.org/en/master/api/#module-requests





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

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

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

khoros.errors.handlers.get_error_from_xml(xml_error, endpoint='', fail_on_no_results=True)This function retrieves any API errors returned from one of the Community APIs in XML format.

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

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

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

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

khoros.errors.handlers.verify_core_object_present(khoros_object)This function verifies whether or not the core object was supposed and raises an exception if not.


Returns None

Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.errors.handlers.verify_v1_response(api_response, query_type='get', endpoint='',

fail_on_no_results=False)This function evaluates a Community API v1 response to identify any failures.

Parameters• api_response – The response from the API call

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

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


Returns None

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

Return to Top











Translations Module (khoros.errors.translations)

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

Module khoros.errors.translations

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

Usage from khoros.errors import translations

Example error_msg = translations.translate_error(error_msg, khoros_object)



Modified Date 26 Dec 2020

khoros.errors.translations.parse_message(error_msg)This function parses error messages when necessary to prepare them for translation.

Parameters error_msg (str) – The original error message

Returns The prepared error message

khoros.errors.translations.translate_error(error_msg, khoros_object=None, translate_errors=True)This function translates API response errors into more relevant messages where possible and permitted.

Parameters• error_msg (str) – The original error message


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

Returnskhoros.errors.translations.translation_enabled(translate_errors=True, khoros_object=None)

This function identifies whether or not error translation is permitted.


Parameters• translate_errors (bool) – Defines if errors can be transmitted (True by default) even

with no core object


Returns Boolean value defining if translation is enabled

Return to Top







1.9.2 Tools & Utilities

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

Core Utilities Module (khoros.utils.core_utils)

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

Module khoros.utils.core_utils

Synopsis Collection of supporting utilities and functions to complement the primary modules

Usage from khoros.utils import core_utils

Example encoded_string = core_utils.encode_url(decoded_string)




khoros.utils.core_utils.convert_dict_id_values_to_strings(dict_list)This function ensures that the id keys in a list of dictionaries use string values.

Parameters dict_list (list, tuple, dict, None) – List (or tuple) of dictionaries (or a sin-gle dictionary) containing API object data

Returns A new dictionary list with properly formatted id values

Raises TypeError

khoros.utils.core_utils.convert_dict_list_to_simple_list(dict_list, fields)This function converts a list of dictionaries into a simple list consisting of the provided field(s).


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

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

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

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

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

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

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

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















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

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

Returns A new list of converted values

Raises TypeError, ValueError

khoros.utils.core_utils.convert_set(iterable, convert_to='list')This function casts a set variable to be a list instead so that it can be scriptable.

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

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

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

khoros.utils.core_utils.convert_single_value_to_tuple(value)This function converts a single value of nearly any type into a tuple.

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


Parameters value – The value to convert into a tuple

khoros.utils.core_utils.convert_string_to_tuple(value, delimiter='')THis function converts a value to a tuple if in string format.

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


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

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

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

khoros.utils.core_utils.decode_binary(binary)This function decodes a binary into a UTF-8 encoded string.


Parameters binary – The binary to be decoded

Returns The properly decoded string

Raises TypeError, ValueError

khoros.utils.core_utils.decode_html_entities(html_string)This function converts HTML entities (e.g. &, ', etc.) back to their original characters.

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

Returns The string with decoded HTML entities











khoros.utils.core_utils.display_warning(warn_msg)This function displays a UserWarning message via the warnings module.


Parameters warn_msg (str) – The message to be displayed

Returns None

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

This function encodes a string or bytes-like object


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

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

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

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

Returns The encoded object as a string or bytes-like object

Raises TypeError

khoros.utils.core_utils.encode_query_string(url_dict, no_encode=None, json_payload=False)This function compiles a URL query string from a dictionary of parameters.

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

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

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


Returns The URL query string in string format

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

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

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

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

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


https://docs.python.org/3/library/exceptions.html#UserWarning

https://docs.python.org/3/library/warnings.html#module-warnings
















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

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

Raises TypeError

khoros.utils.core_utils.get_file_type(file_path)This function attempts to identify if a given file path is for a YAML or JSON file.


Parameters file_path (str) – The full path to the file

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

Raises FileNotFoundError, khoros.errors.exceptions.UnknownFileTypeError

khoros.utils.core_utils.get_random_string(length=32, prefix_string='')This function returns a random alphanumeric string to use as a salt or password.

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

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

Returns The alphanumeric string

khoros.utils.core_utils.is_iterable(var)This function identifies if a given variable is an iterable.


Parameters var – The variable to check

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

khoros.utils.core_utils.is_numeric(value)This function checks whether or not a value is numeric either as an integer or a numeric string.


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

Returns Boolean value indicating if the examined value is numeric

khoros.utils.core_utils.merge_and_dedup(*data)This function merges various data elements into a single, deduplicated list.

Parameters data – One or more data elements to merge and deduplicate

Returns A merged and deduplicated list of data

khoros.utils.core_utils.remove_tld(url, strip_anchors=True)This function removes the top-level domain (TLD) from a Khoros Community platform URL.

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

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

Returns The URL beginning with /t5/














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

This function executes a shell command on the operating system.

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


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

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

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

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

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

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

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

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

Returns The results from the executed script

Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.utils.core_utils.url_decode(encoded_string)

This function decodes a url-encoded string.

Parameters encoded_string (str) – The url-encoded string

Returns The unencoded string

khoros.utils.core_utils.url_encode(raw_string)This function encodes a string for use in URLs.

Parameters raw_string (str) – The raw string to be encoded

Returns The encoded string

Return to Top


https://bandit.readthedocs.io/en/latest/plugins/b602_subprocess_popen_with_shell_equals_true.html




https://docs.python.org/3/library/subprocess.html#subprocess.run









Logging Utilities Module (khoros.utils.log_utils)

This module includes various utilities to assist with logging.

Module khoros.utils.log_utils

Synopsis Collection of logging utilities and functions

Usage from khoros.utils import log_utils

Example logger = log_utils.initialize_logging(__name__)




class khoros.utils.log_utils.LessThanFilter(exclusive_maximum, name='')This class allows filters to be set to limit log levels to only less than a specified level.


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

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


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

Return to Top

Environment Module (khoros.utils.environment)

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

Module khoros.objects.messages

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

Usage from khoros.utils import environment

Example TBD




khoros.utils.environment.get_env_variables()

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


Returns A dictionary with any relevant, defined environment variables


https://stackoverflow.com/users/5124424/zoey-greer

https://stackoverflow.com/a/31459386


khoros.utils.environment.update_env_variable_names(custom_names)This function updates the original environment variable names with custom names when applicable.


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

Returns None

Return to Top

Helper Module (khoros.utils.helper)

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

Module khoros.utils.helper

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

Usage from khoros.utils import helper

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



Modified Date 23 Feb 2021

class khoros.utils.helper.HelperParsing

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

khoros.utils.helper.get_helper_settings(file_path, file_type='yaml', defined_settings=None)This function returns a dictionary of the defined helper settings.

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

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

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

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

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

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

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

Returns Dictionary of helper variables

Raises khoros.errors.exceptions.InvalidHelperFileTypeError








khoros.utils.helper.import_helper_file(file_path, file_type)This function imports a YAML (.yml) or JSON (.json) helper config file.

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

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

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

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

Returns The parsed configuration data

Raises FileNotFoundError, khoros.errors.exceptions.InvalidHelperFileTypeError

Return to Top

Version Module (khoros.utils.version)

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

Module khoros.utils.version

Synopsis This simple script contains the package version

Usage from .utils import version

Example __version__ = version.get_full_version()




khoros.utils.version.get_full_version()

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

khoros.utils.version.get_latest_stable()

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

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

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

Returns The latest stable version in string format

khoros.utils.version.get_major_minor_version()

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

khoros.utils.version.latest_version()

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

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






Returns Boolean value indicating if the versions match

khoros.utils.version.log_current_version(debug=False)This function reports the current running version of the library in a debug log entry.


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

Returns None

khoros.utils.version.warn_when_not_latest()

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

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

Returns None

Return to Top

1.9.3 Unit Testing

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

Tests Module (khoros.utils.tests)

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

Module khoros.utils.tests

Synopsis This package includes tests for the khoros library.




Return to Top



https://docs.python.org/3/library/exceptions.html#RuntimeWarning



Resources Modules (khoros.utils.tests.resources)

This module includes frequently used resources for performing unit testing.

Module khoros.utils.tests.resources

Synopsis Frequently used resources for performing unit testing

Usage from khoros.utils.tests import resources

Example exceptions = resources.import_exceptions_module()




khoros.utils.tests.resources.get_structure_collection(structure_type)This function identifies the API collection for a given structure type.


Parameters structure_type – The structure type for which to return the corresponding collec-tion.

Returnskhoros.utils.tests.resources.get_testing_config()

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


khoros.utils.tests.resources.import_modules(*modules)This function imports and returns one or more modules to utilize in a unit test.


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

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

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

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

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


Returns The initialized khoros.core.Khoros object

khoros.utils.tests.resources.instantiate_with_local_helper(production=False)This function instantiates a Khoros object using a local helper file for unit testing.


Parameters production (bool, None) – Defines whether or not the helper file is associated witha Production environment

Returns The instantiated khoros.core.Khoros object




khoros.utils.tests.resources.local_helper_exists(production=False)This function checks to see if a helper file is present in the local/ directory.


Parameters production (bool, None) – Defines whether or not the helper file is associated witha Production environment

Returns Boolean value indicating whether or not the local helper file was found

khoros.utils.tests.resources.local_test_config_exists()

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


Returns Boolean value indicating whether or not the file was found

khoros.utils.tests.resources.parse_testing_config_file()

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


Returns None

khoros.utils.tests.resources.set_package_path()

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


Returns None

Return to Top

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

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

Module khoros.utils.tests.test_board_creation

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




khoros.utils.tests.test_board_creation.get_dict_for_required_fields(required_fields)This function places the required fields in a properly formatted dictionary.

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

Returns Dictionary containing the required fields

khoros.utils.tests.test_board_creation.get_required_fields(board_type='forum', all_types=False)This function defines required fields that can be used in other tests.

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








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

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

khoros.utils.tests.test_board_creation.test_description()

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

khoros.utils.tests.test_board_creation.test_invalid_board_type()

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

khoros.utils.tests.test_board_creation.test_no_arguments()

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

khoros.utils.tests.test_board_creation.test_required_fields()

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

khoros.utils.tests.test_board_creation.test_valid_board_types()

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

khoros.utils.tests.test_board_creation.verify_data_fields(payload, data_fields)This function checks a dictionary of data fields and values to ensure they match what is in the payload.

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

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

Returns Boolean value indicating whether or not the verification checks out

Return to Top

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

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

Module khoros.utils.tests.test_core_utils

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




khoros.utils.tests.test_core_utils.import_core_utils()

This function imports the khoros.utils.core_utils module.

khoros.utils.tests.test_core_utils.set_package_path()


khoros.utils.tests.test_core_utils.test_convert_set()

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

khoros.utils.tests.test_core_utils.test_merge_and_dedup()

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






khoros.utils.tests.test_core_utils.test_numeric_eval()

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

khoros.utils.tests.test_core_utils.test_query_string_encoding()

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

khoros.utils.tests.test_core_utils.test_remove_tld()

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

khoros.utils.tests.test_core_utils.test_url_encoding()

This function tests the khoros.utils.core_utils.url_encode() and khoros.utils.core_utils.url_decode() functions.

Return to Top

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

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

Module khoros.utils.tests.test_grouphub_creation

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




khoros.utils.tests.test_grouphub_creation.test_no_arguments()

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

khoros.utils.tests.test_grouphub_creation.test_only_id()

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

khoros.utils.tests.test_grouphub_creation.verify_data_fields(payload, data_fields)This function checks a dictionary of data fields and values to ensure they match what is in the payload.

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

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

Returns Boolean value indicating whether or not the verification checks out

Return to Top





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

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

Module khoros.utils.tests.test_helper_file

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




khoros.utils.tests.test_helper_file.get_helper_path()

This function defines the appropriate path to the helper file.

khoros.utils.tests.test_helper_file.set_package_path()


khoros.utils.tests.test_helper_file.test_yaml_file()

This function tests the import of a YAML file.

Return to Top

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

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

Module khoros.utils.tests.test_http_headers

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




khoros.utils.tests.test_http_headers.compare_headers(headers)This function compares two HTTP headers to ensure they are the same.


khoros.utils.tests.test_http_headers.test_normalize_empty_headers()

This function verifies that passing an empty dictionary to khoros.api._normalize_headers() returnsthe same empty dictionary.


khoros.utils.tests.test_http_headers.test_normalize_headers()

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




khoros.utils.tests.test_http_headers.test_normalize_type_error()

This function verifies that passing no arguments to khoros.api._normalize_headers() raises aTypeError exception.


Return to Top

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

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

Module khoros.utils.tests.test_library_import

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




khoros.utils.tests.test_library_import.import_pkg_operation()

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

khoros.utils.tests.test_library_import.set_package_path()


khoros.utils.tests.test_library_import.test_library_import()

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

Return to Top

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

This module tests parsing and/or executing LiQL queries.

Module khoros.utils.tests.test_liql

Synopsis This module is used by pytest to verify that LiQL queries can be performed and parsed success-fully.




khoros.utils.tests.test_liql.parse_where_clauses()

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

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




khoros.utils.tests.test_liql.perform_test_query(return_items=False)This function performs a LiQL query and saves the response in a global variable.

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

Returns None

khoros.utils.tests.test_liql.set_package_path()


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

khoros.utils.tests.test_liql.test_liql_query()

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


khoros.utils.tests.test_liql.test_return_items_option()

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


khoros.utils.tests.test_liql.test_where_clause_parsing()

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

Return to Top

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

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

Module khoros.utils.tests.test_mentions

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




khoros.utils.tests.test_mentions.expected_content_response(response)This function replaces the TLD to match the example constant and then identifies if the response was expected.


Parameters response (str) – The response received from the function

Returns Boolean value indicating if the response was expected

khoros.utils.tests.test_mentions.expected_user_response(response)This function identifies if the response was expected.


Parameters response (str) – The response received from the function






Returns Boolean value indicating if the response was expected

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

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


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

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

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

Returns A tuple containing the appropriate test data

khoros.utils.tests.test_mentions.get_user_test_data()

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


Returns The User ID and login as a tuple of two strings

khoros.utils.tests.test_mentions.set_package_path()



khoros.utils.tests.test_mentions.test_bad_content_url()

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


Returns None

Raises khoros.errors.exceptions.MessageTypeNotFoundErrorkhoros.utils.tests.test_mentions.test_content_mention_with_all_arguments()

This function tests the khoros.objects.messages.format_content_mention() when all required argumentshave been supplied.


Returns None

khoros.utils.tests.test_mentions.test_content_mention_with_false_id_arg()

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


Returns None

khoros.utils.tests.test_mentions.test_content_mention_with_false_id_dict()

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


Returns None





khoros.utils.tests.test_mentions.test_content_mention_with_full_dict()

This function tests the khoros.objects.messages.format_content_mention() when all required dictionarykeys and values have been supplied.


Returns None

khoros.utils.tests.test_mentions.test_content_mention_with_no_id_arg()

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


Returns None

khoros.utils.tests.test_mentions.test_content_mention_with_no_id_dict()

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


Returns None

khoros.utils.tests.test_mentions.test_relative_content_url_with_object()

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


Returns None

khoros.utils.tests.test_mentions.test_relative_content_url_without_object()

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


Returns None

Raises khoros.errors.exceptions.MissingRequiredDataErrorkhoros.utils.tests.test_mentions.test_user_mention_with_args_no_object()

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


Returns None

Raises khoros.errors.exceptions.MissingAuthDataErrorkhoros.utils.tests.test_mentions.test_user_mention_with_arguments()

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


Returns None

khoros.utils.tests.test_mentions.test_user_mention_with_dict_and_object()

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


Returns None



khoros.utils.tests.test_mentions.test_user_mention_with_dictionary()

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


Returns None

khoros.utils.tests.test_mentions.test_user_mention_with_dictionary_no_object()

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


Returns None

Raises khoros.errors.exceptions.MissingAuthDataErrorReturn to Top

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

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

Module khoros.utils.tests.test_messages

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




khoros.utils.tests.test_messages.assert_tags_present(payload, tags_to_find)This function asserts that specific tags are found within API payload.

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

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

Returns None

Raises AssertionError

khoros.utils.tests.test_messages.get_control_data(test_type)This function retrieves control data to use in unit tests.

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

Returns Payload control data in dictionary format

khoros.utils.tests.test_messages.test_construct_only_subject()

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






https://docs.python.org/3/library/exceptions.html#AssertionError



khoros.utils.tests.test_messages.test_construct_with_body()

This function tests constructing payload using a message body.

khoros.utils.tests.test_messages.test_construct_with_node()

This function tests constructing payload using properly formatted node data.

khoros.utils.tests.test_messages.test_construct_with_node_id()

This function tests constructing payload using a Node ID.

khoros.utils.tests.test_messages.test_construct_with_node_url()

This function tests constructing payload using a Node URL.

khoros.utils.tests.test_messages.test_construct_with_one_int_tag()

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

khoros.utils.tests.test_messages.test_construct_with_one_str_tag()

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

khoros.utils.tests.test_messages.test_construct_with_str_iter_int_tags()

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

khoros.utils.tests.test_messages.test_construct_with_str_iter_int_tags_ignore()

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

khoros.utils.tests.test_messages.test_construct_with_tag_iterables()

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

khoros.utils.tests.test_messages.test_payload_validation()

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


Return to Top

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

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

Module khoros.utils.tests.test_node_id_extract

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




Version 1.0.2

khoros.utils.tests.test_node_id_extract.get_test_data()

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

Returns The test_data dictionary with the node types and associated test URLs



khoros.utils.tests.test_node_id_extract.set_package_path()


khoros.utils.tests.test_node_id_extract.test_url_without_node()

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

Returns None

Raises AssertionError, khoros.errors.exceptions.NodeTypeNotFoundError

khoros.utils.tests.test_node_id_extract.test_with_invalid_node_types()

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

Returns None

Raises AssertionError, khoros.errors.exceptions.InvalidNodeTypeError

khoros.utils.tests.test_node_id_extract.test_with_only_url()

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

Returns None

Raises AssertionError

khoros.utils.tests.test_node_id_extract.test_with_valid_node_types()

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

Returns None

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

Return to Top

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

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

Module khoros.utils.tests.test_settings

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




khoros.utils.tests.test_settings.set_package_path()



khoros.utils.tests.test_settings.test_invalid_node_type_exception()

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








khoros.utils.tests.test_settings.test_node_setting_retrieval()

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


Return to Top

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

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

Module khoros.utils.tests.test_tags

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




khoros.utils.tests.test_tags.get_structure_control_data(test_type)This function retrieves the control data to use in tag structure tests.

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

Returns The control data for the given test type

khoros.utils.tests.test_tags.test_message_structure_one_string_tag_ignore()

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

khoros.utils.tests.test_tags.test_message_structure_one_tag()

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

khoros.utils.tests.test_tags.test_message_structure_str_int()

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

khoros.utils.tests.test_tags.test_message_structure_str_int_ignore()

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

khoros.utils.tests.test_tags.test_message_structure_two_string_tags_ignore()

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

khoros.utils.tests.test_tags.test_message_structure_two_tags()

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

khoros.utils.tests.test_tags.test_single_tag_structure()

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

Return to Top




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

1.10 Change Log

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

1.10.1 v4.5.0

Release Date: 2022-01-16

Added

Core Object

Additions to the Khoros Core Object.

• Added the khoros.core.Khoros.Message.get_metadata() method.

Primary Modules

Additions to the primary modules.

• Added the khoros.objects.messages.get_metadata() function.

Supporting Modules

Additions to the supporting modules.

• Added the khoros.errors.exceptions.InvalidMetadataError exception class.

Changed

Core Object

Changes to the Khoros Core Object.

• Replaced the phrase “This function” with “This method” in all of the core method docstrings.



1.10.2 v4.4.0


Changed

Core Object


• Introduced the proxy_user_object parameter to the khoros.core.Khoros.Message.create()method toallow messages to be created on behalf of other users.

• Introduced the proxy_user_object parameter to the khoros.core.Khoros.Message.update()method toallow messages to be updated on behalf of other users.

Primary Modules

Changes to the primary modules.

• Introduced the proxy_user_object parameter to the khoros.objects.messages.create() function to al-low messages to be created on behalf of other users.

• Introduced the proxy_user_object parameter to the khoros.objects.messages.update() function to al-low messages to be updated on behalf of other users.

1.10.3 v4.3.0.post1


Changed

General

• Added Python version 3.10 to setup.py.

1.10. Change Log 357


1.10.4 v4.3.0


Added

Core Object


• Added the khoros.core.Khoros.Message.validate_message_payload() static method.

• Added the khoros.core.Khoros.SAML inner class with the following methods:– khoros.core.Khoros.SAML.import_assertion()– khoros.core.Khoros.SAML.send_assertion()

• Added the khoros.core.Khoros._import_saml_class() method.

Primary Modules


• Added the khoros.saml module with the following functions:– khoros.saml.import_assertion()– khoros.saml.send_assertion()– khoros.saml._is_decoded()

– khoros.saml._get_api_uri()

• Added the khoros.objects.messages.validate_message_payload() function.

• Added the khoros.objects.labels module to begin addressing the enhancement request #48.

• Added the global variable ssl_verify_disabled to the khoros.api module to allow the verification to beperformed even in functions that do not leverage the instantiated core object.

• Added the khoros.api._display_ssl_verify_warning() function.

Supporting Modules


• Added the khoros.errors.exceptions.InvalidMessagePayloadError exception class.

• Added the khoros.utils.tests.test_messages.test_payload_validation() test function.


https://github.com/jeffshurtliff/khoros/issues/48


Documentation

• Added the khoros.saml and khoros.objects.labels modules to the Primary Modules page.

• Added a TODO section in the docstring for the khoros.objects.messages.construct_payload() functionto indicate the missing functionality that still remains to be added.

• Added the new Managing Node Settings page to the documentation.

General

• Created the GitHub issue template .github/ISSUE_TEMPLATE/documentation_request.md.

Changed

Core Object


• Added support for the full_payload parameter in the khoros.core.Khoros.Message.create() methodto implement the enhancement request #46.

• Added support for the wrap_json parameter in the khoros.core.Khoros.Tag.structure_tags_for_message() function to implement the enhancement request #47.

• Updated the __init__ module for the core object class to define the ssl_verify_disabled global variablein the khoros.api module as True when the ssl_verify flag in the core settings are explicitly set to False.(See line 186)

Primary Modules


• Added support for the full_payload parameter in the khoros.objects.messages.create() function toimplement the enhancement request #46.

• Added support for the wrap_json parameter in the khoros.objects.tags.structure_tags_for_message() function to implement the enhancement request #47.

• Updated the __all__ variable in the khoros.objects init module (__init__py.) and added import state-ments for the khoros.objects.attachments, khoros.objects.base and khoros.objects.labelsmod-ules.

• Updated the khoros.api.should_verify_tls() function to introduce the ssl_verify_disabled globalvariable, which allows the check to be performed even when the core object is not passed to the function.







Supporting Modules

Changes to the supporting modules.

• Added support for utilizing the defined_settings parameter in the khoros.utils.tests.resources.initialize_khoros_object() function.

General

• Updated the GitHub issue template .github/ISSUE_TEMPLATE/bug_report.md to be more intuitive.

• Added quotes in pythonpackage.yml to avoid issue referenced in actions/setup-python#160.

• Added Python v3.10 to pythonpackage.yml.

• Refactored pythonpackage.yml to perform macOS builds in order to ensure support for Python v3.10 perrequest #50.

Fixed

Core Object

Fixes in the Khoros Core Object.

• Fixed some incorrect information in the docstring for khoros.core.Khoros.User.get_username().

• Fixed an issue in the __init__ method of the core object where the ssl_verify parameter was being mostlydisregarded.

• Fixed an issue in the __init__ method of the core object where the auto_connect parameter defined via thedefined_settings parameter was being disregarded.

Primary Modules

Fixes in the primary modules.

• Fixed an issue in the following functions that prevented the SSL verification from being disabled when configuredto do so in the helper settings.

– khoros.api._api_request_with_payload()

– khoros.api._api_request_without_payload()

– khoros.api.delete()– khoros.api.perform_v1_search()– khoros.api.make_v1_request()– khoros.api.get_platform_version()

• Refactored the khoros.liql.parse_where_clause() function to be more efficient and Pythonic, and addedmissing parenthesis on the exception classes. Docstring syntax errors were also fixed.


https://github.com/actions/setup-python/issues/160

https://docs.python.org/3/whatsnew/3.10.html



Supporting Modules

Fixes in the supporting modules.

• Fixed an issue in the khoros.utils.helper.get_helper_settings() function where the ssl_verify fieldwas being overridden even if defined elsewhere.

1.10.5 v4.2.1


Fixed

Primary Modules

Fixes to the primary modules.

• Updated the khoros.api.put_request_with_retries() function call within the khoros.roles._assign_role_with_v2() function to explicitly define the content-type as application/json in order toresolve Issue #45.

1.10.6 v4.2.0


Added

Core Object


• Added the khoros.core.Khoros._connect_with_lithium_token()method to connect using LithiumSSOToken authentication.

Note: This change was introduced by stevenspasbo via Pull Request #42.



https://developer.khoros.com/khoroscommunitydevdocs/docs/lithiumsso-token


https://github.com/stevenspasbo

https://github.com/jeffshurtliff/khoros/pull/42


Primary Modules


• Added the khoros.auth.get_sso_key() function.

• Added the khoros.auth._get_khoros_login_url() private function.

Note: This change was introduced by stevenspasbo via Pull Request #42. However, the use of the xml.etree.ElementTree module was replaced with the defusedxml.ElementTree module to proactively mitigate aknown XML attack vulnerability in the former module.

Supporting Modules


• Added the khoros.errors.exceptions.SsoAuthenticationError exception for use with LithiumSSO To-ken authentication.

• Added the khoros.utils.tests.test_ssl_verify module with the following test functions:– khoros.utils.tests.test_ssl_verify.test_default_core_object_setting()

– khoros.utils.tests.test_ssl_verify.test_core_object_with_param_setting()

– khoros.utils.tests.test_ssl_verify.test_api_global_variable_assignment()

– khoros.utils.tests.test_ssl_verify.test_api_should_verify_function()

Documentation

• Added example syntax for authenticating using a LithiumSSO token in the README.md file.


Changed

Core Object


• Support was introduced in the khoros.core.Khoros core object class to support LithiumSSO Token authenti-cation.


• Support was introduced in the khoros.core.Khoros core object class to support user impersonation with Lithi-umSSO token authentication.





https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree

https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree

https://bandit.readthedocs.io/en/latest/blacklists/blacklist_calls.html#b313-b320-xml













• The following methods within the khoros.core.Khoros core object class were improved to avoid unnecessaryKeyError exceptions:

– khoros.core.Khoros._populate_core_settings()

– khoros.core.Khoros._populate_auth_settings()

– khoros.core.Khoros._populate_construct_settings()

– khoros.core.Khoros._parse_helper_settings()

– khoros.core.Khoros._validate_base_url()

– khoros.core.Khoros._define_url_settings()

– khoros.core.Khoros._session_auth_credentials_defined()

– khoros.core.Khoros._connect_with_session_key()

– khoros.core.Khoros.connect()– khoros.core.Khoros.get()

• General code improvements were made throughout the __init__ method for the khoros.core.Khoros coreobject class.

Primary Modules


• The URI in the khoros.auth.get_session_key() function is now generated utilizing the khoros.auth._get_khoros_login_url() function.


• Support was introduced in the khoros.objects.users.ImpersonatedUser object class to support user im-personation with LithiumSSO token authentication.


General

• Added the defusedxml package to requirements.txt and as a required install package in setup.py.

Fixed

Core Object

Fixes to the Khoros Core Object.

• Resolved Issue #41 which involved the requests.exceptions.InvalidSchema exception being raised whenusing absolute URLs with the khoros.core.Khoros.get(), khoros.core.Khoros.post() and khoros.core.Khoros.put() core methods.

• Corrected how the exception error message is defined in the khoros.core.Khoros.connect() method.









1.10.7 v4.1.1


Changed

Primary Modules


• Updated the khoros.objects.archives.aggregate_results_data() function to properly handle theARCHIVED status when it is returned.

1.10.8 v4.1.0


Added

Core Object


• Added the khoros.core.Khoros.Archives inner class within the core khoros.Khoros object with the fol-lowing methods:

– khoros.core.Khoros.Archives.archive()– khoros.core.Khoros.Archives.unarchive()– khoros.core.Khoros.Archives.aggregate_results()

• Added the khoros.core.Khoros._import_archives_class() method.

• Added the khoros.core.Khoros.Tag inner class within the core khoros.Khoros object with the followingmethods:

– khoros.core.Khoros.Tag.get_tags_for_message()– khoros.core.Khoros.Tag.add_single_tag_to_message()– khoros.core.Khoros.Tag.add_tags_to_message()– khoros.core.Khoros.Tag.structure_single_tag_payload()



– khoros.core.Khoros.Tag.structure_tags_for_message()• Added the khoros.core.Khoros._import_tag_class() method.

Primary Modules


• Added the khoros.objects.archives.aggregate_results_data() function.

Supporting Modules


• Added the following functions to utilize with the pytest package for unit testing:

– khoros.utils.tests.resources.local_helper_exists()– khoros.utils.tests.resources.instantiate_with_local_helper()– khoros.utils.tests.resources._get_local_helper_file_name()

– khoros.utils.tests.resources.local_test_config_exists()– khoros.utils.tests.resources.parse_testing_config_file()– khoros.utils.tests.resources.get_testing_config()– khoros.utils.tests.resources.get_structure_collection()

• Added the following functions to the khoros.utils.tests.test_liql module:– khoros.utils.tests.test_liql.perform_test_query()– khoros.utils.tests.test_liql.test_liql_query()– khoros.utils.tests.test_liql.test_return_items_option()

• Added the khoros.utils.tests.test_settings module with the following functions:– khoros.utils.tests.test_settings.set_package_path()– khoros.utils.tests.test_settings.test_node_setting_retrieval()– khoros.utils.tests.test_settings.test_invalid_node_type_exception()

Documentation

• Added sections for the khoros.core.Khoros.Archives and khoros.core.Khoros.Archives inner classeson the Khoros Core Object page.

• Added a section for the khoros.utils.tests.test_settings module on the Supporting Modules page.



Changed

Core Object


• Removed the following parameters from the khoros.core.Khoros.Archives.archive() andkhoros.core.Khoros.Archives.unarchive() methods: full_response, return_id, return_url,return_api_url, return_http_code, return_status, return_error_messages and split_errors

• Introduced the return_items parameter in the khoros.core.Khoros.query() function to automatically re-duce the JSON response to only the returned items when desired. (False by default)

Primary Modules


• Some minor docstring adjustments were made in the khoros.objects.archives.archive andkhoros.objects.archives.unarchive functions.

• Explicitly set the full_response flag in the khoros.objects.archives.archive() and khoros.objects.archives.unarchive() functions because of unique response format and subsequently removed thefollowing parameters: full_response, return_id, return_url, return_api_url, return_http_code,return_status, return_error_messages and split_errors

• Introduced the optional aggregate_results parameter in the khoros.objects.archives.archive andkhoros.objects.archives.unarchive functions.

• Introduced the return_items parameter in the khoros.liql.perform_query() function to automaticallyreduce the JSON response to only the returned items when desired. (False by default)

• Imported the khoros.objects.tags module within the __init__ file for the khoros.objects module andadded tags to the __all__ special variable.

Supporting Modules


• Renamed the khoros.utils.tests.test_liql_where_parsing module to be khoros.utils.tests.test_liql to allow other LiQL tests to be performed within the same module.

• Updated the khoros.utils.tests.test_liql.set_package_path() function to leverage a global variableto ensure the operation is only performed once.

Documentation

• Updated the supporting modules to account for the renamed khoros.utils.tests.test_liql module.



General

• Adjusted the Sphinx-related package versions in requirements.txt.

Fixed

Core Object


• Corrected an issue in the khoros.core.Khoros.Role.get_roles_for_user() docstring where the wrongraised exception was referenced.


• Added some missing exception references in the khoros.core.Khoros.query() docstring.

Primary Modules


• Fixed an issue with the khoros.objects.archives.structure_archive_payload() function call in thekhoros.objects.archives.archive() function.

• Renamed the incorrect JSON field messageID to be messageId instead in the khoros.objects.archives._format_single_archive_entry() function to prevent the following error from getting returned:

{'status': 'error','message': 'A possible invalid request has been made.

Make sure you are following the API spec and have used the correct␣→˓URL,

are included all required parameters and if a request payload is␣→˓required

you have included one.','data': {'type': 'error_data','code': 309,'developer_message': '','more_info': ''

},'metadata': {}

}

• Added a missing section of the docstring for the khoros.objects.tags.structure_tags_for_message()function.





1.10.9 v4.0.0


Added

Core Object


• Added the khoros.core.Khoros.User.impersonate_user() method.

• Added the khoros.core.Khoros.Role.get_role_id() method.

• Added the khoros.core.Khoros.V2 class with the following methods:– khoros.core.Khoros.V2.get()– khoros.core.Khoros.V2.post()– khoros.core.Khoros.V2.put()

• Added and called the khoros.core.Khoros._import_v2_class() protected class.

Primary Modules


• Added the khoros.objects.users.ImpersonatedUser object class for performing API calls as other users.

• Added the khoros.objects.users.impersonate_user() function to assist in instantiating the khoros.objects.users.ImpersonatedUser object.

• Added the following functions to the khoros.objects.roles() module:– khoros.objects.roles.get_role_id()– khoros.objects.roles.assign_roles_to_user()– khoros.objects.roles._assign_role_with_v1()

– khoros.objects.roles._assign_role_with_v2()

– khoros.objects.roles._validate_node_type()

– khoros.objects.roles._query_for_users()

• Added the khoros.api._add_json_query_to_uri() function.

Supporting Modules


• Added the khoros.errors.exceptions.FeatureNotConfiguredError exception.



General

• Added the read() and get_version() functions to setup.py to address Issue #28.

Note: This change was introduced by truthbyron via Pull Request #31.

Changed

Core Object


• Updated the methods below to introduce the proxy_user_object parameter to allow API requests to be per-formed on behalf of other users.

– khoros.core.Khoros.get()– khoros.core.Khoros.post()– khoros.core.Khoros.put()– khoros.core.Khoros.Subscription.add_subscription()– khoros.core.Khoros.Subscription.subscribe_to_board()– khoros.core.Khoros.Subscription.subscribe_to_category()– khoros.core.Khoros.Subscription.subscribe_to_label()– khoros.core.Khoros.Subscription.subscribe_to_message()– khoros.core.Khoros.Subscription.subscribe_to_product()– khoros.core.Khoros.V1.get()– khoros.core.Khoros.V1.post()– khoros.core.Khoros.V1.put()– khoros.core.Khoros.V1.search()

• Changed the default value of the return_json parameter to True in the khoros.core.Khoros.Settings.define_node_setting() function.

• Updated the khoros.core.Khoros.User.create() method to return the API response and introduced theignore_exceptions parameter.

Primary Modules


• Updated the functions below to introduce the proxy_user_object parameter to allow API requests to be per-formed on behalf of other users.

– khoros.api.define_headers()– khoros.api.get_request_with_retries()– khoros.api.payload_request_with_retries()– khoros.api.post_request_with_retries()



https://github.com/truthbyron



– khoros.api.put_request_with_retries()– khoros.api.delete()– khoros.api.perform_v1_search()– khoros.api.make_v1_request()– khoros.objects.subscriptions.add_subscription()– khoros.objects.subscriptions.subscribe_to_board()– khoros.objects.subscriptions.subscribe_to_category()– khoros.objects.subscriptions.subscribe_to_label()– khoros.objects.subscriptions.subscribe_to_message()– khoros.objects.subscriptions.subscribe_to_product()

• Introduced the user_and_type parameter in the khoros.api.get_v1_user_path() function that can bepassed instead of a parameter for a specific type.

• Changed the default value of the return_json parameter to True in the khoros.objects.settings.define_node_setting() function.

• Added proper support for group hubs in the khoros.objects.settings.define_node_setting() andkhoros.objects.settings._get_v1_node_setting() functions.

• Removed node type validation from the khoros.objects.settings.define_node_setting() function.

• Added node type validation in the khoros.objects.settings._get_v2_node_setting() function.

• Updated the khoros.objects.users.create() function to return the API response and introduced theignore_exceptions parameter.

• Updated the khoros.objects.users.delete() function to raise the new khoros.errors.exceptions.FeatureNotConfiguredError exception when appropriate.

• Added group hub support in the khoros.api.get_v1_node_collection() function.

Supporting Modules


• Introduced the ability for the khoros.errors.exceptions.MissingRequiredDataError exception to ac-cept the param keyword argument and display a more specific message.

• Updated the khoros.utils.environmentmodule to no longer import the PyYAML package directly and insteadto leverage the importlib module in the khoros.utils.environment._import_custom_names_file()function as necessary.


https://docs.python.org/3/library/importlib.html#module-importlib


Documentation

Changes to the documentation.

• Added missing information to the docstring for the following methods and functions:– khoros.core.Khoros.connect()– khoros.core.Khoros.get_session_key()– khoros.core.Khoros.put()– khoros.api._confirm_field_supplied()

• Updated the example in the header block for the khoros.objects.users module.

• Updated the header block in the setup.py script to have more information.

General

• Moved the PyYAML, urllib3, requests and setuptools packages from the requirements.txt file to thesetup.py file within the install_requires list to address Issue #28.

Note: This change was introduced by truthbyron via Pull Request #31.

Fixed

Primary Modules


• Fixed issues with the primary functions in the khoros.api module that was resulting in raised ex-ceptions if JSON responses were requested in v1 API calls without explicitly including the restapi.response_format=json query string.

• Fixed issues in the khoros.objects.users.structure_payload() and khoros.objects.users.process_user_settings() functions that were resulting in a KeyError exception potentially getting raised.

• Added the missing type key to the payload dictionary in the khoros.objects.users.structure_payload() function that was preventing users from getting created successfully.

• Fixed an issue in the khoros.objects.subscriptions._construct_category_payload()where the pay-load was getting double-wrapped with the data dictionary key.

• Refactored the khoros.objects.roles.get_users_with_role() function to leverage a while loop insteadof recursion in order to avoid raising a RecursionError exception with larger queries.

• Wrapped the cursor string in the khoros.liql.structure_cursor_clause() function in single quotes tofix an Invalid query syntax error that was raising the khoros.errors.exceptions.LiQLParseErrorexception.



https://github.com/truthbyron



https://docs.python.org/3/library/exceptions.html#RecursionError


1.10.10 v3.5.0


Added

Core Object


• Added the khoros.core.Khoros.get_session_key() method.

• Added the khoros.core.Khoros.Role.get_users_with_role() method.

• Added the khoros.core.Khoros.Subscription inner class with the following methods:– khoros.core.Khoros.Subscription.add_subscription()– khoros.core.Khoros.Subscription.get_subscription_uri()– khoros.core.Khoros.Subscription.subscribe_to_board()– khoros.core.Khoros.Subscription.subscribe_to_category()– khoros.core.Khoros.Subscription.subscribe_to_label()– khoros.core.Khoros.Subscription.subscribe_to_message()– khoros.core.Khoros.Subscription.subscribe_to_product()

• Added the khoros.core.Khoros._import_subscription_class() method and leveraged it to allowsubscription-related methods to be called with the khoros.subscriptions namespace.

Primary Modules


• Added the khoros.api.get_v1_user_path() and khoros.api.get_v1_node_collection() functions tofacilitate crafting API v1 endpoint URIs.

• Added the new khoros.objects.subscriptions module with the following functions:– khoros.objects.subscriptions.add_subscription()– khoros.objects.subscriptions.get_subscription_uri()– khoros.objects.subscriptions.subscribe_to_board()– khoros.objects.subscriptions.subscribe_to_category()– khoros.objects.subscriptions.subscribe_to_label()– khoros.objects.subscriptions.subscribe_to_message()– khoros.objects.subscriptions.subscribe_to_product()– khoros.objects.subscriptions._construct_category_payload()

– khoros.objects.subscriptions._construct_target_subscription()

• Updated the __init__.py file for the khoros.objects module to import the new khoros.objects.subscriptions module and add it to the __all__ variable.

• Added the khoros.auth._get_session_key_payload() function.



• Added the khoros.auth._get_session_key_header() function.

• Added the following functions to the khoros.objects.roles module.– khoros.objects.roles.get_users_with_role()

• Added the khoros.errors.exceptions.structure_cursor_clause() function.

Supporting Modules


• Added the khoros.utils.core_utils.convert_dict_list_to_simple_list() function.

• Added the khoros.utils.core_utils.is_iterable() function.

Documentation

Additions to the documentation.

• Added a badge for the latest beta / release candidate (RC) release on the README page.

• Added badges for the security audits (bandit and PyCharm Python Security Scanner) to the README page.

• Added a badge for the CodeFactor Grade on the README page.

General

• Added the .github/workflows/bandit.yml GitHub Action workflow configuration file to leverage thePython security check using Bandit action to perform security audits with each push event.

• Added badges in the README page.

• Added comments in multiple scripts within the library to address how the bandit GitHub Action will identifyusers.

Changed

Core Object


• Updated the khoros.core.Khoros.Role.get_roles_for_user() method to allow SELECT fields to beexplicitly defined.

• Removed the unnecessary pass statement in the khoros.core.Khoros.close() method.

• Removed the unnecessary return statements in the khoros.core.Khoros.signout() and khoros.core.Khoros.User.create() methods.

• Replaced type() with isinstance() when performing typechecks throughout the khoros.core module.


https://github.com/jeffshurtliff/khoros/blob/master/README.md



https://github.com/marketplace/actions/python-security-check-using-bandit



Primary Modules


• The khoros.auth.get_session_key() function has been updated to allow a secondary user to be authenti-cated by passing either a username and password or by passing only a username when calling the function as apreviously authenticated user with Administrator privileges.

• Added the community, grouphub and global keys to the ROLE_TYPES dictionary constant in the khoros.objects.roles module.

• Updated the khoros.objects.roles.get_roles_for_user() function to allow SELECT fields to be ex-plicitly defined.

• Renamed the khoros.liql._parse_select_fields() function to be khoros.liql.parse_select_fields() instead. (i.e. private to public function)

• Refactored the khoros.liql.parse_select_fields() function to leverage the isinstance() built-in func-tion.

• Removed the mandatory dependency on the requests_toolbelt package by leveraging the importlib pack-age to attempt to import it locally as needed within the khoros.api.encode_multipart_data() function.

• Removed an unnecessary else statement in the khoros.api.define_headers() function after the khoros.errors.exceptions.MissingAuthDataError exception is raised.

• Replaced type() with isinstance() when performing the typecheck in the khoros.api.perform_v1_search() function.

• Removed the unnecessary pass statement in the following functions:– khoros.api._api_request_with_payload()


Supporting Modules


• Added the khoros.utils.log_utils.initialize_logging() function call to initialize logging within thekhoros.utils.core_utils module.

• Changed the default value for the shell parameter to be False in the khoros.utils.core_utils.run_cmd()function to improve overall security of the library.

• Added the optional delimiter parameter to the khoros.utils.core_utils.convert_string_to_tuple() function and added functionality to convert delimited strings.

General

• Removed the stale branch 3.0.0 from the .github/workflows/codeql-analysis.yml file.

• Removed requests_toolbelt from requirements.txt.



https://docs.python.org/3/library/importlib.html#module-importlib

https://bandit.readthedocs.io/en/latest/plugins/b602_subprocess_popen_with_shell_equals_true.html


Fixed

Core Object


• Updated the khoros.core.Khoros.post() function so that the query_url no longer gets prefixed with aslash (/) if the relative_url parameter is set to False.

Primary Modules


• Fixed an issue with the khoros.api.payload_request_with_retries() function where non-payload APIcalls (including those with query parameters defined in the URI) were incorrectly raising a khoros.errors.exceptions.PayloadMismatchError exception.

1.10.11 v3.4.0


Added

Core Object


• Added the khoros.core.Khoros.get_platform_version() method.

Primary Modules


• Added the khoros.api.should_verify_tls() function to determine if SSL/TLS certificates should be ver-ified when making REST API calls.

• Added a warning to the khoros.api.should_verify_tls() to inform of the suppressed warnings.



Changed

Core Object


• Updated the __init__method for the khoros.core.Khoros object class to include the ssl_verify parameterand to establish a key-value pair for it in the core_settings dictionary.

Primary Modules


• Removed an unnecessary pass statement from the khoros.api.get_request_with_retries() function andinitially defined the response variable with a NoneType value to prevent a linting error from being reported.

• Introduced support for the ssl_verify core setting in the khoros.core.Khoros object within the followingfunctions:

– khoros.api._api_request_with_payload()


– khoros.api.delete()– khoros.api.get_platform_version()– khoros.api.get_request_with_retries()– khoros.api.payload_request_with_retries()– khoros.api.perform_v1_search()– khoros.api.post_request_with_retries()– khoros.api.put_request_with_retries()– khoros.auth.get_session_key()– khoros.liql.perform_query()

• Renamed the function khoros.liql.__parse_select_fields() to be khoros.liql.__parse_select_fields().

• Renamed the function khoros.liql.__wrap_string_vales() to be khoros.liql._wrap_string_values().

• Renamed the function khoros.liql.__convert_where_dicts_to_lists() to be khoros.liql._convert_where_dicts_to_lists().

• Renamed the function khoros.liql.__parse_where_clause() to be khoros.liql.parse_where_clause() and converted it from a private to a public function.



Supporting Modules


• Added support for the ssl_verify field in the khoros.utils.helper module.

• Refactored the khoros.utils.version.get_latest_stable() function to leverage the Python standard li-brary instead of the requests library which helps address issue #28.

1.10.12 v3.3.3


Fixed

Primary Modules


• Added error handling in the khoros.objects.settings._get_v2_node_setting() function to prevent anAttributeError exception from being raised.

1.10.13 v3.3.2


Added

Core Object


• Added the optional skip_env_variables argument to the __init__ method of the khoros.core.Khorosclass to explicitly ignore valid environment variables when instantiating the core object.

• Added the optional empty argument to the __init__ method of the khoros.core.Khoros class to instantiatean empty core object with default values.

• Added the method khoros.core.Khoros._populate_empty_object() to populates necessary fields to al-low an empty object to be instantiated successfully.


https://docs.python.org/3/library/urllib.request.html#module-urllib.request

https://docs.python.org/3/library/urllib.request.html#module-urllib.request

https://requests.readthedocs.io/


https://docs.python.org/3/library/exceptions.html#AttributeError


• Logging (via the khoros.utils.log_utilsmodule) was introduced in methods throughout the khoros.coremodule.

Changed

Core Object


• Introduced the return_json parameter in the khoros.core.Khoros.Settings.define_node_setting()method and the khoros.objects.settings.define_node_setting() function to optionally return theCommunity API response in JSON format. (This option prevents the khoros.errors.exceptions.POSTRequestError exception from being raised after an unsuccessful API call.)

• Introduced the convert_json parameter in the khoros.core.Khoros.Settings.get_node_setting()method and the khoros.objects.settings.get_node_setting() function to optionally convert JSONstrings into Python dictionaries.

Primary Modules


• Introduced the return_json parameter in the khoros.objects.settings.define_node_setting() tooptionally return the Community API response in JSON format. (This option prevents the khoros.errors.exceptions.POSTRequestError exception from being raised after an unsuccessful API call.)

Documentation


• Merged the release notes for version 3.3.0.post0 into those for the subsequent stable version 3.3.1.

• Added an example function call in the header block of the khoros.utils.log_utils module.

• Made further improvements to the documentation styling in the custom.css file.

Fixed

Core Object


• Updated the __init__ method for the khoros.core.Khoros class to only skip method arguments when theyexplicitly have a None value and are not just implicitly False.



Primary Modules


• The error handling has been improved in the khoros.liql.get_returned_items() function to avoidIndexError exceptions from being raised when no items were found in the LiQL response.

1.10.14 v3.3.1


Added

Documentation


• Added the Settings Subclass (khoros.core.Khoros.Settings) section to the Khoros Core Object page.

• Added the Settings Module (khoros.objects.settings) section to the Primary Modules page.

• Updated the CSS styling in custom.css to improve readability of methods and functions.

Changed

Documentation


• Alphabetized the sections on the Khoros Core Object page.

• Removed the introductory sentence for each of the modules on the Primary Modules page as they had becomeredundant with the same information already present in the docstrings.

• Moved the Studio Subclass (khoros.core.Khoros.Studio) section out of the Core Object Subclasses(khoros.core.Khoros) section and into its own, similar to where it is located on the Primary Modules page.

Fixed

Primary Modules


• Fixed an issue with the khoros.api.make_v1_request() function call within the khoros.objects.settings._get_v2_node_setting() that was resulting in IndexError exceptions.

• Fixed an issue in khoros.objects.settings._get_v2_node_setting() resulting in an IndexError ex-ception if the setting field is not found, and made changes to return a None value in that situation.






Documentation

Fixes in the documentation.

• A minor fix was made to the docstring in the khoros.objects.settings.define_node_setting() functionto correct a Sphinx parsing issue. The function itself was not changed.

1.10.15 v3.3.0


Added

Core Object


• Defined the version variable within the khoros.core.Khoros core object to make it easy to determine thecurrent version of the package after having instantiated said object.

Changed

General

• Added Khoros to the __all__ dictionary in the primary __init__.py file.

Core Object


• Renamed the _settings dictionary (private) to be core_settings (public) in the core object to avoid warningmessages being displayed in PyCharm and other IDEs as reported in Issue #26.

• Renamed the settings argument in the __init__ method for the khoros.core.Khoros object to bedefined_settings to avoid conflicting with the khoros.core.Khoros.Settings() method.

• Made some minor PEP8 compliance-related adjustments in the khoros.core module.




Primary Modules


• Updated the functions below to change _settings to core_settings.– khoros.auth.get_session_key()– khoros.auth.invalidate_session()– khoros.auth.get_oauth_authorization_url()– khoros.objects.users.create()– khoros.objects.users.delete()– khoros.structures.grouphubs.refresh_enabled_discussion_styles()

Supporting Modules


• Updated the khoros.errors.translations.translation_enabled() function to change _settings tocore_settings.

Return to Top

1.10.16 v3.2.0


Added

General

• Created the dev-requirements.txt to indicate which packages may be required for contributors, whereas therequirements.txt file now only contains the absolute necessities to use the package.

Core Object


• Added the khoros.core.Khoros.Settings class with the following methods:– khoros.core.Khoros.Settings.get_node_setting()– khoros.core.Khoros.Settings.define_node_setting()

• Added the khoros.core.Khoros._import_settings_class() method.



Primary Modules


• Added the new khoros.objects.settings module with the following functions:– khoros.objects.settings.get_node_setting()– khoros.objects.settings._get_v1_node_setting()

– khoros.objects.settings._get_v2_node_setting()

– khoros.objects.settings._validate_node_type()

• Added the khoros.objects.settings module to the __init__.py file for the khoros.objects module.

• Added the new khoros.liql.get_returned_items() function.

• Added the new khoros.api.encode_payload_values() function.

Supporting Modules


• Added the following new exception classes:– khoros.errors.exceptions.UnsupportedNodeTypeError– khoros.errors.exceptions.LiQLParseError– khoros.errors.exceptions.PayloadMismatchError

Changed

General

• Updated setup.py to enable support for Python v3.8.x and v3.9.x now that compatibility testing has been per-formed and no issues have been identified.

• Updated the Development Status classifier in setup.py to be 5 - Production/Stable.

• Added some additional Topic classifiers in setup.py.

• Significantly cleaned up the requirements.txt file to only include the absolute necessities.

• Updated requirements.txt to replace == with >= to be less strict on dependency versions as long as they meeta minimum version requirement.

• Made a minor adjustment to the README.md file relating to documentation.

• Updated the docs/conf.py file to require Sphinx version 3.4.0.

• Re-added the Sphinx-related dependencies to requirements.txt to allow ReadTheDocs builds to be success-ful.



Core Object


• Updated the methods below to support API v1 calls using payloads:– khoros.core.Khoros.V1.post()– khoros.core.Khoros.V1.put()

Primary Modules


• Updated the functions below to support API v1 calls using JSON payloads:– khoros.api.make_v1_request()– khoros.api.encode_v1_query_string()

• Added support for URL-encoded string payloads in the following functions:– khoros.api.payload_request_with_retries()– khoros.api.post_request_with_retries()– khoros.api.put_request_with_retries()

Supporting Modules


• Moved the exceptions within the Base Object Exceptions section of khoros.errors.exceptions into a newsection entitled Node Exceptions.

• Updated the following exceptions to optionally accept status_code and message as arguments:– khoros.errors.exceptions.GETRequestError– khoros.errors.exceptions.POSTRequestError– khoros.errors.exceptions.PUTRequestError

• Updated the khoros.errors.exceptions.SessionAuthenticationError exception to optionally acceptmessage as an argument.

• Updated the khoros.utils.core_utils.encode_query_string() function to support API v1 calls usingJSON payloads.

• Updated the function khoros.utils.core_utils.convert_single_value_to_tuple() to be more PEP8compliant.



Fixed

Core Object


• Fixed an argument mismatch issue in the khoros.core.Khoros.parse_v2_response() and khoros.core.Khoros.Message.parse_v2_response() (deprecated) methods.

• Updated the methods below to pass the query parameters in the message body to avoid exceeding the URI limitand receiving responses with 413 or 414 status codes.

– khoros.core.Khoros.V1.post()– khoros.core.Khoros.V1.put()

Primary Modules


• Added a missing docstring for the khoros.api.payload_request_with_retries() function.

• Updated the function khoros.api.make_v1_request() to pass the query parameters in the message body toavoid exceeding the URI limit and receiving responses with 413 or 414 status codes.

• Fixed an issue where v1 GET requests were not appending the restapi.response_format=json query stringwhen a JSON response has been requested.

Supporting Modules

Fixes in the supporting modules.

• Updated the default message in the khoros.errors.exceptions.TooManyResultsError exception to beappropriate as it was inadvertently using the same message leveraged in the khoros.errors.exceptions.OperatorMismatchError exception.

Return to Top

1.10.17 v3.1.1




Fixed

Core Object


• Fixed issues in the following methods to address the bug #20:– khoros.core.Khoros.post()– khoros.core.Khoros.put()

Primary Modules


• Fixed issues in the function khoros.api.post_request_with_retries() to address the bug #20.

Return to Top

1.10.18 v3.1.0


Added

Core Object


• Added the khoros.get() method to perform simple GET requests that leverage the core object authorizationheaders where necessary.

• Added the khoros.post() method to perform simple POST requests that leverage the core object authorizationheaders where necessary.

• Added the khoros.put() method to perform simple PUT requests that leverage the core object authorizationheaders where necessary.





Primary Modules


• Added the khoros.api.payload_request_with_retries() function to act as a “master function” forkhoros.api.post_request_with_retries() and khoros.api.put_request_with_retries().

• Added the khoros.api._is_plaintext_payload() function.

Documentation


• Added missing sections to the Core Object Methods page.

Changed

Primary Modules


• Added support for text/plain payloads and introduced the content_type parameter in the following functions:

– khoros.api.post_request_with_retries()– khoros.api._api_request_with_payload()

• Updated the khoros.api.post_request_with_retries() and khoros.api.put_request_with_retries() functions to leverage the new khoros.api.payload_request_with_retries() function.

Return to Top

1.10.19 v3.0.0


Added

Core Object


• Added the khoros.core.Khoros.V1 inner class with the following methods:– khoros.core.Khoros.V1.get()– khoros.core.Khoros.V1.post()



– khoros.core.Khoros.V1.put()– khoros.core.Khoros.V1.search()

• Added the khoros.core.Khoros._import_v1_class() and accompanying method call.

Primary Modules


• Added the khoros.api.get_platform_version()

• Added the khoros.api._normalize_base_url()

• Instantiated a logger in the following modules:– khoros.api– khoros.auth– khoros.liql– khoros.objects.albums– khoros.objects.archives– khoros.objects.attachments– khoros.objects.base– khoros.objects.messages– khoros.objects.roles– khoros.objects.tags– khoros.objects.users– khoros.structures.base– khoros.structures.boards– khoros.structures.categories– khoros.structures.communities– khoros.structures.grouphubs– khoros.structures.nodes– khoros.studio.base

Supporting Modules


• Introduced logging within the library:– Added the khoros.utils.log_utils module with the following functions, classes and methods:

∗ khoros.utils.log_utils.initialize_logging()

∗ khoros.utils.log_utils.LessThanFilter

∗ khoros.utils.log_utils.LessThanFilter.filter()



∗ khoros.utils.log_utils._apply_defaults()

∗ khoros.utils.log_utils._get_log_levels_from_dict()

∗ khoros.utils.log_utils._set_logging_level()

∗ khoros.utils.log_utils._add_handlers()

∗ khoros.utils.log_utils._add_file_handler()

∗ khoros.utils.log_utils._add_stream_handler()

∗ khoros.utils.log_utils._add_split_stream_handlers()

∗ khoros.utils.log_utils._add_syslog_handler()

– Added a logging section to the examples/helper.yml file to indicate how logging can be con-figured.

• Added the khoros.utils.core_utils.encode_base64() function.

• Added the khoros.utils.version.log_current_version() function.

Documentation

• Added the changelog-1.1.0-thru-2.5.2.rst file and embedded it into this Change Log page to have less content perRST document.

• Added Return to Top links at the bottom of each version section.

Changed

Core Object


• Replaced the basic logging initialization with a call to the khoros.utils.log_utils.initialize_logging() function.

Primary Modules


• Updated the khoros.api.make_v1_request() function to make the query_params argument optional.

• Updated the khoros.api.make_v1_request() function to allow full query strings to be passed within theendpoint argument.


https://docs.python.org/3/library/logging.html#module-logging


Supporting Modules


• The following changes were made to the khoros.utils.version module:– Initialized a logger at the beginning of the module.

– Added a debug log entry to the khoros.utils.versions.get_full_version() which reportsthe current version of the library.

– Reduced the khoros.utils.version.latest_version() function to a single return statement.

– Added error handling and logging in the khoros.utils.version.get_latest_stable() func-tion to avoid an exception if PyPI cannot be queried successfully.

– Updated the khoros.utils.version.warn_when_not_latest() function to use logging for thewarning rather than the warnings module.

General

• Updated the Sphinx configuration file (conf.py) to suppress the duplicate label warnings.

• Added version 3.0.x to the SECURITY.md file under Supported.

Return to Top

Fixed

General

• Changed the pyYAML version in requirements.txt to be 5.3.1 rather than 5.3 in order to avoid the CI buildfailure in GitHub Actions.

Deprecated

Core Object

Deprecations in the Khoros Core Object.

• Deprecated the khoros.core.Khoros.perform_v1_search()method as it has been replaced by the khoros.core.Khoros.V1.search() method.

Return to Top



https://pypi.org/project/PyYAML/


1.10.20 v2.8.0


Added

Core Object


• Added the khoros.core.Khoros.Message.update() method.

• Added the translate_errors default setting to the core object.

Primary Modules


• Added the following functions within the khoros.objects.messages module:– khoros.objects.messages.update()– khoros.objects.messages.is_read_only()– khoros.objects.messages.set_read_only()– khoros.objects.messages._verify_message_id()

– khoros.objects.messages._add_moderation_status_to_payload()

• Added the new khoros.objects.tags module with the following functions:– khoros.objects.tags.structure_single_tag_payload()– khoros.objects.tags.add_single_tag_to_message()– khoros.objects.tags.add_tags_to_message()– khoros.objects.tags.get_tags_for_message()– khoros.objects.tags._format_tag_data()

• Added the khoros.objects.attachments._structure_attachments_to_add() function.

• Introduced the ability for error messages to be translated where possible to be more relevant withinthe khoros.api.parse_v2_response(), khoros.api.deliver_v2_response() and khoros.api._get_v2_return_values() functions, and added the optional khoros_object or _khoros_object argu-ment to facilitate this.

Supporting Modules


• Added the khoros.errors.handlers.verify_core_object_present() function.

• Added the khoros.errors.translations module with the following functions:– khoros.errors.translations.translate_error()– khoros.errors.translations.translation_enabled()



– khoros.errors.translations.parse_message()• Added the khoros.errors.translations module to the __all__ special variable and imported it by default

within the khoros.errors (__init__.py) module.

• Added the khoros.utils.tests.test_tags module with the following functions:– khoros.utils.tests.test_tags.test_single_tag_structure()– khoros.utils.tests.test_tags.get_structure_control_data()– khoros.utils.tests.test_tags.test_message_structure_one_tag()– khoros.utils.tests.test_tags.test_message_structure_two_tags()– khoros.utils.tests.test_tags.test_message_structure_one_string_tag_ignore()– khoros.utils.tests.test_tags.test_message_structure_two_string_tags_ignore()– khoros.utils.tests.test_tags.test_message_structure_str_int()– khoros.utils.tests.test_tags.test_message_structure_str_int_ignore()

• Added the khoros.utils.tests.test_messages module with the following functions:– khoros.utils.tests.test_messages.get_control_data()– khoros.utils.tests.test_messages.test_construct_only_subject()– khoros.utils.tests.test_messages.test_construct_with_node()– khoros.utils.tests.test_messages.test_construct_with_node_id()– khoros.utils.tests.test_messages.test_construct_with_node_url()– khoros.utils.tests.test_messages.test_construct_with_body()– khoros.utils.tests.test_messages.test_construct_with_one_str_tag()– khoros.utils.tests.test_messages.test_construct_with_one_int_tag()– khoros.utils.tests.test_messages.test_construct_with_str_iter_int_tags()– khoros.utils.tests.test_messages.test_construct_with_str_iter_int_tags_ignore()– khoros.utils.tests.test_messages.test_construct_with_tag_iterables()– khoros.utils.tests.test_messages.assert_tags_present()

• Added the khoros.utils.core_utils.remove_tld() function.

• Added the khoros.utils.tests.test_core_utils.test_remove_tld() function.

• Added the khoros.utils.core_utils.merge_and_dedup() function.

• Added the khoros.utils.tests.test_core_utils.test_merge_and_dedup() function.



Documentation


• Added the khoros.objects.tags module to the Primary Modules page.

• Added the khoros.errors.translations module to the Supporting Modules page.

• Added the khoros.utils.tests.test_tags module to the Supporting Modules page.

• Added the khoros.utils.tests.test_messages module to the Supporting Modules page.

• Added a reference to the KHOROS_TRANSLATE_ERRORS environment variable and added a new Roadmap sectionto both the Introduction page and the README.md file.

• Created the currently in-progress Working with Messages page, per Enhancement #1.

General

• Added the file v2_message_attachment_update_payload.json to the examples/example_output direc-tory.

Changed

Core Object


• Introduced the ignore_non_string_tags, return_status, return_error_messages and split_errorsarguments in the khoros.core.Khoros.Message.create() method, and changed the default value of thefull_response, return_id, return_url, return_api_url and return_http_code arguments to Nonerather than False.

• Added support for the translate_errors Helper setting and any other future top-level setting within thekhoros.core.Khoros._parse_helper_settings() method.

Primary Modules


• Updated the functions below to support the khoros.objects.messages.update() function.– khoros.objects.messages.structure_payload()

– khoros.objects.attachments.construct_multipart_payload()– khoros.objects.attachments.format_attachment_payload()– khoros.objects.attachments.get_file_upload_info()

• Updated the if statement in khoros.objects.messages._verify_required_fields() to leverage theisinstance() function.

• Added the return_status, return_error_messages and split_errors arguments to the khoros.objects.messages.create() function, and changed the default value of the full_response, return_id,return_url, return_api_url`` and return_http_code arguments to None rather than False.





Supporting Modules


• Updated the khoros.utils.helper.get_helper_settings() function to capture the translate_errorsvalue when defined in the configuration file.

• Refactored the khoros.utils.helper._get_construct_info() function to leverage the khoros.utils.helper._collect_values() function.

Documentation


• Updated the Supported Versions chart in the Security Policy.

• Made a very minor formatting change on the Introduction page.

• Added the Working with Messages page to the master Table of Contents.

• Added a link to the PyPI package page in the first paragraph of the index page.

• Changed the intersphinx inventory URL for the built-in Python 3 modules from https://docs.python.org/ to https://docs.python.org/3/ in the docs/conf.py file.

General

• Updated the examples/helper.yml file to include the translate_errors setting.

• Added the KHOROS_TRANSLATE_ERRORS environment variable to the examples/custom_env_variables.yml and examples/custom_env_variables.json files.

Return to Top

1.10.21 v2.7.6


Added

Documentation


• Added the LGTM Grade to the README.md file.


https://github.com/jeffshurtliff/khoros/security/policy

https://pypi.org/project/khoros

https://docs.python.org/

https://docs.python.org/3/

https://docs.python.org/3/

https://lgtm.com/projects/g/jeffshurtliff/khoros


General

• Added the two files below to the examples/example_output/ directory.– v2_message_attachment_create_payload.json

– v2_message_attachment_create_success.json

Changed

Documentation


• Added the Khoros Core Object page amd moved the documentation for the khoros (__init__.py) module andthe khoros.core module to the new page from the Primary Modules page.

• Added the new Khoros Core Object page to the Python SDK for Khoros Communities page.

• Added navigational sentences at the bottom of the Primary Modules, Supporting Modules and Khoros CoreObject pages.

Fixed

Primary Modules


• Fixed the “Exception objects instantiated but not raised” issue reported in GitHub. (Issue #2)

Return to Top

1.10.22 v2.7.5


Added

General

• Added the v2_error_not_authorized.json file to the examples/example_output directory.




Changed

Primary Modules


• Added the default_content_type argument to the khoros.api.define_headers() function.

Fixed

Primary Modules


• Updated the khoros.api._normalize_headers() function to ensure that authentication/authorization tokenswould not be altered.

Return to Top

1.10.23 v2.7.4


Added

Primary Modules


• Added the khoros.api._normalize_headers() function to normalize the HTTP headers.

Supporting Modules


• Added the khoros.utils.tests.resources module with the following functions:– khoros.utils.tests.resources.set_package_path()– khoros.utils.tests.resources.import_modules()– khoros.utils.tests.resources.initialize_khoros_object()

• Added the khoros.utils.tests.test_http_headers module for unit testing.



Documentation


• Added a section to the Primary Modules page for the khoros.objects.archives module.

• Added sections to the Supporting Modules page for the following modules:– khoros.utils.tests.resources()– khoros.utils.tests.test_board_creation()– khoros.utils.tests.test_grouphub_creation()– khoros.utils.tests.test_http_headers()

Changed

Primary Modules


• Standardized the case-sensitivity of the HTTP headers to all be lower-case in the following functions:– khoros.api.define_headers()– khoros.api.make_v1_request()– khoros.auth.get_session_key()– khoros.objects.users.create()

• Included a function call for khoros.api._normalize_headers() in khoros.api.define_headers().

Supporting Modules


• Updated the unit testing modules below to utilize the khoros.utils.tests.resources module:– khoros.utils.tests.test_board_creation– khoros.utils.tests.test_grouphub_creation

Return to Top



1.10.24 v2.7.3


Added

Supporting Modules


• Added the khoros.utils.tests.test_grouphub_creation module for unit testing with pytest.

Changed

Primary Modules


• Added the debug_mode Boolean argument (False by default) to the __init__ method for the khoros.core.Khoros class which populates within the _settings protected dictionary.

General

• Added dist.old/ to the .gitignore file in the root directory of the repository.

Fixed

Primary Modules


• Fixed how the payload in khoros.structures.grouphubs.structure_payload() is initially de-fined to avoid a TypeError exception from being raised during the khoros.structures.grouphubs._structure_simple_string_fields() function call.

Return to Top




1.10.25 v2.7.2


Fixed

Primary Modules


• Fixed some bad logic in the khoros.structures.grouphubs.structure_payload() that was raising falsepositive exceptions.

Documentation

Fixes to the documentation.

• Changed the data type for membership_type from dict to str in the docstring for the khoros.structures.grouphubs.create(), khoros.structures.grouphubs.structure_payload() andkhoros.structures.grouphubs._structure_membership_type() functions.

Return to Top

1.10.26 v2.7.1


Fixed

Primary Modules


• Removed some print debugging found in the khoros.api.make_v1_request() function.

• Fixed a syntax error with raising the khoros.errors.exceptions.CurrentlyUnsupportedError exceptionclass within the khoros.api.make_v1_request() function.



General

• Added several API v1 output examples in the examples/example_output directory.

Return to Top

1.10.27 v2.7.0


Added

Primary Modules


• Added the new khoros.objects.archives module with the following functions:– khoros.objects.archives.archive()– khoros.objects.archives.unarchive()– khoros.objects.archives.structure_archive_payload()– khoros.objects.archives._valid_entries_type()

– khoros.objects.archives._convert_entries_to_dict()

– khoros.objects.archives._format_single_archive_entry()

• Added the khoros.structures.base.structure_exists() function.

• Added the khoros.structures.boards.board_exists() function.

• Added the khoros.structures.categories.category_exists() function.

• Added the khoros.structures.grouphubs.grouphub_exists() function.

• Added the khoros.structures.nodes.node_exists() function.

• Added the following methods in the core structure subclasses:– khoros.core.Khoros.Board.board_exists()– khoros.core.Khoros.Category.category_exists()– khoros.core.Khoros.GroupHub.grouphub_exists()– khoros.core.Khoros.Node.node_exists()



Changed

Primary Modules


• Added the khoros.objects.archives module to the __all__ special variable in the khoros.objects__init__ module and configured it to be imported by default.

• Added several additional keys and values to the structure_types_to_tables dictionary in the khoros.structures.base.Mapping class.

Return to Top

1.10.28 v2.6.0


Added

Primary Modules


• Added the khoros.core.Khoros.GroupHub inner class with the following methods:– khoros.core.Khoros.GroupHub.create()– khoros.core.Khoros.GroupHub.structure_payload()– khoros.core.Khoros.GroupHub.get_total_count()– khoros.core.Khoros.GroupHub.update_title()

• Added the khoros.core.Khoros._import_grouphub_class() and its accompanying method call.

• Added the khoros.structures.grouphubs module to the __all__ special variable in the khoros.structures __init__ module and configured the module to import by default.

• Added the khoros.structures.boards.get_board_id() function.

• Added the khoros.core.Khoros.Board.structure_payload() and khoros.core.Khoros.Board.get_board_id() methods.

• Added the khoros.api.format_avatar_payload() function.

• Added the khoros.api.combine_json_and_avatar_payload() function.

• Added the khoros.structures.grouphubs module with the following functions:– khoros.structures.grouphubs.create()– khoros.structures.grouphubs._create_group_hub_with_avatar()

– khoros.structures.grouphubs._create_group_hub_without_avatar()



– khoros.structures.grouphubs.structure_payload()– khoros.structures.grouphubs._structure_simple_string_fields()

– khoros.structures.grouphubs._structure_membership_type()

– khoros.structures.grouphubs._structure_discussion_styles()

– khoros.structures.grouphubs._structure_parent_category()

– khoros.structures.grouphubs.get_total_count()– khoros.structures.grouphubs.get_grouphub_id()– khoros.structures.grouphubs.refresh_enabled_discussion_styles()– khoros.structures.grouphubs._remove_disabled_discussion_styles()

– khoros.structures.grouphubs.update_title()– khoros.structures.grouphubs._verify_group_hub_id()

• Added the khoros.structures.categories.get_total_count() function to replace the deprecatedkhoros.structures.categories.get_total_category_count() function.

• Added the khoros.core.Khoros.Category.get_total_count() method to replace the deprecatedkhoros.core.Khoros.Category.get_total_category_count() method.

Supporting Modules


• Added the khoros.utils.tests.test_board_creation unit test module with the following functions:

– khoros.utils.tests.test_board_creation.set_package_path()

– khoros.utils.tests.test_board_creation.import_boards_module()

– khoros.utils.tests.test_board_creation.import_exceptions_module()

– khoros.utils.tests.test_board_creation.initialize_khoros_object()

– khoros.utils.tests.test_board_creation.get_required_fields()– khoros.utils.tests.test_board_creation.get_dict_for_required_fields()– khoros.utils.tests.test_board_creation.verify_data_fields()– khoros.utils.tests.test_board_creation.test_required_fields()– khoros.utils.tests.test_board_creation.test_valid_board_types()– khoros.utils.tests.test_board_creation.test_no_arguments()– khoros.utils.tests.test_board_creation.test_invalid_board_type()– khoros.utils.tests.test_board_creation.test_description()

• Added the khoros.errors.exceptions.InvalidPayloadValueError exception class.

• Added the khoros.utils.helper._get_discussion_styles() function.



Documentation


• Added the khoros.structures.grouphubs module to the Primary Modules page.

• Added the khoros.utils.tests.test_board_creation module to the Supporting Modules page.

• Added a docstring for khoros.utils.core_utils._is_zero_length().

• Added the discussion_styles field to the example helper file on the Introduction page.

General

• Added the helper.yml file in the examples/ directory of the repository using the syntax found on the Intro-duction page of the documentation.

• Added the discussion_styles list to the examples/helper.yml file.

Changed

Primary Modules


• Renamed the khoros.structures.base._get_node_id() function to be khoros.structures.base.get_structure_id() and converted it from a private to public function.

• Added the gh-p and ct-p entries in the node_url_identifiers list within the khoros.structures.base.Mapping class.

• Refactored the khoros.structures.categories.get_category_id() function to leverage the khoros.structures.base.get_structure_id() function.

Supporting Modules


• Updated the khoros.utils.helper.get_helper_settings() function to capture the enabled discussionstyles via the khoros.utils.helper._get_discussion_styles() function.

• Updated the khoros.core.Khoros class to define the enabled discussion styles even if a helper configurationfile is not supplied.

Documentation


• Added a caution message to the docstring for khoros.structures.boards.create().



Deprecated

• Deprecated the khoros.structures.categories.get_total_category_count() function as it has beenreplaced with the khoros.structures.categories.get_total_count() function.

• Deprecated the khoros.core.Khoros.Category.get_total_category_count()method as it has been re-placed with the khoros.core.Khoros.Category.get_total_count() method.

Return to Top

1.10.29 v2.5.2


Added

Primary Modules


• Added the private function khoros.api._get_v2_return_values() to address possible KeyError excep-tions in the khoros.api.deliver_v2_results() function.

Documentation


• Added the Working with Boards document as a tutorial for managing boards.

Changed

Primary Modules


• Removed the assert function call from the khoros.core.Khoros._populate_construct_settings()method.

• Updated the khoros.api.parse_v2_response() function so that the http_code value returns as an integerrather than a string.

• Replaced the return_developer_message argument with return_error_messages in the khoros.api.parse_v2_response(), khoros.api.deliver_v2_results(), khoros.structures.boards.create()and khoros.core.Khoros.Board.create() functions.




• Updated the khoros.api.parse_v2_response() function to merge the message and developer_messageresponse values into the error_msg field in the dictionary, and included the split_errors argument whichdetermines if they should be split within a tuple or consolidated into a single string separated by a hyphen. (e.g.Invalid query syntax - An invalid value was passed...)

• Included the split_errors argument in the khoros.api.deliver_v2_results(), khoros.structures.boards.create() and khoros.core.Khoros.Board.create() functions.

Supporting Modules


• Renamed the khoros.utils.core_utils.__is_zero_length() function to be khoros.utils.core_utils._is_zero_length() instead.

• Renamed the khoros.utils.core_utils.__structure_query_string() function to be khoros.utils.core_utils._structure_query_string() instead.

Documentation


• Added the Working with Boards page to the Python SDK for Khoros Communities home page.

Return to Top

1.10.30 v2.5.1


Added

Primary Modules


• Added the khoros.studio module with the khoros.studio.base sub-module.

• Added the following functions to the khoros.studio.base module:– khoros.studio.base.sdk_installed()– khoros.studio.base.get_sdk_version()– khoros.studio.base.node_installed()– khoros.studio.base.get_node_version()– khoros.studio.base.npm_installed()– khoros.studio.base.get_npm_version()



• Added the khoros.core.Khoros.Studio subclass with the following functions:– khoros.core.Khoros.Studio.sdk_installed()– khoros.core.Khoros.Studio.get_sdk_version()– khoros.core.Khoros.Studio.node_installed()– khoros.core.Khoros.Studio.get_node_version()– khoros.core.Khoros.Studio.npm_installed()– khoros.core.Khoros.Studio.get_npm_version()

• Added the khoros.core.Khoros._import_studio_class() function and associated function call.

Supporting Modules


• Added the khoros.utils.core_utils.run_cmd() function.

• Added the khoros.utils.core_utils.decode_binary() function.

Documentation


• Added the khoros.core.Khoros.Board subclass to the primary modules page.

• Added the khoros.studio module to the primary modules page.

Changed

Documentation


• Swapped the Objects Module (khoros.objects) section with the Structures Module (khoros.structures) section onthe primary modules page.

Return to Top



1.10.31 v2.5.0


Added

Primary Modules


• Added the following functions to the khoros.api module:– khoros.api.make_v1_request()– khoros.api.encode_v1_query_string()– khoros.api.deliver_v2_results()– khoros.api.parse_v2_response()– khoros.api._api_request_without_payload()

– khoros.api._report_failed_attempt()

– khoros.api._raise_exception_for_repeated_timeouts()

– khoros.api._attempt_json_conversion()

• Added the following functions to the khoros.objects.users module:– khoros.objects.users.structure_user_dict_list()– khoros.objects.users.get_ids_from_login_list()

• Added the new khoros.structures.boards module with the following functions:– khoros.structures.boards.create()– khoros.structures.boards.structure_payload()– khoros.structures.boards._structure_id_and_title()

– khoros.structures.boards._structure_discussion_style()

– khoros.structures.boards._structure_parent_category()

– khoros.structures.boards._structure_simple_fields()

– khoros.structures.boards._structure_label_settings()

– khoros.structures.boards._structure_blog_settings()

– khoros.structures.boards._structure_contest_settings()

– khoros.structures.boards._warn_about_ignored_settings()

• Added the khoros.structures.categories.create() function.

• Added khoros.core.Khoros.Category.create() method.

• Added the khoros.core.Khoros.User.get_ids_from_login_list() method.

• Added the khoros.core.Khoros.Board class with the khoros.core.Khoros.Board.create() method.

• Added the khoros.core.Khoros._import_board_class() method and accompanying method call.



Supporting Modules


• Added the khoros.utils.core_utils.convert_dict_id_values_to_strings() function.

• Added the khoros.utils.core_utils.extract_key_values_from_dict_list() function.

• Added the khoros.utils.core_utils.convert_list_values() function.

• Added the khoros.utils.tests.test_core_utils module with the following functions:– khoros.utils.tests.test_core_utils.set_package_path()– khoros.utils.tests.test_core_utils.import_core_utils()– khoros.utils.tests.test_core_utils.test_url_encoding()– khoros.utils.tests.test_core_utils.test_query_string_encoding()– khoros.utils.tests.test_core_utils.test_numeric_eval()– khoros.utils.tests.test_core_utils.test_convert_set()– khoros.utils.tests.test_core_utils._check_type_and_items()

Documentation


• Added the khoros.structures.boards module to the primary modules page.

• Added the khoros.utils.tests.test_core_utils module to the supporting modules page.

• Added a docstring to the khoros.api._get_json_query_string() function.

Changed

Primary Modules


• Updated the khoros.api.post_request_with_retries(), khoros.api.put_request_with_retries() and khoros.api._api_request_with_payload() functions toperform the API requests even if no JSON payload is provided, and to leverage the new khoros.api._report_failed_attempt() and khoros.api._raise_exception_for_repeated_timeouts()functions.

• Updated the khoros.api.get_request_with_retries() function to leverage the new khoros.api._report_failed_attempt() and khoros.api._raise_exception_for_repeated_timeouts() func-tions.

• Updated the khoros.api.get_request_with_retries(), khoros.api.post_request_with_retries() and khoros.api.put_request_with_retries() functions to utilizethe khoros.api._attempt_json_conversion() function.

• Updated the khoros.objects.messages.create() to leverage the khoros.api.parse_v2_response()function.

• Added the khoros.structures.boards module to the __all__ special variable in the khoros.structures(i.e. __init__.py) module and imported it by default.



Deprecated

Primary Modules

Deprecations in the primary modules.

• Deprecated the khoros.core.Khoros.Message.parse_v2_response() function as it was replaced with thekhoros.core.Khoros.parse_v2_response() function which is a bit more generalized.

• Deprecated the khoros.objects.messages.parse_v2_response() function as it was replaced with thekhoros.api.parse_v2_response() function which is a bit more generalized.

Return to Top

1.10.32 v2.4.0


Added

Primary Modules


• Added the following functions to the khoros.objects.messages module:– khoros.objects.messages.format_user_mention()– khoros.objects.messages._get_required_user_mention_data()

• Added the khoros.objects.roles module with the following functions:– khoros.objects.roles.get_total_role_count()– khoros.objects.roles.count_role_types()– khoros.objects.roles.get_roles_for_user()

• Added the khoros.objects.messages.MESSAGE_SEO_URLS dictionary constant.

• Added the following methods to the khoros.core.Khoros class:– khoros.core.Khoros.Message.format_content_mention()– khoros.core.Khoros.Message.format_user_mention()

• Added the from . import roles statement to the khoros.objectsmodule and added roles to the __all__special variable.

• Added the khoros.core.Khoros.Role inner class with the following methods:– khoros.core.Khoros.Role.get_total_role_count()– khoros.core.Khoros.Role.get_total_role_count()



• Added the method khoros.core.Khoros._import_role_class() to the core object and added the methodcall in the initialization method.

Supporting Modules


• Added the following exception classes:– khoros.errors.exceptions.MessageTypeNotFoundError– khoros.errors.exceptions.InvalidRoleError– khoros.errors.exceptions.InvalidRoleTypeError

• Added the khoros.utils.tests.test_mentions unit test module.

Documentation


• Added khoros.utils.tests.test_mentions to the Support Modules page.

• Added khoros.objects.roles to the primary modules page.

• Added khoros.core.Khoros.Role to the primary modules page.

• Added a code coverage badge to the README.md file.

General

• Added a code coverage section to the pythonpackage.yml file.

• Added the codecov.yml file for coverage reports.

Changed

General

• Changed the PyPI Development Status in setup.py to be Development Status :: 4 - Beta.

Fixed

Primary Modules


• Fixed how and when values are cast to integers in khoros.objects.users._get_user_identifier().

• Added missing method calls for the khoros.core.Khoros._import_message_class() and khoros.core.Khoros._import_album_class() methods in the initialization method for the khoros.core.Khoros class.

Return to Top



https://github.com/jeffshurtliff/khoros/blob/master/codecov.yml


1.10.33 v2.3.0


Added

Primary Modules


• Added the khoros.api.encode_multipart_data() function.

• Added the following functions to the khoros.objects.messages module:– khoros.objects.messages.create()– khoros.objects.messages.construct_payload()– khoros.objects.messages._verify_required_fields()

– khoros.objects.messages.parse_v2_response()– khoros.objects.messages._confirm_field_supplied()

• Created the khoros.objects.attachments module with the following functions:– khoros.objects.attachments.construct_multipart_payload()– khoros.objects.attachments.format_attachment_payload()– khoros.objects.attachments.get_list_items()– khoros.objects.attachments.get_file_upload_info()– khoros.objects.attachments._format_single_file()

– khoros.objects.attachments._format_multiple_files()

• Created the khoros.objects.albums module with the following functions:– khoros.objects.albums.create()– khoros.objects.albums.format_album_json()– khoros.objects.albums.get_albums_for_user()– khoros.objects.albums._null_to_blank()

• Added the following methods to the khoros.core.Khoros class:– khoros.core.Khoros._import_album_class()

– khoros.core.Khoros._import_message_class()

• Added the khoros.core.Khoros.Album inner class with the following methods:– khoros.core.Khoros.Album.create()– khoros.core.Khoros.Album.get_albums_for_user()



• Added the khoros.core.Khoros.Message inner class with the following methods:– khoros.core.Khoros.Message.create()– khoros.core.Khoros.Message.parse_v2_response()

• Added an import statement for khoros.objects.albums to the khoros.objects module.

Supporting Modules


• Added the khoros.utils.core_utils.convert_single_value_to_tuple() function.

• Added the khoros.utils.core_utils.convert_string_to_tuple() function.

• Added the khoros.utils.core_utils.is_numeric() function.

• Added the khoros.errors.exceptions.DataMismatchError exception class.

Documentation


• Added the Utilizing environment variables section to the Introduction page.

• Updated the README.md file to match the Introduction page.

• Added the khoros.objects.messages module to the primary modules page.

• Added the khoros.objects.albums module to the primary modules page.

• Added the khoros.objects.attachments module to the primary modules page.

• Added the khoros.core.Khoros.Album class to the primary modules page.

• Added the khoros.core.Khoros.Message class to the primary modules page.

• Added the SECURITY.md and CODE_OF_CONDUCT.md files to the source repository.

General

• Added requests-toolbelt==0.9.1 to the requirements.txt file.

Changed

Primary Modules


• Updated the khoros.core.Khoros class so that environment variables are ignored if a Helper configurationfile is supplied when instantiating the core object.

• Added the ability to perform multipart/form-data API calls in functions below.– khoros.api.post_request_with_retries()– khoros.api.put_request_with_retries()– khoros.api._api_request_with_payload()



https://github.com/jeffshurtliff/khoros/blob/master/SECURITY.md

https://github.com/jeffshurtliff/khoros/blob/master/CODE_OF_CONDUCT.md


• Added the associated exception type (e.g. ValueError) to the failure messages in khoros.api.get_request_with_retries() and khoros.api._api_request_with_payload().

• Updated the khoros.api.get_request_with_retries() to use the khoros.errors.exceptions.APIConnectionError exception class rather than ConnectionError.

• Updated the khoros.api.get_request_with_retries() and khoros.api._api_request_with_payload() functions to only retry if relevant exception classes are raised in thetry/except.

• Added functionality to khoros.api.post_request_with_retries() and khoros.api.put_request_with_retries() to display an error but still return the API response if unable to convert theresponse to JSON format when requested.

• Renamed the khoros.api.__api_request_with_payload() function to be khoros.api._api_request_with_payload() instead.

• Replaced print() statements in the khoros.api.get_request_with_retries() and khoros.api._api_request_with_payload() functions with khoros.errors.handlers.eprint() function calls.

• Added the multipart Boolean argument to the khoros.api.define_headers() which will remove theContent-Type header key and value if the API call is for a multipart/form-data query.

• Added the allow_exceptions argument (True by default) to the khoros.liql.perform_query() functionto allow the khoros.errors.exceptions.GETRequestError exception to be disabled if an error response isreturned.

• Updated the error/exception message in the khoros.liql.perform_query() to be more specific.

Documentation


• Added a full docstring to the khoros.api._api_request_with_payload() function.

Fixed

Primary Modules


• Removed the Aurea reference from the failure message in khoros.api._api_request_with_payload.

Supporting Modules

Fixes to the supporting modules.

• Changed “v1” to “v2” in the full error message string within the khoros.errors.handlers._get_v2_error_from_json() function.

Return to Top


https://docs.python.org/3/library/exceptions.html#ConnectionError

https://docs.python.org/3/library/functions.html#print


1.10.34 v2.2.0


Added

Primary Modules


• Added the ability to use environmental variables to initialize the khoros.core.Khoros object.– Added the khoros.core.Khoros._parse_env_settings() method to parse the environmental

variables.

• Added the khoros.core.Khoros._session_auth_credentials_defined() method to automatically setthe auth_type value in the _settings attribute to be session_auth if a session authentication username andpassword have been defined.

Supporting Modules


• Added the khoros.utils.environment module with the following functions and constants:– khoros.utils.environment.get_env_variables()– khoros.utils.environment._env_variable_exists()

– khoros.utils.environment._get_env_variable_value()

– khoros.utils.environment.update_env_variable_names()– khoros.utils.environment._update_env_list()

– khoros.utils.environment._update_env_mapping()

– khoros.utils.environment._import_custom_names_file()

– khoros.utils.environment.ENV_VARIABLE_NAMES

• Added the khoros.utils.core_utils.get_file_type() function.

• Added the khoros.errors.exceptions.UnknownFileTypeError exception class.

• Added the khoros.utils.tests.test_helper_file unit test module.

Examples

New additions to the example files for the library.

• Added the custom_env_variables.json file.

• Added the custom_env_variables.yml file.



Documentation


• Added the khoros.utils.environment module to the supporting modules page.

• Added the khoros.utils.tests.test_helper_file module to the supporting modules page.

General

• Added the encrypted YAML Helper configuration file khoros_helper.yml.gpg in the khoros/utils/tests/ directory for use with pytest.

• Added the shell script decrypt_helper.sh in the .github/scripts/ directory per GitHub guidelines.

• Updated the pythonpackage.ymlworkflow for GitHub Actions to decrypt the helper configuration file (YAML)and utilize environment variables.

Changed

Primary Modules


• Made an adjustment to the khoros.core.Khoros object class so that any values explicitly passed via thesettings argument will overwrite any existing settings defined by default values and/or environmental vari-ables.

• Added khoros.structures.base to the __all__ special variable in khoros.structures.

• Added khoros.objects.messages to the __all__ special variable in khoros.objects and added animport statement to import the module by default.

• Removed khoros.objects.base from the __all__ special variable in khoros.objects and removed theimport statement to prevent the module from being imported by default.

Supporting Modules


• Replaced the yaml.load() function call with yaml.safe_load() in khoros.utils.helper.import_yaml_file() as it is a better security practice.

• Introduced support for JSON formatted helper configuration files in khoros.utils.helper.

• Removed the extra preceding underscore in private functions within khoros.utils.helper.


https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets


Documentation


• Added :special-members: __init__ to the khoros and khoros.core modules to display the docstringsfor the __init__ method in the khoros.core.Khoros object class.

• Replaced NoneType with None in function and method docstrings to use proper syntax and to comply with PEP287.

Return to Top

1.10.35 v2.1.0


Added

Primary Modules


• Added the khoros.liql.get_total_count() function.

• Added the khoros.core.Khoros.get_total_count() method within the core Khoros object.

• Added the khoros.structures module.

• Added the khoros.structures.base module with the following functions and class:– khoros.structures.base.get_details()– khoros.structures.base._check_url_for_identifier()

– khoros.structures.base.get_structure_field()– khoros.structures.base.is_category_url()– khoros.structures.base.is_node_url()– khoros.structures.base.verify_structure_type()– khoros.structures.base.get_structure_type_from_url()– khoros.structures.base.Mapping

• Added the khoros.structures.categories module with the following functions:– khoros.structures.categories.get_category_id()– khoros.structures.categories.get_total_category_count()– khoros.structures.categories.get_category_details()– khoros.structures.categories.get_category_field()





– khoros.structures.categories.get_url()– khoros.structures.categories.get_title()– khoros.structures.categories.get_description()– khoros.structures.categories.get_parent_type()– khoros.structures.categories.get_parent_id()– khoros.structures.categories.get_parent_url()– khoros.structures.categories.get_root_type()– khoros.structures.categories.get_root_id()– khoros.structures.categories.get_root_url()– khoros.structures.categories.get_language()– khoros.structures.categories.is_hidden()– khoros.structures.categories.get_views()– khoros.structures.categories.friendly_date_enabled()– khoros.structures.categories.get_friendly_date_max_age()– khoros.structures.categories.get_active_skin()– khoros.structures.categories.get_depth()– khoros.structures.categories.get_position()– khoros.structures.categories.get_creation_date()

• Added the khoros.structures.communities module with the following functions:– khoros.structures.communities.get_community_details()– khoros.structures.communities._check_for_multiple_tenants()

– khoros.structures.communities.get_community_field()– khoros.structures.communities.get_tenant_id()– khoros.structures.communities.get_title()– khoros.structures.communities.get_description()– khoros.structures.communities.get_primary_url()– khoros.structures.communities.get_max_attachments()– khoros.structures.communities.get_permitted_attachment_types()– khoros.structures.communities.email_confirmation_required_to_post()– khoros.structures.communities.get_language()– khoros.structures.communities.get_ooyala_player_branding_id()– khoros.structures.communities.get_date_pattern()– khoros.structures.communities.friendly_date_enabled()– khoros.structures.communities.get_friendly_date_max_age()– khoros.structures.communities.get_active_skin()– khoros.structures.communities.get_sign_out_url()



– khoros.structures.communities.get_creation_date()– khoros.structures.communities.top_level_categories_enabled()– khoros.structures.communities.show_community_node_in_breadcrumb()– khoros.structures.communities.show_breadcrumb_at_top_level()– khoros.structures.communities.top_level_categories_on_community_page()

• Added the khoros.structures.nodes module with the following functions and classes:– khoros.structures.nodes.get_node_id()– khoros.structures.nodes.get_node_type_from_url()– khoros.structures.nodes._get_node_type_identifier()

– khoros.structures.nodes.get_total_node_count()– khoros.structures.nodes.get_node_details()– khoros.structures.nodes.get_node_field()– khoros.structures.nodes.get_url()– khoros.structures.nodes.get_type()– khoros.structures.nodes.get_discussion_style()– khoros.structures.nodes.get_title()– khoros.structures.nodes.get_description()– khoros.structures.nodes.get_parent_type()– khoros.structures.nodes.get_parent_id()– khoros.structures.nodes.get_parent_url()– khoros.structures.nodes.get_root_type()– khoros.structures.nodes.get_root_id()– khoros.structures.nodes.get_root_url()– khoros.structures.nodes.get_avatar_url()– khoros.structures.nodes.get_creation_date()– khoros.structures.nodes.get_depth()– khoros.structures.nodes.get_position()– khoros.structures.nodes.is_hidden()– khoros.structures.nodes.get_views()– khoros.structures.nodes.Mapping

• Added the khoros.core.Khoros.Category inner class with the following methods:– khoros.core.Khoros.Category.get_category_id()– khoros.core.Khoros.Category.get_total_category_count()– khoros.core.Khoros.Category.get_category_details()– khoros.core.Khoros.Category.get_category_field()– khoros.core.Khoros.Category.get_url()



– khoros.core.Khoros.Category.get_title()– khoros.core.Khoros.Category.get_description()– khoros.core.Khoros.Category.get_parent_type()– khoros.core.Khoros.Category.get_parent_id()– khoros.core.Khoros.Category.get_parent_url()– khoros.core.Khoros.Category.get_root_type()– khoros.core.Khoros.Category.get_root_id()– khoros.core.Khoros.Category.get_root_url()– khoros.core.Khoros.Category.get_language()– khoros.core.Khoros.Category.is_hidden()– khoros.core.Khoros.Category.get_views()– khoros.core.Khoros.Category.friendly_date_enabled()– khoros.core.Khoros.Category.get_friendly_date_max_age()– khoros.core.Khoros.Category.get_active_skin()– khoros.core.Khoros.Category.get_depth()– khoros.core.Khoros.Category.get_position()– khoros.core.Khoros.Category.get_creation_date()

• Added the khoros.core.Khoros.Community inner class with the following methods:– khoros.core.Khoros.Community.get_community_details()– khoros.core.Khoros.Community.get_tenant_id()– khoros.core.Khoros.Community.get_title()– khoros.core.Khoros.Community.get_description()– khoros.core.Khoros.Community.get_primary_url()– khoros.core.Khoros.Community.get_max_attachments()– khoros.core.Khoros.Community.get_permitted_attachment_types()– khoros.core.Khoros.Community.email_confirmation_required_to_post()– khoros.core.Khoros.Community.get_language()– khoros.core.Khoros.Community.get_ooyala_player_branding_id()– khoros.core.Khoros.Community.get_date_pattern()– khoros.core.Khoros.Community.friendly_date_enabled()– khoros.core.Khoros.Community.get_friendly_date_max_age()– khoros.core.Khoros.Community.get_active_skin()– khoros.core.Khoros.Community.get_sign_out_url()– khoros.core.Khoros.Community.get_creation_date()– khoros.core.Khoros.Community.top_level_categories_enabled()– khoros.core.Khoros.Community.show_community_node_in_breadcrumb()



– khoros.core.Khoros.Community.show_breadcrumb_at_top_level()– khoros.core.Khoros.Community.top_level_categories_on_community_page()

• Added the following methods to the khoros.core.Khoros.Node inner class:– khoros.core.Khoros.Node.get_total_node_count()– khoros.core.Khoros.Node.get_node_details()– khoros.core.Khoros.Node.get_node_field()– khoros.core.Khoros.Node.get_url()– khoros.core.Khoros.Node.get_type()– khoros.core.Khoros.Node.get_discussion_style()– khoros.core.Khoros.Node.get_title()– khoros.core.Khoros.Node.get_description()– khoros.core.Khoros.Node.get_parent_type()– khoros.core.Khoros.Node.get_parent_id()– khoros.core.Khoros.Node.get_parent_url()– khoros.core.Khoros.Node.get_root_type()– khoros.core.Khoros.Node.get_root_id()– khoros.core.Khoros.Node.get_root_url()– khoros.core.Khoros.Node.get_avatar_url()– khoros.core.Khoros.Node.get_creation_date()– khoros.core.Khoros.Node.get_depth()– khoros.core.Khoros.Node.get_position()– khoros.core.Khoros.Node.is_hidden()– khoros.core.Khoros.Node.get_views()

• Added the khoros.core.Khoros._import_category_class() method and accompanying method call.

• Added the khoros.core.Khoros._import_community_class() method and accompanying method call.

• Added the khoros.liql.COLLECTIONS constant.

Supporting Modules


• Added the khoros.utils.core_utils.display_warning() function.

• Added the following exception classes:– khoros.errors.exceptions.InvalidFieldError– khoros.errors.exceptions.InvalidStructureTypeError– khoros.errors.exceptions.InvalidURLError



Documentation


• Added the khoros.structures module and its submodules to the primary modules page.

Changed

Primary Modules


• Updated the khoros.objects to import all submodules by default.

• Moved the khoros.objects.base.get_node_id() function to the khoros.structures.nodes moduleand added a DeprecationWarning.

• Moved the khoros.objects.base.get_node_type_from_url() function to the khoros.structures.nodes module and added a DeprecationWarning.

• Moved the khoros.objects.base.__get_node_type_identifier() function to the khoros.structures.nodes module and added a DeprecationWarning.

• Moved the khoros.objects.base.Mapping class to the khoros.structures.nodes module and added aDeprecationWarning.

• Added the khoros.structures.nodes.Mapping.avatar_size_mapping dictionary.

Fixed

Primary Modules


• Removed some print debugging that hadn’t been removed in the khoros.api.query_successful() function.

Documentation

Fixes to the documentation.

• Fixed the module name in the header docstring for the khoros.objects module.

• Fixed a typo in the docstring for the khoros.objects.users.query_users_table_by_id() function.

Supporting Modules


• Fixed the khoros.utils.tests.test_node_id_extract to use the new khoros.structures.nodesmodule.

Return to Top







1.10.36 v2.0.0


Added

Primary Modules


• Added the khoros.core.Khoros.perform_v1_search() method.

• Added the khoros.core.Khoros._import_node_class() and khoros.core.Khoros._import_user_class() methods within the core khoros.Khoros object class.

• Added the khoros.core.Khoros.Node inner class within the core khoros.Khoros object class.

• Added the static methods below within the core khoros.core.Khoros object class:– khoros.core.Khoros.Node.get_node_id()– khoros.core.Khoros.Node.get_node_type_from_url()

• Added the khoros.core.Khoros.User inner class within the core khoros.Khoros object class.

• Added the methods below within the core khoros.core.Khoros object class:– khoros.core.Khoros.User.create()– khoros.core.Khoros.User.delete()– khoros.core.Khoros.User.get_user_id()– khoros.core.Khoros.User.get_username()– khoros.core.Khoros.User.get_login()– khoros.core.Khoros.User.get_email()– khoros.core.Khoros.User.query_users_table_by_id()– khoros.core.Khoros.User.get_user_data()– khoros.core.Khoros.User.get_album_count()– khoros.core.Khoros.User.get_followers_count()– khoros.core.Khoros.User.get_following_count()– khoros.core.Khoros.User.get_images_count()– khoros.core.Khoros.User.get_public_images_count()– khoros.core.Khoros.User.get_messages_count()– khoros.core.Khoros.User.get_roles_count()– khoros.core.Khoros.User.get_solutions_authored_count()– khoros.core.Khoros.User.get_topics_count()– khoros.core.Khoros.User.get_replies_count()



– khoros.core.Khoros.User.get_videos_count()– khoros.core.Khoros.User.get_kudos_given_count()– khoros.core.Khoros.User.get_kudos_received_count()– khoros.core.Khoros.User.get_online_user_count()– khoros.core.Khoros.User.get_registration_data()– khoros.core.Khoros.User.get_registration_timestamp()– khoros.core.Khoros.User.get_registration_status()– khoros.core.Khoros.User.get_last_visit_timestamp()

• Added the khoros.api.query_successful() function.

• Added the khoros.api.get_results_count() function.

• Added the khoros.api.get_items_list() function.

• Added the khoros.api.perform_v1_search() function.

• Added the khoros.api.delete() function.

• Added the new khoros.objects module to contain sub-modules for the various API objects.

• Added the khoros.objects.base module with the following functions and classes:– khoros.objects.base.get_node_id()– khoros.objects.base.get_node_type_from_url()– khoros.objects.base.__get_node_type_identifier()

– khoros.objects.base.Mapping• Added the khoros.objects.users module with the following functions:

– khoros.objects.users.create()– khoros.objects.users.process_user_settings()– khoros.objects.users.structure_payload()– khoros.objects.users.delete()– khoros.objects.users.get_user_id()– khoros.objects.users.get_username()– khoros.objects.users.get_login()– khoros.objects.users.get_email()– khoros.objects.users.get_user_data_with_v1()– khoros.objects.users._get_where_clause_for_user_id()

– khoros.objects.users._get_where_clause_for_username()

– khoros.objects.users._get_where_clause_for_email()

– khoros.objects.users._get_user_identifier()

– khoros.objects.users.query_users_table_by_id()– khoros.objects.users._get_count()

– khoros.objects.users._get_sum_weight()



– khoros.objects.users.get_user_data()– khoros.objects.users.get_album_count()– khoros.objects.users.get_followers_count()– khoros.objects.users.get_following_count()– khoros.objects.users.get_images_count()– khoros.objects.users.get_public_images_count()– khoros.objects.users.get_messages_count()– khoros.objects.users.get_replies_count()– khoros.objects.users.get_roles_count()– khoros.objects.users.get_solutions_authored_count()– khoros.objects.users.get_topics_count()– khoros.objects.users.get_videos_count()– khoros.objects.users.get_kudos_given_count()– khoros.objects.users.get_kudos_received_count()– khoros.objects.users.get_online_user_count()– khoros.objects.users.get_registration_data()– khoros.objects.users.get_registration_timestamp()– khoros.objects.users.get_registration_status()– khoros.objects.users.get_last_visit_timestamp()

Supporting Modules


• Added the khoros.utils.core_utils.decode_html_entities() function.

• Added the following exception classes:– khoros.errors.exceptions.APIRequestError– khoros.errors.exceptions.DELETERequestError– khoros.errors.exceptions.InvalidNodeTypeError– khoros.errors.exceptions.MissingRequiredDataError– khoros.errors.exceptions.NodeIDNotFoundError– khoros.errors.exceptions.NodeTypeNotFoundError– khoros.errors.exceptions.TooManyResultsError– khoros.errors.exceptions.UserCreationError

• Added the following functions to the khoros.errors.handlers module.– khoros.errors.handlers.get_error_from_xml()– khoros.errors.handlers.get_error_from_json()– khoros.errors.handlers._get_v1_error_from_json()



– khoros.errors.handlers._get_v2_error_from_json()

– khoros.errors.handlers.verify_v1_response()– khoros.errors.handlers._import_exception_classes()

– khoros.errors.handlers._exceptions_module_imported()

– khoros.errors.handlers._import_exceptions_module()

• Added the khoros.utils.tests.test_node_id_extract module with the following functions:– khoros.utils.tests.test_node_id_extract.set_package_path()– khoros.utils.tests.test_node_id_extract.get_test_data()– khoros.utils.tests.test_node_id_extract.test_with_valid_node_types()– khoros.utils.tests.test_node_id_extract.test_with_invalid_node_types()– khoros.utils.tests.test_node_id_extract.test_with_only_url()– khoros.utils.tests.test_node_id_extract.test_url_without_node()

Documentation


• Added the Core Object Subclasses to the primary modules page.

• Added the khoros.objects module and the khoros.objects.base and khoros.objects.users sub-modules to the primary modules page.

• Added the khoros.utils.tests.test_node_id_extract module to the supporting modules page.

General

• Added PyCharm Python Security Scanner to the pythonpackage.yml file.

Changed

Primary Modules


• Updated the khoros.liql.perform_query() function to allow a raw LiQL query to be passed rather thanonly pre-formatted query URLs.

• Updated the khoros.liql.perform_query() function to include an optional verify_success argu-ment which verifies that the API query was successful and raises the khoros.errors.exceptions.GETRequestError exception if not.

• Removed the unnecessary import requests line in the khoros.liql module.

• Renamed the khoros.core.Khoros.__connect_with_session_key() method to be khoros.core.Khoros._connect_with_session_key() (single underscore prefix) instead.

• Renamed the khoros.core.Khoros.__define_url_settings() method to be khoros.core.Khoros._define_url_settings() (single underscore prefix) instead.


https://github.com/jeffshurtliff/khorosjx/blob/master/.github/workflows/pythonpackage.yml


• Renamed the khoros.core.Khoros.__parse_helper_settings() method to be khoros.core.Khoros._parse_helper_settings() (single underscore prefix) instead.

• Renamed the khoros.core.Khoros.__populate_auth_settings()method to be khoros.core.Khoros._populate_auth_settings() (single underscore prefix) instead.

• Renamed the khoros.core.Khoros.__populate_construct_settings() method to be khoros.core.Khoros._populate_construct_settings() (single underscore prefix) instead.

• Renamed the khoros.core.Khoros.__populate_core_settings()method to be khoros.core.Khoros._populate_core_settings() (single underscore prefix) instead.

• Renamed the khoros.core.Khoros.__validate_base_url() method to be khoros.core.Khoros._validate_base_url() (single underscore prefix) instead.

Supporting Modules


• Updated the khoros.errors.exceptions.CurrentlyUnsupportedError exception class to allow the re-spective feature to be passed as a string argument for it to be explicitly referenced in the exception message.

• Updated the khoros.errors.handlers.get_error_from_html() function to have a second v1 argument,which is False by default.

Documentation


• Updated the docstring in khoros.api.query_successful() indicating the API response should be in JSONformat.

General

• Changed the Development Status in setup.py to be 3 - Alpha.

Fixed

Primary Modules


• Updated the khoros.liql.format_query() function to properly encode the double-quote (") character andseveral other special characters.



Documentation

Fixes in the documentation.

• Fixed two bad hyperlinks in the README.md file.

• Fixed the docstrings in the khoros.errors.exceptions.InvalidOperatorError exception class to be ac-curate.

• Fixed the docstrings in the khoros.errors.exceptions.OperatorMismatchError exception class to beaccurate.

Return to Top

1.10.37 v1.2.0


Added

Primary Modules


• Added the khoros.core.Khoros.signout() method.

• Added the khoros.auth.get_oauth_authorization_url() function.

• Added the khoros.auth.get_oauth_callback_url_from_user() function.

• Added the khoros.auth.invalidate_session() function.

• Added the khoros.api module with the following functions:– khoros.api.define_headers()– khoros.api.get_request_with_retries()– khoros.api.post_request_with_retries()– khoros.api.put_request_with_retries()– khoros.api.__api_request_with_payload()




Supporting Modules


• Added the khoros.utils.core_utils.get_random_string() function.

• Added the khoros.utils.core_utils.__structure_query_string() function.

• Added the following exception classes:– khoros.errors.exceptions.APIConnectionError– khoros.errors.exceptions.GETRequestError– khoros.errors.exceptions.InvalidCallbackURLError– khoros.errors.exceptions.InvalidEndpointError– khoros.errors.exceptions.InvalidLookupTypeError– khoros.errors.exceptions.InvalidRequestTypeError– khoros.errors.exceptions.LookupMismatchError– khoros.errors.exceptions.NotFoundResponseError– khoros.errors.exceptions.POSTRequestError– khoros.errors.exceptions.PUTRequestError

Documentation


• Added the khoros.api module to the primary modules page.

Changed

Primary Modules


• Updated the core khoros.core.Khoros class to include the active Boolean flag in self.auth.

• Updated the khoros.liql.perform_query() function to utilize the khoros.api.get_request_with_retries() function.

• Made minor docstring adjustments to the khoros.liql.perform_query() function.

Supporting Modules


• Added the no_encode argument and associated functionality to the khoros.utils.core_utils.encode_query_string() function.

Return to Top



1.10.38 v1.1.0


Added

Primary Modules


• Added the khoros.utils.version.warn_when_not_latest() function call to the main khoros module.

Supporting Modules


• Added the khoros.utils.version.get_latest_stable() function.

• Added the khoros.utils.version.latest_version() function.

• Added the khoros.utils.version.warn_when_not_latest() function.

Documentation


• Added the Changelog and Usage sections to the README.md file.

• Created the Change Log page and populated it with the v1.1.0 changes.

• Created the primary modules and supporting modules pages.

Return to Top



CHAPTER

TWO

MODULE INDEX AND SEARCH

• genindex

• modindex

• search

429


430 Chapter 2. Module Index and Search

PYTHON MODULE INDEX

kkhoros, 40khoros.api, 229khoros.auth, 241khoros.core, 103khoros.errors, 327khoros.errors.exceptions, 328khoros.errors.handlers, 331khoros.errors.translations, 333khoros.liql, 243khoros.objects, 247khoros.objects.albums, 249khoros.objects.archives, 250khoros.objects.attachments, 253khoros.objects.base, 248khoros.objects.labels, 255khoros.objects.messages, 255khoros.objects.roles, 265khoros.objects.settings, 269khoros.objects.subscriptions, 270khoros.objects.tags, 274khoros.objects.users, 276khoros.saml, 289khoros.structures, 290khoros.structures.base, 291khoros.structures.boards, 294khoros.structures.categories, 298khoros.structures.communities, 307khoros.structures.grouphubs, 312khoros.structures.nodes, 317khoros.studio, 325khoros.studio.base, 325khoros.utils.core_utils, 334khoros.utils.environment, 339khoros.utils.helper, 340khoros.utils.log_utils, 339khoros.utils.tests, 342khoros.utils.tests.resources, 343khoros.utils.tests.test_board_creation, 344khoros.utils.tests.test_core_utils, 345khoros.utils.tests.test_grouphub_creation,

346

khoros.utils.tests.test_helper_file, 347khoros.utils.tests.test_http_headers, 347khoros.utils.tests.test_library_import, 348khoros.utils.tests.test_liql, 348khoros.utils.tests.test_mentions, 349khoros.utils.tests.test_messages, 352khoros.utils.tests.test_node_id_extract, 353khoros.utils.tests.test_settings, 354khoros.utils.tests.test_tags, 355khoros.utils.version, 341

431


432 Python Module Index

INDEX

Symbols__init__() (khoros.Khoros method), 95__init__() (khoros.Khoros.Album method), 40__init__() (khoros.Khoros.Archives method), 41__init__() (khoros.Khoros.Board method), 43__init__() (khoros.Khoros.Category method), 46__init__() (khoros.Khoros.Community method), 52__init__() (khoros.Khoros.GroupHub method), 56__init__() (khoros.Khoros.Message method), 59__init__() (khoros.Khoros.Node method), 65__init__() (khoros.Khoros.Role method), 72__init__() (khoros.Khoros.SAML method), 75__init__() (khoros.Khoros.Settings method), 76__init__() (khoros.Khoros.Studio method), 77__init__() (khoros.Khoros.Subscription method), 78__init__() (khoros.Khoros.Tag method), 81__init__() (khoros.Khoros.User method), 82__init__() (khoros.Khoros.V1 method), 91__init__() (khoros.Khoros.V2 method), 93__init__() (khoros.core.Khoros method), 163__init__() (khoros.core.Khoros.Album method), 103__init__() (khoros.core.Khoros.Archives method), 105__init__() (khoros.core.Khoros.Board method), 106__init__() (khoros.core.Khoros.Category method),

110__init__() (khoros.core.Khoros.Community method),

118__init__() (khoros.core.Khoros.GroupHub method),

122__init__() (khoros.core.Khoros.Message method), 126__init__() (khoros.core.Khoros.Node method), 133__init__() (khoros.core.Khoros.Role method), 140__init__() (khoros.core.Khoros.SAML method), 143__init__() (khoros.core.Khoros.Settings method), 143__init__() (khoros.core.Khoros.Studio method), 145__init__() (khoros.core.Khoros.Subscription method),

145__init__() (khoros.core.Khoros.Tag method), 148__init__() (khoros.core.Khoros.User method), 150__init__() (khoros.core.Khoros.V1 method), 158__init__() (khoros.core.Khoros.V2 method), 161

Aadd_single_tag_to_message() (in module

khoros.objects.tags), 274add_single_tag_to_message()

(khoros.core.Khoros.Tag method), 148add_single_tag_to_message() (khoros.Khoros.Tag

method), 81add_subscription() (in module

khoros.objects.subscriptions), 271add_subscription() (khoros.core.Khoros.Subscription

method), 146add_subscription() (khoros.Khoros.Subscription

method), 78add_tags_to_message() (in module

khoros.objects.tags), 274add_tags_to_message() (khoros.core.Khoros.Tag

method), 149add_tags_to_message() (khoros.Khoros.Tag method),

81aggregate_results() (khoros.core.Khoros.Archives

static method), 105aggregate_results() (khoros.Khoros.Archives static

method), 41aggregate_results_data() (in module

khoros.objects.archives), 250APIConnectionError, 328APIRequestError, 328archive() (in module khoros.objects.archives), 251archive() (khoros.core.Khoros.Archives method), 105archive() (khoros.Khoros.Archives method), 41assert_tags_present() (in module

khoros.utils.tests.test_messages), 352assign_roles_to_user() (in module

khoros.objects.roles), 265assign_roles_to_user() (khoros.core.Khoros.Role

method), 140assign_roles_to_user() (khoros.Khoros.Role

method), 73

Bboard_exists() (in module khoros.structures.boards),

294

433


board_exists() (khoros.core.Khoros.Board method),106

board_exists() (khoros.Khoros.Board method), 43

Ccategory_exists() (in module

khoros.structures.categories), 298category_exists() (khoros.core.Khoros.Category

method), 111category_exists() (khoros.Khoros.Category

method), 46close() (khoros.core.Khoros method), 164close() (khoros.Khoros method), 97close() (khoros.objects.users.ImpersonatedUser

method), 276combine_json_and_avatar_payload() (in module

khoros.api), 230compare_headers() (in module

khoros.utils.tests.test_http_headers), 347connect() (khoros.core.Khoros method), 164connect() (khoros.Khoros method), 97construct_multipart_payload() (in module

khoros.objects.attachments), 253construct_payload() (in module

khoros.objects.messages), 255convert_dict_id_values_to_strings() (in module

khoros.utils.core_utils), 334convert_dict_list_to_simple_list() (in module

khoros.utils.core_utils), 334convert_list_values() (in module

khoros.utils.core_utils), 334convert_set() (in module khoros.utils.core_utils), 335convert_single_value_to_tuple() (in module

khoros.utils.core_utils), 335convert_string_to_tuple() (in module

khoros.utils.core_utils), 335count_role_types() (in module khoros.objects.roles),

266create() (in module khoros.objects.albums), 249create() (in module khoros.objects.messages), 257create() (in module khoros.objects.users), 276create() (in module khoros.structures.boards), 294create() (in module khoros.structures.categories), 299create() (in module khoros.structures.grouphubs), 312create() (khoros.core.Khoros.Album method), 103create() (khoros.core.Khoros.Board method), 107create() (khoros.core.Khoros.Category method), 111create() (khoros.core.Khoros.GroupHub method), 122create() (khoros.core.Khoros.Message method), 126create() (khoros.core.Khoros.User method), 150create() (khoros.Khoros.Album method), 40create() (khoros.Khoros.Board method), 43create() (khoros.Khoros.Category method), 46create() (khoros.Khoros.GroupHub method), 56

create() (khoros.Khoros.Message method), 59create() (khoros.Khoros.User method), 82CurrentlyUnsupportedError, 328

DDataMismatchError, 328decode_binary() (in module khoros.utils.core_utils),

335decode_html_entities() (in module

khoros.utils.core_utils), 335define_headers() (in module khoros.api), 230define_node_setting() (in module

khoros.objects.settings), 269define_node_setting() (khoros.core.Khoros.Settings

method), 144define_node_setting() (khoros.Khoros.Settings

method), 76delete() (in module khoros.api), 230delete() (in module khoros.objects.users), 277delete() (khoros.core.Khoros.User method), 150delete() (khoros.Khoros.User method), 83DELETERequestError, 328deliver_v2_results() (in module khoros.api), 231display_warning() (in module khoros.utils.core_utils),

335

Eemail_confirmation_required_to_post() (in mod-

ule khoros.structures.communities), 307email_confirmation_required_to_post()

(khoros.core.Khoros.Community method),118

email_confirmation_required_to_post()(khoros.Khoros.Community method), 52

encode_base64() (in module khoros.utils.core_utils),336

encode_multipart_data() (in module khoros.api),232

encode_payload_values() (in module khoros.api),232

encode_query_string() (in modulekhoros.utils.core_utils), 336

encode_v1_query_string() (in module khoros.api),232

eprint() (in module khoros.errors.handlers), 331expected_content_response() (in module

khoros.utils.tests.test_mentions), 349expected_user_response() (in module

khoros.utils.tests.test_mentions), 349extract_key_values_from_dict_list() (in module

khoros.utils.core_utils), 336

FFeatureNotConfiguredError, 328

434 Index


filter() (khoros.utils.log_utils.LessThanFiltermethod), 339

format_album_json() (in modulekhoros.objects.albums), 249

format_attachment_payload() (in modulekhoros.objects.attachments), 254

format_avatar_payload() (in module khoros.api),232

format_content_mention() (in modulekhoros.objects.messages), 260

format_content_mention()(khoros.core.Khoros.Message method), 128

format_content_mention() (khoros.Khoros.Messagemethod), 61

format_query() (in module khoros.liql), 243format_user_mention() (in module

khoros.objects.messages), 260format_user_mention()

(khoros.core.Khoros.Message method), 129format_user_mention() (khoros.Khoros.Message

method), 61friendly_date_enabled() (in module

khoros.structures.categories), 299friendly_date_enabled() (in module

khoros.structures.communities), 307friendly_date_enabled()

(khoros.core.Khoros.Category method),111

friendly_date_enabled()(khoros.core.Khoros.Community method),118

friendly_date_enabled() (khoros.Khoros.Categorymethod), 47

friendly_date_enabled()(khoros.Khoros.Community method), 53

Gget() (khoros.core.Khoros method), 164get() (khoros.core.Khoros.V1 method), 158get() (khoros.core.Khoros.V2 method), 161get() (khoros.Khoros method), 97get() (khoros.Khoros.V1 method), 91get() (khoros.Khoros.V2 method), 94get_active_skin() (in module

khoros.structures.categories), 299get_active_skin() (in module

khoros.structures.communities), 307get_active_skin() (khoros.core.Khoros.Category

method), 111get_active_skin() (khoros.core.Khoros.Community

method), 118get_active_skin() (khoros.Khoros.Category

method), 47

get_active_skin() (khoros.Khoros.Communitymethod), 53

get_album_count() (in module khoros.objects.users),277

get_album_count() (khoros.core.Khoros.Usermethod), 151

get_album_count() (khoros.Khoros.User method), 83get_albums_for_user() (in module

khoros.objects.albums), 250get_albums_for_user() (khoros.core.Khoros.Album

method), 104get_albums_for_user() (khoros.Khoros.Album

method), 41get_avatar_url() (in module

khoros.structures.nodes), 317get_avatar_url() (khoros.core.Khoros.Node method),

133get_avatar_url() (khoros.Khoros.Node method), 65get_board_id() (in module khoros.structures.boards),

296get_board_id() (khoros.core.Khoros.Board static

method), 109get_board_id() (khoros.Khoros.Board static method),

45get_category_details() (in module

khoros.structures.categories), 300get_category_details()


get_category_details() (khoros.Khoros.Categorymethod), 47

get_category_field() (in modulekhoros.structures.categories), 300

get_category_field() (khoros.core.Khoros.Categorymethod), 112

get_category_field() (khoros.Khoros.Categorymethod), 47

get_category_id() (in modulekhoros.structures.categories), 300

get_category_id() (khoros.core.Khoros.Categorystatic method), 112

get_category_id() (khoros.Khoros.Category staticmethod), 48

get_community_details() (in modulekhoros.structures.communities), 307

get_community_details()(khoros.core.Khoros.Community method),119

get_community_details()(khoros.Khoros.Community method), 53

get_community_field() (in modulekhoros.structures.communities), 308

get_community_field()(khoros.core.Khoros.Community method),

Index 435


119get_community_field() (khoros.Khoros.Community

method), 53get_content_test_data() (in module

khoros.utils.tests.test_mentions), 350get_control_data() (in module

khoros.utils.tests.test_messages), 352get_creation_date() (in module

khoros.structures.categories), 301get_creation_date() (in module

khoros.structures.communities), 308get_creation_date() (in module

khoros.structures.nodes), 318get_creation_date() (khoros.core.Khoros.Category

method), 112get_creation_date()


get_creation_date() (khoros.core.Khoros.Nodemethod), 133

get_creation_date() (khoros.Khoros.Categorymethod), 48

get_creation_date() (khoros.Khoros.Communitymethod), 53

get_creation_date() (khoros.Khoros.Node method),66

get_date_pattern() (in modulekhoros.structures.communities), 308

get_date_pattern() (khoros.core.Khoros.Communitymethod), 119

get_date_pattern() (khoros.Khoros.Communitymethod), 53

get_depth() (in module khoros.structures.categories),301

get_depth() (in module khoros.structures.nodes), 318get_depth() (khoros.core.Khoros.Category method),

113get_depth() (khoros.core.Khoros.Node method), 134get_depth() (khoros.Khoros.Category method), 48get_depth() (khoros.Khoros.Node method), 66get_description() (in module

khoros.structures.categories), 301get_description() (in module

khoros.structures.communities), 308get_description() (in module

khoros.structures.nodes), 318get_description() (khoros.core.Khoros.Category

method), 113get_description() (khoros.core.Khoros.Community

method), 119get_description() (khoros.core.Khoros.Node

method), 134get_description() (khoros.Khoros.Category

method), 48

get_description() (khoros.Khoros.Communitymethod), 54

get_description() (khoros.Khoros.Node method), 67get_details() (in module khoros.structures.base), 291get_dict_for_required_fields() (in module

khoros.utils.tests.test_board_creation), 344get_discussion_style() (in module

khoros.structures.nodes), 319get_discussion_style() (khoros.core.Khoros.Node

method), 134get_discussion_style() (khoros.Khoros.Node

method), 67get_email() (in module khoros.objects.users), 277get_email() (khoros.core.Khoros.User method), 151get_email() (khoros.Khoros.User method), 84get_env_variables() (in module

khoros.utils.environment), 339get_error_from_html() (in module

khoros.errors.handlers), 331get_error_from_json() (in module

khoros.errors.handlers), 331get_error_from_xml() (in module

khoros.errors.handlers), 332get_file_type() (in module khoros.utils.core_utils),

337get_file_upload_info() (in module

khoros.objects.attachments), 254get_followers_count() (in module

khoros.objects.users), 278get_followers_count() (khoros.core.Khoros.User

method), 151get_followers_count() (khoros.Khoros.User

method), 84get_following_count() (in module

khoros.objects.users), 278get_following_count() (khoros.core.Khoros.User

method), 152get_following_count() (khoros.Khoros.User

method), 84get_friendly_date_max_age() (in module

khoros.structures.categories), 302get_friendly_date_max_age() (in module

khoros.structures.communities), 309get_friendly_date_max_age()


get_friendly_date_max_age()(khoros.core.Khoros.Community method),120

get_friendly_date_max_age()(khoros.Khoros.Category method), 49

get_friendly_date_max_age()(khoros.Khoros.Community method), 54

get_full_version() (in module khoros.utils.version),

436 Index


341get_grouphub_id() (in module

khoros.structures.grouphubs), 314get_helper_path() (in module

khoros.utils.tests.test_helper_file), 347get_helper_settings() (in module

khoros.utils.helper), 340get_id_from_url() (in module

khoros.objects.messages), 261get_ids_from_login_list() (in module

khoros.objects.users), 278get_ids_from_login_list()

(khoros.core.Khoros.User method), 152get_ids_from_login_list() (khoros.Khoros.User

method), 85get_images_count() (in module khoros.objects.users),

279get_images_count() (khoros.core.Khoros.User

method), 152get_images_count() (khoros.Khoros.User method), 85get_items_list() (in module khoros.api), 233get_kudos_given_count() (in module

khoros.objects.users), 279get_kudos_given_count() (khoros.core.Khoros.User

method), 152get_kudos_given_count() (khoros.Khoros.User

method), 85get_kudos_received_count() (in module

khoros.objects.users), 279get_kudos_received_count()

(khoros.core.Khoros.User method), 153get_kudos_received_count() (khoros.Khoros.User

method), 85get_language() (in module

khoros.structures.categories), 302get_language() (in module

khoros.structures.communities), 309get_language() (khoros.core.Khoros.Category

method), 114get_language() (khoros.core.Khoros.Community

method), 120get_language() (khoros.Khoros.Category method), 49get_language() (khoros.Khoros.Community method),

54get_last_visit_timestamp() (in module

khoros.objects.users), 280get_last_visit_timestamp()

(khoros.core.Khoros.User method), 153get_last_visit_timestamp() (khoros.Khoros.User

method), 86get_latest_stable() (in module khoros.utils.version),

341get_list_items() (in module

khoros.objects.attachments), 254

get_login() (in module khoros.objects.users), 280get_login() (khoros.core.Khoros.User method), 153get_login() (khoros.Khoros.User method), 86get_major_minor_version() (in module

khoros.utils.version), 341get_max_attachments() (in module

khoros.structures.communities), 309get_max_attachments()


get_max_attachments() (khoros.Khoros.Communitymethod), 54

get_messages_count() (in modulekhoros.objects.users), 280

get_messages_count() (khoros.core.Khoros.Usermethod), 153

get_messages_count() (khoros.Khoros.User method),86

get_metadata() (in module khoros.objects.messages),261

get_metadata() (khoros.core.Khoros.Messagemethod), 129

get_metadata() (khoros.Khoros.Message method), 62get_node_details() (in module

khoros.structures.nodes), 319get_node_details() (khoros.core.Khoros.Node

method), 135get_node_details() (khoros.Khoros.Node method),

67get_node_field() (in module

khoros.structures.nodes), 319get_node_field() (khoros.core.Khoros.Node method),

135get_node_field() (khoros.Khoros.Node method), 67get_node_id() (in module khoros.objects.base), 248get_node_id() (in module khoros.structures.nodes),

320get_node_id() (khoros.core.Khoros.Node static

method), 135get_node_id() (khoros.Khoros.Node static method), 68get_node_setting() (in module

khoros.objects.settings), 270get_node_setting() (khoros.core.Khoros.Settings

method), 144get_node_setting() (khoros.Khoros.Settings method),

77get_node_type_from_url() (in module

khoros.objects.base), 248get_node_type_from_url() (in module

khoros.structures.nodes), 320get_node_type_from_url()

(khoros.core.Khoros.Node static method),135

get_node_type_from_url() (khoros.Khoros.Node

Index 437


static method), 68get_node_version() (in module khoros.studio.base),

325get_node_version() (khoros.core.Khoros.Studio static

method), 145get_node_version() (khoros.Khoros.Studio static

method), 77get_npm_version() (in module khoros.studio.base),

325get_npm_version() (khoros.core.Khoros.Studio static

method), 145get_npm_version() (khoros.Khoros.Studio static

method), 77get_oauth_authorization_url() (in module

khoros.auth), 241get_oauth_callback_url_from_user() (in module

khoros.auth), 242get_online_user_count() (in module

khoros.objects.users), 280get_online_user_count() (khoros.core.Khoros.User

method), 154get_online_user_count() (khoros.Khoros.User

method), 86get_ooyala_player_branding_id() (in module

khoros.structures.communities), 309get_ooyala_player_branding_id()


get_ooyala_player_branding_id()(khoros.Khoros.Community method), 54

get_parent_id() (in modulekhoros.structures.categories), 302

get_parent_id() (in module khoros.structures.nodes),320

get_parent_id() (khoros.core.Khoros.Categorymethod), 114

get_parent_id() (khoros.core.Khoros.Node method),136

get_parent_id() (khoros.Khoros.Category method),49

get_parent_id() (khoros.Khoros.Node method), 68get_parent_type() (in module

khoros.structures.categories), 303get_parent_type() (in module

khoros.structures.nodes), 321get_parent_type() (khoros.core.Khoros.Category

method), 114get_parent_type() (khoros.core.Khoros.Node

method), 136get_parent_type() (khoros.Khoros.Category

method), 49get_parent_type() (khoros.Khoros.Node method), 69get_parent_url() (in module

khoros.structures.categories), 303

get_parent_url() (in modulekhoros.structures.nodes), 321

get_parent_url() (khoros.core.Khoros.Categorymethod), 115

get_parent_url() (khoros.core.Khoros.Node method),136

get_parent_url() (khoros.Khoros.Category method),50

get_parent_url() (khoros.Khoros.Node method), 69get_permitted_attachment_types() (in module

khoros.structures.communities), 310get_permitted_attachment_types()


get_permitted_attachment_types()(khoros.Khoros.Community method), 54

get_platform_version() (in module khoros.api), 233get_platform_version() (khoros.core.Khoros

method), 165get_platform_version() (khoros.Khoros method), 97get_position() (in module

khoros.structures.categories), 303get_position() (in module khoros.structures.nodes),

321get_position() (khoros.core.Khoros.Category

method), 115get_position() (khoros.core.Khoros.Node method),

137get_position() (khoros.Khoros.Category method), 50get_position() (khoros.Khoros.Node method), 69get_primary_url() (in module

khoros.structures.communities), 310get_primary_url() (khoros.core.Khoros.Community

method), 120get_primary_url() (khoros.Khoros.Community

method), 55get_public_images_count() (in module

khoros.objects.users), 280get_public_images_count()

(khoros.core.Khoros.User method), 154get_public_images_count() (khoros.Khoros.User

method), 86get_query_url() (in module khoros.liql), 244get_random_string() (in module

khoros.utils.core_utils), 337get_registration_data() (in module

khoros.objects.users), 281get_registration_data() (khoros.core.Khoros.User

method), 154get_registration_data() (khoros.Khoros.User

method), 87get_registration_status() (in module

khoros.objects.users), 281get_registration_status()

438 Index


(khoros.core.Khoros.User method), 154get_registration_status() (khoros.Khoros.User

method), 87get_registration_timestamp() (in module

khoros.objects.users), 281get_registration_timestamp()

(khoros.core.Khoros.User method), 155get_registration_timestamp()

(khoros.Khoros.User method), 87get_replies_count() (in module

khoros.objects.users), 282get_replies_count() (khoros.core.Khoros.User

method), 155get_replies_count() (khoros.Khoros.User method),

87get_request_with_retries() (in module

khoros.api), 233get_required_fields() (in module

khoros.utils.tests.test_board_creation), 344get_results_count() (in module khoros.api), 234get_returned_items() (in module khoros.liql), 244get_role_id() (in module khoros.objects.roles), 266get_role_id() (khoros.core.Khoros.Role static

method), 141get_role_id() (khoros.Khoros.Role static method), 73get_roles_count() (in module khoros.objects.users),

282get_roles_count() (khoros.core.Khoros.User

method), 155get_roles_count() (khoros.Khoros.User method), 88get_roles_for_user() (in module

khoros.objects.roles), 266get_roles_for_user() (khoros.core.Khoros.Role

method), 141get_roles_for_user() (khoros.Khoros.Role method),

73get_root_id() (in module

khoros.structures.categories), 304get_root_id() (in module khoros.structures.nodes),

321get_root_id() (khoros.core.Khoros.Category method),

115get_root_id() (khoros.core.Khoros.Node method), 137get_root_id() (khoros.Khoros.Category method), 50get_root_id() (khoros.Khoros.Node method), 69get_root_type() (in module

khoros.structures.categories), 304get_root_type() (in module khoros.structures.nodes),

322get_root_type() (khoros.core.Khoros.Category

method), 116get_root_type() (khoros.core.Khoros.Node method),

137get_root_type() (khoros.Khoros.Category method),

50get_root_type() (khoros.Khoros.Node method), 70get_root_url() (in module

khoros.structures.categories), 304get_root_url() (in module khoros.structures.nodes),

322get_root_url() (khoros.core.Khoros.Category

method), 116get_root_url() (khoros.core.Khoros.Node method),

138get_root_url() (khoros.Khoros.Category method), 51get_root_url() (khoros.Khoros.Node method), 70get_sdk_version() (in module khoros.studio.base),

325get_sdk_version() (khoros.core.Khoros.Studio static

method), 145get_sdk_version() (khoros.Khoros.Studio static

method), 78get_session_header() (in module khoros.auth), 242get_session_key() (in module khoros.auth), 242get_session_key() (khoros.core.Khoros method), 165get_session_key() (khoros.Khoros method), 98get_sign_out_url() (in module

khoros.structures.communities), 310get_sign_out_url() (khoros.core.Khoros.Community

method), 121get_sign_out_url() (khoros.Khoros.Community

method), 55get_solutions_authored_count() (in module

khoros.objects.users), 282get_solutions_authored_count()

(khoros.core.Khoros.User method), 155get_solutions_authored_count()

(khoros.Khoros.User method), 88get_sso_key() (in module khoros.auth), 242get_structure_collection() (in module

khoros.utils.tests.resources), 343get_structure_control_data() (in module

khoros.utils.tests.test_tags), 355get_structure_field() (in module

khoros.structures.base), 291get_structure_id() (in module

khoros.structures.base), 292get_structure_type_from_url() (in module

khoros.structures.base), 292get_subscription_uri() (in module

khoros.objects.subscriptions), 271get_subscription_uri()

(khoros.core.Khoros.Subscription method),146

get_subscription_uri()(khoros.Khoros.Subscription method), 79

get_tags_for_message() (in modulekhoros.objects.tags), 274

Index 439


get_tags_for_message() (khoros.core.Khoros.Tagmethod), 149

get_tags_for_message() (khoros.Khoros.Tagmethod), 81

get_tenant_id() (in modulekhoros.structures.communities), 310

get_tenant_id() (khoros.core.Khoros.Communitymethod), 121

get_tenant_id() (khoros.Khoros.Community method),55

get_test_data() (in modulekhoros.utils.tests.test_node_id_extract), 353

get_testing_config() (in modulekhoros.utils.tests.resources), 343

get_title() (in module khoros.structures.categories),305

get_title() (in modulekhoros.structures.communities), 311

get_title() (in module khoros.structures.nodes), 322get_title() (khoros.core.Khoros.Category method),

116get_title() (khoros.core.Khoros.Community method),

121get_title() (khoros.core.Khoros.Node method), 138get_title() (khoros.Khoros.Category method), 51get_title() (khoros.Khoros.Community method), 55get_title() (khoros.Khoros.Node method), 70get_topics_count() (in module khoros.objects.users),

283get_topics_count() (khoros.core.Khoros.User

method), 156get_topics_count() (khoros.Khoros.User method), 88get_total_category_count() (in module

khoros.structures.categories), 305get_total_category_count()


get_total_category_count()(khoros.Khoros.Category method), 51

get_total_count() (in module khoros.liql), 244get_total_count() (in module

khoros.structures.categories), 305get_total_count() (in module

khoros.structures.grouphubs), 314get_total_count() (khoros.core.Khoros method), 166get_total_count() (khoros.core.Khoros.Category

method), 117get_total_count() (khoros.core.Khoros.GroupHub

method), 124get_total_count() (khoros.Khoros method), 98get_total_count() (khoros.Khoros.Category

method), 51get_total_count() (khoros.Khoros.GroupHub

method), 57

get_total_node_count() (in modulekhoros.structures.nodes), 323

get_total_node_count() (khoros.core.Khoros.Nodemethod), 138

get_total_node_count() (khoros.Khoros.Nodemethod), 71

get_total_role_count() (in modulekhoros.objects.roles), 267

get_total_role_count() (khoros.core.Khoros.Rolemethod), 141

get_total_role_count() (khoros.Khoros.Rolemethod), 74

get_type() (in module khoros.structures.nodes), 323get_type() (khoros.core.Khoros.Node method), 138get_type() (khoros.Khoros.Node method), 71get_url() (in module khoros.structures.categories), 305get_url() (in module khoros.structures.nodes), 323get_url() (khoros.core.Khoros.Category method), 117get_url() (khoros.core.Khoros.Node method), 139get_url() (khoros.Khoros.Category method), 52get_url() (khoros.Khoros.Node method), 71get_user_data() (in module khoros.objects.users), 283get_user_data() (khoros.core.Khoros.User method),

156get_user_data() (khoros.Khoros.User method), 88get_user_data_with_v1() (in module

khoros.objects.users), 283get_user_id() (in module khoros.objects.users), 283get_user_id() (khoros.core.Khoros.User method), 156get_user_id() (khoros.Khoros.User method), 89get_user_test_data() (in module

khoros.utils.tests.test_mentions), 350get_username() (in module khoros.objects.users), 284get_username() (khoros.core.Khoros.User method),

157get_username() (khoros.Khoros.User method), 89get_users_with_role() (in module

khoros.objects.roles), 267get_users_with_role() (khoros.core.Khoros.Role

method), 142get_users_with_role() (khoros.Khoros.Role

method), 74get_v1_node_collection() (in module khoros.api),

234get_v1_user_path() (in module khoros.api), 234get_videos_count() (in module khoros.objects.users),

285get_videos_count() (khoros.core.Khoros.User

method), 157get_videos_count() (khoros.Khoros.User method), 90get_views() (in module khoros.structures.categories),

306get_views() (in module khoros.structures.nodes), 324get_views() (khoros.core.Khoros.Category method),

440 Index


117get_views() (khoros.core.Khoros.Node method), 139get_views() (khoros.Khoros.Category method), 52get_views() (khoros.Khoros.Node method), 72GETRequestError, 328grouphub_exists() (in module

khoros.structures.grouphubs), 314grouphub_exists() (khoros.core.Khoros.GroupHub

method), 124grouphub_exists() (khoros.Khoros.GroupHub

method), 57

HHelperFunctionNotFoundError, 328HelperParsing (class in khoros.utils.helper), 340

Iimpersonate_user() (in module khoros.objects.users),

285impersonate_user() (khoros.core.Khoros.User

method), 157impersonate_user() (khoros.Khoros.User method), 90ImpersonatedUser (class in khoros.objects.users), 276import_assertion() (in module khoros.saml), 289import_assertion() (khoros.core.Khoros.SAML static

method), 143import_assertion() (khoros.Khoros.SAML static

method), 75import_core_utils() (in module

khoros.utils.tests.test_core_utils), 345import_helper_file() (in module

khoros.utils.helper), 340import_modules() (in module

khoros.utils.tests.resources), 343import_pkg_operation() (in module

khoros.utils.tests.test_library_import), 348initialize_khoros_object() (in module

khoros.utils.tests.resources), 343instantiate_with_local_helper() (in module

khoros.utils.tests.resources), 343invalidate_session() (in module khoros.auth), 242InvalidCallbackURLError, 328InvalidEndpointError, 328InvalidFieldError, 328InvalidHelperArgumentsError, 329InvalidHelperFileTypeError, 329InvalidLookupTypeError, 329InvalidMessagePayloadError, 329InvalidMetadataError, 329InvalidNodeTypeError, 329InvalidOperatorError, 329InvalidPayloadValueError, 329InvalidRequestTypeError, 329InvalidRoleError, 329

InvalidRoleTypeError, 329InvalidStructureTypeError, 329InvalidURLError, 329is_category_url() (in module

khoros.structures.base), 292is_hidden() (in module khoros.structures.categories),

306is_hidden() (in module khoros.structures.nodes), 324is_hidden() (khoros.core.Khoros.Category method),

118is_hidden() (khoros.core.Khoros.Node method), 139is_hidden() (khoros.Khoros.Category method), 52is_hidden() (khoros.Khoros.Node method), 72is_iterable() (in module khoros.utils.core_utils), 337is_node_url() (in module khoros.structures.base), 292is_numeric() (in module khoros.utils.core_utils), 337is_read_only() (in module khoros.objects.messages),

261

Kkhoros

module, 40Khoros (class in khoros), 40Khoros (class in khoros.core), 103Khoros.Album (class in khoros), 40Khoros.Album (class in khoros.core), 103khoros.api

module, 229Khoros.Archives (class in khoros), 41Khoros.Archives (class in khoros.core), 104khoros.auth

module, 241Khoros.Board (class in khoros), 43Khoros.Board (class in khoros.core), 106Khoros.Category (class in khoros), 46Khoros.Category (class in khoros.core), 110Khoros.Community (class in khoros), 52Khoros.Community (class in khoros.core), 118khoros.core

module, 103khoros.errors

module, 327khoros.errors.exceptions

module, 328khoros.errors.handlers

module, 331khoros.errors.translations

module, 333Khoros.GroupHub (class in khoros), 56Khoros.GroupHub (class in khoros.core), 122khoros.liql

module, 243Khoros.Message (class in khoros), 59Khoros.Message (class in khoros.core), 126

Index 441


Khoros.Node (class in khoros), 65Khoros.Node (class in khoros.core), 133khoros.objects

module, 247khoros.objects.albums

module, 249khoros.objects.archives

module, 250khoros.objects.attachments

module, 253khoros.objects.base

module, 248khoros.objects.labels

module, 255khoros.objects.messages

module, 255khoros.objects.roles

module, 265khoros.objects.settings

module, 269khoros.objects.subscriptions

module, 270khoros.objects.tags

module, 274khoros.objects.users

module, 276Khoros.Role (class in khoros), 72Khoros.Role (class in khoros.core), 140khoros.saml

module, 289Khoros.SAML (class in khoros), 75Khoros.SAML (class in khoros.core), 143Khoros.Settings (class in khoros), 76Khoros.Settings (class in khoros.core), 143khoros.structures

module, 290khoros.structures.base

module, 291khoros.structures.boards

module, 294khoros.structures.categories

module, 298khoros.structures.communities

module, 307khoros.structures.grouphubs

module, 312khoros.structures.nodes

module, 317khoros.studio

module, 325Khoros.Studio (class in khoros), 77Khoros.Studio (class in khoros.core), 145khoros.studio.base

module, 325

Khoros.Subscription (class in khoros), 78Khoros.Subscription (class in khoros.core), 145Khoros.Tag (class in khoros), 81Khoros.Tag (class in khoros.core), 148Khoros.User (class in khoros), 82Khoros.User (class in khoros.core), 150khoros.utils.core_utils

module, 334khoros.utils.environment

module, 339khoros.utils.helper

module, 340khoros.utils.log_utils

module, 339khoros.utils.tests

module, 342khoros.utils.tests.resources

module, 343khoros.utils.tests.test_board_creation

module, 344khoros.utils.tests.test_core_utils

module, 345khoros.utils.tests.test_grouphub_creation

module, 346khoros.utils.tests.test_helper_file

module, 347khoros.utils.tests.test_http_headers

module, 347khoros.utils.tests.test_library_import

module, 348khoros.utils.tests.test_liql

module, 348khoros.utils.tests.test_mentions

module, 349khoros.utils.tests.test_messages

module, 352khoros.utils.tests.test_node_id_extract

module, 353khoros.utils.tests.test_settings

module, 354khoros.utils.tests.test_tags

module, 355khoros.utils.version

module, 341Khoros.V1 (class in khoros), 91Khoros.V1 (class in khoros.core), 158Khoros.V2 (class in khoros), 93Khoros.V2 (class in khoros.core), 161KhorosError, 329

Llatest_version() (in module khoros.utils.version),

341LessThanFilter (class in khoros.utils.log_utils), 339

442 Index


limit_to_first_child() (in modulekhoros.structures.base), 293

LiQLParseError, 329LiQLSyntax (class in khoros.liql), 243local_helper_exists() (in module

khoros.utils.tests.resources), 343local_test_config_exists() (in module

khoros.utils.tests.resources), 344log_current_version() (in module

khoros.utils.version), 342LookupMismatchError, 329

Mmake_v1_request() (in module khoros.api), 235Mapping (class in khoros.objects.base), 248Mapping (class in khoros.structures.base), 291Mapping (class in khoros.structures.nodes), 317merge_and_dedup() (in module khoros.utils.core_utils),

337MessageTypeNotFoundError, 330MissingAuthDataError, 330MissingRequiredDataError, 330module

khoros, 40khoros.api, 229khoros.auth, 241khoros.core, 103khoros.errors, 327khoros.errors.exceptions, 328khoros.errors.handlers, 331khoros.errors.translations, 333khoros.liql, 243khoros.objects, 247khoros.objects.albums, 249khoros.objects.archives, 250khoros.objects.attachments, 253khoros.objects.base, 248khoros.objects.labels, 255khoros.objects.messages, 255khoros.objects.roles, 265khoros.objects.settings, 269khoros.objects.subscriptions, 270khoros.objects.tags, 274khoros.objects.users, 276khoros.saml, 289khoros.structures, 290khoros.structures.base, 291khoros.structures.boards, 294khoros.structures.categories, 298khoros.structures.communities, 307khoros.structures.grouphubs, 312khoros.structures.nodes, 317khoros.studio, 325khoros.studio.base, 325

khoros.utils.core_utils, 334khoros.utils.environment, 339khoros.utils.helper, 340khoros.utils.log_utils, 339khoros.utils.tests, 342khoros.utils.tests.resources, 343khoros.utils.tests.test_board_creation,

344khoros.utils.tests.test_core_utils, 345khoros.utils.tests.test_grouphub_creation,

346khoros.utils.tests.test_helper_file, 347khoros.utils.tests.test_http_headers, 347khoros.utils.tests.test_library_import,

348khoros.utils.tests.test_liql, 348khoros.utils.tests.test_mentions, 349khoros.utils.tests.test_messages, 352khoros.utils.tests.test_node_id_extract,

353khoros.utils.tests.test_settings, 354khoros.utils.tests.test_tags, 355khoros.utils.version, 341

Nnode_exists() (in module khoros.structures.nodes),

324node_exists() (khoros.core.Khoros.Node method), 140node_exists() (khoros.Khoros.Node method), 72node_installed() (in module khoros.studio.base), 325node_installed() (khoros.core.Khoros.Studio static

method), 145node_installed() (khoros.Khoros.Studio static

method), 78NodeIDNotFoundError, 330NodeTypeNotFoundError, 330NotFoundResponseError, 330npm_installed() (in module khoros.studio.base), 326npm_installed() (khoros.core.Khoros.Studio static

method), 145npm_installed() (khoros.Khoros.Studio static

method), 78

OOperatorMismatchError, 330

Pparse_message() (in module

khoros.errors.translations), 333parse_query_elements() (in module khoros.liql), 245parse_select_fields() (in module khoros.liql), 245parse_testing_config_file() (in module

khoros.utils.tests.resources), 344parse_v2_response() (in module khoros.api), 236

Index 443


parse_v2_response() (in modulekhoros.objects.messages), 262

parse_v2_response() (khoros.core.Khoros staticmethod), 166

parse_v2_response() (khoros.core.Khoros.Messagestatic method), 129

parse_v2_response() (khoros.Khoros static method),99

parse_v2_response() (khoros.Khoros.Message staticmethod), 62

parse_where_clause() (in module khoros.liql), 245parse_where_clauses() (in module

khoros.utils.tests.test_liql), 348payload_request_with_retries() (in module

khoros.api), 237PayloadMismatchError, 330perform_query() (in module khoros.liql), 246perform_test_query() (in module

khoros.utils.tests.test_liql), 349perform_v1_search() (in module khoros.api), 238perform_v1_search() (khoros.core.Khoros method),

166perform_v1_search() (khoros.Khoros method), 99post() (khoros.core.Khoros method), 167post() (khoros.core.Khoros.V1 method), 159post() (khoros.core.Khoros.V2 method), 161post() (khoros.Khoros method), 99post() (khoros.Khoros.V1 method), 91post() (khoros.Khoros.V2 method), 94post_request_with_retries() (in module

khoros.api), 238POSTRequestError, 330process_user_settings() (in module

khoros.objects.users), 285put() (khoros.core.Khoros method), 168put() (khoros.core.Khoros.V1 method), 159put() (khoros.core.Khoros.V2 method), 162put() (khoros.Khoros method), 100put() (khoros.Khoros.V1 method), 92put() (khoros.Khoros.V2 method), 95put_request_with_retries() (in module

khoros.api), 240PUTRequestError, 330

Qquery() (khoros.core.Khoros method), 169query() (khoros.Khoros method), 101query_successful() (in module khoros.api), 241query_users_table_by_id() (in module

khoros.objects.users), 287query_users_table_by_id()

(khoros.core.Khoros.User method), 158query_users_table_by_id() (khoros.Khoros.User

method), 90

Rrefresh_enabled_discussion_styles() (in module

khoros.structures.grouphubs), 315remove_tld() (in module khoros.utils.core_utils), 337run_cmd() (in module khoros.utils.core_utils), 337

Ssdk_installed() (in module khoros.studio.base), 326sdk_installed() (khoros.core.Khoros.Studio static

method), 145sdk_installed() (khoros.Khoros.Studio static

method), 78search() (khoros.core.Khoros method), 169search() (khoros.core.Khoros.V1 method), 160search() (khoros.Khoros method), 102search() (khoros.Khoros.V1 method), 93send_assertion() (in module khoros.saml), 290send_assertion() (khoros.core.Khoros.SAML

method), 143send_assertion() (khoros.Khoros.SAML method), 76SessionAuthenticationError, 330set_package_path() (in module

khoros.utils.tests.resources), 344set_package_path() (in module

khoros.utils.tests.test_core_utils), 345set_package_path() (in module

khoros.utils.tests.test_helper_file), 347set_package_path() (in module

khoros.utils.tests.test_library_import), 348set_package_path() (in module

khoros.utils.tests.test_liql), 349set_package_path() (in module

khoros.utils.tests.test_mentions), 350set_package_path() (in module

khoros.utils.tests.test_node_id_extract), 353set_package_path() (in module

khoros.utils.tests.test_settings), 354set_read_only() (in module khoros.objects.messages),

262should_verify_tls() (in module khoros.api), 241show_breadcrumb_at_top_level() (in module

khoros.structures.communities), 311show_breadcrumb_at_top_level()


show_breadcrumb_at_top_level()(khoros.Khoros.Community method), 55

show_community_node_in_breadcrumb() (in modulekhoros.structures.communities), 311

show_community_node_in_breadcrumb()(khoros.core.Khoros.Community method),121

show_community_node_in_breadcrumb()(khoros.Khoros.Community method), 55

444 Index


signout() (khoros.core.Khoros method), 170signout() (khoros.Khoros method), 103SsoAuthenticationError, 330structure_archive_payload() (in module

khoros.objects.archives), 252structure_cursor_clause() (in module khoros.liql),

247structure_exists() (in module

khoros.structures.base), 293structure_payload() (in module

khoros.objects.users), 288structure_payload() (in module

khoros.structures.boards), 296structure_payload() (in module

khoros.structures.grouphubs), 315structure_payload() (khoros.core.Khoros.Board

method), 109structure_payload() (khoros.core.Khoros.GroupHub

method), 124structure_payload() (khoros.Khoros.Board method),

45structure_payload() (khoros.Khoros.GroupHub

method), 57structure_single_tag_payload() (in module

khoros.objects.tags), 275structure_single_tag_payload()

(khoros.core.Khoros.Tag static method),149

structure_single_tag_payload()(khoros.Khoros.Tag static method), 82

structure_tags_for_message() (in modulekhoros.objects.tags), 275

structure_tags_for_message()(khoros.core.Khoros.Tag method), 149

structure_tags_for_message() (khoros.Khoros.Tagmethod), 82

structure_user_dict_list() (in modulekhoros.objects.users), 288

subscribe_to_board() (in modulekhoros.objects.subscriptions), 271

subscribe_to_board()(khoros.core.Khoros.Subscription method),146

subscribe_to_board() (khoros.Khoros.Subscriptionmethod), 79

subscribe_to_category() (in modulekhoros.objects.subscriptions), 272

subscribe_to_category()(khoros.core.Khoros.Subscription method),147

subscribe_to_category()(khoros.Khoros.Subscription method), 79

subscribe_to_label() (in modulekhoros.objects.subscriptions), 272

subscribe_to_label()(khoros.core.Khoros.Subscription method),147

subscribe_to_label() (khoros.Khoros.Subscriptionmethod), 80

subscribe_to_message() (in modulekhoros.objects.subscriptions), 273

subscribe_to_message()(khoros.core.Khoros.Subscription method),147

subscribe_to_message()(khoros.Khoros.Subscription method), 80

subscribe_to_product() (in modulekhoros.objects.subscriptions), 273

subscribe_to_product()(khoros.core.Khoros.Subscription method),148

subscribe_to_product()(khoros.Khoros.Subscription method), 80

Ttest_bad_content_url() (in module

khoros.utils.tests.test_mentions), 350test_construct_only_subject() (in module

khoros.utils.tests.test_messages), 352test_construct_with_body() (in module

khoros.utils.tests.test_messages), 352test_construct_with_node() (in module

khoros.utils.tests.test_messages), 353test_construct_with_node_id() (in module

khoros.utils.tests.test_messages), 353test_construct_with_node_url() (in module

khoros.utils.tests.test_messages), 353test_construct_with_one_int_tag() (in module

khoros.utils.tests.test_messages), 353test_construct_with_one_str_tag() (in module

khoros.utils.tests.test_messages), 353test_construct_with_str_iter_int_tags() (in

module khoros.utils.tests.test_messages), 353test_construct_with_str_iter_int_tags_ignore()

(in module khoros.utils.tests.test_messages),353

test_construct_with_tag_iterables() (in modulekhoros.utils.tests.test_messages), 353

test_content_mention_with_all_arguments() (inmodule khoros.utils.tests.test_mentions), 350

test_content_mention_with_false_id_arg() (inmodule khoros.utils.tests.test_mentions), 350

test_content_mention_with_false_id_dict() (inmodule khoros.utils.tests.test_mentions), 350

test_content_mention_with_full_dict() (in mod-ule khoros.utils.tests.test_mentions), 350

test_content_mention_with_no_id_arg() (in mod-ule khoros.utils.tests.test_mentions), 351

Index 445


test_content_mention_with_no_id_dict() (inmodule khoros.utils.tests.test_mentions), 351

test_convert_set() (in modulekhoros.utils.tests.test_core_utils), 345

test_description() (in modulekhoros.utils.tests.test_board_creation), 345

test_invalid_board_type() (in modulekhoros.utils.tests.test_board_creation), 345

test_invalid_node_type_exception() (in modulekhoros.utils.tests.test_settings), 354

test_library_import() (in modulekhoros.utils.tests.test_library_import), 348

test_liql_query() (in modulekhoros.utils.tests.test_liql), 349

test_merge_and_dedup() (in modulekhoros.utils.tests.test_core_utils), 345

test_message_structure_one_string_tag_ignore()(in module khoros.utils.tests.test_tags), 355

test_message_structure_one_tag() (in modulekhoros.utils.tests.test_tags), 355

test_message_structure_str_int() (in modulekhoros.utils.tests.test_tags), 355

test_message_structure_str_int_ignore() (inmodule khoros.utils.tests.test_tags), 355

test_message_structure_two_string_tags_ignore()(in module khoros.utils.tests.test_tags), 355

test_message_structure_two_tags() (in modulekhoros.utils.tests.test_tags), 355

test_no_arguments() (in modulekhoros.utils.tests.test_board_creation), 345

test_no_arguments() (in modulekhoros.utils.tests.test_grouphub_creation),346

test_node_setting_retrieval() (in modulekhoros.utils.tests.test_settings), 354

test_normalize_empty_headers() (in modulekhoros.utils.tests.test_http_headers), 347

test_normalize_headers() (in modulekhoros.utils.tests.test_http_headers), 347

test_normalize_type_error() (in modulekhoros.utils.tests.test_http_headers), 347

test_numeric_eval() (in modulekhoros.utils.tests.test_core_utils), 345

test_only_id() (in modulekhoros.utils.tests.test_grouphub_creation),346

test_payload_validation() (in modulekhoros.utils.tests.test_messages), 353

test_query_string_encoding() (in modulekhoros.utils.tests.test_core_utils), 346

test_relative_content_url_with_object() (inmodule khoros.utils.tests.test_mentions), 351

test_relative_content_url_without_object()(in module khoros.utils.tests.test_mentions),

351test_remove_tld() (in module

khoros.utils.tests.test_core_utils), 346test_required_fields() (in module

khoros.utils.tests.test_board_creation), 345test_return_items_option() (in module

khoros.utils.tests.test_liql), 349test_single_tag_structure() (in module

khoros.utils.tests.test_tags), 355test_url_encoding() (in module

khoros.utils.tests.test_core_utils), 346test_url_without_node() (in module

khoros.utils.tests.test_node_id_extract), 354test_user_mention_with_args_no_object() (in

module khoros.utils.tests.test_mentions), 351test_user_mention_with_arguments() (in module

khoros.utils.tests.test_mentions), 351test_user_mention_with_dict_and_object() (in

module khoros.utils.tests.test_mentions), 351test_user_mention_with_dictionary() (in module

khoros.utils.tests.test_mentions), 351test_user_mention_with_dictionary_no_object()

(in module khoros.utils.tests.test_mentions),352

test_valid_board_types() (in modulekhoros.utils.tests.test_board_creation), 345

test_where_clause_parsing() (in modulekhoros.utils.tests.test_liql), 349

test_with_invalid_node_types() (in modulekhoros.utils.tests.test_node_id_extract), 354

test_with_only_url() (in modulekhoros.utils.tests.test_node_id_extract), 354

test_with_valid_node_types() (in modulekhoros.utils.tests.test_node_id_extract), 354

test_yaml_file() (in modulekhoros.utils.tests.test_helper_file), 347

TooManyResultsError, 330top_level_categories_enabled() (in module

khoros.structures.communities), 312top_level_categories_enabled()


top_level_categories_enabled()(khoros.Khoros.Community method), 56

top_level_categories_on_community_page() (inmodule khoros.structures.communities), 312

top_level_categories_on_community_page()(khoros.core.Khoros.Community method), 122

top_level_categories_on_community_page()(khoros.Khoros.Community method), 56

translate_error() (in modulekhoros.errors.translations), 333

translation_enabled() (in modulekhoros.errors.translations), 333

446 Index


Uunarchive() (in module khoros.objects.archives), 252unarchive() (khoros.core.Khoros.Archives method),

106unarchive() (khoros.Khoros.Archives method), 42UnknownFileTypeError, 330UnsupportedNodeTypeError, 331update() (in module khoros.objects.messages), 262update() (khoros.core.Khoros.Message method), 130update() (khoros.Khoros.Message method), 63update_env_variable_names() (in module

khoros.utils.environment), 340update_sso_id() (in module khoros.objects.users), 288update_sso_id() (khoros.core.Khoros.User method),

158update_sso_id() (khoros.Khoros.User method), 90update_title() (in module

khoros.structures.grouphubs), 316update_title() (khoros.core.Khoros.GroupHub

method), 125update_title() (khoros.Khoros.GroupHub method),

58url_decode() (in module khoros.utils.core_utils), 338url_encode() (in module khoros.utils.core_utils), 338UserCreationError, 331

Vvalidate_message_payload() (in module

khoros.objects.messages), 265validate_message_payload()

(khoros.core.Khoros.Message static method),132

validate_message_payload()(khoros.Khoros.Message static method),65

verify_core_object_present() (in modulekhoros.errors.handlers), 332

verify_data_fields() (in modulekhoros.utils.tests.test_board_creation), 345

verify_data_fields() (in modulekhoros.utils.tests.test_grouphub_creation),346

verify_structure_type() (in modulekhoros.structures.base), 293

verify_v1_response() (in modulekhoros.errors.handlers), 332

Wwarn_when_not_latest() (in module

khoros.utils.version), 342

Index 447

Documents

Khoros Python Library Documentation