Skip to content

Python readme update #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 8, 2019
Merged

Python readme update #26

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
66ff583
Update README.md
MattKingDS Apr 30, 2019
6610694
Update README.md
MattKingDS Apr 30, 2019
ae1b592
Update README.md
MattKingDS Apr 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 60 additions & 146 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,188 +8,102 @@

[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)
- 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.

# 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)
<ol>
<li>Open the Windows <b>Control Panel.</b></li>
<li>Under the System and Security category, open the <b>System</b></li>
<li>Select <b>Advanced System Settings</b> to open the <b>System Properties</b> dialog box.</li>
<li>On the <b>Advanced</b> tab, select the <b>Environmental Variables</b> button at the lower-right corner.
<ol style="list-style-type: lower-alpha">
<li>Check if <b>PYTHONPATH</b> has been added as a <b>system variable.</b></li>
<li>If it has not, select <b>New</b> to add it. The variable you add is the path to the <b>site-packages</b></li>
</ol>
</li>
</ol>

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&#39;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&#39;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
Expand Down