Ciscosparkapi

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:**

python
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:

python
from webexteamssdk import ApiError, WebexTeamsAPI

api = WebexTeamsAPI()

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


See `ApiError` in the [API Docs](https://webexteamssdk.readthedocs.io/en/latest/user/api.htmlwebexteamssdk.ApiError) 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](https://developer.ciscospark.com/resource-events.html)! See the [Events API](http://ciscosparkapi.readthedocs.io/en/latest/user/api.htmlevents) and [Event data model](http://ciscosparkapi.readthedocs.io/en/latest/user/api.htmlevent) docs for more details.

> **Note:** Compliance Officers may retrieve events for all users within an organization. See the [Compliance Guide](https://developer.ciscospark.com/docs/api/guides/compliance.html) 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](https://docs.python.org/3/library/warnings.html) 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](https://docs.python.org/3/library/logging.htmllogging.captureWarnings) 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:
python
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... 💤