Merge pull request #93 from kbussell/77-edit-recipients

Support the add/update/delete recipient APIs

Author: zebuline

pydocusign/client.py

@@ -498,3 +498,66 @@ def get_connect_failures(self):
         url = '/accounts/{accountId}/connect/failures' \
               .format(accountId=self.account_id)
         return self.get(url)['failures']
+
+    def add_envelope_recipients(self, envelopeId, recipients,
+                                resend_envelope=False):
+        """Add one or more recipients to an envelope
+
+        DocuSign reference:
+        https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/create/
+        """
+        if not self.account_url:
+            self.login_information()
+        url = '/accounts/{accountId}/envelopes/{envelopeId}/recipients' \
+            .format(accountId=self.account_id,
+                    envelopeId=envelopeId)
+        if resend_envelope:
+            url += '?resend_envelope=true'
+        data = {'signers': [recipient.to_dict() for recipient in recipients]}
+        return self.post(url, data=data)
+
+    def update_envelope_recipients(self, envelopeId, recipients,
+                                   resend_envelope=False):
+        """Modify recipients in a draft envelope or correct recipient information
+        for an in process envelope
+
+        DocuSign reference:
+        https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/update/
+        """
+        if not self.account_url:
+            self.login_information()
+        url = '/accounts/{accountId}/envelopes/{envelopeId}/recipients' \
+              .format(accountId=self.account_id,
+                      envelopeId=envelopeId)
+        if resend_envelope:
+            url += '?resend_envelope=true'
+        data = {'signers': [recipient.to_dict() for recipient in recipients]}
+        return self.put(url, data=data)
+
+    def delete_envelope_recipient(self, envelopeId, recipientId):
+        """Deletes one or more recipients from a draft or sent envelope.
+
+        DocuSign reference:
+        https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/delete/
+        """
+        if not self.account_url:
+            self.login_information()
+        url = '/accounts/{accountId}/envelopes/{envelopeId}/recipients/' \
+              '{recipientId}'.format(accountId=self.account_id,
+                                     envelopeId=envelopeId,
+                                     recipientId=recipientId)
+        return self.delete(url)
+
+    def delete_envelope_recipients(self, envelopeId, recipientIds):
+        """Deletes one or more recipients from a draft or sent envelope.
+
+        DocuSign reference:
+        https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/deleteList/
+        """
+        if not self.account_url:
+            self.login_information()
+        url = '/accounts/{accountId}/envelopes/{envelopeId}/recipients' \
+            .format(accountId=self.account_id,
+                    envelopeId=envelopeId)
+        data = {'signers': [{'recipientId': id_} for id_ in recipientIds]}
+        return self.delete(url, data=data)

tests/test_client.py

@@ -0,0 +1,95 @@
+import unittest
+try:
+    from unittest import mock
+except ImportError:  # Python 2 fallback.
+    import mock
+
+from pydocusign import DocuSignClient, Signer
+
+
+class DocuSignTestClient(DocuSignClient):
+    def login_information(self):
+        self.account_id = 'test'
+        self.account_url = '{root}/accounts/test'.format(root=self.root_url)
+
+
+class ClientRequestTest(unittest.TestCase):
+    def test_create_envelope_recipients(self):
+        client = DocuSignTestClient()
+
+        with mock.patch.object(client, 'post') as post_mock:
+            signers = [
+                Signer(clientUserId='userid_2', email='signer1@example.com',
+                       name='Signer 2'),
+                Signer(clientUserId='userid_2', email='signer2@example.com',
+                       name='Signer 2'),
+            ]
+            client.add_envelope_recipients('ABC123', signers)
+
+        url = '/accounts/{account_id}/envelopes/ABC123/recipients'.format(
+            account_id=client.account_id)
+
+        post_mock.assert_called_once_with(
+            url, data={'signers': [signers[0].to_dict(), signers[1].to_dict()]}
+        )
+
+        with mock.patch.object(client, 'post') as post_mock:
+            client.add_envelope_recipients('ABC123', [], resend_envelope=True)
+
+        post_mock.assert_called_once_with(
+            '/accounts/{}/envelopes/ABC123/recipients'
+            '?resend_envelope=true'.format(client.account_id),
+            data={'signers': []}
+        )
+
+    def test_update_envelope_recipients(self):
+        client = DocuSignTestClient()
+
+        with mock.patch.object(client, 'put') as put_mock:
+            signers = [
+                Signer(clientUserId='userid_2', email='signer1@example.com',
+                       name='Signer 2'),
+                Signer(clientUserId='userid_2', email='signer2@example.com',
+                       name='Signer 2'),
+            ]
+            client.update_envelope_recipients('ABC123', signers)
+
+        url = '/accounts/{account_id}/envelopes/ABC123/recipients'.format(
+            account_id=client.account_id)
+
+        put_mock.assert_called_once_with(
+            url, data={'signers': [signers[0].to_dict(), signers[1].to_dict()]}
+        )
+
+        with mock.patch.object(client, 'put') as put_mock:
+            client.update_envelope_recipients('ABC123', [], resend_envelope=True)
+
+        put_mock.assert_called_once_with(
+            '/accounts/{}/envelopes/ABC123/recipients'
+            '?resend_envelope=true'.format(client.account_id),
+            data={'signers': []}
+        )
+
+    def test_delete_envelope_recipient(self):
+        client = DocuSignTestClient()
+
+        with mock.patch.object(client, 'delete') as delete_mock:
+            client.delete_envelope_recipient('ABC123', '1')
+
+        url = '/accounts/{account_id}/envelopes/ABC123/recipients/1'.format(
+            account_id=client.account_id)
+
+        delete_mock.assert_called_once_with(url)
+
+    def test_delete_envelope_recipients(self):
+        client = DocuSignTestClient()
+
+        with mock.patch.object(client, 'delete') as delete_mock:
+            client.delete_envelope_recipients('ABC123', ['1', '2'])
+
+        url = '/accounts/{account_id}/envelopes/ABC123/recipients'.format(
+            account_id=client.account_id)
+
+        delete_mock.assert_called_once_with(
+            url, data={'signers': [{'recipientId': '1'}, {'recipientId': '2'}]}
+        )