Repository files navigation

Thekhoros library acts as a Python software development kit (SDK) to administer and manageKhoros Communities (formerly Lithium) online community platforms.

Latest Stable Release
Latest Beta/RC Release
Build Status
Supported Versions
Code Coverage
CodeFactor Grade
Documentation
Security Audits
License
Issues
Pull Requests

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/python setup.py install

The change log can be found in thedocumentation.

This section provides basic usage instructions for the package.

Rather than importing the base package, it is recommended that you import the primaryKhoros class using the syntaxbelow.

fromkhorosimportKhoros

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

The primaryKhoros object serves many purposes, the most important being to establish a connection to the KhorosCommunity environment with which you intend to interact. As such, when initializing an instance of theKhoros object,you will need to pass it the community URL, the credentials it will use and related information so that the connectioncan be established.

TheKhoros object can be initiated in two different ways:

• Passing the information directly into the object
• Leveraging a "helper" configuration file

The community and connection information can be passed directly into theKhoros object when initializing it, asdemonstrated in the example below.

# Using Session Key authenticationkhoros=Khoros(community_url='https://community.example.com',session_auth={'username':USERNAME,'password':PASSWD})# Using LithiumSSO Token authenticationkhoros=Khoros(community_url='https://community.example.com',sso={'sso.authentication_token':LITHIUM_SSO_TOKEN})

Alternatively, configuration settings can be passed at once using theoptions argument in theKhoros class, asshown below.

my_settings= {'community_url':'https://community.example.com','community_name':'mycommunity','auth_type':'session_auth','session_auth': {'username':USERNAME,'password':PASSWD    }}

As an alternative to passing the connection information to theKhoros class in the ways demonstrated above, a"helper" configuration file inyaml orjson format can be leveraged instead and passed to theKhoros 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!# Bulk Data API connection informationbulk_data:community_id:example.prodclient_id:ay0CXXXXXXXXXX/XXXX+XXXXXXXXXXXXX/XXXXX4KhQ=token:2f25XXXXXXXXXXXXXXXXXXXXXXXXXa10dec04068europe:no# Define the preferred format for API responsesprefer_json:yes

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

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

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

fromkhorosimportKhoroskhoros=Khoros()

This is accomplished by defining environment variables within your Operating System, either through thegraphical UI, the command-line or within the PythonIDE using theos module andadding entries to theos.environ dictionary, as shown below.

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

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

# 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 terminalwindow or using a batch/script file. (Files should use the.bat or.cmd extension for theCommand Prompt and.ps1 for PowerShell.)

Command Prompt

@echooffecho 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")

Once theKhoros object instance has been initialized, it can be leveraged to interact with a Khoros Communityenvironment in many ways, which is fully documented in the officialdocumentation. The example below demonstrates how a search can beperformed 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)

The documentation is located here:https://khoros.readthedocs.io/en/latest/

MIT License

Issues can be reported within theGitHub repository.

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

• 2020 Roadmap on GitHub
• 2021 Roadmap on GitHub
• 2022 Roadmap on GitHub

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

If you would like to donate to this project then you can do so usingthis PayPal link.

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