python-library-ewelink 0.1.0__tar.gz

python_library_ewelink-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+config.yaml
+logs/

python_library_ewelink-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: python-library-ewelink
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: aiohttp
+Requires-Dist: pydantic>=2

python_library_ewelink-0.1.0/README.md

@@ -0,0 +1,48 @@
+# Action 参数手册
+
+## set_switch
+
+控制单通道设备开关。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| device | str | 是 | 设备 ID |
+| state | state | 是 | `"on"` / `"off"` |
+
+## set_outlet
+
+控制多通道设备的某一个通道。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| device | str | 是 | 设备 ID |
+| outlet | int | 是 | 通道编号（从 0 开始） |
+| state | state | 是 | `"on"` / `"off"` |
+
+## set_outlets
+
+同时控制多个通道。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| device | str | 是 | 设备 ID |
+| switches | list | 是 | 通道列表，每项含 `outlet` (int) 和 `state` (state) |
+
+## pulse_outlet
+
+脉冲控制：开启指定通道 → 等待 → 自动关闭。
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| device | str | 是 | | 设备 ID |
+| outlet | int | 是 | | 通道编号 |
+| hold_seconds | float | 否 | 0.5 | 保持时长（秒），必须 > 0 |
+
+## set_params
+
+原始参数透传，直接发送任意 params 到设备。当以上 action 不能满足需求时使用。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| device | str | 是 | 设备 ID |
+| params | dict | 是 | 发送给设备的原始参数 |

python_library_ewelink-0.1.0/ewelink/__init__.py

@@ -0,0 +1,34 @@
+from .actions import (
+    REGISTRY,
+    ActionBase,
+    State,
+    SwitchEntry,
+    register,
+    supported_actions,
+    validate_task,
+    validate_tasks,
+)
+from .client import EWeLinkClient
+from .exceptions import EWeLinkAPIError, EWeLinkAuthError, EWeLinkError
+from .regions import infer_country_code
+from .sync import SyncEWeLinkClient
+from .types import SwitchItem, SwitchState
+
+__all__ = [
+    "EWeLinkClient",
+    "EWeLinkError",
+    "EWeLinkAuthError",
+    "EWeLinkAPIError",
+    "SyncEWeLinkClient",
+    "SwitchState",
+    "SwitchItem",
+    "infer_country_code",
+    "REGISTRY",
+    "ActionBase",
+    "State",
+    "SwitchEntry",
+    "register",
+    "supported_actions",
+    "validate_task",
+    "validate_tasks",
+]

python_library_ewelink-0.1.0/ewelink/actions/__init__.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from ._base import ActionBase, State, SwitchEntry
+from ._registry import REGISTRY, register
+
+# ── 自动扫描：导入本目录下所有非下划线开头的 .py ──
+_pkg_dir = Path(__file__).parent
+for _info in pkgutil.iter_modules([str(_pkg_dir)]):
+    if not _info.name.startswith("_"):
+        importlib.import_module(f".{_info.name}", __package__)
+
+
+def validate_task(data: dict[str, Any]) -> ActionBase:
+    """校验单个任务配置，返回对应的 action 模型实例。"""
+    action = data.get("action")
+    if not action:
+        raise ValueError("缺少必填字段 'action'")
+    if action not in REGISTRY:
+        supported = ", ".join(sorted(REGISTRY))
+        raise ValueError(f"不支持的 action: {action!r}，当前支持: {supported}")
+
+    payload = {k: v for k, v in data.items() if k != "action"}
+    try:
+        return REGISTRY[action].model_validate(payload)
+    except ValidationError as e:
+        raise ValueError(f"action={action!r} 校验失败:\n{e}") from None
+
+
+def validate_tasks(raw_list: list[dict[str, Any]]) -> list[ActionBase]:
+    """批量校验，所有错误一次性报出。"""
+    results: list[ActionBase] = []
+    errors: list[str] = []
+    for i, raw in enumerate(raw_list, 1):
+        try:
+            results.append(validate_task(raw))
+        except ValueError as e:
+            errors.append(f"任务 #{i}: {e}")
+    if errors:
+        raise ValueError("配置校验失败:\n" + "\n".join(errors))
+    return results
+
+
+def supported_actions() -> dict[str, str]:
+    """返回所有已注册的 action 及其描述。"""
+    return {
+        name: (cls.__doc__ or "").strip()
+        for name, cls in sorted(REGISTRY.items())
+    }

