Merge branch 'master' into feature/adaptive_cards

Author: cmlccie

Pipfile

@@ -4,7 +4,7 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-"e1839a8" = {editable = true, path = "."}
+webexteamssdk = {editable = true,path = "."}
 
 [dev-packages]
 versioneer = "*"

Pipfile.lock

@@ -7,7 +7,9 @@ webexteamssdk
 .. image:: https://img.shields.io/badge/license-MIT-blue.svg
     :target: https://github.com/CiscoDevNet/webexteamssdk/blob/master/LICENSE
 .. image:: https://img.shields.io/pypi/v/webexteamssdk.svg
-    :target: https://pypi.python.org/pypi/webexteamssdk
+    :target: https://pypi.org/project/webexteamssdk/
+.. image:: https://img.shields.io/pypi/dw/webexteamssdk.svg
+    :target: https://pypi.org/project/webexteamssdk/
 .. image:: https://travis-ci.org/CiscoDevNet/webexteamssdk.svg?branch=master
     :target: https://travis-ci.org/CiscoDevNet/webexteamssdk
 .. image:: https://readthedocs.org/projects/webexteamssdk/badge/?version=latest
@@ -16,9 +18,9 @@ webexteamssdk
 -------------------------------------------------------------------------------
 
 
-Looking for **``ciscosparkapi``**?  You are in the right place.  ``ciscosparkapi`` is now ``webexteamssdk``!  It still has all of the native and natural Webex Teams Python functionality that you love and now we have made room for even more functionality to be added in the future.
+Looking for ``ciscosparkapi``?  You are in the right place.  ``ciscosparkapi`` is now ``webexteamssdk``!  It still has all of the native and natural Webex Teams Python functionality that you love and now we have made room for even more functionality to be added in the future.
 
-We will maintain the ``ciscosparkapi`` package (bug fixes, etc.) in the `ciscosparkapi`_ branch of this repository and continue to publish package updates with these fixes to PyPI (through the;nd of 2019). Maintaining the ``ciscosparkapi`` package should keep your code and projects up and running while giving you 12+ months to migrate your code to the new ``webexteamssdk`` library.
+We will maintain the ``ciscosparkapi`` package (bug fixes, etc.) in the `ciscosparkapi`_ branch of this repository and continue to publish package updates with these fixes to PyPI (through the end of 2019). Maintaining the ``ciscosparkapi`` package should keep your code and projects up and running while giving you 12+ months to migrate your code to the new ``webexteamssdk`` library.
 
 *Migration Note:* Migrating should be easy.  The ``WebexTeamsAPI`` class and the Python objects returned by the API calls are nearly identical to their ``CiscoSparkAPI`` predecessors.  Does the word "nearly" scare you?  Here are some specifics:
 

README.rst

