isvalid-sdk 0.2.0__tar.gz

isvalid_sdk-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: python -m mypy isvalid_sdk
+      - run: python -m pytest

isvalid_sdk-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

isvalid_sdk-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

isvalid_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 isvalid.dev
+
+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.

isvalid_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: isvalid-sdk
+Version: 0.2.0
+Summary: Python SDK for the isvalid.dev validation API
+Project-URL: Homepage, https://isvalid.dev
+Project-URL: Documentation, https://isvalid.dev/docs
+Project-URL: Repository, https://github.com/isvalid-dev/isvalid-sdk-python
+Author: isvalid.dev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,email,iban,isin,isvalid,lei,sdk,validation,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.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# isvalid-sdk
+
+Python SDK for the [isvalid.dev](https://isvalid.dev) validation API.
+
+## Features
+
+- **Single dependency** — only `httpx`
+- **Full type hints** with `TypedDict` for every endpoint response
+- **Context manager** support for proper resource cleanup
+- **Automatic retry** with exponential backoff for 429/5xx
+- **Custom exception classes** for auth and rate limit errors
+- **Python 3.9+**
+
+## Installation
+
+```bash
+pip install isvalid-sdk
+```
+
+## Quick Start
+
+Get your free API key at [isvalid.dev/getting-started](https://isvalid.dev/getting-started).
+
+```python
+from isvalid_sdk import IsValidConfig, create_client
+
+iv = create_client(IsValidConfig(api_key="your-api-key"))
+
+# Simple validation
+email = iv.email("user@example.com", check_mx=True)
+# => {"valid": True, "local": "user", "domain": "example.com", "mxValid": True}
+
+iban = iv.iban("DE89370400440532013000")
+# => {"valid": True, "countryCode": "DE", "bankName": "Commerzbank", ...}
+
+vat = iv.vat("DE123456789", check_vies=True)
+# => {"valid": True, "countryCode": "DE", "isEU": True, "vies": {"checked": True, ...}}
+```
+
+## Context Manager
+
+```python
+with create_client(IsValidConfig(api_key="your-api-key")) as iv:
+    result = iv.email("user@example.com")
+```
+
+## Namespaced Methods
+
+```python
+# LEI
+lei = iv.lei("5493001KJTIIGC8Y1R12")
+search = iv.lei.search("Apple", country="US", limit=5)
+lous = iv.lei.lous()
+
+# Country / Currency / Language
+country = iv.country("PL")
+countries = iv.country.list()
+
+currency = iv.currency("USD")
+currencies = iv.currency.list()
+
+language = iv.language("en")
+languages = iv.language.list()
+
+# IATA
+flight = iv.iata.flight("LH1234")
+airline = iv.iata.airline("LH")
+airlines = iv.iata.airline.list()
+airport = iv.iata.airport("WAW")
+```
+
+## Country-Specific Endpoints
+
+```python
+# Poland
+iv.pl.pesel("44051401358")
+iv.pl.regon("012345678", lookup=True)
+iv.pl.krs("0000123456", lookup=True)
+
+# Brazil
+iv.br.cnpj("11.222.333/0001-81")
+iv.br.cpf("123.456.789-09")
+
+# Other
+iv.au.abn("51824753556")
+iv.es.nif("12345678Z")
+iv.in_.gstin("27AAPFU0939F1ZV")  # note: in_ (reserved word)
+iv.us.npi("1234567893")
+iv.gb.sort_code("12-34-56")
+```
+
+## Network & Financial
+
+```python
+# Network
+iv.net.ip("192.168.1.1")
+iv.net.mac("00:1B:44:11:3A:B7")
+
+# Financial
+iv.isin("US0378331005")
+iv.dti("B1234567Z")
+iv.bic("DEUTDEFF")
+iv.cusip("037833100")
+iv.credit_card("4111111111111111")  # POST endpoint
+```
+
+## All Simple Endpoints
+
+```python
+iv.email(value, check_mx=)     iv.iban(value, country_code=)
+iv.isin(value)                  iv.dti(value)
+iv.vat(value, country_code=, check_vies=)
+iv.gps(value)                   iv.phone(value, country_code=)
+iv.url(value)                   iv.ean(value)
+iv.isbn(value)                  iv.issn(value)
+iv.bic(value)                   iv.cusip(value)
+iv.cfi(value)                   iv.mic(value)
+iv.nuts(value)                  iv.uuid(value, version=)
+iv.jwt(value)                   iv.vin(value)
+iv.imei(value)                  iv.semver(value)
+iv.color(value)                 iv.boolean(value)
+iv.date(value, format=)         iv.btc_address(value)
+iv.postal_code(value, country_code=)
+iv.aba(value)                   iv.container_code(value)
+iv.sscc(value)                  iv.gln(value)
+iv.qr(value)                    iv.credit_card(number)
+```
+
+## Configuration
+
+```python
+from isvalid_sdk import IsValidConfig, RetryConfig, create_client
+
+iv = create_client(IsValidConfig(
+    api_key="your-api-key",
+    base_url="https://api.isvalid.dev",  # default
+    timeout=15.0,                         # default: 10.0 (seconds)
+    retry=RetryConfig(
+        max_retries=5,                   # default: 3
+        initial_delay=1.0,               # default: 0.5
+        max_delay=30.0,                  # default: 10.0
+        retry_on=(429, 500, 502, 503),   # default
+    ),
+))
+
+# Disable retry
+iv = create_client(IsValidConfig(api_key="...", retry=None))
+```
+
+## Error Handling
+
+```python
+from isvalid_sdk import (
+    IsValidError, IsValidAuthError, IsValidRateLimitError, create_client
+)
+
+try:
+    iv.email("test@example.com")
+except IsValidRateLimitError as e:
+    print("Rate limited, retry after:", e.retry_after, "seconds")
+except IsValidAuthError as e:
+    print("Invalid API key")
+except IsValidError as e:
+    print("API error:", e.status, e.body["error"])
+```
+
+## API Reference
+
+Full endpoint documentation: [isvalid.dev/docs](https://isvalid.dev/docs)
+
+## License
+
+MIT

isvalid_sdk-0.2.0/README.md

@@ -0,0 +1,173 @@
+# isvalid-sdk
+
+Python SDK for the [isvalid.dev](https://isvalid.dev) validation API.
+
+## Features
+
+- **Single dependency** — only `httpx`
+- **Full type hints** with `TypedDict` for every endpoint response
+- **Context manager** support for proper resource cleanup
+- **Automatic retry** with exponential backoff for 429/5xx
+- **Custom exception classes** for auth and rate limit errors
+- **Python 3.9+**
+
+## Installation
+
+```bash
+pip install isvalid-sdk
+```
+
+## Quick Start
+
+Get your free API key at [isvalid.dev/getting-started](https://isvalid.dev/getting-started).
+
+```python
+from isvalid_sdk import IsValidConfig, create_client
+
+iv = create_client(IsValidConfig(api_key="your-api-key"))
+
+# Simple validation
+email = iv.email("user@example.com", check_mx=True)
+# => {"valid": True, "local": "user", "domain": "example.com", "mxValid": True}
+
+iban = iv.iban("DE89370400440532013000")
+# => {"valid": True, "countryCode": "DE", "bankName": "Commerzbank", ...}
+
+vat = iv.vat("DE123456789", check_vies=True)
+# => {"valid": True, "countryCode": "DE", "isEU": True, "vies": {"checked": True, ...}}
+```
+
+## Context Manager
+
+```python
+with create_client(IsValidConfig(api_key="your-api-key")) as iv:
+    result = iv.email("user@example.com")
+```
+
+## Namespaced Methods
+
+```python
+# LEI
+lei = iv.lei("5493001KJTIIGC8Y1R12")
+search = iv.lei.search("Apple", country="US", limit=5)
+lous = iv.lei.lous()
+
+# Country / Currency / Language
+country = iv.country("PL")
+countries = iv.country.list()
+
+currency = iv.currency("USD")
+currencies = iv.currency.list()
+
+language = iv.language("en")
+languages = iv.language.list()
+
+# IATA
+flight = iv.iata.flight("LH1234")
+airline = iv.iata.airline("LH")
+airlines = iv.iata.airline.list()
+airport = iv.iata.airport("WAW")
+```
+
+## Country-Specific Endpoints
+
+```python
+# Poland
+iv.pl.pesel("44051401358")
+iv.pl.regon("012345678", lookup=True)
+iv.pl.krs("0000123456", lookup=True)
+
+# Brazil
+iv.br.cnpj("11.222.333/0001-81")
+iv.br.cpf("123.456.789-09")
+
+# Other
+iv.au.abn("51824753556")
+iv.es.nif("12345678Z")
+iv.in_.gstin("27AAPFU0939F1ZV")  # note: in_ (reserved word)
+iv.us.npi("1234567893")
+iv.gb.sort_code("12-34-56")
+```
+
+## Network & Financial
+
+```python
+# Network
+iv.net.ip("192.168.1.1")
+iv.net.mac("00:1B:44:11:3A:B7")
+
+# Financial
+iv.isin("US0378331005")
+iv.dti("B1234567Z")
+iv.bic("DEUTDEFF")
+iv.cusip("037833100")
+iv.credit_card("4111111111111111")  # POST endpoint
+```
+
+## All Simple Endpoints
+
+```python
+iv.email(value, check_mx=)     iv.iban(value, country_code=)
+iv.isin(value)                  iv.dti(value)
+iv.vat(value, country_code=, check_vies=)
+iv.gps(value)                   iv.phone(value, country_code=)
+iv.url(value)                   iv.ean(value)
+iv.isbn(value)                  iv.issn(value)
+iv.bic(value)                   iv.cusip(value)
+iv.cfi(value)                   iv.mic(value)
+iv.nuts(value)                  iv.uuid(value, version=)
+iv.jwt(value)                   iv.vin(value)
+iv.imei(value)                  iv.semver(value)
+iv.color(value)                 iv.boolean(value)
+iv.date(value, format=)         iv.btc_address(value)
+iv.postal_code(value, country_code=)
+iv.aba(value)                   iv.container_code(value)
+iv.sscc(value)                  iv.gln(value)
+iv.qr(value)                    iv.credit_card(number)
+```
+
+## Configuration
+
+```python
+from isvalid_sdk import IsValidConfig, RetryConfig, create_client
+
+iv = create_client(IsValidConfig(
+    api_key="your-api-key",
+    base_url="https://api.isvalid.dev",  # default
+    timeout=15.0,                         # default: 10.0 (seconds)
+    retry=RetryConfig(
+        max_retries=5,                   # default: 3
+        initial_delay=1.0,               # default: 0.5
+        max_delay=30.0,                  # default: 10.0
+        retry_on=(429, 500, 502, 503),   # default
+    ),
+))
+
+# Disable retry
+iv = create_client(IsValidConfig(api_key="...", retry=None))
+```
+
+## Error Handling
+
+```python
+from isvalid_sdk import (
+    IsValidError, IsValidAuthError, IsValidRateLimitError, create_client
+)
+
+try:
+    iv.email("test@example.com")
+except IsValidRateLimitError as e:
+    print("Rate limited, retry after:", e.retry_after, "seconds")
+except IsValidAuthError as e:
+    print("Invalid API key")
+except IsValidError as e:
+    print("API error:", e.status, e.body["error"])
+```
+
+## API Reference
+
+Full endpoint documentation: [isvalid.dev/docs](https://isvalid.dev/docs)
+
+## License
+
+MIT

isvalid_sdk-0.2.0/isvalid_sdk/__init__.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from isvalid_sdk.client import HttpClient, IsValidConfig, RetryConfig
+from isvalid_sdk.errors import IsValidAuthError, IsValidError, IsValidRateLimitError
+from isvalid_sdk.namespaces.au import AuNamespace
+from isvalid_sdk.namespaces.br import BrNamespace
+from isvalid_sdk.namespaces.country import CountryNamespace
+from isvalid_sdk.namespaces.currency import CurrencyNamespace
+from isvalid_sdk.namespaces.es import EsNamespace
+from isvalid_sdk.namespaces.gb import GbNamespace
+from isvalid_sdk.namespaces.iata import IataNamespace
+from isvalid_sdk.namespaces.india import InNamespace
+from isvalid_sdk.namespaces.language import LanguageNamespace
+from isvalid_sdk.namespaces.lei import LeiNamespace
+from isvalid_sdk.namespaces.net import NetNamespace
+from isvalid_sdk.namespaces.pl import PlNamespace
+from isvalid_sdk.namespaces.us import UsNamespace
+from isvalid_sdk.types.simple import (
+    AbaResponse,
+    BicResponse,
+    BooleanResponse,
+    BtcAddressResponse,
+    CfiResponse,
+    ColorResponse,
+    ContainerCodeResponse,
+    CreditCardResponse,
+    CusipResponse,
+    DateResponse,
+    DtiResponse,
+    EanResponse,
+    EmailResponse,
+    GlnResponse,
+    GpsResponse,
+    IbanResponse,
+    ImeiResponse,
+    IsbnResponse,
+    IsinResponse,
+    IssnResponse,
+    JwtResponse,
+    MicResponse,
+    NutsResponse,
+    PhoneResponse,
+    PostalCodeResponse,
+    QrResponse,
+    SemverResponse,
+    SsccResponse,
+    UrlResponse,
+    UuidResponse,
+    VatResponse,
+    VinResponse,
+)
+
+__all__ = [
+    "IsValid",
+    "create_client",
+    "IsValidConfig",
+    "RetryConfig",
+    "IsValidError",
+    "IsValidAuthError",
+    "IsValidRateLimitError",
+]
+
+
+class IsValid:
+    def __init__(self, config: IsValidConfig) -> None:
+        self._client = HttpClient(config)
+
+        self.lei = LeiNamespace(self._client)
+        self.country = CountryNamespace(self._client)
+        self.currency = CurrencyNamespace(self._client)
+        self.language = LanguageNamespace(self._client)
+        self.iata = IataNamespace(self._client)
+        self.net = NetNamespace(self._client)
+        self.pl = PlNamespace(self._client)
+        self.br = BrNamespace(self._client)
+        self.au = AuNamespace(self._client)
+        self.es = EsNamespace(self._client)
+        self.in_ = InNamespace(self._client)
+        self.us = UsNamespace(self._client)
+        self.gb = GbNamespace(self._client)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "IsValid":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    # --- Simple endpoints ---
+
+    def email(self, value: str, *, check_mx: bool = False) -> EmailResponse:
+        return self._client.get(
+            "/v0/email",
+            {"value": value, "checkMx": str(check_mx).lower() if check_mx else None},
+        )
+
+    def iban(self, value: str, *, country_code: Optional[str] = None) -> IbanResponse:
+        return self._client.get(
+            "/v0/iban", {"value": value, "countryCode": country_code}
+        )
+
+    def isin(self, value: str) -> IsinResponse:
+        return self._client.get("/v0/isin", {"value": value})
+
+    def dti(self, value: str) -> DtiResponse:
+        return self._client.get("/v0/dti", {"value": value})
+
+    def vat(
+        self,
+        value: str,
+        *,
+        country_code: Optional[str] = None,
+        check_vies: bool = False,
+    ) -> VatResponse:
+        return self._client.get(
+            "/v0/vat",
+            {
+                "value": value,
+                "countryCode": country_code,
+                "checkVies": str(check_vies).lower() if check_vies else None,
+            },
+        )
+
+    def gps(self, value: str) -> GpsResponse:
+        return self._client.get("/v0/gps", {"value": value})
+
+    def phone(self, value: str, *, country_code: Optional[str] = None) -> PhoneResponse:
+        return self._client.get(
+            "/v0/phone", {"value": value, "countryCode": country_code}
+        )
+
+    def url(self, value: str) -> UrlResponse:
+        return self._client.get("/v0/url", {"value": value})
+
+    def ean(self, value: str) -> EanResponse:
+        return self._client.get("/v0/ean", {"value": value})
+
+    def isbn(self, value: str) -> IsbnResponse:
+        return self._client.get("/v0/isbn", {"value": value})
+
+    def issn(self, value: str) -> IssnResponse:
+        return self._client.get("/v0/issn", {"value": value})
+
+    def bic(self, value: str) -> BicResponse:
+        return self._client.get("/v0/bic", {"value": value})
+
+    def cusip(self, value: str) -> CusipResponse:
+        return self._client.get("/v0/cusip", {"value": value})
+
+    def cfi(self, value: str) -> CfiResponse:
+        return self._client.get("/v0/cfi", {"value": value})
+
+    def mic(self, value: str) -> MicResponse:
+        return self._client.get("/v0/mic", {"value": value})
+
+    def nuts(self, value: str) -> NutsResponse:
+        return self._client.get("/v0/nuts", {"value": value})
+
+    def uuid(self, value: str, *, version: Optional[int] = None) -> UuidResponse:
+        return self._client.get(
+            "/v0/uuid",
+            {"value": value, "version": str(version) if version is not None else None},
+        )
+
+    def jwt(self, value: str) -> JwtResponse:
+        return self._client.get("/v0/jwt", {"value": value})
+
+    def vin(self, value: str) -> VinResponse:
+        return self._client.get("/v0/vin", {"value": value})
+
+    def imei(self, value: str) -> ImeiResponse:
+        return self._client.get("/v0/imei", {"value": value})
+
+    def semver(self, value: str) -> SemverResponse:
+        return self._client.get("/v0/semver", {"value": value})
+
+    def color(self, value: str) -> ColorResponse:
+        return self._client.get("/v0/color", {"value": value})
+
+    def boolean(self, value: str) -> BooleanResponse:
+        return self._client.get("/v0/boolean", {"value": value})
+
+    def date(self, value: str, *, format: Optional[str] = None) -> DateResponse:
+        return self._client.get("/v0/date", {"value": value, "format": format})
+
+    def btc_address(self, value: str) -> BtcAddressResponse:
+        return self._client.get("/v0/btc-address", {"value": value})
+
+    def postal_code(
+        self, value: str, *, country_code: Optional[str] = None
+    ) -> PostalCodeResponse:
+        return self._client.get(
+            "/v0/postal-code", {"value": value, "countryCode": country_code}
+        )
+
+    def aba(self, value: str) -> AbaResponse:
+        return self._client.get("/v0/aba", {"value": value})
+
+    def container_code(self, value: str) -> ContainerCodeResponse:
+        return self._client.get("/v0/container-code", {"value": value})
+
+    def sscc(self, value: str) -> SsccResponse:
+        return self._client.get("/v0/sscc", {"value": value})
+
+    def gln(self, value: str) -> GlnResponse:
+        return self._client.get("/v0/gln", {"value": value})
+
+    def qr(self, value: str) -> QrResponse:
+        return self._client.get("/v0/qr", {"value": value})
+
+    def credit_card(self, number: str) -> CreditCardResponse:
+        return self._client.post("/v0/credit-card", {"number": number})
+
+
+def create_client(config: IsValidConfig) -> IsValid:
+    return IsValid(config)