Package: khoros
Python SDK for Khoros CommunitiesThekhoroslibrary acts as a Python software development kit (SDK) to administer and manageKhoros Communities(formerly Lithium) online community platforms.Latest Stable ReleaseLatest Beta/RC ReleaseBuild StatusSupported VersionsCode CoverageCodeFactor GradeDocumentationSecurity AuditsLicenseIssuesPull RequestsInstallationThe package can be installed via pip using the syntax below.pipinstallkhoros--upgradeYou may also clone the repository and install from source using below.gitclonegit://github.com/jeffshurtliff/khoros.gitcdkhoros/
pythonsetup.pyinstallChange LogThe change log can be found in thedocumentation.UsageThis section provides basic usage instructions for the package.Importing the packageRather than importing the base package, it is recommended that you import the primaryKhorosclass using the syntax
below.fromkhorosimportKhorosThis recommendation is because the best practice is to use the namekhoroswhen naming your object instance.Initializing a Khoros object instanceThe primaryKhorosobject serves many purposes, the most important being to establish a connection to the Khoros
Community environment with which you intend to interact. As such, when initializing an instance of theKhorosobject,
you will need to pass it the community URL, the credentials it will use and related information so that the connection
can be established.TheKhorosobject can be initiated in two different ways:Passing the information directly into the objectLeveraging a "helper" configuration filePassing the information directly into the objectThe community and connection information can be passed directly into theKhorosobject when initializing it, as
demonstrated 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 theoptionsargument in theKhorosclass, as
shown below.my_settings={'community_url':'https://community.example.com','community_name':'mycommunity','auth_type':'session_auth','session_auth':{'username':USERNAME,'password':PASSWD}}Leveraging a "helper" configuration fileAs an alternative to passing the connection information to theKhorosclass in the ways demonstrated above, a
"helper" configuration file inyamlorjsonformat can be leveraged instead and passed to theKhorosclass
when 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:yesThe file can then be referenced using thehelperargument when initializing the object instance, as shown below.HELPER_FILE="/path/to/helper.yml"khoros=Khoros(helper=HELPER_FILE)Utilizing environment variablesThis third method of initializing a Khoros object instance is definitely the easiest, as it allows you to call
upon theKhorosclass 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 Python
IDE using theosmodule andadding entriesto theos.environdictionary, as shown below.importosos.environ['KHOROS_URL']='https://community.example.com'Environment VariableDescriptionExampleKHOROS_URLThe base URL of the environmenthttps://community.example.comKHOROS_TENANT_IDTheTenant IDassociated with your environmentabcde12345KHOROS_DEFAULT_AUTHThe default authentication method you wish to usesession_authKHOROS_OAUTH_IDThe Client ID utilized by theOAuth 2.0authorization grant flowFXXXXXXb7owXXXXXXo+jFlPXXXXXXjZcWQXXXXXX6bo=KHOROS_OAUTH_SECRETThe Client Secret utilized by theOAuth 2.0authorization grant flow1XXXXXX+/kZXXXXXXZZ9u1B5+1uXXXXXXfJCeOszYw=KHOROS_OAUTH_REDIRECT_URLThe Redirect URL utilized by theOAuth 2.0authorization grant flowhttp://redirect.community.example.com/getAccessTokenKHOROS_SESSION_USERThe username to use withSession KeyauthenticationapiuserKHOROS_SESSION_PWThe password to use withSession KeyauthenticationCh@ng3M3!KHOROS_PREFER_JSONBoolean string indicating if JSON responses are preferredTrueKHOROS_LIQL_PRETTYBoolean string indicating if reader-friendly formatting should be usedFalseKHOROS_LIQL_TRACK_LSIBoolean string indicating if queries should be captured in Community Analytics search reportsFalseKHOROS_LIQL_ALWAYS_OKBoolean string indicating if all responses should return a200 OKstatus codeFalseKHOROS_TRANSLATE_ERRORSBoolean string indicating if errors in API responses should be made more relevant where possibleTrueIf you are leveraging this library on a macOS or Linux operating system (e.g. Ubuntu Server) then you can simply
add the environment variables you wish to define to either the/etc/environmentfile if you wish to apply
them to all users, or to your user's~/.bashrcfile 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 environment
variables 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
window or using a batch/script file.  (Files should use the.bator.cmdextension for the
Command Prompt and.ps1for PowerShell.)Command Prompt@echooffechoDefining 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")Interacting with the Community APIsOnce theKhorosobject instance has been initialized, it can be leveraged to interact with a Khoros Community
environment in many ways, which is fully documented in the officialdocumentation. The example below demonstrates 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)DocumentationThe documentation is located here:https://khoros.readthedocs.io/en/latest/LicenseMIT LicenseReporting IssuesIssues can be reported within theGitHub repository.RoadmapUpcoming improvements to the library can be found in the following locations:2020 Roadmap on GitHub2021 Roadmap on GitHub2022 Roadmap on GitHubAdditional ResourcesAdditional resources for leveraging the Community APIs can be found in the officialKhoros Developer Documentation.DonationsIf you would like to donate to this project then you can do so usingthis PayPal link.DisclaimerThis package is considered unofficial and is in no way endorsed or supported byKhoros, LLC.