easyid-python 1.0.2__tar.gz

easyid_python-1.0.2/.github/workflows/publish-python-pypi.yml

@@ -0,0 +1,40 @@
+name: Publish Python Package
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    if: github.repository == 'easyid-com-cn/easyid-python'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Install package with test dependencies
+        run: python -m pip install -e .[test]
+
+      - name: Run tests
+        run: pytest
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

easyid_python-1.0.2/LICENSE

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

easyid_python-1.0.2/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: easyid-python
+Version: 1.0.2
+Summary: Official Python SDK for the EasyID identity verification API.
+Project-URL: Homepage, https://github.com/easyid-com-cn/easyid-python
+Project-URL: Repository, https://github.com/easyid-com-cn/easyid-python
+Project-URL: Documentation, https://www.easyid.com.cn
+Author: EasyID Team
+License: MIT
+License-File: LICENSE
+Keywords: easyid,identity,kyc,risk,verification
+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 :: Only
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests<3,>=2.31.0
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# EasyID Python SDK
+
+Official Python SDK for the EasyID identity verification API.
+
+EasyID 易验云 focuses on identity verification and security risk control APIs, including real-name verification, liveness detection, face recognition, phone verification, and fraud-risk related capabilities.
+
+中文文档： [README.zh-CN.md](README.zh-CN.md)
+
+## Install
+
+```bash
+pip install easyid-python
+```
+
+## Quick Start
+
+```python
+from easyid import EasyID
+
+client = EasyID("ak_xxx", "sk_xxx")
+result = client.idcard.verify2(name="张三", id_number="110101199001011234")
+
+print(result.match)
+```
+
+## Supported APIs
+
+- IDCard: `verify2`, `verify3`, `ocr`
+- Phone: `status`, `verify3`
+- Face: `liveness`, `compare`, `verify`
+- Bank: `verify4`
+- Risk: `score`, `store_fingerprint`
+- Billing: `balance`, `records`
+
+## Configuration
+
+- `base_url`
+- `timeout`
+- `session`
+
+## Error Handling
+
+Service-side business errors raise `APIError`.
+
+```python
+from easyid import APIError
+
+try:
+    client.phone.status(phone="13800138000")
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## Security Notice
+
+This is a server-side SDK. Never expose `secret` in browsers, mobile apps, or other untrusted clients.
+
+## Official Resources
+
+- Official website: `https://www.easyid.com.cn/`
+- GitHub organization: `https://github.com/easyid-com-cn/`

easyid_python-1.0.2/README.md

@@ -0,0 +1,61 @@
+# EasyID Python SDK
+
+Official Python SDK for the EasyID identity verification API.
+
+EasyID 易验云 focuses on identity verification and security risk control APIs, including real-name verification, liveness detection, face recognition, phone verification, and fraud-risk related capabilities.
+
+中文文档： [README.zh-CN.md](README.zh-CN.md)
+
+## Install
+
+```bash
+pip install easyid-python
+```
+
+## Quick Start
+
+```python
+from easyid import EasyID
+
+client = EasyID("ak_xxx", "sk_xxx")
+result = client.idcard.verify2(name="张三", id_number="110101199001011234")
+
+print(result.match)
+```
+
+## Supported APIs
+
+- IDCard: `verify2`, `verify3`, `ocr`
+- Phone: `status`, `verify3`
+- Face: `liveness`, `compare`, `verify`
+- Bank: `verify4`
+- Risk: `score`, `store_fingerprint`
+- Billing: `balance`, `records`
+
+## Configuration
+
+- `base_url`
+- `timeout`
+- `session`
+
+## Error Handling
+
+Service-side business errors raise `APIError`.
+
+```python
+from easyid import APIError
+
+try:
+    client.phone.status(phone="13800138000")
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## Security Notice
+
+This is a server-side SDK. Never expose `secret` in browsers, mobile apps, or other untrusted clients.
+
+## Official Resources
+
+- Official website: `https://www.easyid.com.cn/`
+- GitHub organization: `https://github.com/easyid-com-cn/`

easyid_python-1.0.2/README.zh-CN.md

