Add US Enrichment Business API with ETag support

Ports the US Business Enrichment API from smartystreets-dotnet-sdk 13.0.0
and fills in example coverage for the rest of the Enrichment client.

- New Business.Summary endpoint (send_business_lookup) accepting either a
  smartykey or address components, returning BusinessSummaryResponse with
  a list of BusinessEntry records.
- New Business.Detail endpoint (send_business_detail_lookup) hitting
  /business/{business_id} and returning a scalar BusinessDetailResponse
  with ~153 attribute fields.
- First-class ETag round trip: set request_etag on the Lookup to send an
  Etag request header; 200 responses capture the server Etag into
  response_etag; 304 responses raise NotModifiedError carrying the
  refreshed Etag. Case-insensitive header extraction via a new
  Response.find_header helper.
- Extract LookupBase so Lookup and BusinessDetailLookup share
  include/exclude/custom-parameter/etag state, matching the dotnet
  EnrichmentLookupBase split.
- Tighten validation: reject whitespace-only smartykey/street/freeform on
  the standard Lookup and whitespace-only business_id on
  BusinessDetailLookup.
- Refactor the Enrichment client for idiomatic style: collapse the
  duplicated send_lookup/send_business_lookup bodies into one function
  parameterized by response class, and consolidate build_request into
  decomposed helpers (_url_components, _address_parameters,
  _common_parameters, _apply_etag_header) so a Request is populated in a
  single pass instead of being mutated across build_request and a
  follow-up _apply_common_request_fields call.
- Add examples for every public send_* method on the Enrichment client:
  business, etag, geo-reference, risk, secondary, secondary-count, and
  the generic dataset/data_subset pass-through.

Author: RyanLCox1

examples/us_enrichment_business_example.py

@@ -0,0 +1,63 @@
+import os
+
+from smartystreets_python_sdk import BasicAuthCredentials, ClientBuilder
+
+
+def run():
+    auth_id = os.environ['SMARTY_AUTH_ID']
+    auth_token = os.environ['SMARTY_AUTH_TOKEN']
+
+    credentials = BasicAuthCredentials(auth_id, auth_token)
+    client = ClientBuilder(credentials).build_us_enrichment_api_client()
+
+    smarty_key = "1962995076"
+
+    try:
+        summary_results = client.send_business_lookup(smarty_key)
+    except Exception as err:
+        print(err)
+        return
+
+    if not summary_results:
+        print("No response returned for SmartyKey {}".format(smarty_key))
+        return
+
+    summary = summary_results[0]
+    if not summary.businesses:
+        print("SmartyKey {} has no business tenants".format(smarty_key))
+        return
+
+    print("Summary results for SmartyKey: {}".format(smarty_key))
+    for biz in summary.businesses:
+        print("  - {} (ID: {})".format(biz.company_name, biz.business_id))
+
+    first = summary.businesses[0]
+    print("\nFetching details for business: {} (ID: {})".format(first.company_name, first.business_id))
+
+    try:
+        detail_result = client.send_business_detail_lookup(first.business_id)
+    except Exception as err:
+        print(err)
+        return
+
+    if detail_result is None:
+        print("\nNo detail result returned")
+        return
+
+    print("\nDetail result:")
+    print_result(detail_result)
+
+
+def print_result(obj):
+    for key, value in vars(obj).items():
+        if value is None:
+            continue
+        if key == 'attributes':
+            print_result(value)
+            continue
+        print("{}: {}".format(key, value))
+    print()
+
+
+if __name__ == "__main__":
+    run()

examples/us_enrichment_etag_example.py

