smartystreets-python-sdk 5.6.0__tar.gz → 6.0.0__tar.gz

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: smartystreets_python_sdk
-Version: 5.6.0
+Version: 6.0.0
 Summary: An official library to help Python developers easily access the SmartyStreets APIs
 Home-page: https://github.com/smartystreets/smartystreets-python-sdk
-Download-URL: https://github.com/smartystreets/smartystreets-python-sdk/tarball/5.6.0
+Download-URL: https://github.com/smartystreets/smartystreets-python-sdk/tarball/6.0.0
 Author: SmartyStreets SDK Team
 Author-email: support@smartystreets.com
 License: Apache 2

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/custom_header_sender.py

@@ -14,6 +14,9 @@ class CustomHeaderSender:
     def build_request(self, smarty_request):
         request = Request(url=smarty_request.url_prefix, params=smarty_request.parameters)
         request.headers = self.apply_headers()
+        if smarty_request.headers:
+            for key, value in smarty_request.headers.items():
+                request.headers[key] = value
         if smarty_request.payload:
             request.data = smarty_request.payload
             request.method = 'POST'

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/errors.py

@@ -22,3 +22,5 @@ SERVICE_UNAVAILABLE = "Service Unavailable. Try again later."
 
 GATEWAY_TIMEOUT = "The upstream data provider did not respond in a timely fashion and the request failed. " \
                   "A serious, yet rare occurrence indeed."
+
+NOT_MODIFIED = "Not Modified: The requested record has not been modified since the previous request with the Etag value."

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/exceptions.py

@@ -44,3 +44,9 @@ class GatewayTimeoutError(SmartyException):
 
 class BatchFullError(SmartyException):
     pass
+
+
+class NotModifiedError(SmartyException):
+    def __init__(self, message=None, response_etag=None):
+        super().__init__(message)
+        self.response_etag = response_etag

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/request.py

@@ -10,3 +10,4 @@ class Request:
         self.referer = None
         self.content_type = 'application/json'
         self.auth = None
+        self.headers = {}

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/requests_sender.py

@@ -55,6 +55,9 @@ def build_request(smarty_request):
         request.headers['Content-Type'] = smarty_request.content_type
         if smarty_request.referer:
             request.headers['Referer'] = smarty_request.referer
+        if smarty_request.headers:
+            for key, value in smarty_request.headers.items():
+                request.headers[key] = value
         if smarty_request.auth:
             request.auth = smarty_request.auth
         if smarty_request.payload:

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/response.py

@@ -10,3 +10,12 @@ class Response:
             return None
         else:
             return self.headers[header]
+
+    def find_header(self, name):
+        if self.headers is None:
+            return None
+        target = name.lower()
+        for key, value in self.headers.items():
+            if key.lower() == target:
+                return value
+        return None

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/status_code_sender.py

@@ -25,10 +25,12 @@ class StatusCodeSender:
         response = self.inner.send(request)
 
         if not response.error:
-            if response.status_code != 429:
-                response.error = statuses.get(response.status_code)
-            else:
+            if response.status_code == 304:
+                response.error = exceptions.NotModifiedError(errors.NOT_MODIFIED, response.find_header('etag'))
+            elif response.status_code == 429:
                 response.error = self.parse_rate_limit_response(response)
+            else:
+                response.error = statuses.get(response.status_code)
 
         return response
 

smartystreets_python_sdk-6.0.0/smartystreets_python_sdk/us_enrichment/__init__.py

@@ -0,0 +1,14 @@
+from .business import BusinessDetailAttributes, BusinessDetailResponse, BusinessEntry, BusinessSummaryResponse
+from .client import Client
+from .lookup import (
+    BusinessDetailLookup,
+    BusinessLookup,
+    GeoReferenceLookup,
+    Lookup,
+    LookupBase,
+    PrincipalLookup,
+    RiskLookup,
+    SecondaryCountLookup,
+    SecondaryLookup,
+)
+from .response import *