python_library_ewelink-0.1.0/ewelink/actions/_base.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict
+
+if TYPE_CHECKING:
+    from ..client import EWeLinkClient
+
+
+def _normalize_state(v: Any) -> str:
+    """YAML 会把 on/off 解析为 True/False，在此统一转回字符串。"""
+    if v is True:
+        return "on"
+    if v is False:
+        return "off"
+    if v in ("on", "off"):
+        return v
+    raise ValueError(f"无效值 {v!r}，应为 'on' 或 'off'")
+
+
+State = Annotated[str, BeforeValidator(_normalize_state)]
+
+
+class SwitchEntry(BaseModel):
+    outlet: int
+    state: State
+
+
+class ActionBase(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    action_name: ClassVar[str] = ""
+    device: str
+
+    async def execute(self, client: EWeLinkClient) -> dict[str, Any] | None:
+        raise NotImplementedError

python_library_ewelink-0.1.0/ewelink/actions/_registry.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._base import ActionBase
+
+REGISTRY: dict[str, type[ActionBase]] = {}
+
+
+def register(action: str):
+    """装饰器：将 action 模型注册到 REGISTRY。"""
+    def decorator(cls: type[ActionBase]) -> type[ActionBase]:
+        if action in REGISTRY:
+            raise ValueError(f"Duplicate action: {action!r}")
+        cls.action_name = action
+        REGISTRY[action] = cls
+        return cls
+    return decorator

python_library_ewelink-0.1.0/ewelink/actions/pulse_outlet.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+from pydantic import Field
+
+from ._base import ActionBase
+from ._registry import register
+
+
+@register("pulse_outlet")
+class PulseOutletAction(ActionBase):
+    """脉冲控制（开→等待→关）"""
+
+    outlet: int
+    hold_seconds: float = Field(default=0.5, gt=0)
+
+    async def execute(self, client) -> dict[str, Any] | None:
+        await client.pulse_outlet(self.device, self.outlet, self.hold_seconds)
+        return None

python_library_ewelink-0.1.0/ewelink/actions/set_outlet.py

@@ -0,0 +1,15 @@
+from typing import Any
+
+from ._base import ActionBase, State
+from ._registry import register
+
+
+@register("set_outlet")
+class SetOutletAction(ActionBase):
+    """控制多通道设备的某一个通道"""
+
+    outlet: int
+    state: State
+
+    async def execute(self, client) -> dict[str, Any] | None:
+        return await client.set_outlet(self.device, self.outlet, self.state)

python_library_ewelink-0.1.0/ewelink/actions/set_outlets.py

@@ -0,0 +1,15 @@
+from typing import Any
+
+from ._base import ActionBase, SwitchEntry
+from ._registry import register
+
+
+@register("set_outlets")
+class SetOutletsAction(ActionBase):
+    """同时控制多个通道"""
+
+    switches: list[SwitchEntry]
+
+    async def execute(self, client) -> dict[str, Any] | None:
+        payload = [{"outlet": s.outlet, "switch": s.state} for s in self.switches]
+        return await client.set_outlets(self.device, payload)

python_library_ewelink-0.1.0/ewelink/actions/set_params.py

@@ -0,0 +1,14 @@
+from typing import Any
+
+from ._base import ActionBase
+from ._registry import register
+
+
+@register("set_params")
+class SetParamsAction(ActionBase):
+    """原始参数透传（万能兜底）"""
+
+    params: dict[str, Any]
+
+    async def execute(self, client) -> dict[str, Any] | None:
+        return await client.set_device_params(self.device, self.params)

python_library_ewelink-0.1.0/ewelink/actions/set_switch.py

@@ -0,0 +1,14 @@
+from typing import Any
+
+from ._base import ActionBase, State
+from ._registry import register
+
+
+@register("set_switch")
+class SetSwitchAction(ActionBase):
+    """控制单通道设备开关"""
+
+    state: State
+
+    async def execute(self, client) -> dict[str, Any] | None:
+        return await client.set_switch(self.device, self.state)

python_library_ewelink-0.1.0/ewelink/auth.py

@@ -0,0 +1,26 @@
+import base64
+import hashlib
+import hmac
+
+APP_ID = "R8Oq3y0eSZSYdKccHlrQzT1ACCOUT9Gv"
+_APP_SECRET = "1ve5Qk9GXfUhKAn1svnKwpAlxXkMarru"
+
+
+def sign_payload(msg: bytes) -> bytes:
+    return hmac.new(_APP_SECRET.encode(), msg, hashlib.sha256).digest()
+
+
+def build_phone_number(username: str, country_code: str) -> str:
+    if username.startswith("+"):
+        return username
+    if username.startswith(country_code.lstrip("+")):
+        return "+" + username
+    return country_code + username
+
+if __name__ == "__main__":
+    from regions import REGIONS
+    import base64
+    encoded = base64.b64encode(str(REGIONS).encode())
+    secret_map = "L8KDAMO6wpomxpYZwrHhu4AuEjQKBy8nwoMHNB7DmwoWwrvCsSYGw4wDAxs="
+    key = bytes(encoded[ord(ch)] for ch in base64.b64decode(secret_map).decode())
+    print(key.decode())  # ← 这就是 _APP_SECRET 的值

python_library_ewelink-0.1.0/ewelink/client.py

@@ -0,0 +1,196 @@
+import asyncio
+import base64
+import json
+from typing import Any
+
+import aiohttp
+
+from .auth import APP_ID, build_phone_number, sign_payload
+from .exceptions import EWeLinkAPIError, EWeLinkAuthError
+from .regions import API, REGIONS, infer_country_code
+from .types import SwitchItem, SwitchState
+
+_TIMEOUT = aiohttp.ClientTimeout(total=15)
+_MAX_RETRIES = 3
+
+
+class EWeLinkClient:
+    def __init__(self, session: aiohttp.ClientSession | None = None):
+        self._external_session = session is not None
+        self.session = session
+        self.region: str | None = None
+        self.auth: dict[str, Any] | None = None
+
+    # ── lifecycle ──
+
+    async def __aenter__(self):
+        if self.session is None:
+            self.session = aiohttp.ClientSession()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        if self.session and not self._external_session:
+            await self.session.close()
+
+    # ── auth ──
+
+    async def login(
+        self,
+        username: str,
+        password: str,
+        country_code: str | None = None,
+        region: str | None = None,
+    ) -> dict[str, Any]:
+        if not self.session:
+            raise RuntimeError("Use 'async with EWeLinkClient()' or provide a session")
+
+        country_code = country_code or infer_country_code(username)
+        self.region = region or REGIONS.get(country_code, ("Unknown", "cn"))[1]
+
+        payload: dict[str, Any] = {"password": password, "countryCode": country_code}
+        if "@" in username:
+            payload["email"] = username
+        else:
+            payload["phoneNumber"] = build_phone_number(username, country_code)
+
+        data = json.dumps(payload, separators=(",", ":")).encode()
+        headers = {
+            "Authorization": "Sign " + base64.b64encode(sign_payload(data)).decode(),
+            "Content-Type": "application/json",
+            "X-CK-Appid": APP_ID,
+        }
+
+        resp = await self._request("POST", "/v2/user/login", data=data, headers=headers)
+
+        if resp.get("error") == 10004 and resp.get("data", {}).get("region"):
+            self.region = resp["data"]["region"]
+            resp = await self._request("POST", "/v2/user/login", data=data, headers=headers)
+
+        if resp.get("error") != 0:
+            raise EWeLinkAuthError(
+                f"Login failed: error={resp.get('error')} msg={resp.get('msg')}"
+            )
+
+        self.auth = resp["data"]
+        self.auth["appid"] = APP_ID
+        return self.auth
+
+    # ── devices: query ──
+
+    async def get_devices(self, family_id: str | None = None) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"num": 0}
+        if family_id:
+            params["familyid"] = family_id
+
+        resp = await self._api_get("/v2/device/thing", params=params)
+        return [
+            item["itemData"]
+            for item in resp["data"]["thingList"]
+            if "deviceid" in item.get("itemData", {})
+        ]
+
+    async def get_device(self, device_id: str) -> dict[str, Any] | None:
+        resp = await self._api_post(
+            "/v2/device/thing",
+            json={"thingList": [{"itemType": 1, "id": device_id}]},
+        )
+        for item in resp["data"].get("thingList", []):
+            data = item.get("itemData", {})
+            if data.get("deviceid") == device_id:
+                return data
+        return None
+
+    # ── devices: control ──
+
+    async def set_device_params(self, device_id: str, params: dict[str, Any]) -> dict[str, Any]:
+        return await self._api_post(
+            "/v2/device/thing/status",
+            json={"type": 1, "id": device_id, "params": params},
+        )
+
+    async def set_switch(self, device_id: str, state: SwitchState) -> dict[str, Any]:
+        return await self.set_device_params(device_id, {"switch": state})
+
+    async def set_outlet(
+        self, device_id: str, outlet: int, state: SwitchState,
+    ) -> dict[str, Any]:
+        return await self.set_device_params(
+            device_id, {"switches": [{"outlet": outlet, "switch": state}]},
+        )
+
+    async def set_outlets(
+        self, device_id: str, switches: list[SwitchItem],
+    ) -> dict[str, Any]:
+        return await self.set_device_params(device_id, {"switches": switches})
+
+    async def pulse_outlet(
+        self, device_id: str, outlet: int, hold_seconds: float = 0.5,
+    ) -> None:
+        if hold_seconds <= 0:
+            raise ValueError("hold_seconds must be > 0")
+        await self.set_outlet(device_id, outlet, "on")
+        try:
+            await asyncio.sleep(hold_seconds)
+        finally:
+            await self.set_outlet(device_id, outlet, "off")
+
+    # ── internal: HTTP ──
+
+    def _ensure_ready(self) -> None:
+        if not self.session:
+            raise RuntimeError("Use 'async with EWeLinkClient()' or provide a session")
+        if not self.auth or not self.region:
+            raise EWeLinkAuthError("Not logged in")
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": "Bearer " + self.auth["at"],
+            "X-CK-Appid": APP_ID,
+        }
+
+    async def _api_get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        self._ensure_ready()
+        resp = await self._request("GET", path, headers=self._headers, **kwargs)
+        _check_response(resp)
+        return resp
+
+    async def _api_post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        self._ensure_ready()
+        resp = await self._request("POST", path, headers=self._headers, **kwargs)
+        _check_response(resp)
+        return resp
+
+    async def _request(
+        self, method: str, path: str, *, retries: int = _MAX_RETRIES, **kwargs: Any,
+    ) -> dict[str, Any]:
+        if not self.session or not self.region:
+            raise EWeLinkAuthError("Client not initialized")
+
+        url = API[self.region] + path
+        last_exc: Exception | None = None
+
+        for attempt in range(retries):
+            try:
+                async with self.session.request(
+                    method, url, timeout=_TIMEOUT, **kwargs,
+                ) as response:
+                    text = await response.text()
+                    try:
+                        return json.loads(text)
+                    except json.JSONDecodeError as exc:
+                        raise EWeLinkAPIError(
+                            -1, f"Non-JSON response (HTTP {response.status})",
+                        ) from exc
+            except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
+                last_exc = exc
+                if attempt < retries - 1:
+                    await asyncio.sleep(0.5 * 2**attempt)
+
+        raise EWeLinkAPIError(-1, f"Request failed after {retries} retries") from last_exc
+
+
+def _check_response(resp: dict[str, Any]) -> None:
+    error = resp.get("error", 0)
+    if error != 0:
+        raise EWeLinkAPIError(error, resp.get("msg"), resp.get("data"))

