Automatic Rate-Limit Handling!

If you have sent a few too many messages (actually usually a lot of messages) in a short period of time, you may receive a 429 response from Cisco Spark (which the ciscosparkapi package raises as a Python exception). While you can catch and handle these exceptions yourself... Why don't we just do that for you? 😎

Experience with the New Rate-Limit Handling

Now, when a rate-limit message is received in response to one of your requests, the ciscosparkapi package will automatically:

1. Catch the exception
2. Wait / sleep for the time interval provided by Cisco Spark
3. Automatically retry your request

All of this should be transparent to the execution of your code, and you shouldn't need to make any modifications to your code to take advantage of the new functionality (unless you were already handling rate-limit responses, in which case you should be able to pull out that code and simplify your app 🙂 ).

Experience: Your code should run as expected with the package handling any rate-limit responses that are received. Note that if your requests do trigger a rate-limit response, the wait times prescribed by Cisco Spark usually measure in the minutes (averaging about 5 minutes from my experience). It may appear that your code is running very slowly due to these wait times, but the good news is that your code is running and your requests are being handled as quickly as possible.

Can I disable the automated rate-limit handling?

Absolutely. Should you desire to disable the automatic rate-limit handling, you can do so by setting the wait_on_rate_limit parameter to False when creating your CiscoSparkAPI connection object. Like So:

spark = CiscoSparkAPI(wait_on_rate_limit=False)

New Package Exception | Error

Rate limit messages (if you have disabled the automated handling) are now raised as a more specific SparkRateLimitError instead of the more general SparkApiError. Since SparkRateLimitError is a sub-class of SparkApiError, your code should still work as needed if you are catching rate-limit messages by catching SparkApiErrors. It's just a little easier to catch the rate-limit messages separately from the broader API errors.

As always, please raise an issue if you are experiencing any challenges or have ideas for enhancement.

Thank You!

Squashed bug preventing Team Updates

@Deepar3292 corrected an errant HTTP method causing Team Updates to fail.

Corrected Python v2 non-unicode string issues introduced in v0.6

The Python v2 & v3 compatibility changes made the v0.6 release introduced an issue where non-unicode strings would fail the API method's type-checking assertions. This issue slipped by the test suite because the test suite had been simultaneously updated to use the Python-Future module (which as used ensured unicode type consistency in both Python v2 & v3).

We have removed the Python-Future use from the test suite (so we are testing with more 'native' Python v2 and v3 code), and corrected the issue with the package's type-checking assertions.

Sorry for any headaches you might have had over the weekend (since the v0.6 package was released), upgrading to v0.6.1 should correct this issue.

As always, please do open an issue if you are experiencing any problems or challenges working with the ciscosparkapi package.

-Thank You!

Python v2 & v3 Compatibility Update ...and more!

v0.6 has several cool things in it...

• Python v2 and v3 compatibility was refactored to only depend upon the Python-Future package ( the six package dependency has been removed).
• @Deepar3292 removed the now lifted requirement on providing either a displayName and email parameter when searching for people (you can now list all of the people in your organization, by calling the people.list() method without providing any parameters).
• Several package-level updates to make it easier for contributors to setup their environment in preparation for contributing to the package (check out the Makefile and requirements.txt updates, contributor docs are coming soon).
• Several new and/or updated bot examples running on various Python web frameworks (now includes examples for web.py, Flask, and Pyramid) - thank you @jbogarin !

Initial Test Suite Complete!!

ciscosparkapi now has a full automated testing suite (using py.test)!! All on-line testable user-facing methods (API calls) have been thoroughly worked through their paces. :-) (issue #4)

The test suite uses a moderate array of py.text fixtures to align object and API dependencies, order test execution, cache results, and optimize API calls. All of this speeds up testing time by minimizing the number of API requests that must be completed to finish a test run. ...and the tests clean-up after themselves as well (though I still recommend using a dedicated test account when running the tests + it will need admin privileges).

Caught and fixed a couple of bugs in the process.

There are a couple of Cisco Spark APIs that are not responding properly (according to the API docs). I will investigate these and re-enable these tests shortly.

Added API wrappers for new Admin APIs and Endpoints

#20 Added wrappers for the new Admin API Endpoints:

• Organizations
• Licenses
• Roles
• people.create() and people.update()

Squashed some Bugs:

• #30 team_memberships.update() was using the wrong HTTP verb
• memberships.update() was also using the wrong HTTP verb

Update Copyright to Cisco Systems, Inc.

Updated package and file copyright references to specify ‘Cisco
Systems, Inc.’ as per recommendations from Cisco legal.

Added support for uploading local files, when posting messages! (Issue #9)

Thank you @brbester for the enhancement request and sharing your code on how you had solved this previously!

When creating a new message, the files argument now accepts either a valid HTTP/HTTPS Internet URL or a path to a local file that should be uploaded when the message is created.

Note that the files argument only accepts a list containing a single item (a string containing either a URL or a local file path). This is a Spark API limitation that may be lifted at a future date. We have implemented method consistent with the Spark API to provide for backwards compatibility if/when this enhancement is made in the future. This way, when Spark opens up support for attaching multiple files on a single message (and we update the package to support that capability), we will not change the method's API and break calls to this method from existing code leveraging the package.

Example of the new functionality:

from ciscosparkapi import CiscoSparkAPI


api = CiscoSparkAPI()


DEMO_ROOM_NAME = "ciscosparkapi Test Room"
DEMO_PEOPLE = ["[email protected]", "[email protected]"]
DEMO_TEXT = u"Cisco Spark rocks!  \ud83d\ude0e"
DEMO_FILE_URL = "https://developer.ciscospark.com/images/[email protected]"
MARKDOWN_TEXT = "**This was uploaded from a local file!**"
DEMO_LOCAL_FILE = "picture.jpg"


# Create a new test room
demo_room = api.rooms.create(DEMO_ROOM_NAME)

# Add people to the room
for person_email in DEMO_PEOPLE:
    api.memberships.create(test_room.id, personEmail=person_email)

# Post a plain-text message to the room, with an attachment from an Internet URL
message1 = api.messages.create(test_room.id, text=DEMO_TEXT, files=[DEMO_FILE_URL])
print(message1)

# Post a markdown-message to the room, with an attachment uploaded from a local file
message2 = api.messages.create(test_room.id, markdown=MARKDOWN_TEXT, files=[DEMO_LOCAL_FILE])
print(message2)

Fix for Bugs #11 and #13

• Corrected an issue where a ciscosparkapiException was incorrectly being raised when a search for people (using CiscoSparkAPI.people.list()) returns an empty list.
• Corrected an issue that caused calls to CiscoSparkAPI.webhooks.update() to fail.

Now Supporting Python v2/v3!

The package now supports Python v2 and v3! Please upgrade to this release to test the package with your v2 or v3 code, and report any issues via the issues page.

Upgrade also includes:

• Example / sample scripts (thank you @brbester !).
• Default / native support for retrieving your Spark access token from the SPARK_ACCESS_TOKEN environment variable (thank you @ObjectIsAdvantag !).