smartystreets_python_sdk-6.0.0/smartystreets_python_sdk/us_enrichment/client.py

@@ -0,0 +1,206 @@
+from urllib.parse import quote
+
+from smartystreets_python_sdk import Request
+from smartystreets_python_sdk.exceptions import SmartyException
+from .business import BusinessSummaryResponse, BusinessDetailResponse
+from .lookup import (
+    BusinessDetailLookup,
+    BusinessLookup,
+    GeoReferenceLookup,
+    Lookup,
+    PrincipalLookup,
+    RiskLookup,
+    SecondaryCountLookup,
+    SecondaryLookup,
+)
+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_principal_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = PrincipalLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'property'
+            lookup.dataSubset = 'principal'
+            send_lookup(self, lookup)
+            return lookup.result
+
+    def send_geo_reference_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = GeoReferenceLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'geo-reference'
+            lookup.dataSubset = None
+            send_lookup(self, lookup)
+            return lookup.result
+
+    def send_risk_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = RiskLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'risk'
+            lookup.dataSubset = None
+            send_lookup(self, lookup)
+            return lookup.result
+
+    def send_secondary_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = SecondaryLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'secondary'
+            lookup.dataSubset = None
+            send_lookup(self, lookup)
+            return lookup.result
+
+    def send_secondary_count_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = SecondaryCountLookup(lookup)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = 'secondary'
+            lookup.dataSubset = 'count'
+            send_lookup(self, lookup)
+            return lookup.result
+
+    def send_generic_lookup(self, lookup, dataset, dataSubset):
+        if isinstance(lookup, str):
+            l = Lookup(lookup, dataset, dataSubset)
+            send_lookup(self, l)
+            return l.result
+        else:
+            lookup.dataset = dataset
+            lookup.dataSubset = dataSubset
+            send_lookup(self, lookup)
+            return lookup.result
+
+    def send_business_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = BusinessLookup(lookup)
+            send_lookup(self, l, BusinessSummaryResponse)
+            return l.result
+        else:
+            lookup.dataset = 'business'
+            lookup.dataSubset = None
+            send_lookup(self, lookup, BusinessSummaryResponse)
+            return lookup.result
+
+    def send_business_detail_lookup(self, lookup):
+        if isinstance(lookup, str):
+            l = BusinessDetailLookup(lookup)
+            send_business_detail_lookup(self, l)
+            return l.result
+        else:
+            send_business_detail_lookup(self, lookup)
+            return lookup.result
+
+
+def send_lookup(client: Client, lookup, response_class=Response):
+    """
+    Sends a Lookup object to the US Enrichment API and stores the result in the Lookup's result field.
+    """
+    if lookup is None or (
+        _is_blank(getattr(lookup, 'smartykey', None))
+        and _is_blank(getattr(lookup, 'street', None))
+        and _is_blank(getattr(lookup, 'freeform', None))
+    ):
+        raise SmartyException("Lookup requires one of 'smartykey', 'street', or 'freeform' to be set")
+
+    request = build_request(lookup)
+    raw = _dispatch(client, request, lookup)
+    lookup.result = [response_class(candidate) for candidate in raw]
+    return lookup.result
+
+
+def send_business_detail_lookup(client: Client, lookup):
+    if lookup is None or _is_blank(getattr(lookup, 'business_id', None)):
+        raise SmartyException("BusinessDetailLookup requires a non-empty 'business_id'")
+
+    request = Request()
+    request.url_components = 'business/' + quote(lookup.business_id, safe='')
+    request.parameters = _common_parameters(lookup)
+    _apply_etag_header(request, lookup)
+
+    raw = _dispatch(client, request, lookup)
+    if not raw:
+        lookup.result = None
+    elif len(raw) > 1:
+        raise SmartyException(
+            "business detail response contained {} results; expected at most 1".format(len(raw))
+        )
+    else:
+        lookup.result = BusinessDetailResponse(raw[0])
+    return lookup.result
+
+
+def build_request(lookup):
+    request = Request()
+    request.url_components = _url_components(lookup)
+    request.parameters = _address_parameters(lookup)
+    request.parameters.update(_common_parameters(lookup))
+    _apply_etag_header(request, lookup)
+    return request
+
+
+def _url_components(lookup):
+    if lookup.smartykey is not None:
+        base = lookup.smartykey + "/" + lookup.dataset
+    else:
+        base = 'search/' + lookup.dataset
+    if lookup.dataSubset is None:
+        return base
+    return base + "/" + lookup.dataSubset
+
+
+def _address_parameters(lookup):
+    params = {}
+    for key in ('freeform', 'street', 'city', 'state', 'zipcode', 'features'):
+        value = getattr(lookup, key, None)
+        if value:
+            params[key] = value
+    return params
+
+
+def _common_parameters(lookup):
+    params = {}
+    if lookup.include_array:
+        params['include'] = ','.join(lookup.include_array)
+    if lookup.exclude_array:
+        params['exclude'] = ','.join(lookup.exclude_array)
+    for key, value in lookup.custom_parameter_array.items():
+        params[key] = value
+    return params
+
+
+def _apply_etag_header(request, lookup):
+    if lookup.request_etag is not None:
+        request.headers['Etag'] = lookup.request_etag
+
+
+def _dispatch(client, request, lookup):
+    response = client.sender.send(request)
+    lookup.response_etag = response.find_header('etag')
+    if response.error:
+        raise response.error
+    raw = client.serializer.deserialize(response.payload)
+    return raw or []
+
+
+def _is_blank(value):
+    return value is None or (isinstance(value, str) and value.strip() == '')

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/us_enrichment/lookup.py