@@ -0,0 +1,79 @@
+# EasyID Python SDK
+
+EasyID Python SDK 是易验云身份验证 API 的官方 Python 客户端。
+
+English README: [README.md](README.md)
+
+EasyID 提供身份证核验、手机号核验、人脸识别、银行卡核验、风控评分等能力。本 SDK 适用于服务端应用，自动处理认证头、签名和统一响应解析。
+
+## 安装
+
+```bash
+pip install easyid-python
+```
+
+如果是开发调试当前仓库，也可以在 `python/` 目录下执行：
+
+```bash
+pip install -e .
+```
+
+## 快速开始
+
+```python
+from easyid import EasyID, APIError
+
+client = EasyID("ak_xxx", "sk_xxx")
+
+try:
+    result = client.idcard.verify2(name="张三", id_number="110101199001011234")
+    print("是否匹配：", result.match)
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## 已支持接口
+
+- `client.idcard.verify2()`：身份证二要素核验
+- `client.idcard.verify3()`：身份证三要素核验
+- `client.idcard.ocr()`：身份证 OCR
+- `client.phone.status()`：手机号状态查询
+- `client.phone.verify3()`：手机号三要素核验
+- `client.face.liveness()`：人脸活体检测
+- `client.face.compare()`：人脸比对
+- `client.face.verify()`：人脸核验
+- `client.bank.verify4()`：银行卡四要素核验
+- `client.risk.score()`：风控评分
+- `client.risk.store_fingerprint()`：存储设备指纹
+- `client.billing.balance()`：查询账户余额
+- `client.billing.records()`：查询账单记录
+
+## 配置项
+
+- `base_url`：自定义 API 地址
+- `timeout`：请求超时，单位秒
+- `session`：自定义 `requests.Session`
+
+## 错误处理
+
+服务端业务错误会抛出 `APIError`。
+
+```python
+from easyid import APIError
+
+try:
+    client.phone.status(phone="13800138000")
+except APIError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## 安全说明
+
+- 这是服务端 SDK，不要在浏览器、移动端或其他不可信环境暴露 `secret`
+- `key_id` 必须符合 `ak_[0-9a-f]+`
+- SDK 会自动处理 HMAC-SHA256 签名和认证请求头
+
+## 官方资源
+
+- 官网：`https://www.easyid.com.cn/`
+- GitHub：`https://github.com/easyid-com-cn/`

easyid_python-1.0.2/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "easyid-python"
+version = "1.0.2"
+description = "Official Python SDK for the EasyID identity verification API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "EasyID Team" }
+]
+keywords = ["easyid", "identity", "verification", "kyc", "risk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "requests>=2.31.0,<3"
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8,<9"
+]
+
+[project.urls]
+Homepage = "https://github.com/easyid-com-cn/easyid-python"
+Repository = "https://github.com/easyid-com-cn/easyid-python"
+Documentation = "https://www.easyid.com.cn"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/easyid"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

easyid_python-1.0.2/src/easyid/__init__.py

@@ -0,0 +1,39 @@
+"""EasyID Python SDK."""
+
+from .bank import BankService, BankVerify4Result
+from .billing import BillingRecord, BillingRecordsResult, BillingService, BillingBalanceResult
+from .client import EasyID
+from .error import APIError, is_api_error
+from .face import CompareResult, FaceService, FaceVerifyResult, LivenessResult
+from .idcard import IDCardOCRResult, IDCardService, IDCardVerifyResult
+from .phone import PhoneService, PhoneStatusResult, PhoneVerify3Result
+from .risk import RiskDetails, RiskScoreResult, RiskService, StoreFingerprintResult
+
+__version__ = EasyID.version
+
+__all__ = [
+    "APIError",
+    "BankService",
+    "BankVerify4Result",
+    "BillingBalanceResult",
+    "BillingRecord",
+    "BillingRecordsResult",
+    "BillingService",
+    "CompareResult",
+    "EasyID",
+    "FaceService",
+    "FaceVerifyResult",
+    "IDCardOCRResult",
+    "IDCardService",
+    "IDCardVerifyResult",
+    "LivenessResult",
+    "PhoneService",
+    "PhoneStatusResult",
+    "PhoneVerify3Result",
+    "RiskDetails",
+    "RiskScoreResult",
+    "RiskService",
+    "StoreFingerprintResult",
+    "__version__",
+    "is_api_error",
+]

easyid_python-1.0.2/src/easyid/bank.py

@@ -0,0 +1,48 @@
+"""Bank APIs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .transport import Transport
+
+
+@dataclass(frozen=True)
+class BankVerify4Result:
+    result: bool
+    match: bool
+    bank_name: str
+    supplier: str
+    score: float
+    masked_bank_card: str
+    card_type: str
+
+
+class BankService:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def verify4(
+        self,
+        *,
+        name: str,
+        id_number: str,
+        bank_card: str,
+        mobile: Optional[str] = None,
+        trace_id: Optional[str] = None,
+    ) -> BankVerify4Result:
+        body = {
+            "name": name,
+            "id_number": id_number,
+            "bank_card": bank_card,
+            "mobile": mobile,
+            "trace_id": trace_id,
+        }
+        data = self._transport.request_json(
+            "POST",
+            "/v1/bank/verify4",
+            body={key: value for key, value in body.items() if value is not None},
+        )
+        return BankVerify4Result(**data)
+

easyid_python-1.0.2/src/easyid/billing.py

@@ -0,0 +1,62 @@
+"""Billing APIs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from .transport import Transport
+
+
+@dataclass(frozen=True)
+class BillingBalanceResult:
+    app_id: str
+    available_cents: int
+
+
+@dataclass(frozen=True)
+class BillingRecord:
+    id: int
+    app_id: str
+    request_id: str
+    change_cents: int
+    balance_before: int
+    balance_after: int
+    reason: str
+    operator: str
+    created_at: int
+
+
+@dataclass(frozen=True)
+class BillingRecordsResult:
+    total: int
+    page: int
+    records: List[BillingRecord]
+
+
+class BillingService:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def balance(self, *, app_id: str) -> BillingBalanceResult:
+        data = self._transport.request_json(
+            "GET",
+            "/v1/billing/balance",
+            query={"app_id": app_id},
+        )
+        return BillingBalanceResult(**data)
+
+    def records(self, *, app_id: str, page: int = 1, page_size: int = 20) -> BillingRecordsResult:
+        if page <= 0:
+            page = 1
+        if page_size <= 0:
+            page_size = 20
+        else:
+            page_size = min(page_size, 100)
+        data = self._transport.request_json(
+            "GET",
+            "/v1/billing/records",
+            query={"app_id": app_id, "page": page, "page_size": page_size},
+        )
+        records = [BillingRecord(**record) for record in data.get("records", [])]
+        return BillingRecordsResult(total=data["total"], page=data["page"], records=records)

