salestax-python 0.1.0__py3-none-any.whl

salestax/resources/tax.py

@@ -0,0 +1,146 @@
+"""``client.tax`` resource."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Union
+
+from .._config import MAX_BATCH_SIZE
+from ..errors import ValidationError
+from ..models import BatchResult, CalculateTaxParams, TaxCalculation
+from ..utils import chunk
+
+_TransactionLike = Union[CalculateTaxParams, dict[str, Any]]
+
+
+def _amount(value: Any) -> float:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise ValidationError(
+            "INVALID_AMOUNT",
+            "amount must be a non-negative number",
+            status_code=400,
+            param="amount",
+        )
+    amount = float(value)
+    if amount < 0:
+        raise ValidationError(
+            "INVALID_AMOUNT",
+            "amount must be a non-negative number",
+            status_code=400,
+            param="amount",
+        )
+    return amount
+
+
+class TaxResource:
+    """Tax calculation endpoints. Do not instantiate directly."""
+
+    def __init__(self, http: Any, *, chunk_batch: bool = False) -> None:
+        self._http = http
+        self._chunk_batch = chunk_batch
+
+    def calculate(
+        self,
+        *,
+        zip_code: str,
+        amount: float,
+        state: str | None = None,
+        country: str | None = None,
+        city: str | None = None,
+        idempotency_key: str | None = None,
+        retryable: bool = True,
+    ) -> TaxCalculation:
+        """Calculate tax for a single transaction.
+
+        Raises:
+            ValidationError: If ``zip_code`` or ``amount`` is invalid.
+            ApiError: If the API returns a non-2xx response.
+        """
+        if not zip_code:
+            raise ValidationError(
+                "MISSING_PARAM", "zip_code is required", status_code=400, param="zip_code"
+            )
+        _amount(amount)
+
+        payload: dict[str, Any] = {"zipCode": zip_code, "amount": amount}
+        if state is not None:
+            payload["state"] = state
+        if country is not None:
+            payload["country"] = country
+        if city is not None:
+            payload["city"] = city
+
+        return self._http.send("POST", "/calculate", body=payload)  # type: ignore[no-any-return]
+
+    def calculate_batch(
+        self,
+        transactions: Sequence[_TransactionLike],
+        *,
+        idempotency_key: str | None = None,
+        retryable: bool = True,
+    ) -> BatchResult:
+        """Calculate tax for up to 100 transactions in one call.
+
+        Raises:
+            ValidationError: If the batch is empty, exceeds 100 items without
+                ``chunk_batch=True``, or contains an invalid amount.
+        """
+        self._validate_batch(transactions)
+        for t in transactions:
+            _amount(t.get("amount"))
+        payload = {"transactions": list(transactions)}
+        return self._http.send(  # type: ignore[no-any-return]
+            "POST",
+            "/calculate/batch",
+            body=payload,
+            options=_request_options(idempotency_key, retryable),
+        )
+
+    def calculate_batch_chunked(
+        self,
+        transactions: Sequence[_TransactionLike],
+        *,
+        idempotency_key: str | None = None,
+        retryable: bool = True,
+    ) -> BatchResult:
+        """Calculate tax for an arbitrary number of transactions.
+
+        Automatically splits the input into batches of ``MAX_BATCH_SIZE`` and
+        concatenates results in the original order.
+        """
+        if not transactions:
+            raise ValidationError(
+                "EMPTY_BATCH", "Batch must contain at least one transaction", status_code=400
+            )
+        for t in transactions:
+            _amount(t.get("amount"))
+
+        results: list[TaxCalculation] = []
+        for batch in chunk(list(transactions), MAX_BATCH_SIZE):
+            res = self._http.send(
+                "POST",
+                "/calculate/batch",
+                body={"transactions": batch},
+                options=_request_options(idempotency_key, retryable),
+            )
+            results.extend(res.get("results", []))
+        return {"results": results, "count": len(results)}
+
+    def _validate_batch(self, transactions: Sequence[_TransactionLike]) -> None:
+        if not transactions:
+            raise ValidationError(
+                "EMPTY_BATCH", "Batch must contain at least one transaction", status_code=400
+            )
+        if len(transactions) > MAX_BATCH_SIZE and not self._chunk_batch:
+            raise ValidationError(
+                "BATCH_LIMIT_EXCEEDED",
+                f"Batch is limited to {MAX_BATCH_SIZE} transactions. "
+                "Use calculate_batch_chunked() or enable chunk_batch=True.",
+                status_code=400,
+            )
+
+
+def _request_options(idempotency_key: str | None, retryable: bool) -> Any:
+    from .._transport.types import RequestOptions
+
+    return RequestOptions(idempotency_key=idempotency_key, retryable=retryable)

salestax/utils.py

@@ -0,0 +1,22 @@
+"""Small internal helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def chunk(items: Sequence[T], size: int) -> list[list[T]]:
+    """Split ``items`` into lists of at most ``size`` elements."""
+    if size <= 0:
+        raise ValueError("size must be positive")
+    return [list(items[i : i + size]) for i in range(0, len(items), size)]
+
+
+def redact(value: str, keep: int = 4) -> str:
+    """Redact all but the last ``keep`` characters. Used in log output."""
+    if len(value) <= keep:
+        return "*" * len(value)
+    return "*" * (len(value) - keep) + value[-keep:]

