service-objects 0.1.0__py3-none-any.whl

service_objects/__init__.py

@@ -0,0 +1,7 @@
+def __getattr__(name):
+    if name == "AV3":
+        from .av3 import AV3
+        return AV3
+    raise AttributeError(f"module {__name__} has no attribute {name}")
+
+__all__ = ["AV3"]

service_objects/av3.py

@@ -0,0 +1,224 @@
+"""
+Service Objects, Inc.
+
+AV3 client for validating and standardizing US addresses
+using Service Objects AV3 API. Handles production/trial/backup
+endpoints, fallback logic, and JSON parsing.
+"""
+
+from __future__ import annotations
+from typing import Any
+from .base import BaseClient
+import requests
+
+class AV3(BaseClient):
+    _ENDPOINTS = {
+        "production": "https://sws.serviceobjects.com/AV3/api.svc",
+        "backup":     "https://swsbackup.serviceobjects.com/AV3/api.svc",
+        "trial":      "https://trial.serviceobjects.com/AV3/api.svc",
+    }
+
+    def __init__(self, *, license_key: str, environment: str = "production", **kwargs):
+        if environment not in self._ENDPOINTS:
+            raise ValueError(f"Unknown environment: {environment}")
+
+        self.environment = environment
+        self.primary_url = self._ENDPOINTS[environment]
+        self.backup_url = (
+            self._ENDPOINTS["backup"]
+            if environment == "production"
+            else None
+        )
+
+        super().__init__(
+            base_url=self.primary_url,
+            license_key=license_key,
+            **kwargs
+        )
+
+    def _request_with_fallback(
+        self,
+        *,
+        path: str,
+        params: dict[str, Any],
+    ) -> dict:
+        try:
+            data = self._request(path=path, params=params)
+
+            if self.environment == "production" and data.get("Error"):
+                type_code = (data["Error"] or {}).get("TypeCode")
+                if type_code == "3" and self.backup_url:
+                    data = self._request_direct(self.backup_url, path, params)
+
+            return data
+
+        except requests.RequestException as e:
+            if self.environment == "production" and self.backup_url:
+                data = self._request_direct(self.backup_url, path, params)
+                if data.get("Error"):
+                    raise RuntimeError(f"AV3 backup error: {data['Error']}") from e
+                return data
+
+            raise RuntimeError(f"AV3 {self.environment} error: {str(e)}") from e
+
+    def _request_direct(self, base_url: str, path: str, params: dict[str, Any]) -> dict:
+        p = dict(params)
+        p["LicenseKey"] = self.license_key
+        url = f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+        resp = self.session.get(url, params=p, timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+    def GetBestMatches(
+        self,
+        *,
+        business_name: str = "",
+        address: str,
+        address_2: str = "",
+        city: str = "",
+        state: str = "",
+        postal_code: str = "",
+        **extra_params: Any,
+    ) -> dict[str, Any]:
+        """
+        Validate and standardize a US address using AV3.
+
+        Args:
+            business_name: Company name to assist suite parsing.
+            address: Primary street address (e.g., "123 Main St"). Required.
+            address_2: Secondary address information (e.g., "Apt 4B", "C/O John Smith").
+            city: City name. Required if postal_code is not provided.
+            state: State code or full name. Required if postal_code is not provided.
+            postal_code: 5- or 9-digit ZIP. Required if city/state are not provided.
+            **extra_params: Additional AV3 query parameters.
+
+        Returns:
+            Parsed JSON response containing address candidates, corrections, or an error payload.
+
+        Raises:
+            RuntimeError: If the service returns an error payload or all endpoints are unreachable.
+        """
+        params = {
+            "BusinessName": business_name,
+            "Address": address,
+            "Address2": address_2,
+            "City": city,
+            "State": state,
+            "PostalCode": postal_code,
+            **extra_params,
+        }
+
+        return self._request_with_fallback(
+            path="GetBestMatchesJson",
+            params=params,
+        )
+
+    def GetBestMatchesSingleLine(
+        self,
+        *,
+        business_name: str = "",
+        address: str,
+        **extra_params: Any,
+    ) -> dict[str, Any]:
+        """
+        Validate and standardize a single-line US address using AV3.
+
+        Args:
+            business_name: Company name to assist suite parsing.
+            address: Full address in one line (e.g., "123 Main St, Anytown CA 99999").
+            **extra_params: Additional AV3 query parameters.
+
+        Returns:
+            Parsed JSON response containing the best match candidate or an error payload.
+
+        Raises:
+            RuntimeError: If the service returns an error payload or all endpoints are unreachable.
+        """
+
+        params = {
+            "BusinessName": business_name,
+            "Address": address,
+            **extra_params,
+        }
+
+        return self._request_with_fallback(
+            path="GetBestMatchesSingleLineJson",
+            params=params,
+        )
+    
+    def ValidateCityStateZip(
+        self,
+        *,
+        city: str = "",
+        state: str = "",
+        zip: str = "",
+        **extra_params: Any,
+    ) -> dict[str, Any]:
+        """
+        Validate a City/State/ZIP combination using AV3.
+
+        Args:
+            city: City name. Required if postal_code is not provided.
+            state: State code or full name. Required if postal_code is not provided.
+            zip: 5- or 9-digit ZIP. Required if city/state are not provided.
+            **extra_params: Additional AV3 query parameters.
+
+        Returns:
+            Parsed JSON response containing location validation results or an error payload.
+
+        Raises:
+            RuntimeError: If the service returns an error payload or all endpoints are unreachable.
+        """
+        params = {
+            "City": city,
+            "State": state,
+            "ZIP": zip,
+            **extra_params,
+        }
+
+        return self._request_with_fallback(
+            path="ValidateCityStateZipJson",
+            params=params,
+        )
+    
+    def GetSecondaryNumbers(
+        self,
+        *,
+        address: str,
+        city: str = "",
+        state: str = "",
+        postal_code: str = "",
+        **extra_params: Any,
+    ) -> dict[str, Any]:
+        """
+        Retrieve potential secondary numbers (unit/suite) for a U.S. address using AV3.
+
+        This operation complements GetBestMatches by returning plausible secondary numbers
+        when the input address is missing or has incorrect unit information.
+
+        Args:
+            address: Primary street address (e.g., "123 Main St"). Required.
+            city: City name. Required if postal_code is not provided.
+            state: State code or full name. Required if postal_code is not provided.
+            postal_code: 5- or 9-digit ZIP. Required if city/state are not provided.
+            **extra_params: Additional AV3 query parameters.
+
+        Returns:
+            Parsed JSON response containing validated address elements and a list of
+            possible secondary numbers, or an error payload.
+
+        Raises:
+            RuntimeError: If the service returns an error payload or all endpoints are unreachable.
+        """
+        params = {
+            "Address": address,
+            "City": city,
+            "State": state,
+            "PostalCode": postal_code,
+            **extra_params,
+        }
+
+        return self._request_with_fallback(
+            path="GetSecondaryNumbersJson",
+            params=params,
+        )

service_objects/base.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+from typing import Any, Optional
+import requests
+
+class BaseClient:
+    def __init__(self, *, base_url: str, license_key: str, session: Optional[requests.Session] = None, timeout: float = 10.0):
+        if not license_key:
+            raise ValueError("license_key is required")
+        self.base_url = base_url.rstrip("/")
+        self.license_key = license_key
+        self.session = session or requests.Session()
+        self.timeout = timeout
+
+    def _request(self, *, path: str, params: dict[str, Any] | None = None) -> Any:
+        params = dict(params or {})
+        params["LicenseKey"] = self.license_key
+
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        resp = self.session.get(url, params=params, timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.json()

service_objects-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: service-objects
+Version: 0.1.0
+Summary: Python client for Service Objects APIs
+Project-URL: Homepage, https://github.com/serviceobjects/service-objects
+Author-email: Jan Rehorik <jrehorik@serviceobjects.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: requests-mock; extra == 'dev'

service_objects-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+service_objects/__init__.py,sha256=lvEp3S2sh4PIMkaOO6OIrmfF8Bz2wTQnpJu00zf5ttc,188
+service_objects/av3.py,sha256=de1W8JzrATa-ovC6Dt29fyZFktpVHXo3JPVwKQm_6RQ,7654
+service_objects/base.py,sha256=GHGUWYqZrDrh-sbrwR5LUgxQ5TJya05-v7P29icCWqk,855
+service_objects-0.1.0.dist-info/METADATA,sha256=wDGCyZIqmfIEncme37Zj206jxjTfkl4aoLgpcQO5_GY,483
+service_objects-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+service_objects-0.1.0.dist-info/licenses/LICENSE,sha256=ul3mBFUa57euquRnv1vpwLouANels2Wz-A8YYfh9CEw,1097
+service_objects-0.1.0.dist-info/RECORD,,

service_objects-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

service_objects-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Service Objects, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.