python_library_ewelink-0.1.0/ewelink/exceptions.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+
+class EWeLinkError(Exception):
+    """Base exception for all eWeLink errors."""
+
+
+class EWeLinkAuthError(EWeLinkError):
+    """Authentication or authorization failure."""
+
+
+class EWeLinkAPIError(EWeLinkError):
+    """API returned a non-zero error code."""
+
+    def __init__(self, error: int, msg: str | None = None, data: dict[str, Any] | None = None):
+        self.error = error
+        self.msg = msg
+        self.data = data or {}
+        super().__init__(f"API error {error}: {msg}")

python_library_ewelink-0.1.0/ewelink/regions.py

@@ -0,0 +1,221 @@
+API = {
+    "cn": "https://cn-apia.coolkit.cn",
+    "as": "https://as-apia.coolkit.cc",
+    "us": "https://us-apia.coolkit.cc",
+    "eu": "https://eu-apia.coolkit.cc",
+}
+
+REGIONS = {
+    "+93": ("Afghanistan", "as"),
+    "+355": ("Albania", "eu"),
+    "+213": ("Algeria", "eu"),
+    "+376": ("Andorra", "eu"),
+    "+244": ("Angola", "eu"),
+    "+1264": ("Anguilla", "us"),
+    "+1268": ("Antigua and Barbuda", "as"),
+    "+54": ("Argentina", "us"),
+    "+374": ("Armenia", "as"),
+    "+297": ("Aruba", "eu"),
+    "+247": ("Ascension", "eu"),
+    "+61": ("Australia", "us"),
+    "+43": ("Austria", "eu"),
+    "+994": ("Azerbaijan", "as"),
+    "+1242": ("Bahamas", "us"),
+    "+973": ("Bahrain", "as"),
+    "+880": ("Bangladesh", "as"),
+    "+1246": ("Barbados", "us"),
+    "+375": ("Belarus", "eu"),
+    "+32": ("Belgium", "eu"),
+    "+501": ("Belize", "us"),
+    "+229": ("Benin", "eu"),
+    "+1441": ("Bermuda", "as"),
+    "+591": ("Bolivia", "us"),
+    "+387": ("Bosnia and Herzegovina", "eu"),
+    "+267": ("Botswana", "eu"),
+    "+55": ("Brazil", "us"),
+    "+673": ("Brunei", "as"),
+    "+359": ("Bulgaria", "eu"),
+    "+226": ("Burkina Faso", "eu"),
+    "+257": ("Burundi", "eu"),
+    "+855": ("Cambodia", "as"),
+    "+237": ("Cameroon", "eu"),
+    "+238": ("Cape Verde Republic", "eu"),
+    "+1345": ("Cayman Islands", "as"),
+    "+236": ("Central African Republic", "eu"),
+    "+235": ("Chad", "eu"),
+    "+56": ("Chile", "us"),
+    "+86": ("China", "cn"),
+    "+57": ("Colombia", "us"),
+    "+682": ("Cook Islands", "us"),
+    "+506": ("Costa Rica", "us"),
+    "+385": ("Croatia", "eu"),
+    "+53": ("Cuba", "us"),
+    "+357": ("Cyprus", "eu"),
+    "+420": ("Czech", "eu"),
+    "+243": ("Democratic Republic of Congo", "eu"),
+    "+45": ("Denmark", "eu"),
+    "+253": ("Djibouti", "eu"),
+    "+1767": ("Dominica", "as"),
+    "+1809": ("Dominican Republic", "us"),
+    "+670": ("East Timor", "as"),
+    "+684": ("Eastern Samoa (US)", "us"),
+    "+593": ("Ecuador", "us"),
+    "+20": ("Egypt", "eu"),
+    "+503": ("El Salvador", "us"),
+    "+372": ("Estonia", "eu"),
+    "+251": ("Ethiopia", "eu"),
+    "+298": ("Faroe Islands", "eu"),
+    "+679": ("Fiji", "us"),
+    "+358": ("Finland", "eu"),
+    "+33": ("France", "eu"),
+    "+594": ("French Guiana", "us"),
+    "+689": ("French Polynesia", "as"),
+    "+241": ("Gabon", "eu"),
+    "+220": ("Gambia", "eu"),
+    "+995": ("Georgia", "as"),
+    "+49": ("Germany", "eu"),
+    "+233": ("Ghana", "eu"),
+    "+350": ("Gibraltar", "eu"),
+    "+30": ("Greece", "eu"),
+    "+299": ("Greenland", "us"),
+    "+1473": ("Grenada", "as"),
+    "+590": ("Guadeloupe", "us"),
+    "+1671": ("Guam", "us"),
+    "+502": ("Guatemala", "us"),
+    "+240": ("Guinea", "eu"),
+    "+224": ("Guinea", "eu"),
+    "+592": ("Guyana", "us"),
+    "+509": ("Haiti", "us"),
+    "+504": ("Honduras", "us"),
+    "+852": ("Hong Kong, China", "as"),
+    "+36": ("Hungary", "eu"),
+    "+354": ("Iceland", "eu"),
+    "+91": ("India", "as"),
+    "+62": ("Indonesia", "as"),
+    "+98": ("Iran", "as"),
+    "+353": ("Ireland", "eu"),
+    "+269": ("Islamic Federal Republic of Comoros", "eu"),
+    "+972": ("Israel", "as"),
+    "+39": ("Italian", "eu"),
+    "+225": ("Ivory Coast", "eu"),
+    "+1876": ("Jamaica", "us"),
+    "+81": ("Japan", "as"),
+    "+962": ("Jordan", "as"),
+    "+254": ("Kenya", "eu"),
+    "+975": ("Kingdom of Bhutan", "as"),
+    "+383": ("Kosovo", "eu"),
+    "+965": ("Kuwait", "as"),
+    "+996": ("Kyrgyzstan", "as"),
+    "+856": ("Laos", "as"),
+    "+371": ("Latvia", "eu"),
+    "+961": ("Lebanon", "as"),
+    "+266": ("Lesotho", "eu"),
+    "+231": ("Liberia", "eu"),
+    "+218": ("Libya", "eu"),
+    "+423": ("Liechtenstein", "eu"),
+    "+370": ("Lithuania", "eu"),
+    "+352": ("Luxembourg", "eu"),
+    "+853": ("Macau, China", "as"),
+    "+261": ("Madagascar", "eu"),
+    "+265": ("Malawi", "eu"),
+    "+60": ("Malaysia", "as"),
+    "+960": ("Maldives", "as"),
+    "+223": ("Mali", "eu"),
+    "+356": ("Malta", "eu"),
+    "+596": ("Martinique", "us"),
+    "+222": ("Mauritania", "eu"),
+    "+230": ("Mauritius", "eu"),
+    "+52": ("Mexico", "us"),
+    "+373": ("Moldova", "eu"),
+    "+377": ("Monaco", "eu"),
+    "+976": ("Mongolia", "as"),
+    "+382": ("Montenegro", "as"),
+    "+1664": ("Montserrat", "as"),
+    "+212": ("Morocco", "eu"),
+    "+258": ("Mozambique", "eu"),
+    "+95": ("Myanmar", "as"),
+    "+264": ("Namibia", "eu"),
+    "+977": ("Nepal", "as"),
+    "+31": ("Netherlands", "eu"),
+    "+599": ("Netherlands Antilles", "as"),
+    "+687": ("New Caledonia", "as"),
+    "+64": ("New Zealand", "us"),
+    "+505": ("Nicaragua", "us"),
+    "+227": ("Niger", "eu"),
+    "+234": ("Nigeria", "eu"),
+    "+47": ("Norway", "eu"),
+    "+968": ("Oman", "as"),
+    "+92": ("Pakistan", "as"),
+    "+970": ("Palestine", "as"),
+    "+507": ("Panama", "us"),
+    "+675": ("Papua New Guinea", "as"),
+    "+595": ("Paraguay", "us"),
+    "+51": ("Peru", "us"),
+    "+63": ("Philippines", "as"),
+    "+48": ("Poland", "eu"),
+    "+351": ("Portugal", "eu"),
+    "+974": ("Qatar", "as"),
+    "+242": ("Republic of Congo", "eu"),
+    "+964": ("Republic of Iraq", "as"),
+    "+389": ("Republic of Macedonia", "eu"),
+    "+262": ("Reunion", "eu"),
+    "+40": ("Romania", "eu"),
+    "+7": ("Russia", "eu"),
+    "+250": ("Rwanda", "eu"),
+    "+1869": ("Saint Kitts and Nevis", "as"),
+    "+1758": ("Saint Lucia", "us"),
+    "+1784": ("Saint Vincent", "as"),
+    "+378": ("San Marino", "eu"),
+    "+239": ("Sao Tome and Principe", "eu"),
+    "+966": ("Saudi Arabia", "as"),
+    "+221": ("Senegal", "eu"),
+    "+381": ("Serbia", "eu"),
+    "+248": ("Seychelles", "eu"),
+    "+232": ("Sierra Leone", "eu"),
+    "+65": ("Singapore", "as"),
+    "+421": ("Slovakia", "eu"),
+    "+386": ("Slovenia", "eu"),
+    "+27": ("South Africa", "eu"),
+    "+82": ("South Korea", "as"),
+    "+34": ("Spain", "eu"),
+    "+94": ("Sri Lanka", "as"),
+    "+249": ("Sultan", "eu"),
+    "+597": ("Suriname", "us"),
+    "+268": ("Swaziland", "eu"),
+    "+46": ("Sweden", "eu"),
+    "+41": ("Switzerland", "eu"),
+    "+963": ("Syria", "as"),
+    "+886": ("Taiwan, China", "as"),
+    "+992": ("Tajikistan", "as"),
+    "+255": ("Tanzania", "eu"),
+    "+66": ("Thailand", "as"),
+    "+228": ("Togo", "eu"),
+    "+676": ("Tonga", "us"),
+    "+1868": ("Trinidad and Tobago", "us"),
+    "+216": ("Tunisia", "eu"),
+    "+90": ("Turkey", "as"),
+    "+993": ("Turkmenistan", "as"),
+    "+1649": ("Turks and Caicos", "as"),
+    "+44": ("UK", "eu"),
+    "+256": ("Uganda", "eu"),
+    "+380": ("Ukraine", "eu"),
+    "+971": ("United Arab Emirates", "as"),
+    "+1": ("United States", "us"),
+    "+598": ("Uruguay", "us"),
+    "+998": ("Uzbekistan", "as"),
+    "+678": ("Vanuatu", "us"),
+    "+58": ("Venezuela", "us"),
+    "+84": ("Vietnam", "as"),
+    "+685": ("Western Samoa", "us"),
+    "+1340": ("Wilk Islands", "as"),
+    "+967": ("Yemen", "as"),
+    "+260": ("Zambia", "eu"),
+    "+263": ("Zimbabwe", "eu"),
+}
+
+
+def infer_country_code(username: str, fallback: str = "+86") -> str:
+    if not username.startswith("+"):
+        return fallback
+    matches = [code for code in REGIONS if username.startswith(code)]
+    return max(matches, key=len) if matches else fallback

