Add upsert_person method to ActionNetwork (#734)

* Add upsert_person method to ActionNetwork, add deprecation warnings to add_person and update_person

parsons/action_network/action_network.py

@@ -90,10 +90,14 @@ def get_person(self, person_id):
         """
         return self.api.get_request(url=f"people/{person_id}")
 
-    def add_person(self, email_address=None, given_name=None, family_name=None, tags=None,
-                   languages_spoken=None, postal_addresses=None, mobile_number=None,
-                   mobile_status='subscribed', **kwargs):
+    def upsert_person(self, email_address=None, given_name=None, family_name=None, tags=None,
+                      languages_spoken=None, postal_addresses=None, mobile_number=None,
+                      mobile_status='subscribed', **kwargs):
         """
+        Creates or updates a person record. In order to update an existing record instead of
+        creating a new one, you must supply an email or mobile number which matches a record
+        in the database.
+
         `Args:`
             email_address:
                 Either email_address or mobile_number are required. Can be any of the following
@@ -197,11 +201,31 @@ def add_person(self, email_address=None, given_name=None, family_name=None, tags
         identifiers = response['identifiers']
         person_id = [entry_id.split(':')[1]
                      for entry_id in identifiers if 'action_network:' in entry_id][0]
-        logger.info(f"Entry {person_id} successfully added to people.")
+        if response['created_date'] == response['modified_date']:
+            logger.info(f"Entry {person_id} successfully added.")
+        else:
+            logger.info(f"Entry {person_id} successfully updated.")
         return response
 
+    def add_person(self, email_address=None, given_name=None, family_name=None, tags=None,
+                   languages_spoken=None, postal_addresses=None, mobile_number=None,
+                   mobile_status='subscribed', **kwargs):
+        """
+        Creates a person in the database. WARNING: this endpoint has been deprecated in favor of
+        upsert_person.
+        """
+        logger.warning("Method 'add_person' has been deprecated. Please use 'upsert_person'.")
+        # Pass inputs to preferred method:
+        self.upsert_person(email_address=email_address, given_name=given_name,
+                           family_name=family_name, languages_spoken=languages_spoken,
+                           postal_addresses=postal_addresses, mobile_number=mobile_number,
+                           mobile_status=mobile_status, **kwargs)
+
     def update_person(self, entry_id, **kwargs):
         """
+        Updates a person's data in Action Network, given their Action Network ID. Note that you
+        can't alter a person's tags with this method. Instead, use upsert_person.
+
         `Args:`
             entry_id:
                 The person's Action Network id
@@ -225,8 +249,6 @@ def update_person(self, entry_id, **kwargs):
                         The person's given name
                     family_name:
                         The person's family name
-                    tags:
-                        Any tags to be applied to the person
                     languages_spoken:
                         Optional field. A list of strings of the languages spoken by the person
                     postal_addresses:
@@ -235,11 +257,10 @@ def update_person(self, entry_id, **kwargs):
                         https://actionnetwork.org/docs/v2/people#put
                     custom_fields:
                         A dictionary of any other fields to store about the person.
-        Updates a person's data in Action Network
         """
         data = {**kwargs}
         response = self.api.put_request(url=f"{self.api_url}/people/{entry_id}",
-                                        json=json.dumps(data), success_codes=[204, 201, 200])
+                                        data=json.dumps(data), success_codes=[204, 201, 200])
         logger.info(f"Person {entry_id} successfully updated")
         return response
 

test/test_action_network/test_action_network.py

@@ -20,8 +20,8 @@ def setUp(self, m):
         self.fake_customer_email_1 = 'fake_customer_email_1@fake_customer_email.com'
         self.fake_customer_email_2 = 'fake_customer_email_2@fake_customer_email.com'
         self.fake_filter_by_email_1 = f"filter eq '{self.fake_customer_email_1}'"
-        self.fake_person_id_1 = "fake_person_id_1"
-        self.fake_person_id_2 = "fake_person_id_2"
+        self.fake_person_id_1 = "action_network:fake_person_id_1"
+        self.fake_person_id_2 = "action_network:fake_person_id_2"
         self.fake_tag_id_1 = "fake_tag_id_1"
         self.fake_tag_id_2 = "fake_tag_id_2"
         self.fake_tag_filter = "name eq 'fake_tag_1'"
@@ -133,6 +133,16 @@ def setUp(self, m):
                                       'modified_date': self.fake_datetime,
                                       'identifiers': [self.fake_tag_id_1],
                                       '_links': {'self': {'href': self.fake_tag_id_1}}}]}}
+        self.fake_upsert_person = {
+            'given_name': 'Fakey',
+            'family_name': 'McFakerson',
+            'identifiers': [self.fake_person_id_1],
+            'email_address': [{'primary': True,
+                               'address': '[email protected]',
+                               'status': 'unsubscribed'}],
+            'created_date': self.fake_datetime,
+            'modified_date': self.fake_datetime
+        }
         self.fake_person = [
                {'given_name': 'Fakey',
                 'family_name': 'McFakerson',
@@ -264,6 +274,11 @@ def test_get_tag(self, m):
         m.get(f"{self.api_url}/tags/{self.fake_tag_id_1}", text=json.dumps(self.fake_tag))
         self.assertEqual(self.an.get_tag(self.fake_tag_id_1), self.fake_tag)
 
+    @requests_mock.Mocker()
+    def test_upsert_person(self, m):
+        m.post(f"{self.api_url}/people", text=json.dumps(self.fake_upsert_person))
+        self.assertEqual(self.an.upsert_person(**self.fake_upsert_person), self.fake_upsert_person)
+
     @requests_mock.Mocker()
     def test_update_person(self, m):
         m.put(f"{self.api_url}/people/{self.fake_person_id_1}",