salestax-python 0.1.0__tar.gz

salestax_python-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# -- Python bytecode / caches --
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# -- Distribution / packaging --
+build/
+dist/
+*.egg-info/
+*.egg
+MANIFEST
+
+# -- Virtual environments --
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# -- Test / coverage artifacts --
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# -- Type checker / linter caches --
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+
+# -- Build backends --
+.hatch/
+
+# -- Editors / IDEs --
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# -- OS noise --
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# -- Secrets / local config (never commit) --
+.env
+.env.*
+!.env.example

salestax_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-22
+
+### Added
+
+- Initial release.
+- `SalesTaxClient` (sync) with zero runtime dependencies.
+- `AsyncSalesTaxClient` (async, requires `[async]` extra).
+- Resources: `client.tax`, `client.rates`, `client.jurisdictions`.
+- Automatic retries with exponential backoff, jitter, and `Retry-After` support.
+- Full error hierarchy: `RateLimitError`, `ValidationError`, `TimeoutError`, and more.
+- Lifecycle hooks: `on_request`, `on_response`, `on_retry`.
+- Batch chunking via `calculate_batch_chunked()`.
+- PEP 561 `py.typed` marker; `mypy --strict` clean.

salestax_python-0.1.0/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.

salestax_python-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,120 @@
+# 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/examples/async_usage.py

@@ -0,0 +1,20 @@
+"""Async client example. Requires: pip install salestax-python[async]"""
+
+import asyncio
+
+from salestax import AsyncSalesTaxClient
+
+
+async def main() -> None:
+    async with AsyncSalesTaxClient() as client:
+        results = await asyncio.gather(
+            client.tax.calculate(zip_code="90210", amount=100),
+            client.tax.calculate(zip_code="10001", amount=200),
+            client.rates.get("60601"),
+        )
+        for r in results:
+            print(r)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

salestax_python-0.1.0/examples/basic_calculation.py

@@ -0,0 +1,13 @@
+"""Minimal single-calculation example.
+
+Run:
+    SALESTAX_API_KEY=sk_live_... python examples/basic_calculation.py
+"""
+
+from salestax import SalesTaxClient
+
+with SalesTaxClient() as client:
+    tax = client.tax.calculate(zip_code="90210", amount=100)
+
+print(f"Tax:   ${tax['taxAmount']:.2f}")
+print(f"Total: ${tax['totalAmount']:.2f}")

salestax_python-0.1.0/examples/batch_calculation.py

@@ -0,0 +1,17 @@
+"""Batch example with automatic chunking for >100 transactions."""
+
+from salestax import SalesTaxClient
+
+transactions = [
+    {"zipCode": "90210", "amount": 100},
+    {"zipCode": "10001", "amount": 250},
+    {"zipCode": "60601", "amount": 75.50},
+]
+
+with SalesTaxClient() as client:
+    result = client.tax.calculate_batch(
+        transactions, idempotency_key="order-2026-0922-001"
+    )
+
+for i, calc in enumerate(result["results"]):
+    print(f"#{i}: tax={calc['taxAmount']:.2f} total={calc['totalAmount']:.2f}")

salestax_python-0.1.0/examples/error_handling.py

@@ -0,0 +1,18 @@
+"""Catch and branch on specific error types."""
+
+from salestax import (
+    RateLimitError,
+    SalesTaxClient,
+    TimeoutError,
+    ValidationError,
+)
+
+with SalesTaxClient() as client:
+    try:
+        client.tax.calculate(zip_code="90210", amount=100)
+    except RateLimitError as err:
+        print(f"Rate limited. Retry in {err.retry_after_ms}ms. req={err.request_id}")
+    except ValidationError as err:
+        print(f"Bad input on `{err.param}`: {err.message}")
+    except TimeoutError:
+        print("Request timed out — safe to retry.")