salestax_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: salestax-python
+Version: 0.1.0
+Summary: Official Python SDK for Sales Tax Calculator API — real-time sales tax across 70+ countries, 51 US jurisdictions, and batch processing.
+Project-URL: Homepage, https://salestaxcalculatorapi.com
+Project-URL: Documentation, https://salestaxcalculatorapi.com/docs
+Project-URL: Repository, https://github.com/InstaBlick-USA/salestax-python
+Project-URL: Issues, https://github.com/InstaBlick-USA/salestax-python/issues
+Project-URL: Changelog, https://github.com/InstaBlick-USA/salestax-python/blob/main/CHANGELOG.md
+Author-email: InstaBlick USA <dev@salestaxcalculatorapi.com>
+License: MIT
+License-File: LICENSE
+Keywords: api-client,async,checkout,ecommerce,gst,python,sales-tax,tax-api,vat
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: async
+Requires-Dist: httpx>=0.27; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# salestax-python
+
+[![PyPI](https://img.shields.io/pypi/v/salestax-python)](https://pypi.org/project/salestax-python/)
+[![Python versions](https://img.shields.io/pypi/pyversions/salestax-python)](https://pypi.org/project/salestax-python/)
+[![CI](https://github.com/InstaBlick-USA/salestax-python/actions/workflows/ci.yml/badge.svg)](https://github.com/InstaBlick-USA/salestax-python/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Official Python SDK for the **[Sales Tax Calculator API](https://salestaxcalculatorapi.com)** —
+real-time sales tax for 70+ countries, 51 US jurisdictions, and 13 Canadian provinces.
+Batch up to 100 transactions. Zero runtime dependencies (sync). Full type hints.
+
+## Install
+
+```bash
+pip install salestax-python
+```
+
+Async support:
+
+```bash
+pip install salestax-python[async]
+```
+
+## Quickstart
+
+```python
+from salestax import SalesTaxClient
+
+with SalesTaxClient() as client:  # reads SALESTAX_API_KEY
+    tax = client.tax.calculate(zip_code="90210", amount=100)
+
+print(tax["taxAmount"])   # 9.75
+print(tax["totalAmount"]) # 109.75
+```
+
+Get your API key → **[salestaxcalculatorapi.com](https://salestaxcalculatorapi.com)**
+
+## Features
+
+- **Zero runtime dependencies** for the sync client — stdlib `urllib` only.
+- **Optional async client** via `httpx` (`pip install salestax-python[async]`).
+- **Automatic retries** with exponential backoff + jitter, honors `Retry-After`.
+- **Typed errors** — `RateLimitError`, `ValidationError`, `TimeoutError`, and more.
+  No string parsing. Every error carries `code`, `request_id`, and (where applicable) `param`.
+- **Lifecycle hooks** — `on_request`, `on_response`, `on_retry` for logging and telemetry.
+- **Batch chunking** — `calculate_batch_chunked()` splits >100 automatically.
+- **Fully typed** — ships `py.typed`, `mypy --strict` clean.
+
+## Async
+
+```python
+import asyncio
+from salestax import AsyncSalesTaxClient
+
+async def main():
+    async with AsyncSalesTaxClient() as client:
+        tax = await client.tax.calculate(zip_code="90210", amount=100)
+        print(tax["taxAmount"])
+
+asyncio.run(main())
+```
+
+## Batch
+
+```python
+with SalesTaxClient() as client:
+    result = client.tax.calculate_batch_chunked(
+        transactions,           # any length
+        idempotency_key="order-12345",
+    )
+```
+
+## Error Handling
+
+```python
+from salestax import RateLimitError, ValidationError
+
+try:
+    client.tax.calculate(zip_code="90210", amount=100)
+except RateLimitError as err:
+    # err.retry_after_ms — back off
+    ...
+except ValidationError as err:
+    # err.param — which field failed
+    ...
+```
+
+## Configuration
+
+```python
+from salestax import SalesTaxClient, RetryPolicy
+
+client = SalesTaxClient(
+    api_key="sk_live_...",
+    timeout_ms=20_000,
+    chunk_batch=True,
+    retry=RetryPolicy(max_retries=4),
+)
+```
+
+## Hooks
+
+```python
+client = SalesTaxClient(hooks={
+    "on_retry": lambda info: print(f"retry {info['attempt']} in {info['delay_ms']}ms"),
+})
+```
+
+## Also Available For
+
+- [salestax-node](https://github.com/InstaBlick-USA/salestax-node) — Node.js / TypeScript
+- [salestax-ruby](https://github.com/InstaBlick-USA/salestax-ruby) — Ruby
+
+## Documentation
+
+Full API reference → **[salestaxcalculatorapi.com/docs](https://salestaxcalculatorapi.com/docs)**
+
+## License
+
+MIT © [InstaBlick USA](https://github.com/InstaBlick-USA)

salestax_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+salestax/__init__.py,sha256=rpr-zj2hpvKdXa9Oz5kMtcfmBArwkED1kAz8jLeN6yw,1320
+salestax/_config.py,sha256=Y2OqwHEUQVpclhMUKiXmtGHR-qYTxejwgniebkXfLYU,1659
+salestax/_version.py,sha256=VmPUojNETb-e_3dWOA7kZeosNlKu8t67NvIMY5AV5lU,73
+salestax/client.py,sha256=sPAnXbqJSC59QiZo_8D3FgfXpAz59WQZp72RFpvCpX4,7524
+salestax/errors.py,sha256=ZQw7jmnZSFiysXiUyP1akdOHf0jCZvBKmRXEV2AOvAA,5307
+salestax/models.py,sha256=n6vfoWGyvue595tzpdlcbSlATIIhQBpl-2FyqwXrxOQ,1703
+salestax/py.typed,sha256=S2JdbeRy7souiuGCm5NHAx_wf4AZZewwlWSTyuYq89o,44
+salestax/utils.py,sha256=pzJdO_fhOlJwVG8t2zc-pCCpQaqp8RhpVYxuQIuadMA,655
+salestax/_transport/__init__.py,sha256=dWzJhvFxSNMs5-z7fnzYbfO_IcHpy_f44S0qp5GjYbc,497
+salestax/_transport/http_client.py,sha256=KgVpvi3s2o1LEZcNevkPYdjlp5YSXMqhLKgiStnE-ao,9399
+salestax/_transport/httpx_transport.py,sha256=E_AUrIiYmaQcmuQKBfn3eii4i2mi4tuN-NjNZyVR8VY,1605
+salestax/_transport/retry.py,sha256=46mhtRnRoSqRSBL5-R0PQnkIBJAdsIhOJXLIhhpYuEU,1435
+salestax/_transport/types.py,sha256=5T4TMAjJf2nME79V_THufa8CqCsba9X5nezWiJqw9lc,2336
+salestax/_transport/urllib_transport.py,sha256=wom8qIrYIUSV33lD0OBuKowsAcMdcNwMsgCZ8WuZG2M,2028
+salestax/_transport/user_agent.py,sha256=wOE5_SMA5kk3KmLUXq3Pe2sUr08ZfbFjoE5gKipLSmI,444
+salestax/resources/__init__.py,sha256=DD4u3HhflZkywAHWGAF0BDMooc-t55NuclLsIMuha6g,180
+salestax/resources/jurisdictions.py,sha256=nenRJp15ds_6DBd8lIsV40U_CJqviYRMWzTWgmSAt9Y,830
+salestax/resources/rates.py,sha256=jiWztqFmAklITTetGt7p3eaOdmp0FVX4pZSO3nhWluo,780
+salestax/resources/tax.py,sha256=sVYSG0Y-w1aNY39f-C7c8ttPuDhe1TKaFlXEuBGXDJM,4925
+salestax_python-0.1.0.dist-info/METADATA,sha256=EvACOB77pM9sKAEN5AhHR9ny6HrAf7jUB7SzFOLzQ70,5207
+salestax_python-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+salestax_python-0.1.0.dist-info/licenses/LICENSE,sha256=KEd6gVA2mih1LR627--d2IqpDOnsqkR9aMn5DGg_PK4,1070
+salestax_python-0.1.0.dist-info/RECORD,,

salestax_python-0.1.0.dist-info/WHEEL

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

salestax_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InstaBlick-USA
+
+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.