@@ -31,11 +31,11 @@ Notes on the Test Suite
 
 To test all the API endpoints, the account that you use for testing must be an *admin* user for your Webex Teams Organization.  Additionally, you should know that that the testing process creates some test people, rooms, messages, teams, and etc. as part of executing the test suite. We strongly recommend *NOT* running the test suite using your personal Webex Teams account (not that you can't; it's just that you probably don't want it cluttering your account with all these test artifacts).
 
-If you cannot create a test account with *admin* privileges or configure your environment to run the test suite locally, you may always submit your code via a pull request.  Our GitHub/Travis CI setup runs the test suite against all pull requests.  All tests must pass before your pull request is accepted.
+If you cannot create a test account with *admin* privileges or configure your environment to run the test suite locally, you may always submit your code via a pull request.  We will test your code before merging and releasing the changes.
 
 
-Contributing Code - Using the CI Automated Testing
---------------------------------------------------
+Contributing Code
+-----------------
 
 1. Check for open `issues`_ or create a new *issue* for the item you want to work on and make sure to comment and let us know that you are working on it.
 
@@ -57,54 +57,33 @@ Contributing Code - Using the CI Automated Testing
 
 7. Commit your changes.
 
-8. Submit a `pull request`_.  The GitHub/Travis CI system runs the test suite against your pull request code.  If any tests fail, please review your changes.  If everything looks good, we will gladly merge your request!
-
-
-Contributing Code - Running the Test Suite Locally
---------------------------------------------------
-
-1. Check for open `issues`_ or create a new 'issue' for the item you want to work on and make sure to comment and let us know that you are working on it.
-
-2. Fork a copy of the `repository`_ and clone your forked repository to your development environment.
-
-   Run ``script/setup`` to install the development dependencies and setup your environment.
-
-3. Configure the following environment variables in your development environment:
+8. Submit a `pull request`_.
 
-   * ``WEBEX_TEAMS_ACCESS_TOKEN`` - Your test account's Webex Teams access token.
-
-   * ``WEBEX_TEAMS_TEST_DOMAIN`` - The test suite creates some users as part of the testing process. The test suite uses this domain name as the e-mail suffix of for the user's e-mail addresses.
-
-   * ``WEBEX_TEAMS_TEST_ID_START`` - The test suite uses this integer as the starting number for creating test user accounts (example: "test42@domain.com").
-
-   * ``WEBEX_TEAMS_TEST_FILE_URL`` - Configure this environment variable with a URL referencing a file that can be downloaded and posted to Webex Teams as part of the testing process.
 
-   *Example:*
+Running the Test Suite Locally
+------------------------------
 
-   .. code-block:: bash
+Configure the following environment variables in your development environment:
 
-       #!/usr/bin/env bash
-       export WEBEX_TEAMS_ACCESS_TOKEN="<test account's access token>"
-       export WEBEX_TEAMS_TEST_DOMAIN="domain.com"
-       export WEBEX_TEAMS_TEST_ID_START=42
-       export WEBEX_TEAMS_TEST_FILE_URL="https://www.webex.com/content/dam/wbx/us/images/dg-integ/teams_icon.png"
+* ``WEBEX_TEAMS_ACCESS_TOKEN`` - Your test account's Webex Teams access token.
 
+* ``WEBEX_TEAMS_TEST_DOMAIN`` - The test suite creates some users as part of the testing process. The test suite uses this domain name as the e-mail suffix of for the user's e-mail addresses.
 
-4. Add your code to your forked repository.
+* ``WEBEX_TEAMS_TEST_ID_START`` - The test suite uses this integer as the starting number for creating test user accounts (example: "test42@domain.com").
 
-   If you are creating some new feature or functionality (excellent!), please also write a `test`_ to verify that your code works as expected.
-
-5. We follow `PEP8`_ reasonably strictly for this project.  Please make sure your code passes the linter.
-
-   Run ``script/test lint`` or simply run ``flake8`` from the project root.
+* ``WEBEX_TEAMS_TEST_FILE_URL`` - Configure this environment variable with a URL referencing a file that can be downloaded and posted to Webex Teams as part of the testing process.
 
-6. Commit your changes.
+*Example:*
 
-7. Ensure your code passes all of the default tests.
+.. code-block:: bash
 
-   Run ``script/test`` and ensure all tests execute successfully.
+   #!/usr/bin/env bash
+   export WEBEX_TEAMS_ACCESS_TOKEN="<test account's access token>"
+   export WEBEX_TEAMS_TEST_DOMAIN="domain.com"
+   export WEBEX_TEAMS_TEST_ID_START=42
+   export WEBEX_TEAMS_TEST_FILE_URL="https://www.webex.com/content/dam/wbx/us/images/dg-integ/teams_icon.png"
 
-8. Submit a `pull request`_.  If everything looks good, we will gladly merge your request!
+Ensure your code passes all of the default tests.  Run ``script/test`` and ensure all tests execute successfully.
 
 
 .. _script: https://github.com/CiscoDevNet/webexteamssdk/tree/master/script

docs/contributing.rst

@@ -102,7 +102,6 @@ roles
 
 .. autoclass:: webexteamssdk.api.roles.RolesAPI()
 
-
 .. _events:
 
 events
@@ -118,6 +117,12 @@ access_tokens
 
 .. autoclass:: webexteamssdk.api.access_tokens.AccessTokensAPI()
 
+.. _guest_issuer:
+
+guest_issuer
+------------
+
+.. autoclass:: webexteamssdk.api.guest_issuer.GuestIssuerAPI()
 
 .. _Webex Teams Data Objects:
 
@@ -241,7 +246,6 @@ Access Token
 .. autoclass:: AccessToken()
     :inherited-members:
 
-
 .. _Exceptions:
 
 Exceptions

docs/user/api.rst

@@ -55,3 +55,5 @@
 |                       | :ref:`access_tokens`    | :meth:`get() <webeteamssdk.api.access_tokens.AccessTokensAPI.get>`              |
 |                       |                         | :meth:`refresh() <webeteamssdk.api.access_tokens.AccessTokensAPI.refresh>`      |
 +-----------------------+-------------------------+---------------------------------------------------------------------------------+
+|                       | :ref:`guest_issuer`     | :meth:`create() <webexteamssdk.api.guest_issuer.create>`                        |
++-----------------------+-------------------------+---------------------------------------------------------------------------------+

docs/user/api_structure_table.rst

@@ -134,6 +134,31 @@ object.
     >>> chris_api = WebexTeamsAPI(access_token=chris_at)
     >>> veronica_api = WebexTeamsAPI(access_token=veronica_at)
 
+If you authenticate a user via a OAuth flow you can also initialize a api object
+directly by providing the OAuth information.
+
+.. code-block:: python
+
+    >>> from webexteamssdk import WebexTeamsAPI
+    >>> client_id = "<from oauth>"
+    >>> client_secret = "<from oauth>"
+    >>> oauth_code = "<from oauth>"
+    >>> redirect_uri = "<from oauth>"
+    >>> api = WebexTeamsAPI(client_id=client_id,
+                            client_secret=client_secret,
+                            oauth_code=oauth_code,
+                            redirect_uri=redirect_uri
+                           )
+
+You can also pass a proxy configuration upon initialization in case you are behind a firewall.  See the `requests
+documentation on Proxies <https://2.python-requests.org/en/master/user/advanced/#proxies>`_ for details.
+
+.. code-block:: python
+
+    >>> from webexteamssdk import WebexTeamsAPI
+    >>> proxy = {'https': 'http://<proxy_ip>:<proxy_port>'}
+    >>> api = WebexTeamsAPI(access_token=<your_access_token>, proxies=proxy)
+
 
 Making API Calls
 ----------------
@@ -443,6 +468,25 @@ contain all of the returned objects.
     >>> rooms_list = list(rooms_iterable)
 
 
+
+Extending the API with bound methods
+------------------------------------
+
+As the Webex Teams API is developed and features are added, it may be necessary to extend the webexteamssdk to access those features.
+Extending the API is simple by binding your own methods to the WebexTeamsAPI connection object. By binding a method, you can 
+extend functionality and leverage all of the objects and quality of life features of webexteamssdk.
+
+.. code-block:: python
+
+    >>> new_method(self, param):
+        ...     json_obj = self._session.get('/example/action/' + param)
+        ...     return json_obj
+    
+    >>> api = WebexTeamsAPI()
+    >>> api.new_method = new_method
+    >>> output = WebexTeamsAPI.new_method(param)
+
+
 *Copyright (c) 2016-2019 Cisco and/or its affiliates.*