salestax_python-0.1.0/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "salestax-python"
+version = "0.1.0"
+description = "Official Python SDK for Sales Tax Calculator API — real-time sales tax across 70+ countries, 51 US jurisdictions, and batch processing."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "InstaBlick USA", email = "dev@salestaxcalculatorapi.com" }]
+keywords = [
+  "sales-tax", "tax-api", "ecommerce", "checkout",
+  "python", "api-client", "vat", "gst", "async"
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial :: Accounting",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://salestaxcalculatorapi.com"
+Documentation = "https://salestaxcalculatorapi.com/docs"
+Repository = "https://github.com/InstaBlick-USA/salestax-python"
+Issues = "https://github.com/InstaBlick-USA/salestax-python/issues"
+Changelog = "https://github.com/InstaBlick-USA/salestax-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+async = ["httpx>=0.27"]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=5.0",
+  "respx>=0.21",
+  "mypy>=1.9",
+  "ruff>=0.4",
+  "build>=1.2",
+  "twine>=5.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["salestax"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "salestax",
+  "tests",
+  "examples",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["salestax", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "C4", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["salestax"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+show_error_codes = true
+files = ["salestax"]
+
+[[tool.mypy.overrides]]
+module = ["httpx.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+asyncio_mode = "auto"
+markers = [
+  "integration: marks tests that hit the live API (deselect with '-m \"not integration\"')",
+]
+
+[tool.coverage.run]
+source = ["salestax"]
+branch = true
+omit = ["salestax/_version.py"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+]

salestax_python-0.1.0/salestax/__init__.py

@@ -0,0 +1,61 @@
+"""Official Python SDK for the Sales Tax Calculator API.
+
+Real-time sales tax for 70+ countries, 51 US jurisdictions, and 13 Canadian
+provinces. Batch up to 100 transactions per call.
+
+Docs: https://salestaxcalculatorapi.com/docs
+"""
+
+from __future__ import annotations
+
+from ._config import ClientOptions, RetryPolicy
+from ._version import __version__
+from .client import AsyncSalesTaxClient, SalesTaxClient
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    SalesTaxError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from .models import (
+    BatchResult,
+    CalculateTaxParams,
+    Jurisdiction,
+    JurisdictionQuery,
+    TaxBreakdownEntry,
+    TaxCalculation,
+    TaxRate,
+)
+
+__all__ = [
+    "ApiError",
+    "AsyncSalesTaxClient",
+    "AuthenticationError",
+    "BatchResult",
+    "CalculateTaxParams",
+    "ClientOptions",
+    "ConflictError",
+    "ConnectionError",
+    "Jurisdiction",
+    "JurisdictionQuery",
+    "NotFoundError",
+    "PermissionError",
+    "RateLimitError",
+    "RetryPolicy",
+    "SalesTaxClient",
+    "SalesTaxError",
+    "ServerError",
+    "TaxBreakdownEntry",
+    "TaxCalculation",
+    "TaxRate",
+    "TimeoutError",
+    "ValidationError",
+    "__version__",
+]

salestax_python-0.1.0/salestax/_config.py

@@ -0,0 +1,53 @@
+"""Configuration and defaults for the SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+
+DEFAULT_BASE_URL = "https://api.salestaxcalculatorapi.com/v1"
+DEFAULT_TIMEOUT_MS = 30_000
+MAX_BATCH_SIZE = 100
+ENV_API_KEY = "SALESTAX_API_KEY"
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Retry behavior for transient failures.
+
+    Attributes:
+        max_retries: Number of retries *after* the initial attempt.
+        initial_delay_ms: Base delay for the first retry.
+        max_delay_ms: Ceiling for any single delay.
+        backoff_factor: Exponential multiplier applied per attempt.
+        jitter: Apply full jitter to each computed delay.
+    """
+
+    max_retries: int = 2
+    initial_delay_ms: int = 250
+    max_delay_ms: int = 8_000
+    backoff_factor: float = 2.0
+    jitter: bool = True
+
+
+@dataclass(frozen=True)
+class ClientOptions:
+    """Immutable options container. Prefer passing keyword args to the client."""
+
+    api_key: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    timeout_ms: int = DEFAULT_TIMEOUT_MS
+    retry: RetryPolicy = field(default_factory=RetryPolicy)
+    default_headers: dict[str, str] = field(default_factory=dict)
+    chunk_batch: bool = False
+
+    def resolved_api_key(self) -> str:
+        key = self.api_key or os.environ.get(ENV_API_KEY)
+        if not key:
+            raise ValueError(
+                f"Missing API key. Pass api_key=... or set the {ENV_API_KEY} environment variable."
+            )
+        return key
+
+    def with_overrides(self, **kwargs: object) -> ClientOptions:
+        return replace(self, **kwargs)  # type: ignore[arg-type]

salestax_python-0.1.0/salestax/_transport/__init__.py

@@ -0,0 +1,18 @@
+from .http_client import AsyncHttpClient, HttpClient
+from .retry import compute_delay_ms, parse_retry_after
+from .types import AsyncTransport, Hooks, RequestOptions, SyncTransport
+from .urllib_transport import UrllibTransport
+from .user_agent import build_user_agent
+
+__all__ = [
+    "AsyncHttpClient",
+    "AsyncTransport",
+    "Hooks",
+    "HttpClient",
+    "RequestOptions",
+    "SyncTransport",
+    "UrllibTransport",
+    "build_user_agent",
+    "compute_delay_ms",
+    "parse_retry_after",
+]