easyid_python-1.0.2/src/easyid/client.py

@@ -0,0 +1,56 @@
+"""Public client entrypoint for the EasyID SDK."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+import requests
+
+from .bank import BankService
+from .billing import BillingService
+from .face import FaceService
+from .idcard import IDCardService
+from .phone import PhoneService
+from .risk import RiskService
+from .transport import DEFAULT_BASE_URL, SDK_VERSION, Transport
+
+_KEY_ID_RE = re.compile(r"^ak_[0-9a-f]+$")
+
+
+class EasyID:
+    """EasyID API client.
+
+    The client is safe to reuse across requests.
+    """
+
+    version = SDK_VERSION
+
+    def __init__(
+        self,
+        key_id: str,
+        secret: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not _KEY_ID_RE.fullmatch(key_id):
+            raise ValueError(f"easyid: key_id must match ak_<hex>, got: {key_id}")
+        if not secret:
+            raise ValueError("easyid: secret must not be empty")
+
+        self._transport = Transport(
+            key_id=key_id,
+            secret=secret,
+            base_url=base_url,
+            timeout=timeout,
+            session=session,
+        )
+        self.idcard = IDCardService(self._transport)
+        self.phone = PhoneService(self._transport)
+        self.face = FaceService(self._transport)
+        self.bank = BankService(self._transport)
+        self.risk = RiskService(self._transport)
+        self.billing = BillingService(self._transport)
+

easyid_python-1.0.2/src/easyid/error.py

@@ -0,0 +1,20 @@
+"""Error types for the EasyID SDK."""
+
+from __future__ import annotations
+
+
+class APIError(Exception):
+    """Business error returned by the EasyID API."""
+
+    def __init__(self, code: int, message: str, request_id: str) -> None:
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        super().__init__(f"easyid: code={code} message={message} request_id={request_id}")
+
+
+def is_api_error(exc: BaseException) -> bool:
+    """Return True when *exc* is an :class:`APIError`."""
+
+    return isinstance(exc, APIError)
+

easyid_python-1.0.2/src/easyid/face.py

@@ -0,0 +1,85 @@
+"""Face APIs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .transport import FileInput, Transport, make_multipart_part
+
+
+@dataclass(frozen=True)
+class LivenessResult:
+    liveness: bool
+    score: float
+    method: str
+    frames_analyzed: int
+    attack_type: Optional[str]
+
+
+@dataclass(frozen=True)
+class CompareResult:
+    match: bool
+    score: float
+
+
+@dataclass(frozen=True)
+class FaceVerifyResult:
+    result: bool
+    supplier: str
+    score: float
+
+
+class FaceService:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def liveness(
+        self,
+        *,
+        media: FileInput,
+        mode: Optional[str] = None,
+        filename: Optional[str] = None,
+    ) -> LivenessResult:
+        fields = {}
+        if mode is not None:
+            fields["mode"] = mode
+        data = self._transport.request_multipart(
+            "/v1/face/liveness",
+            fields=fields,
+            files=[make_multipart_part("media", media, filename)],
+        )
+        return LivenessResult(**data)
+
+    def compare(
+        self,
+        *,
+        image1: FileInput,
+        image2: FileInput,
+        filename1: Optional[str] = None,
+        filename2: Optional[str] = None,
+    ) -> CompareResult:
+        data = self._transport.request_multipart(
+            "/v1/face/compare",
+            files=[
+                make_multipart_part("image1", image1, filename1),
+                make_multipart_part("image2", image2, filename2),
+            ],
+        )
+        return CompareResult(**data)
+
+    def verify(
+        self,
+        *,
+        id_number: str,
+        media_key: Optional[str] = None,
+        callback_url: Optional[str] = None,
+    ) -> FaceVerifyResult:
+        body = {"id_number": id_number}
+        if media_key is not None:
+            body["media_key"] = media_key
+        if callback_url is not None:
+            body["callback_url"] = callback_url
+        data = self._transport.request_json("POST", "/v1/face/verify", body=body)
+        return FaceVerifyResult(**data)
+