@@ -0,0 +1,132 @@
+import os
+
+from smartystreets_python_sdk import BasicAuthCredentials, ClientBuilder
+from smartystreets_python_sdk.exceptions import NotModifiedError
+from smartystreets_python_sdk.us_enrichment import BusinessDetailLookup, BusinessLookup
+
+
+def run():
+    auth_id = os.environ['SMARTY_AUTH_ID']
+    auth_token = os.environ['SMARTY_AUTH_TOKEN']
+
+    credentials = BasicAuthCredentials(auth_id, auth_token)
+    client = ClientBuilder(credentials).build_us_enrichment_api_client()
+
+    smarty_key = "1962995076"
+
+    business_id = exercise_summary_etag(client, smarty_key)
+    if business_id is None:
+        return
+
+    exercise_detail_etag(client, business_id)
+
+
+def exercise_summary_etag(client, smarty_key):
+    print("=== Business.Summary ETag round trip ===")
+
+    first = BusinessLookup(smarty_key)
+    try:
+        client.send_business_lookup(first)
+    except Exception as ex:
+        print("  Initial Summary call failed: {}".format(ex))
+        return None
+
+    initial_results = first.result
+    captured_etag = first.response_etag
+    print("  Call 1 (no Etag): captured Etag={}, results={}".format(
+        display(captured_etag), len(initial_results or [])))
+
+    if not captured_etag:
+        print("  Server did not return an Etag header; skipping conditional calls.")
+        return first_business_id(initial_results)
+
+    second = BusinessLookup(smarty_key)
+    second.request_etag = captured_etag
+    try:
+        client.send_business_lookup(second)
+        print("  Call 2 (matching Etag): 200 — server did NOT honor the conditional. Results={}, Etag={}".format(
+            len(second.result or []), display(second.response_etag)))
+    except NotModifiedError as ex:
+        print("  Call 2 (matching Etag): 304 NotModifiedError — caller treats this as cache-valid. Refreshed Etag={}".format(
+            display(ex.response_etag)))
+    except Exception as ex:
+        print("  Call 2 unexpected failure: {}: {}".format(type(ex).__name__, ex))
+        return None
+
+    third = BusinessLookup(smarty_key)
+    third.request_etag = captured_etag + "X"
+    try:
+        client.send_business_lookup(third)
+        print("  Call 3 (mutated Etag): 200 as expected. Results={}, Etag={}".format(
+            len(third.result or []), display(third.response_etag)))
+    except NotModifiedError:
+        print("  Call 3 (mutated Etag): 304 — UNEXPECTED. Server treated a different Etag as matching.")
+    except Exception as ex:
+        print("  Call 3 unexpected failure: {}: {}".format(type(ex).__name__, ex))
+
+    return first_business_id(initial_results)
+
+
+def exercise_detail_etag(client, business_id):
+    print()
+    print("=== Business.Detail ETag round trip (businessId: {}) ===".format(business_id))
+
+    first = BusinessDetailLookup(business_id)
+    try:
+        client.send_business_detail_lookup(first)
+    except Exception as ex:
+        print("  Initial Detail call failed: {}".format(ex))
+        return
+
+    initial = first.result
+    captured_etag = first.response_etag
+    initial_id = initial.business_id if initial is not None else "<null>"
+    print("  Call 1 (no Etag): captured Etag={}, businessId={}".format(
+        display(captured_etag), initial_id))
+
+    if not captured_etag:
+        print("  Server did not return an Etag header; skipping conditional calls.")
+        return
+
+    second = BusinessDetailLookup(business_id)
+    second.request_etag = captured_etag
+    try:
+        client.send_business_detail_lookup(second)
+        second_id = second.result.business_id if second.result is not None else "<null>"
+        print("  Call 2 (matching Etag): 200 — server did NOT honor the conditional. businessId={}, Etag={}".format(
+            second_id, display(second.response_etag)))
+    except NotModifiedError as ex:
+        print("  Call 2 (matching Etag): 304 NotModifiedError — caller treats this as cache-valid. Refreshed Etag={}".format(
+            display(ex.response_etag)))
+    except Exception as ex:
+        print("  Call 2 unexpected failure: {}: {}".format(type(ex).__name__, ex))
+        return
+
+    third = BusinessDetailLookup(business_id)
+    third.request_etag = captured_etag + "X"
+    try:
+        client.send_business_detail_lookup(third)
+        third_id = third.result.business_id if third.result is not None else "<null>"
+        print("  Call 3 (mutated Etag): 200 as expected. businessId={}, Etag={}".format(
+            third_id, display(third.response_etag)))
+    except NotModifiedError:
+        print("  Call 3 (mutated Etag): 304 — UNEXPECTED. Server treated a different Etag as matching.")
+    except Exception as ex:
+        print("  Call 3 unexpected failure: {}: {}".format(type(ex).__name__, ex))
+
+
+def first_business_id(results):
+    if not results:
+        return None
+    businesses = results[0].businesses
+    if not businesses:
+        return None
+    return businesses[0].business_id
+
+
+def display(s):
+    return "<none>" if not s else s
+
+
+if __name__ == "__main__":
+    run()

examples/us_enrichment_generic_example.py

@@ -0,0 +1,60 @@
+import os
+
+from smartystreets_python_sdk import BasicAuthCredentials, ClientBuilder
+from smartystreets_python_sdk.us_enrichment.lookup import Lookup as EnrichmentLookup
+
+
+def run():
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    auth_id = os.environ['SMARTY_AUTH_ID']
+    auth_token = os.environ['SMARTY_AUTH_TOKEN']
+
+    credentials = BasicAuthCredentials(auth_id, auth_token)
+    client = ClientBuilder(credentials).build_us_enrichment_api_client()
+
+    # send_generic_lookup routes a Lookup to any dataset/dataSubset that the
+    # Enrichment API exposes, including new endpoints that may not yet have a
+    # dedicated helper on the client.
+    smarty_key = "87844267"
+    dataset = "property"
+    data_subset = "principal"
+
+    lookup = EnrichmentLookup()
+    freeform_lookup = EnrichmentLookup()
+
+    lookup.smartykey = smarty_key
+    # lookup.street = "1708 Watson Way"
+    # lookup.city = "Vineyard"
+    # lookup.state = "UT"
+    # lookup.zipcode = "84059"
+    lookup.features = "financial"
+
+    # Uncomment to narrow the response with include/exclude attributes
+    # lookup.add_include_attribute('assessed_value')
+    # lookup.add_exclude_attribute('tax_billed_amount')
+
+    freeform_lookup.freeform = "1708 Watson Way Vineyard UT 84059"
+
+    try:
+        # Send a lookup by SmartyKey alone
+        # results = client.send_generic_lookup(smarty_key, dataset, data_subset)
+        # Or send it by address components
+        results = client.send_generic_lookup(lookup, dataset, data_subset)
+        # Or send it by freeform address
+        # results = client.send_generic_lookup(freeform_lookup, dataset, data_subset)
+    except Exception as err:
+        print(err)
+        return
+
+    if not results:
+        print("No results found. This means the SmartyKey or address is likely not valid, or does not have data in this dataset")
+        return
+
+    top_result = results[0]
+
+    print("Here is your result!")
+    print(top_result)
+
+
+if __name__ == "__main__":
+    run()