@@ -4,15 +4,36 @@ geoReferenceDataset = "geo-reference"
 riskDataset = "risk"
 secondaryDataset = "secondary"
 countDataSubset = "count"
+businessDataset = "business"
 noneDataSubset = None
 
-class Lookup:
-    def __init__(self, smartykey = None, dataset = None, dataSubset = None, features = None, freeform = None, street = None, city = None, state = None, zipcode = None):
+
+class LookupBase:
+    def __init__(self):
+        self.include_array = []
+        self.exclude_array = []
+        self.request_etag = None
+        self.response_etag = None
+        self.custom_parameter_array = {}
+
+    def add_custom_parameter(self, parameter, value):
+        self.custom_parameter_array[parameter] = value
+
+    def add_include_attribute(self, attribute):
+        if attribute not in self.include_array:
+            self.include_array.append(attribute)
+
+    def add_exclude_attribute(self, attribute):
+        if attribute not in self.exclude_array:
+            self.exclude_array.append(attribute)
+
+
+class Lookup(LookupBase):
+    def __init__(self, smartykey=None, dataset=None, dataSubset=None, features=None, freeform=None, street=None, city=None, state=None, zipcode=None):
+        super().__init__()
         self.smartykey = smartykey
         self.dataset = dataset
         self.dataSubset = dataSubset
-        self.include_array = []
-        self.exclude_array = []
         self.features = features
         self.freeform = freeform
         self.street = street
@@ -20,35 +41,40 @@ class Lookup:
         self.state = state
         self.zipcode = zipcode
         self.result = []
-        self.custom_parameter_array = {}
-    
-    def add_custom_parameter(self, parameter, value):
-        self.custom_parameter_array[parameter] = value
 
-    def add_include_attribute(self, attribute):
-        if (attribute not in self.include_array):
-            self.include_array.append(attribute)
-    
-    def add_exclude_attribute(self, attribute):
-        if (attribute not in self.exclude_array):
-            self.exclude_array.append(attribute)
 
 class PrincipalLookup(Lookup):
-    def __init__(self, smartykey = None):
+    def __init__(self, smartykey=None):
         super().__init__(smartykey, propertyDataset, principalDataSubset)
 
