From 66ff583b7a6049db550a5ad6d907e0443b8fe12b Mon Sep 17 00:00:00 2001 From: MattKingDS <43220771+MattKingDS@users.noreply.github.com> Date: Tue, 30 Apr 2019 12:12:58 -0700 Subject: [PATCH 1/3] Update README.md --- README.md | 205 ++++++++++++++++-------------------------------------- 1 file changed, 59 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 80a862b5..67887279 100644 --- a/README.md +++ b/README.md @@ -8,188 +8,101 @@ [Documentation about the DocuSign API](https://developers.docusign.com/) -You can sign up for a free [developer sandbox](https://go.docusign.com/sandbox/productshot/?elqCampaignId=16535). +## Requirements -Requirements -============ +- Python 2.7 (3.6+ recommended) +- Free [Developer Sandbox](https://go.docusign.com/sandbox/productshot/?elqCampaignId=16531) -Python 2.7 and 3.6+. +## Compatibility -## PYTHONPATH set up -### *nix -- Find the path to site-packages folders, for your python version. Usually it's under "/usr/lib/python2.7" (Unix) or "/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7" (Mac) -- export PYTHONPATH = ${PYTHONPATH}:.:/path/to/site-packages +- Python 2.7+ -Ideally you want this last line to be executed each time python command is launched. So you have to add it to ~/.bash_profile, ~/.bashrc or ~/.profile. +## Note -### Windows -- Find the path to site-packages folders, for your python version. Usually it's under "C:\Python27". -- Go to your Windows "Control Panel" -- Open "System Settings" -- Under "Advanced" tab, click on the "Environment Variables" button. -- Check if "PYTHONPATH" variable is defined under the "System Variables" section. -- If not defined yet, click on the "New" button and add it. The value of the varibale should be the path to site-packages (something like "C:\Python27"). +This open-source SDK is provided for cases where you would like to make additional changes that the SDK does not provide out-of-the-box. If you simply want to use the SDK with any of the examples shown in the [Developer Center](https://developers.docusign.com/esign-rest-api/code-examples), follow the installation instructions below. +## Installation -Now that you've added the site-packages folder, to the list of modules python command scans, when it starts, it time to verify it's working: -- open python command prompt and type "help('modules')". Your should now see the list of modules installed under site-packages. +### Path Setup: -Installation -============ +1. Locate your Python installation, also referred to as a **site-packages** folder. This folder is usually labeled in a format of Python{VersionNumber}. -### PyPI Package Index +**Examples:** -Install the client locally: `pip install docusign_esign` (note you may have to use `sudo` based on your permissions) +- **Unix/Linux:** /usr/lib/python2.7 +- **Mac:** /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7 +- **Windows:** C:\Users\{username}\AppData\Local\Programs\Python\Python37 -Alternatively you can just copy the source code directly into your project. +1. Add the path to your Python folder as an environment variable. -#### Dependencies +**Unix/Linux:** -This client has the following external dependencies: - -* certifi >= 14.05.14 -* six == 1.8.0 -* python_dateutil >= 2.5.3 -* setuptools >= 21.0.0 -* urllib3 >= 1.15.1 -* jwcrypto >= 0.4.2 -* py-oauth2 >= 0.0.10 - -Usage -===== - -To initialize the client, make the Login API Call and send a template for signature: - -Run this script using python command -```python -from __future__ import absolute_import, print_function -from pprint import pprint -import unittest -import webbrowser - -import docusign_esign as docusign -from docusign_esign import AuthenticationApi, TemplatesApi, EnvelopesApi -from docusign_esign.rest import ApiException - -user_name = "[USERNAME]" -integrator_key = "[INTEGRATOR_KEY]" -base_url = "https://demo.docusign.net/restapi" -oauth_base_url = "account-d.docusign.com" # use account.docusign.com for Live/Production -redirect_uri = "https://www.docusign.com/api" -private_key_filename = "keys/docusign_private_key.txt" -user_id = "[USER_ID]" -template_id = "[TEMPLATE_ID]" - -api_client = docusign.ApiClient(base_url) - -# IMPORTANT NOTE: -# the first time you ask for a JWT access token, you should grant access by making the following call -# get DocuSign OAuth authorization url: -oauth_login_url = api_client.get_jwt_uri(integrator_key, redirect_uri, oauth_base_url) -# open DocuSign OAuth authorization url in the browser, login and grant access -# webbrowser.open_new_tab(oauth_login_url) -print(oauth_login_url) +- export PYTHONPATH = "${PYTHONPATH}:.:/path/to/site-packages" +- Optionally, you can add this command to your **system profile** , which will run the command each time Python is launched. -# END OF NOTE +**Windows:** -# configure the ApiClient to asynchronously get an access token and store it -api_client.configure_jwt_authorization_flow(private_key_filename, oauth_base_url, integrator_key, user_id, 3600) +
    +
  1. Open the Windows **Control Panel.**
    2. +
  2. Under the System and Security category, open the **System**
    3. +
  3. Select **Advanced System Settings** to open the **System Properties** dialog box.
    4. +
  4. On the **Advanced** tab, select the **Environmental Variables** button at the lower-right corner. +
      +
    1. Check if **PYTHONPATH** has been added as a **system variable.**
      2. +
    2. If it has not, select **New** to add it. The variable you add is the path to the **site-packages**
      3. +
    +
    5. +
-docusign.configuration.api_client = api_client +**Note:** If you are still unable to reference python or pip via your command console,you can also add the path to the site-packages folder to the built-in environment variable labeled **Path** , which will take effect the next time you start your machine. -template_role_name = 'Needs to sign' +### Install via PIP: -# create an envelope to be signed -envelope_definition = docusign.EnvelopeDefinition() -envelope_definition.email_subject = 'Please Sign my Python SDK Envelope' -envelope_definition.email_blurb = 'Hello, Please sign my Python SDK Envelope.' +1. In your command console, type: +pip install docusign-esign -# assign template information including ID and role(s) -envelope_definition.template_id = template_id +Note: This may require the command console be elevated. You can accomplish this via sudoin Unix/Linux, or by running the command console as an administrator in Windows. -# create a template role with a valid template_id and role_name and assign signer info -t_role = docusign.TemplateRole() -t_role.role_name = template_role_name -t_role.name ='Pat Developer' -t_role.email = user_name +## Dependencies -# create a list of template roles and add our newly created role -# assign template role(s) to the envelope -envelope_definition.template_roles = [t_role] - -# send the envelope by setting |status| to "sent". To save as a draft set to "created" -envelope_definition.status = 'sent' - -auth_api = AuthenticationApi() -envelopes_api = EnvelopesApi() - -try: - login_info = auth_api.login(api_password='true', include_account_id_guid='true') - assert login_info is not None - assert len(login_info.login_accounts) > 0 - login_accounts = login_info.login_accounts - assert login_accounts[0].account_id is not None - - base_url, _ = login_accounts[0].base_url.split('/v2') - api_client.host = base_url - docusign.configuration.api_client = api_client - - envelope_summary = envelopes_api.create_envelope(login_accounts[0].account_id, envelope_definition=envelope_definition) - assert envelope_summary is not None - assert envelope_summary.envelope_id is not None - assert envelope_summary.status == 'sent' - - print("EnvelopeSummary: ", end="") - pprint(envelope_summary) +This client has the following external dependencies: -except ApiException as e: - print("\nException when calling DocuSign API: %s" % e) - assert e is None # make the test case fail in case of an API exception -``` +- certifi v14.05.14+ +- six v1.8.0 +- python\_dateutil v2.5.3+ +- setuptools v21.0.0+ +- urllib3 v1.15.1+ +- jwcrypto v0.4.2+ +- py-oauth2 v0.0.10+ -See [unit_tests.py](./test/unit_tests.py) for more examples. +## Code Examples -# Authentication +### Launchers -## Service Integrations that use Legacy Header Authentication +DocuSign provides a sample application referred to as a [Launcher](https://github.com/docusign/eg-03-python-auth-code-grant). The Launcher contains a set of 14 common use cases and associated source files. These examples use DocuSign's [Authorization Code Grant](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-code-grant) flow. -([Legacy Header Authentication](https://docs.docusign.com/esign/guide/authentication/legacy_auth.html) uses the X-DocuSign-Authentication header.) +## Proof-of-concept applications -1. Use the [Authentication: login method](https://docs.docusign.com/esign/restapi/Authentication/Authentication/login/) to retrieve the account number **and the baseUrl** for the account. -The url for the login method is www.docusign.net for production and demo.docusign.net for the developer sandbox. -The `base_url` field is part of the `login_account` object. See the [docs and the login_account object](https://docs.docusign.com/esign/restapi/Authentication/Authentication/login/#/definitions/loginAccount) -2. The base_url for the selected account, in production, will start with na1, na2, na3, eu1, or something else. Use the base_url that is returned to create the *host* (see the next step.) Use the host for all of your subsequent API calls. -3. As returned by login method, the base_url includes the API version and account id. Split the string to obtain the *host*, just the server name and api name. Eg, you will receive `https://na1.docusign.net/restapi/v2/accounts/123123123`. You want just `https://na1.docusign.net/restapi` -4. Instantiate the SDK using the basePath. Eg `api_client = docusign.ApiClient(host)` -5. Set the authentication header as shown in the examples by using `api_client.set_default_header` +If your goal is to create a proof of concept application, DocuSign provides a set of [Quick Start](https://github.com/docusign/qs-python) examples. The Quick Start examples are meant to be used with DocuSign's [OAuth Token Generator](https://developers.docusign.com/oauth-token-generator), which will allow you to generate tokens for the Demo/Sandbox environment only. These tokens last for eight hours and will enable you to build your proof-of-concept application without the need to fully implement an OAuth solution. -## User Applications that use OAuth Authentication -1. After obtaining a Bearer token, call the [OAuth: Userinfo method](https://docs.docusign.com/esign/guide/authentication/userinfo.html). Obtain the selected account's `base_uri` (server name) field. -The url for the Userinfo method is account-d.docusign.com for the demo/developer environment, and account.docusign.com for the production environment. -1. Combine the base_uri with "/restapi" to create the host. The base_uri will start with na1, na2, na3, eu1, or something else. Use the host for your subsequent API calls. -4. Instantiate the SDK using the basePath. Eg `api_client = docusign.ApiClient(host)` -5. Create the `authentication_value` by combining the `token_type` and `access_token` fields you receive from either an [Authorization Code Grant](https://docs.docusign.com/esign/guide/authentication/oa2_auth_code.html) or [Implicit Grant](https://docs.docusign.com/esign/guide/authentication/oa2_implicit.html) OAuth flow. -5. Set the authentication header by using `api_client.set_default_header('Authorization', authentication_value)` +## OAuth Implementations -Testing -======= +For details regarding which type of OAuth grant will work best for your DocuSign integration, see the [REST API Authentication Overview](https://developers.docusign.com/esign-rest-api/guides/authentication) guide located on the [DocuSign Developer Center](https://developers.docusign.com/esign-rest-api/guides/authentication). -Unit tests are available in the [Test](https://github.com/docusign/docusign-python-client/tree/master/test/unit_tests.py) folder. +For security purposes, DocuSign recommends using the [Authorization Code Grant](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-code-grant) flow. -Contributing -============ +There are other use-case scenarios, such as **single-page applications** (SPA) that use **Cross-Origin Resource Sharing** (CORS), or where there may not be a user to interact with your Service Account. For these use cases, DocuSign also supports [JWT](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-jsonwebtoken) and [Implicit](https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-implicit) grants. For code examples, see the links below: -**This SDK is auto-generated from OpenAPI specification file. For that reason, we actually do NOT accept pull requests. If you find a bug or have an idea that you want to see in the SDK, please open a new [issue](https://github.com/docusign/docusign-python-client/issues/new).** +- [JWT (JSON Web Token)](https://github.com/docusign/eg-01-python-jwt) +- Implicit Grant (coming soon) -Support -======= +## Support -Feel free to log issues against this client through GitHub. We also have an active developer community on Stack Overflow, search the [DocuSignAPI](http://stackoverflow.com/questions/tagged/docusignapi) tag. +Log issues against this client through GitHub. We also have an [active developer community on Stack Overflow](http://stackoverflow.com/questions/tagged/docusignapi). -License -======= +## License -The DocuSign Node Client is licensed under the following [License](LICENSE). +The DocuSign Python Client is licensed under the [MIT License](https://github.com/docusign/docusign-python-client/blob/master/LICENSE). [pypi-image]: https://img.shields.io/pypi/v/docusign_esign.svg?style=flat From 6610694ef0b63ae9db0b1c222e47a09419f461e8 Mon Sep 17 00:00:00 2001 From: MattKingDS <43220771+MattKingDS@users.noreply.github.com> Date: Tue, 30 Apr 2019 12:15:22 -0700 Subject: [PATCH 2/3] Update README.md --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 67887279..d134ec22 100644 --- a/README.md +++ b/README.md @@ -43,13 +43,13 @@ This open-source SDK is provided for cases where you would like to make addition **Windows:**
    -
  1. Open the Windows **Control Panel.**
    2. -
  2. Under the System and Security category, open the **System**
    3. -
  3. Select **Advanced System Settings** to open the **System Properties** dialog box.
    4. -
  4. On the **Advanced** tab, select the **Environmental Variables** button at the lower-right corner. +
  5. Open the Windows Control Panel.
    6. +
  6. Under the System and Security category, open the System
    7. +
  7. Select Advanced System Settings to open the System Properties dialog box.
    8. +
  8. On the Advanced tab, select the Environmental Variables button at the lower-right corner.
      -
    1. Check if **PYTHONPATH** has been added as a **system variable.**
      2. -
    2. If it has not, select **New** to add it. The variable you add is the path to the **site-packages**
      3. +
    3. Check if PYTHONPATH has been added as a system variable.
      4. +
    4. If it has not, select New to add it. The variable you add is the path to the site-packages
From ae1b59216dee433cff94a9d6c4f60eea95f651a9 Mon Sep 17 00:00:00 2001 From: MattKingDS <43220771+MattKingDS@users.noreply.github.com> Date: Tue, 30 Apr 2019 14:03:13 -0700 Subject: [PATCH 3/3] Update README.md --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d134ec22..a8e78ede 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,9 @@ This open-source SDK is provided for cases where you would like to make addition **Unix/Linux:** -- export PYTHONPATH = "${PYTHONPATH}:.:/path/to/site-packages" -- Optionally, you can add this command to your **system profile** , which will run the command each time Python is launched. +- Type the following command into your console: + **export PYTHONPATH = "${PYTHONPATH}:.:/path/to/site-packages"** +- Optionally, you can add this command to your system profile, which will run the command each time Python is launched. **Windows:**