examples/us_enrichment_geo_reference_example.py

@@ -0,0 +1,60 @@
+import os
+
+from smartystreets_python_sdk import BasicAuthCredentials, ClientBuilder
+from smartystreets_python_sdk.us_enrichment.lookup import GeoReferenceLookup
+
+
+def run():
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    auth_id = os.environ['SMARTY_AUTH_ID']
+    auth_token = os.environ['SMARTY_AUTH_TOKEN']
+
+    credentials = BasicAuthCredentials(auth_id, auth_token)
+    client = ClientBuilder(credentials).build_us_enrichment_api_client()
+
+    smarty_key = "87844267"
+
+    lookup = GeoReferenceLookup()
+    freeform_lookup = GeoReferenceLookup()
+
+    lookup.smartykey = smarty_key
+    # lookup.street = "1708 Watson Way"
+    # lookup.city = "Vineyard"
+    # lookup.state = "UT"
+    # lookup.zipcode = "84059"
+
+    # Uncomment to narrow the response with include/exclude attributes
+    # lookup.add_include_attribute('census_block')
+    # lookup.add_exclude_attribute('place')
+
+    # Uncomment to add a custom parameter
+    # lookup.add_custom_parameter("parameter", "value")
+
+    freeform_lookup.freeform = "1708 Watson Way Vineyard UT 84059"
+
+    try:
+        # Send a lookup by SmartyKey alone
+        # results = client.send_geo_reference_lookup(smarty_key)
+        # Or send it by address components
+        results = client.send_geo_reference_lookup(lookup)
+        # Or send it by freeform address
+        # results = client.send_geo_reference_lookup(freeform_lookup)
+
+        # Or run it through the generic endpoint instead
+        # results = client.send_generic_lookup(smarty_key, 'geo-reference', None)
+    except Exception as err:
+        print(err)
+        return
+
+    if not results:
+        print("No results found. This means the SmartyKey or address is likely not valid, or does not have data in this dataset")
+        return
+
+    top_result = results[0]
+
+    print("Here is your result!")
+    print(top_result)
+
+
+if __name__ == "__main__":
+    run()

examples/us_enrichment_risk_example.py

@@ -0,0 +1,60 @@
+import os
+
+from smartystreets_python_sdk import BasicAuthCredentials, ClientBuilder
+from smartystreets_python_sdk.us_enrichment.lookup import RiskLookup
+
+
+def run():
+    # We recommend storing your secret keys in environment variables instead---it's safer!
+    auth_id = os.environ['SMARTY_AUTH_ID']
+    auth_token = os.environ['SMARTY_AUTH_TOKEN']
+
+    credentials = BasicAuthCredentials(auth_id, auth_token)
+    client = ClientBuilder(credentials).build_us_enrichment_api_client()
+
+    smarty_key = "87844267"
+
+    lookup = RiskLookup()
+    freeform_lookup = RiskLookup()
+
+    lookup.smartykey = smarty_key
+    # lookup.street = "1708 Watson Way"
+    # lookup.city = "Vineyard"
+    # lookup.state = "UT"
+    # lookup.zipcode = "84059"
+
+    # Uncomment to narrow the response with include/exclude attributes
+    # lookup.add_include_attribute('fema_flood_zone')
+    # lookup.add_exclude_attribute('fire_station_distance')
+
+    # Uncomment to add a custom parameter
+    # lookup.add_custom_parameter("parameter", "value")
+
+    freeform_lookup.freeform = "1708 Watson Way Vineyard UT 84059"
+
+    try:
+        # Send a lookup by SmartyKey alone
+        # results = client.send_risk_lookup(smarty_key)
+        # Or send it by address components
+        results = client.send_risk_lookup(lookup)
+        # Or send it by freeform address
+        # results = client.send_risk_lookup(freeform_lookup)
+
+        # Or run it through the generic endpoint instead
+        # results = client.send_generic_lookup(smarty_key, 'risk', None)
+    except Exception as err:
+        print(err)
+        return
+
+    if not results:
+        print("No results found. This means the SmartyKey or address is likely not valid, or does not have data in this dataset")
+        return
+
+    top_result = results[0]
+
+    print("Here is your result!")
+    print(top_result)
+
+
+if __name__ == "__main__":
+    run()