python_library_ewelink-0.1.0/ewelink/sync.py

@@ -0,0 +1,79 @@
+import asyncio
+from typing import Any
+
+from .client import EWeLinkClient
+from .types import SwitchItem, SwitchState
+
+
+class SyncEWeLinkClient:
+    """Convenience wrapper that reuses a single session and login."""
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        country_code: str | None = None,
+        region: str | None = None,
+    ):
+        self._username = username
+        self._password = password
+        self._country_code = country_code
+        self._region = region
+        self._loop = asyncio.new_event_loop()
+        self._client = EWeLinkClient()
+        self._loop.run_until_complete(self._client.__aenter__())
+        self._logged_in = False
+
+    def _ensure_login(self) -> None:
+        if not self._logged_in:
+            self._loop.run_until_complete(
+                self._client.login(
+                    self._username,
+                    self._password,
+                    self._country_code,
+                    self._region,
+                )
+            )
+            self._logged_in = True
+
+    # ── devices: query ──
+
+    def get_devices(self, family_id: str | None = None) -> list[dict[str, Any]]:
+        self._ensure_login()
+        return self._loop.run_until_complete(self._client.get_devices(family_id))
+
+    def get_device(self, device_id: str) -> dict[str, Any] | None:
+        self._ensure_login()
+        return self._loop.run_until_complete(self._client.get_device(device_id))
+
+    # ── devices: control ──
+
+    def set_switch(self, device_id: str, state: SwitchState) -> dict[str, Any]:
+        self._ensure_login()
+        return self._loop.run_until_complete(self._client.set_switch(device_id, state))
+
+    def set_outlet(self, device_id: str, outlet: int, state: SwitchState) -> dict[str, Any]:
+        self._ensure_login()
+        return self._loop.run_until_complete(self._client.set_outlet(device_id, outlet, state))
+
+    def set_outlets(self, device_id: str, switches: list[SwitchItem]) -> dict[str, Any]:
+        self._ensure_login()
+        return self._loop.run_until_complete(self._client.set_outlets(device_id, switches))
+
+    def pulse_outlet(self, device_id: str, outlet: int, hold_seconds: float = 0.5) -> None:
+        self._ensure_login()
+        self._loop.run_until_complete(
+            self._client.pulse_outlet(device_id, outlet, hold_seconds)
+        )
+
+    # ── lifecycle ──
+
+    def close(self) -> None:
+        self._loop.run_until_complete(self._client.__aexit__(None, None, None))
+        self._loop.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