+
 class GeoReferenceLookup(Lookup):
-    def __init__(self, smartykey = None):
+    def __init__(self, smartykey=None):
         super().__init__(smartykey, geoReferenceDataset, noneDataSubset)
 
+
 class RiskLookup(Lookup):
-    def __init__(self, smartykey = None):
+    def __init__(self, smartykey=None):
         super().__init__(smartykey, riskDataset, noneDataSubset)
 
+
 class SecondaryLookup(Lookup):
-    def __init__(self, smartykey = None):
+    def __init__(self, smartykey=None):
         super().__init__(smartykey, secondaryDataset, noneDataSubset)
 
+
 class SecondaryCountLookup(Lookup):
-    def __init__(self, smartykey = None):
-        super().__init__(smartykey, secondaryDataset, countDataSubset)
+    def __init__(self, smartykey=None):
+        super().__init__(smartykey, secondaryDataset, countDataSubset)
+
+
+class BusinessLookup(Lookup):
+    def __init__(self, smartykey=None):
+        super().__init__(smartykey, businessDataset, noneDataSubset)
+
+
+class BusinessDetailLookup(LookupBase):
+    def __init__(self, business_id=None):
+        super().__init__()
+        self.business_id = business_id
+        self.result = None

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk/us_street/candidate.py

@@ -23,6 +23,7 @@ class Candidate:
         self.last_line = obj.get('last_line', None)
         self.delivery_point_barcode = obj.get('delivery_point_barcode', None)
         self.smarty_key = obj.get('smarty_key', None)
+        self.smarty_key_ext = obj.get('smarty_key_ext', None)
         self.components = Components(obj.get('components', {}))
         self.metadata = Metadata(obj.get('metadata', {}))
         self.analysis = Analysis(obj.get('analysis', {}))
@@ -42,6 +43,7 @@ class Candidate:
             "last_line": self.last_line,
             "delivery_point_barcode": self.delivery_point_barcode,
             "smarty_key": self.smarty_key,
+            "smarty_key_ext": self.smarty_key_ext,
             "components": components_dict or None,
             "metadata": metadata_dict or None,
             "analysis": analysis_dict or None

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: smartystreets_python_sdk
-Version: 5.6.0
+Version: 6.0.0
 Summary: An official library to help Python developers easily access the SmartyStreets APIs
 Home-page: https://github.com/smartystreets/smartystreets-python-sdk
-Download-URL: https://github.com/smartystreets/smartystreets-python-sdk/tarball/5.6.0
+Download-URL: https://github.com/smartystreets/smartystreets-python-sdk/tarball/6.0.0
 Author: SmartyStreets SDK Team
 Author-email: support@smartystreets.com
 License: Apache 2

{smartystreets_python_sdk-5.6.0 → smartystreets_python_sdk-6.0.0}/smartystreets_python_sdk_version/__init__.py

@@ -1,2 +1,2 @@
 __version__ = '0.0.0'  # DO NOT EDIT (this is updated by a build job when a new release is published)
-__version__="5.6.0"
+__version__="6.0.0"

smartystreets_python_sdk-5.6.0/smartystreets_python_sdk/us_enrichment/__init__.py

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

smartystreets_python_sdk-5.6.0/smartystreets_python_sdk/us_enrichment/client.py

