Add utility to format composite resource names (#52)

examples/basic_operations/pause_ad.py

@@ -19,8 +19,9 @@
 import six
 import sys
 
-import google.ads.google_ads.client
 from google.api_core import protobuf_helpers
+from google.ads.google_ads.client import GoogleAdsClient
+from google.ads.google_ads.util import ResourceName
 
 
 def main(client, customer_id, ad_group_id, ad_id):
@@ -30,7 +31,7 @@ def main(client, customer_id, ad_group_id, ad_id):
 
     ad_group_ad = ad_group_ad_operation.update
     ad_group_ad.resource_name = ad_group_ad_service.ad_group_ad_path(
-        customer_id, '%s_%s' % (ad_group_id, ad_id))
+        customer_id, ResourceName.format_composite(ad_group_id, ad_id))
     ad_group_ad.status = client.get_type('AdGroupStatusEnum',
                                          version='v1').PAUSED
     fm = protobuf_helpers.field_mask(None, ad_group_ad)
@@ -56,9 +57,7 @@ def main(client, customer_id, ad_group_id, ad_id):
 if __name__ == '__main__':
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    google_ads_client = (google.ads.google_ads.client.GoogleAdsClient
-                         .load_from_storage())
-
+    google_ads_client = GoogleAdsClient.load_from_storage()
     parser = argparse.ArgumentParser(
         description=('Pauses an ad in the specified customer\'s ad group.'))
     # The following argument(s) should be provided to run the example.

examples/basic_operations/remove_ad.py

@@ -19,15 +19,15 @@
 import six
 import sys
 
-import google.ads.google_ads.client
-
+from google.ads.google_ads.client import GoogleAdsClient
+from google.ads.google_ads.util import ResourceName
 
 def main(client, customer_id, ad_group_id, ad_id):
     ad_group_ad_service = client.get_service('AdGroupAdService', version='v1')
     ad_group_ad_operation = client.get_type('AdGroupAdOperation', version='v1')
 
     resource_name = ad_group_ad_service.ad_group_ad_path(
-        customer_id, '%s_%s' % (ad_group_id, ad_id))
+        customer_id, ResourceName.format_composite(ad_group_id, ad_id))
     ad_group_ad_operation.remove = resource_name
 
     try:
@@ -50,9 +50,7 @@ def main(client, customer_id, ad_group_id, ad_id):
 if __name__ == '__main__':
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    google_ads_client = (google.ads.google_ads.client.GoogleAdsClient
-                         .load_from_storage())
-
+    google_ads_client = GoogleAdsClient.load_from_storage()
     parser = argparse.ArgumentParser(
         description=('Removes an ad from the specified customer\'s ad group.'))
     # The following argument(s) should be provided to run the example.

examples/basic_operations/remove_keyword.py

@@ -19,15 +19,16 @@
 import six
 import sys
 
-import google.ads.google_ads.client
+from google.ads.google_ads.client import GoogleAdsClient
+from google.ads.google_ads.util import ResourceName
 
 
 def main(client, customer_id, ad_group_id, criteria_id):
     agc_service = client.get_service('AdGroupCriterionService', version='v1')
     agc_operation = client.get_type('AdGroupCriterionOperation', version='v1')
 
     resource_name = agc_service.ad_group_criteria_path(
-        customer_id, '%s_%s' % (ad_group_id, criteria_id))
+        customer_id, ResourceName.format_composite(ad_group_id, criteria_id))
     agc_operation.remove = resource_name
 
     try:
@@ -49,9 +50,7 @@ def main(client, customer_id, ad_group_id, criteria_id):
 if __name__ == '__main__':
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    google_ads_client = (google.ads.google_ads.client.GoogleAdsClient
-                         .load_from_storage())
-
+    google_ads_client = GoogleAdsClient.load_from_storage()
     parser = argparse.ArgumentParser(
         description=('Removes given campaign for the specified customer.'))
     # The following argument(s) should be provided to run the example.

examples/basic_operations/update_keyword.py

@@ -19,8 +19,9 @@
 import six
 import sys
 
-import google.ads.google_ads.client
 from google.api_core import protobuf_helpers
+from google.ads.google_ads.client import GoogleAdsClient
+from google.ads.google_ads.util import ResourceName
 
 
 def main(client, customer_id, ad_group_id, criterion_id):
@@ -31,7 +32,7 @@ def main(client, customer_id, ad_group_id, criterion_id):
 
     ad_group_criterion = ad_group_criterion_operation.update
     ad_group_criterion.resource_name = agc_service.ad_group_criteria_path(
-        customer_id, '%s_%s' % (ad_group_id, criterion_id))
+        customer_id, ResourceName.format_composite(ad_group_id, criterion_id))
     ad_group_criterion.status = (client.get_type('AdGroupCriterionStatusEnum',
                                                  version='v1')
                                  .ENABLED)
@@ -59,9 +60,7 @@ def main(client, customer_id, ad_group_id, criterion_id):
 if __name__ == '__main__':
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    google_ads_client = (google.ads.google_ads.client.GoogleAdsClient
-                         .load_from_storage())
-
+    google_ads_client = GoogleAdsClient.load_from_storage()
     parser = argparse.ArgumentParser(
         description=('Pauses an ad in the specified customer\'s ad group.'))
     # The following argument(s) should be provided to run the example.

google/ads/google_ads/__init__.py

@@ -18,6 +18,7 @@
 
 import google.ads.google_ads.client
 import google.ads.google_ads.errors
+import google.ads.google_ads.util
 
 
 VERSION = '1.2.0'

google/ads/google_ads/util.py

@@ -0,0 +1,43 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Common utilities for the Google Ads API client library."""
+
+
+class ResourceName:
+
+    # As of Google Ads API v1 composite resource names are
+    # delimited by a "~" character.
+    _COMPOSITE_DELIMITER = '~'
+
+    @classmethod
+    def format_composite(cls, *arg):
+        """Formats any number of ID strings into a single composite string.
+
+        Note: this utility does not construct an entire resource name string.
+        It only formats the composite portion for IDs that are not globally
+        unique, for example an ad_group_ad.
+
+        Args:
+            arg: Any number of str IDs for resources such as ad_groups or
+            ad_group_ads.
+
+        Returns:
+            A str of all the given strs concatenated with the compsite
+            delimiter.
+
+        Raises:
+           TypeError: If anything other than a string is passed in.
+        """
+        return cls._COMPOSITE_DELIMITER.join(arg)
+

tests/util_test.py

@@ -0,0 +1,25 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for the Google Ads API client library utilities."""
+
+
+from unittest import TestCase
+
+from google.ads.google_ads.util import ResourceName
+
+class ResourceNameTest(TestCase):
+    def test_format_composite(self):
+        composite = ResourceName.format_composite('test', 'test')
+        self.assertEqual(composite, 'test~test')
+