Landon/enrichment sdk (#44)

Add support for the US Enrichment API

examples/us_enrichment_example.py

@@ -0,0 +1,51 @@
+import os
+
+from smartystreets_python_sdk import SharedCredentials, StaticCredentials, exceptions, ClientBuilder
+
+
+# from smartystreets_python_sdk.us_enrichment import
+
+def run():
+    # key = "Your SmartyStreets Key here"
+    # hostname = "Your Hostname here"
+
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    # for client-side requests (browser/mobile), use this code:
+    key = os.environ['SMARTY_AUTH_WEB']
+    hostname = os.environ['SMARTY_WEBSITE_DOMAIN']
+
+    credentials = SharedCredentials(key, hostname)
+
+    # for server-to-server requests, use this code:
+    # auth_id = os.environ['SMARTY_AUTH_ID']
+    # auth_token = os.environ['SMARTY_AUTH_TOKEN']
+    #
+    # credentials = StaticCredentials(auth_id, auth_token)
+
+    # The appropriate license values to be used for your subscriptions
+    # can be found on the Subscriptions page of the account dashboard.
+    # https://www.smartystreets.com/docs/cloud/licensing
+    client = ClientBuilder(credentials).with_licenses(["us-property-data-principal-cloud"]).build_us_enrichment_api_client()
+    # client = ClientBuilder(credentials).with_custom_header({'User-Agent': 'smartystreets (python@0.0.0)', 'Content-Type': 'application/json'}).build_us_enrichment_api_client()
+    # client = ClientBuilder(credentials).with_proxy('localhost:8080', 'user', 'password').build_us_street_api_client()
+    # Uncomment the line above to try it with a proxy instead
+
+    smarty_key = "1682393594"
+    try:
+        results = client.send_property_principal_lookup(smarty_key)
+    except Exception as err:
+        print(err)
+        return
+
+    if not results:
+        print("No results found. This means the Smartykey is likely not valid.")
+        return
+
+    top_result = results[0]
+
+    print("Here is your result!")
+    print(top_result)
+
+
+if __name__ == "__main__":
+    run()

setup.py

@@ -18,7 +18,8 @@
         'smartystreets_python_sdk.international_street',
         'smartystreets_python_sdk.us_reverse_geo',
         'smartystreets_python_sdk.us_autocomplete_pro',
-        'smartystreets_python_sdk.international_autocomplete'
+        'smartystreets_python_sdk.international_autocomplete',
+        'smartystreets_python_sdk.us_enrichment'
     ],
     version=__version__,
     description='An official library to help Python developers easily access the SmartyStreets APIs',

smartystreets_python_sdk/client_builder.py

@@ -7,6 +7,7 @@
 from smartystreets_python_sdk.us_reverse_geo import Client as USReverseGeoClient
 from smartystreets_python_sdk.international_street import Client as InternationalStreetClient
 from smartystreets_python_sdk.international_autocomplete import Client as InternationalAutocompleteClient
+from smartystreets_python_sdk.us_enrichment import Client as USEnrichmentClient
 
 
 class ClientBuilder:
@@ -33,7 +34,8 @@ def __init__(self, signer):
         self.US_EXTRACT_API_URL = "https://us-extract.api.smarty.com"
         self.US_STREET_API_URL = "https://us-street.api.smarty.com/street-address"
         self.US_ZIP_CODE_API_URL = "https://us-zipcode.api.smarty.com/lookup"
-        self.US_REVERSE_GEO_API_URL =  "https://us-reverse-geo.api.smarty.com/lookup"
+        self.US_REVERSE_GEO_API_URL = "https://us-reverse-geo.api.smarty.com/lookup"
+        self.US_ENRICHMENT_API_URL = "https://us-enrichment.api.smarty.com/lookup/"
 
     def retry_at_most(self, max_retries):
         """
@@ -152,6 +154,10 @@ def build_us_reverse_geo_api_client(self):
         self.ensure_url_prefix_not_null(self.US_REVERSE_GEO_API_URL)
         return USReverseGeoClient(self.build_sender(), self.serializer)
 
+    def build_us_enrichment_api_client(self):
+        self.ensure_url_prefix_not_null(self.US_ENRICHMENT_API_URL)
+        return USEnrichmentClient(self.build_sender(), self.serializer)
+
     def build_sender(self):
         if self.http_sender is not None:
             return self.http_sender

smartystreets_python_sdk/us_enrichment/__init__.py

@@ -0,0 +1,2 @@
+from .client import Client
+from .response import *

smartystreets_python_sdk/us_enrichment/client.py

@@ -0,0 +1,52 @@
+from smartystreets_python_sdk import Request
+from smartystreets_python_sdk.exceptions import SmartyException
+from .lookup import FinancialLookup, PrincipalLookup
+from .response import Response
+
+
+class Client:
+    def __init__(self, sender, serializer):
+        """
+        It is recommended to instantiate this class using ClientBuilder.build_us_enrichment_api_client()
+        """
+        self.sender = sender
+        self.serializer = serializer
+
+    def send_property_financial_lookup(self, smartykey):
+        l = FinancialLookup(smartykey)
+        send_lookup(self, l)
+        return l.result
+
+    def send_property_principal_lookup(self, smartykey):
+        l = PrincipalLookup(smartykey)
+        send_lookup(self, l)
+        return l.result
+
+
+def send_lookup(client: Client, lookup):
+    """
+    Sends a Lookup object to the US Enrichment API and stores the result in the Lookup's result field.
+    """
+    if lookup is None or lookup.smartykey is None or not isinstance(lookup.smartykey, str) or len(
+            lookup.smartykey.strip()) == 0:
+        raise SmartyException('Client.send() requires a Lookup with the "smartykey" field set as a string')
+
+    request = build_request(lookup)
+
+    response = client.sender.send(request)
+    if response.error:
+        raise response.error
+
+    response = client.serializer.deserialize(response.payload)
+    result = []
+    for candidate in response:
+        result.append(Response(candidate))
+    lookup.result = result
+    return result
+
+
+def build_request(lookup):
+    request = Request()
+    request.url_prefix = lookup.smartykey + "/" + lookup.dataset + "/" + lookup.dataSubset
+
+    return request

smartystreets_python_sdk/us_enrichment/lookup.py

@@ -0,0 +1,18 @@
+propertyDataset = "property"
+financialDataSubset = "financial"
+principalDataSubset = "principal"
+
+class Lookup:
+    def __init__(self, smartykey, dataset, dataSubset):
+        self.smartykey = smartykey
+        self.dataset = dataset
+        self.dataSubset = dataSubset
+        self.result = []
+
+class FinancialLookup(Lookup):
+    def __init__(self, smartykey):
+        super().__init__(smartykey, propertyDataset, financialDataSubset)
+
+class PrincipalLookup(Lookup):
+    def __init__(self, smartykey):
+        super().__init__(smartykey, propertyDataset, principalDataSubset)