@@ -1,158 +0,0 @@
-from smartystreets_python_sdk import Request
-from smartystreets_python_sdk.exceptions import SmartyException
-from .lookup import PrincipalLookup, GeoReferenceLookup, RiskLookup, SecondaryLookup, SecondaryCountLookup, Lookup
-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_principal_lookup(self, lookup):
-        if isinstance(lookup, str):
-            l = PrincipalLookup(lookup)
-            send_lookup(self, l)
-            return l.result
-        else:
-            lookup.dataset = 'property'
-            lookup.dataSubset = 'principal'
-            send_lookup(self, lookup)
-            return lookup.result
-    
-    def send_geo_reference_lookup(self, lookup):
-        if isinstance(lookup, str):
-            l = GeoReferenceLookup(lookup)
-            send_lookup(self, l)
-            return l.result
-        else:
-            lookup.dataset = 'geo-reference'
-            lookup.dataSubset = None
-            send_lookup(self, lookup)
-            return lookup.result
-    
-    def send_risk_lookup(self, lookup):
-        if isinstance(lookup, str):
-            l = RiskLookup(lookup)
-            send_lookup(self, l)
-            return l.result
-        else:
-            lookup.dataset = 'risk'
-            lookup.dataSubset = None
-            send_lookup(self, lookup)
-            return lookup.result
-
-    def send_secondary_lookup(self, lookup):
-        if isinstance(lookup, str):
-            l = SecondaryLookup(lookup)
-            send_lookup(self, l)
-            return l.result
-        else:
-            lookup.dataset = 'secondary'
-            lookup.dataSubset = None
-            send_lookup(self, lookup)
-            return lookup.result
-    
-    def send_secondary_count_lookup(self, lookup):
-        if isinstance(lookup, str):
-            l = SecondaryCountLookup(lookup)
-            send_lookup(self, l)
-            return l.result
-        else:
-            lookup.dataset = 'secondary'
-            lookup.dataSubset = 'count'
-            send_lookup(self, lookup)
-            return lookup.result
-    
-    def send_generic_lookup(self, lookup, dataset, dataSubset):
-        if isinstance(lookup, str):
-            l = Lookup(lookup, dataset, dataSubset)
-            send_lookup(self, l)
-            return l.result
-        else:
-            lookup.dataset = dataset
-            lookup.dataSubset = dataSubset
-            send_lookup(self, lookup)
-            return lookup.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 and lookup.street is None and lookup.freeform is None):
-        raise SmartyException('Client.send() requires a Lookup with either the "smartykey", "street, or "freeform" 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()
-    if lookup.smartykey != None:
-        if lookup.dataSubset == None:
-            request.url_components = lookup.smartykey + "/" + lookup.dataset
-            request.parameters = remap_keys(lookup)
-            return request
-    
-        request.url_components = lookup.smartykey + "/" + lookup.dataset + "/" + lookup.dataSubset
-        request.parameters = remap_keys(lookup)
-
-        return request
-    else:
-        if lookup.dataSubset == None:
-            request.url_components = 'search/' + lookup.dataset
-            request.parameters = remap_keys(lookup)
-            return request
-    
-        request.url_components = 'search/' + lookup.dataset + "/" + lookup.dataSubset
-
-        request.parameters = remap_keys(lookup)
-        return request
-    
-def remap_keys(lookup):
-    converted_lookup = {}
-
-    if (lookup.freeform != None):
-        add_field(converted_lookup, 'freeform', lookup.freeform)
-    if (lookup.street != None):
-        add_field(converted_lookup, 'street', lookup.street)
-    if (lookup.city != None):
-        add_field(converted_lookup, 'city', lookup.city)
-    if (lookup.state != None):
-        add_field(converted_lookup, 'state', lookup.state)
-    if (lookup.zipcode != None):
-        add_field(converted_lookup, 'zipcode', lookup.zipcode)
-    if (lookup.include_array != None):
-        add_field(converted_lookup, 'include', build_filter_string(lookup.include_array))
-    if (lookup.exclude_array != None):
-        add_field(converted_lookup, 'exclude', build_filter_string(lookup.exclude_array))
-    if (lookup.features != None):
-        add_field(converted_lookup, 'features', lookup.features)
-
-
-    for parameter in lookup.custom_parameter_array:
-        add_field(converted_lookup, parameter, lookup.custom_parameter_array[parameter])
-
-    return converted_lookup
-
-
-def add_field(converted_lookup, key, value):
-    if value:
-        converted_lookup[key] = value
-
-def build_filter_string(filter_list):
-    return ','.join(filter_list or []) or None