python_library_ewelink-0.1.0/ewelink/types.py

@@ -0,0 +1,8 @@
+from typing import Literal, TypedDict
+
+SwitchState = Literal["on", "off"]
+
+
+class SwitchItem(TypedDict):
+    outlet: int
+    switch: SwitchState

python_library_ewelink-0.1.0/example_control_devices.bat

@@ -0,0 +1,11 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    call update.bat
+)
+
+call .venv\Scripts\activate.bat
+
+pip install python-dotenv pyyaml
+python examples/control_device

python_library_ewelink-0.1.0/example_get_devices.bat

@@ -0,0 +1,11 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    call update.bat
+)
+
+call .venv\Scripts\activate.bat
+
+pip install python-dotenv
+python examples/get_devices

python_library_ewelink-0.1.0/examples/control_device/__main__.py

@@ -0,0 +1,45 @@
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+import yaml
+from dotenv import load_dotenv
+
+from ewelink import EWeLinkClient, infer_country_code, validate_tasks
+
+
+async def main() -> None:
+    load_dotenv(".env")
+
+    tasks_file = (
+        Path(sys.argv[1])
+        if len(sys.argv) > 1
+        else Path(__file__).with_name("config.yaml")
+    )
+    if not tasks_file.exists():
+        print(f"Tasks file not found: {tasks_file}")
+        sys.exit(1)
+
+    config = yaml.safe_load(tasks_file.read_text(encoding="utf-8"))
+    tasks = validate_tasks(config.get("tasks", []))
+
+    async with EWeLinkClient() as client:
+        await client.login(
+            username=os.environ["EWELINK_EMAIL"],
+            password=os.environ["EWELINK_PASSWORD"],
+            country_code=infer_country_code(os.environ["EWELINK_EMAIL"]),
+            region=os.environ.get("EWELINK_REGION"),
+        )
+
+        for i, task in enumerate(tasks, 1):
+            print(f"[{i}/{len(tasks)}] device={task.device} action={task.action_name} ...", end=" ")
+            try:
+                await task.execute(client)
+                print("OK")
+            except Exception as exc:
+                print(f"FAILED: {exc}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python_library_ewelink-0.1.0/examples/get_devices/__main__.py

@@ -0,0 +1,35 @@
+import asyncio
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from ewelink import EWeLinkClient, infer_country_code
+
+
+async def main():
+    load_dotenv(".env")
+
+    email = os.environ["EWELINK_EMAIL"]
+    password = os.environ["EWELINK_PASSWORD"]
+    region = os.environ.get("EWELINK_REGION")
+
+    async with EWeLinkClient() as client:
+        await client.login(
+            username=email,
+            password=password,
+            country_code=infer_country_code(email),
+            region=region,
+        )
+
+        devices = await client.get_devices()
+        for d in devices:
+            name = d.get("name")
+            device_id = d.get("deviceid")
+
+            device = await client.get_device(device_id)
+            print(f"[{name}-{device_id}]: \n{device}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python_library_ewelink-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-library-ewelink"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+  "aiohttp",
+  "pydantic>=2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ewelink"]
+
+[tool.hatch.metadata]
+allow-direct-references = true

python_library_ewelink-0.1.0/update.bat

@@ -0,0 +1,9 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    python -m venv .venv
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e .