WebexPythonSDK

Documentation for the newly named package webexpythonsdk is now hosted on github pages at https://webexcommunity.github.io/WebexPythonSDK/

What's Changed

• chore(docs): use rtd theme by @adamweeks in https://github.com/WebexCommunity/WebexPythonSDK/pull/238
• docs: update to gh-pages links by @adamweeks in https://github.com/WebexCommunity/WebexPythonSDK/pull/239

Full Changelog: https://github.com/WebexCommunity/WebexPythonSDK/compare/v2.0.0...v2.0.1

Welcome to the new webexpythonsdk library! The latest release removes support for Python v2 and is compatible with Python v3.10+. The new Webex Python SDK replaces the previous webexteamssdk; and with the exception of the Python version support and the name change, the two libraries are functionally equivalent. The new library is the recommended choice for new projects, and webexteamssdk users are encouraged to migrate.

This release is a hotfix that merges Pull request #175 into the main branch.

What's Changed

• Fix for #147 by @fbradyirl in https://github.com/CiscoDevNet/webexteamssdk/pull/157
• Bump pygments from 2.6.1 to 2.7.4 by @dependabot in https://github.com/CiscoDevNet/webexteamssdk/pull/158
• Fix type check in update by @mallamanis in https://github.com/CiscoDevNet/webexteamssdk/pull/150
• Added option to disable ssl cert verification by @sQu4rks in https://github.com/CiscoDevNet/webexteamssdk/pull/142
• Update Cards Handling to check correct attribute for instance of AdaptiveCards (solves #140) by @sQu4rks in https://github.com/CiscoDevNet/webexteamssdk/pull/141
• fixing OpenUrl action by @craigers521 in https://github.com/CiscoDevNet/webexteamssdk/pull/175

New Contributors

• @fbradyirl made their first contribution in https://github.com/CiscoDevNet/webexteamssdk/pull/157
• @dependabot made their first contribution in https://github.com/CiscoDevNet/webexteamssdk/pull/158
• @mallamanis made their first contribution in https://github.com/CiscoDevNet/webexteamssdk/pull/150
• @craigers521 made their first contribution in https://github.com/CiscoDevNet/webexteamssdk/pull/175

Full Changelog: https://github.com/CiscoDevNet/webexteamssdk/compare/v1.6...v1.6.1

In v1.6, we have updated all of the currently wrapped and supported Webex Teams API endpoints and closed out all existing issues that users opened on the v1.x releases. The library should now be up-to-date in supporting the Webex Teams APIs documented at developer.webex.com. It is not yet up-to-date in supporting the newer and broader Webex Meetings, Calling, and Devices APIs. We are tracking adding these additional API endpoints in issue #113, and we will work to add full support for all of the published Webex APIs in v2.x of the library.

With release v1.6, we are wrapping up active development on the v1.x release and shifting our focus to the next major release v2!

Breaking Change(s)

We have introduced one (1) breaking change in v1.6:

• We have changed the function signature (parameter names) for the WebexTeamsAPI.guest_issuer.create() method to align it with the developer documentation at developer.webex.com.

  Previous method definition:

  def create(self, subject, displayName, issuerToken, expiration, secret):
      ...
  

  def create(self, sub, name, iss, exp, secret):
      ...
  

Version 1.5 adds several minor backend improvements, including:

• Webex Tracking IDs are now prominently displayed for all API errors and warnings.

  Example Error Message:

  ApiError: [401] Unauthorized - The request requires a valid access token set in the Authorization request header. [Tracking ID: ROUTER_5F05F384-D9E9-01BB-00FF-4B0C804F00FF]
  

  You can also access the Tracking IDs via the tracking_id attribute available on the raised exception and warning objects.

  api = webexteamssdk.WebexTeamsAPI(access_token="abc")
  
  try:
      api.people.me()
  except webexteamssdk.ApiError as e:
      print(e.tracking_id)
  

• The webexteamssdk library now sends a custom User-Agent header (inspired by PIP's User-Agent header).

  Example User-Agent Header:

  webexteamssdk/1.5 {"implementation": {"name": "CPython", "version": "3.7.8"}, "distro": {"name": "macOS", "version": "10.15.5"}, "system": {"name": "Darwin", "release": "19.5.0"}, "cpu": "x86_64"}
  

• Minor package and PEP8 improvements.

Version 1.4 adds support for the Admin Audit Events API; however, you should note that pagination is currently broken ☹️ on responses from the /v1/adminAudit/events API endpoint. Hopefully, the Developer Support Team will get this fixed quickly.

Also in this release we...

• Squashed a timezone info bug that was affecting Python v2.7 and 3.5

This minor update adds official support for adding attachments to messages via WebexTeamsAPI.messages.create() thanks to @bradh11, @jianchen2580, @zhanto97, and @jwa1 🙌!

@jpjpjp has created an excellent Webex Teams bot example that demonstrates using webhooks, Adaptive Cards, and response actions! 😎

Python Adaptive Cards Beta

This release includes a beta of @sQu4rks Python Adaptive Cards, but please do not get too attached using this functionality directly from the Webex Teams SDK as we will be migrating this functionality to leverage @sQu4rks newer (and independently maintained) pyadaptivecards library.

Thanks to @sQu4rks 😎, webexteamssdk now (offically) supports configuration and use of an HTTP/HTTPS proxy! Just past a dictionary with the proxy configuration when creating your WebexTeamsAPI connection object, and you are good to go. 👊

>>> from webexteamssdk import WebexTeamsAPI
>>> proxy = {'https': 'http://<proxy_ip>:<proxy_port>'}
>>> api = WebexTeamsAPI(access_token=<your_access_token>, proxies=proxy)

Check out the requests documentation on Proxies for details on what should be in the proxies dictionary.

ApiError messages are now shorter, more insightful, and easier to inspect. 🙌

We have simplified the default string interpretation of the ApiError messages. The simplified messages will use the message attribute of the returned JSON (if present) to provide more insight as to why the request failed and will default to the generic error descriptions from the API docs if a message attribute is not available.

Example of the New Message Format:

ApiError: [400] Bad Request - Message destination could not be determined. Provide only one destination in the roomId, toPersonEmail, or toPersonId field

The ApiError exceptions now have several attributes exposed for easier inspection:

• response - The requests.Response object returned from the API call.
• request - The requests.PreparedRequest used to submit the API request.
• status_code - The HTTP status code from the API response.
• status - The HTTP status from the API response.
• details - The parsed JSON details from the API response.
• message - The error message from the parsed API response.
• description - A description of the HTTP Response Code from the API docs.

To inspect an error, simply catch it in a try block and access the above attributes on the caught error:

from webexteamssdk import ApiError, WebexTeamsAPI

api = WebexTeamsAPI()

try:
    api.messages.create()
except ApiError as error: 
    print(error.message)

See ApiError in the API Docs for more details.

This enhancement addresses enhancement request #62 and resolves 🐛 #68.

The new WebexTeamsDateTime functionality had introduced a minor compatibility bug with Python v2. We squished it. 🐜💀

With the name change from Cisco Spark to Webex Teams, ciscosparkapi is now webexteamssdk!

Don't worry! While it has received quite a bit of enhancing, the WebexTeamsAPI wrapper works just like the CiscoSparkAPI wrapper - only better:

• The Python objects returned by the APIs are now immutable, which means that you can include them in sets and use them as keys in dictionaries.
• Date-times returned by the Webex Teams APIs are now modeled as Python datetime's making them even easier to work with.
• The internal package structure has been overhauled to make way for adding new capabilities to the library.
• The core library code, test suite, and docs have been refactored and are now cleaner and leaner than ever.

We'll have more new capabilities to work-on and announce in the coming months, but this is a good start for now. 😎

With this release, ciscosparkapi now supports the Cisco Spark Events API! See the Events API and Event data model docs for more details.

Note: Compliance Officers may retrieve events for all users within an organization. See the Compliance Guide for more information.

feature: #55

In addition to fixing a bug ( #52 ) in the automated rate-limit handling and several testing improvements, this release also includes some substantial enhancements to the SparkData classes and how objects are created and returned by the API methods. 😎

New Features:

• SparkData classes (Room, Person, Message, etc.) are now composed classes created by inheriting from the SparkData base class and type-specific mixin classes. This makes it easier to create your own composed classes (like we are doing with the enhanced data objects in the ciscosparksdk package).
• The CiscoSparkAPI class now accepts an object_factory= parameter that not surprisingly accepts an object factory function, which is responsible for creating the objects returned by the API methods. This allows you to easily create your own object classes and have them returned by the CiscoSparkAPI methods. #EasilyExtensible 🔌
• Automated rate-limit handling now generates a custom SparkRateLimitWarning ⚠️ warning message when a rate-limit response is received. If you want to know if your code is being rate-limited, you can easily catch and log warnings to see 🙈 what is going on.

Updated feature docs on the new object extensibility are coming soon. I wanted to go ahead and get the rate-limit fixes, and the initial object code out so the development can move forward on the ciscosparksdk package.

Happy Coding!

This update adds:

• Refactored GeneratorContainer's - now with slicing support! (for the #50 guys) - Only need the first 10 rooms, messages, or etc.? All of the package's list() methods (return GeneratorContainers) that can now be easily sliced to give you exactly what you need, for example:

api = CiscoSparkAPI()
rooms = api.rooms.list(type='group')

print("Here are the first ten rooms:")
for room in rooms[:10]:
    print(room)

• Squashed a Python2 SparkData Bug - If you have tried to initialize a SparkData object (like a webhook) using Python v2, it was probably raising a TypeError when you did. #SquishedIt 🐛 ☠️

• Other Boring Stuff:

  • Updated script metadata (copyright notices and etc.).
  • Cleaned up some tests.
  • PEP8 fixes.
  • Blah, blah, blah... 💤

Merged in pull request #49 from @dlspano with a fix to the package's rate-limit handling support where we (me) had accidentally removed the SparkApiError.retry_after attribute that is critical to handling the rate-limit messages. 🤦‍♂️ -Thank you for catching this Dave!

This release also includes a few minor commits that were added to the package in support of the ciscosparksdk work that is underway.

A couple of small feature updates in this release:

• We are now exposing the Spark data object's JSON data in three formats ( #48 ): 💯
  • <spark data object>.json_data returns a copy of the object's JSON data as an OrderedDict.
  • <spark data object>.to_dict() returns a copy of the object's JSON data as a dict object.
  • <spark data object>.to_json() returns a copy of the object's JSON data as an JSON string. Note: You can pass your favorite Python JSON encoding keyword arguments to this method (like indent=2 and etc.).
• We have refactored the ciscosparkapi main package to more clearly articulate what classes and data are being exposed to you for your use. 😎

All of the API wrappers and data models have been reviewed and updated to match the latest Cisco Spark API capabilities. -and- We have completed a significant internal restructuring to improve all of the API wrappers:

• All API methods that accept parameters and post-data have been updated to consistently accept optional (**request_parameters) keyword arguments. So, if Cisco releases an API update tomorrow with some new awesome parameter... You can go ahead and use it. We'll update the code later so that it shows up in your IDE as soon as we can.

• New WebhookEvent - Webhook posts to your bot or automation can now be modeled via a new WebhookEvent. Just pass the JSON body that Spark posts to your web service to the WebhookEvent() initializer and you can use native dot-syntax to access all of the attributes.

• Exceptions - some changes to what exceptions are raised...

  • TypeErrors - If you happen to pass an incorrectly typed parameter to one of the API methods or object initializers, the package will now raise a more appropriate and informative TypeError rather than an AssertionError.
  • ValueErrors - If you pass an incorrect value... You guessed it ValueError.

Exception handling should be very straightforward now. The only exception that you should have to catch and handle at runtime should be the SparkApiError's, which are returned when Cisco Spark responds with an error code. By the way, these were recently updated to show you the full request and response body, when an error occurs. Any other errors should show up and be addressed when you are writing and debugging your code.

Please open an issue if you experience any issues with the package. We have tested it extensively so hopefully you shouldn't! ...but the issue log is there just in case. 🤞 😎

-Thank You!

Micro release with some goodness!

We corrected issue #46 where SparkApiErrors were not printing / displaying correctly, and we enhanced them while we were in correcting the issue. SparkApiErrors now include the full details of the request and response that triggered / caused the error. No more having to go to your debugger to see what the offending request and response looked like. 😎

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!

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