leapmotor-api 0.1.0__tar.gz

leapmotor_api-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Type check with mypy
+        run: mypy src/
+
+      - name: Run tests
+        run: pytest --cov=leapmotor_api --cov-report=term-missing

leapmotor_api-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/leapmotor-api
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

leapmotor_api-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Distribution
+*.tar.gz
+*.whl

leapmotor_api-0.1.0/LICENSE

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

leapmotor_api-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: leapmotor-api
+Version: 0.1.0
+Summary: Unofficial Python client for the Leapmotor vehicle cloud API
+Project-URL: Homepage, https://github.com/markoceri/leapmotor-api
+Project-URL: Issues, https://github.com/markoceri/leapmotor-api/issues
+Author: markoceri
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,ev,iot,leapmotor,vehicle
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: requests>=2.32.4
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: image
+Requires-Dist: pillow>=10.0.0; extra == 'image'
+Description-Content-Type: text/markdown
+
+# leapmotor-api
+
+Unofficial Python client for the Leapmotor vehicle cloud API.
+
+Extracted from the [leapmotor-ha](https://github.com/kerniger/leapmotor-ha) Home Assistant integration
+to provide a reusable, framework-agnostic library.
+
+## Acknowledgments
+
+Special thanks to [Jakob Kern](https://github.com/kerniger) for the impressive reverse engineering work on the Leapmotor application and for generously sharing his work.
+
+## Installation
+
+```bash
+pip install leapmotor-api
+```
+
+## Quick Start
+
+```python
+from leapmotor_api import LeapmotorApiClient
+
+client = LeapmotorApiClient(
+    username="user@example.com",
+    password="password",
+    app_cert_path="/path/to/app_cert.pem",
+    app_key_path="/path/to/app_key.pem",
+    language="it-IT",  # default: en-GB
+)
+
+client.login()
+vehicles = client.get_vehicle_list()
+
+for vehicle in vehicles:
+    print(f"{vehicle.vin} ({vehicle.car_type}) — {vehicle.nickname}")
+    status = client.get_vehicle_status(vehicle)
+    print(f"  Battery: {status.battery.soc}%")
+    print(f"  Range: {status.battery.expected_mileage} km")
+    print(f"  Odometer: {status.driving.total_mileage} km")
+
+client.close()
+```
+
+## Typed Models vs Raw Data
+
+The library exposes two ways to access vehicle data:
+
+### Typed models (recommended)
+
+`get_vehicle_status()` returns a `VehicleStatus` dataclass with typed sub-objects:
+
+```python
+status = client.get_vehicle_status(vehicle)
+
+# Battery & charging
+status.battery.soc                  # int | None — state of charge %
+status.battery.expected_mileage     # int | None — remaining range km
+status.battery.is_charging          # bool | None
+status.battery.charging_power_kw    # float | None
+status.battery.dump_energy_kwh      # float | None — available energy in kWh
+
+# Driving
+status.driving.total_mileage        # int | None — odometer km
+status.driving.speed                # int | None
+status.driving.is_parked            # bool | None
+
+# Location
+status.location.latitude            # float | None
+status.location.longitude           # float | None
+
+# Climate
+status.climate.ac_switch            # bool | None
+status.climate.outdoor_temp         # int | None
+
+# Doors & locks
+status.doors.is_locked              # bool | None
+
+# Windows
+status.windows.left_front_window_percent   # int | None
+
+# Tire pressure
+status.tires.front_left_bar         # float | None — pressure in bar
+status.tires.all_ok                 # bool | None — all pressures normal
+
+# Connectivity
+status.connectivity.bluetooth_state # bool | None
+
+# Timestamps
+status.collect_time                 # datetime | None
+```
+
+### Raw API data
+
+For forward-compatibility or debugging, use `get_vehicle_raw_status()`:
+
+```python
+raw = client.get_vehicle_raw_status(vehicle)
+# Returns the full API JSON dict with signal codes, config, etc.
+# raw["data"]["signal"]["1204"]  → battery SOC
+# raw["data"]["config"]["3"]     → charging plan
+```
+
+The `VehicleStatus` object also retains the raw dict in `status.raw` for convenience.
+
+## Async Usage
+
+```python
+from leapmotor_api import LeapmotorApiClient
+from leapmotor_api.async_client import AsyncLeapmotorApiClient
+
+sync_client = LeapmotorApiClient(
+    username="user@example.com",
+    password="password",
+    app_cert_path="/path/to/app_cert.pem",
+    app_key_path="/path/to/app_key.pem",
+    language="it-IT",
+)
+client = AsyncLeapmotorApiClient(sync_client)
+
+await client.login()
+vehicles = await client.get_vehicle_list()
+status = await client.get_vehicle_status(vehicles[0])
+await client.close()
+```
+
+## Remote Control
+
+Remote actions require the vehicle PIN:
+
+```python
+client = LeapmotorApiClient(
+    username="user@example.com",
+    password="password",
+    app_cert_path="/path/to/app_cert.pem",
+    app_key_path="/path/to/app_key.pem",
+    operation_password="1234",
+    language="de-DE",
+)
+
+client.login()
+client.lock_vehicle("WLM...")
+client.unlock_vehicle("WLM...")
+client.open_trunk("WLM...")
+client.close_trunk("WLM...")
+client.find_vehicle("WLM...")
+client.open_windows("WLM...")
+client.close_windows("WLM...")
+client.ac_switch("WLM...")
+client.quick_cool("WLM...")
+client.quick_heat("WLM...")
+client.windshield_defrost("WLM...")
+client.open_sunshade("WLM...")
+client.close_sunshade("WLM...")
+client.battery_preheat("WLM...")
+client.set_charge_limit("WLM...", charge_limit_percent=80)
+client.close()
+```
+
+## License
+
+MIT
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `username` | `str` | — | Leapmotor account email |
+| `password` | `str` | — | Leapmotor account password |
+| `app_cert_path` | `str` | — | Path to app certificate PEM |
+| `app_key_path` | `str` | — | Path to app private key PEM |
+| `operation_password` | `str \| None` | `None` | Vehicle PIN (required for remote control) |
+| `language` | `str` | `"en-GB"` | API language (`en-GB`, `it-IT`, `de-DE`, `fr-FR`, …) |
+| `verify_ssl` | `bool` | `False` | Verify server TLS certificate |
+| `base_url` | `str` | `DEFAULT_BASE_URL` | API base URL |
+| `timeout` | `int` | `30` | HTTP timeout in seconds |
+| `device_id` | `str \| None` | `None` | Custom device ID (auto-generated if omitted) |

leapmotor_api-0.1.0/README.md

@@ -0,0 +1,176 @@
+# leapmotor-api
+
+Unofficial Python client for the Leapmotor vehicle cloud API.
+
+Extracted from the [leapmotor-ha](https://github.com/kerniger/leapmotor-ha) Home Assistant integration
+to provide a reusable, framework-agnostic library.
+
+## Acknowledgments
+
+Special thanks to [Jakob Kern](https://github.com/kerniger) for the impressive reverse engineering work on the Leapmotor application and for generously sharing his work.
+
+## Installation
+
+```bash
+pip install leapmotor-api
+```
+
+## Quick Start
+
+```python
+from leapmotor_api import LeapmotorApiClient
+
+client = LeapmotorApiClient(
+    username="user@example.com",
+    password="password",
+    app_cert_path="/path/to/app_cert.pem",
+    app_key_path="/path/to/app_key.pem",
+    language="it-IT",  # default: en-GB
+)
+
+client.login()
+vehicles = client.get_vehicle_list()
+
+for vehicle in vehicles:
+    print(f"{vehicle.vin} ({vehicle.car_type}) — {vehicle.nickname}")
+    status = client.get_vehicle_status(vehicle)
+    print(f"  Battery: {status.battery.soc}%")
+    print(f"  Range: {status.battery.expected_mileage} km")
+    print(f"  Odometer: {status.driving.total_mileage} km")
+
+client.close()
+```
+
+## Typed Models vs Raw Data
+
+The library exposes two ways to access vehicle data:
+
+### Typed models (recommended)
+
+`get_vehicle_status()` returns a `VehicleStatus` dataclass with typed sub-objects:
+
+```python
+status = client.get_vehicle_status(vehicle)
+
+# Battery & charging
+status.battery.soc                  # int | None — state of charge %
+status.battery.expected_mileage     # int | None — remaining range km
+status.battery.is_charging          # bool | None
+status.battery.charging_power_kw    # float | None
+status.battery.dump_energy_kwh      # float | None — available energy in kWh
+
+# Driving
+status.driving.total_mileage        # int | None — odometer km
+status.driving.speed                # int | None
+status.driving.is_parked            # bool | None
+
+# Location
+status.location.latitude            # float | None
+status.location.longitude           # float | None
+
+# Climate
+status.climate.ac_switch            # bool | None
+status.climate.outdoor_temp         # int | None
+
+# Doors & locks
+status.doors.is_locked              # bool | None
+
+# Windows
+status.windows.left_front_window_percent   # int | None
+
+# Tire pressure
+status.tires.front_left_bar         # float | None — pressure in bar
+status.tires.all_ok                 # bool | None — all pressures normal
+
+# Connectivity
+status.connectivity.bluetooth_state # bool | None
+
+# Timestamps
+status.collect_time                 # datetime | None
+```
+
+### Raw API data
+
+For forward-compatibility or debugging, use `get_vehicle_raw_status()`:
+
+```python
+raw = client.get_vehicle_raw_status(vehicle)
+# Returns the full API JSON dict with signal codes, config, etc.
+# raw["data"]["signal"]["1204"]  → battery SOC
+# raw["data"]["config"]["3"]     → charging plan
+```
+
+The `VehicleStatus` object also retains the raw dict in `status.raw` for convenience.
+
+## Async Usage
+
+```python
+from leapmotor_api import LeapmotorApiClient
+from leapmotor_api.async_client import AsyncLeapmotorApiClient
+
+sync_client = LeapmotorApiClient(
+    username="user@example.com",
+    password="password",
+    app_cert_path="/path/to/app_cert.pem",
+    app_key_path="/path/to/app_key.pem",
+    language="it-IT",
+)
+client = AsyncLeapmotorApiClient(sync_client)
+
+await client.login()
+vehicles = await client.get_vehicle_list()
+status = await client.get_vehicle_status(vehicles[0])
+await client.close()
+```
+
+## Remote Control
+
+Remote actions require the vehicle PIN:
+
+```python
+client = LeapmotorApiClient(
+    username="user@example.com",
+    password="password",
+    app_cert_path="/path/to/app_cert.pem",
+    app_key_path="/path/to/app_key.pem",
+    operation_password="1234",
+    language="de-DE",
+)
+
+client.login()
+client.lock_vehicle("WLM...")
+client.unlock_vehicle("WLM...")
+client.open_trunk("WLM...")
+client.close_trunk("WLM...")
+client.find_vehicle("WLM...")
+client.open_windows("WLM...")
+client.close_windows("WLM...")
+client.ac_switch("WLM...")
+client.quick_cool("WLM...")
+client.quick_heat("WLM...")
+client.windshield_defrost("WLM...")
+client.open_sunshade("WLM...")
+client.close_sunshade("WLM...")
+client.battery_preheat("WLM...")
+client.set_charge_limit("WLM...", charge_limit_percent=80)
+client.close()
+```
+
+## License
+
+MIT
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `username` | `str` | — | Leapmotor account email |
+| `password` | `str` | — | Leapmotor account password |
+| `app_cert_path` | `str` | — | Path to app certificate PEM |
+| `app_key_path` | `str` | — | Path to app private key PEM |
+| `operation_password` | `str \| None` | `None` | Vehicle PIN (required for remote control) |
+| `language` | `str` | `"en-GB"` | API language (`en-GB`, `it-IT`, `de-DE`, `fr-FR`, …) |
+| `verify_ssl` | `bool` | `False` | Verify server TLS certificate |
+| `base_url` | `str` | `DEFAULT_BASE_URL` | API base URL |
+| `timeout` | `int` | `30` | HTTP timeout in seconds |
+| `device_id` | `str \| None` | `None` | Custom device ID (auto-generated if omitted) |

leapmotor_api-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "leapmotor-api"
+version = "0.1.0"
+description = "Unofficial Python client for the Leapmotor vehicle cloud API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [
+    { name = "markoceri" },
+]
+keywords = ["leapmotor", "ev", "vehicle", "api", "iot"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.32.4",
+    "cryptography>=42.0.0",
+]
+
+[project.optional-dependencies]
+image = [
+    "Pillow>=10.0.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "mypy>=1.10",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/markoceri/leapmotor-api"
+Issues = "https://github.com/markoceri/leapmotor-api/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/leapmotor_api"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "S", "B", "A", "C4", "SIM", "TCH"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

leapmotor_api-0.1.0/src/leapmotor_api/__init__.py

@@ -0,0 +1,93 @@
+"""Leapmotor API — Unofficial Python client for the Leapmotor vehicle cloud API."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .client import LeapmotorApiClient, normalize_vehicle
+from .const import (
+    DEFAULT_BASE_URL,
+    DEFAULT_LANGUAGE,
+    REMOTE_ACTION_SPECS,
+    REMOTE_CTL_AC_SWITCH,
+    REMOTE_CTL_BATTERY_PREHEAT,
+    REMOTE_CTL_FIND_CAR,
+    REMOTE_CTL_LOCK,
+    REMOTE_CTL_QUICK_COOL,
+    REMOTE_CTL_QUICK_HEAT,
+    REMOTE_CTL_SUNSHADE,
+    REMOTE_CTL_SUNSHADE_CLOSE,
+    REMOTE_CTL_SUNSHADE_OPEN,
+    REMOTE_CTL_TRUNK,
+    REMOTE_CTL_TRUNK_CLOSE,
+    REMOTE_CTL_TRUNK_OPEN,
+    REMOTE_CTL_UNLOCK,
+    REMOTE_CTL_WINDSHIELD_DEFROST,
+    REMOTE_CTL_WINDOWS,
+    REMOTE_CTL_WINDOWS_CLOSE,
+    REMOTE_CTL_WINDOWS_OPEN,
+)
+from .exceptions import (
+    LeapmotorAccountCertError,
+    LeapmotorApiError,
+    LeapmotorAuthError,
+    LeapmotorMissingAppCertError,
+)
+from .models import (
+    BatteryStatus,
+    ClimateStatus,
+    ConnectivityStatus,
+    DoorStatus,
+    DrivingStatus,
+    IgnitionStatus,
+    LocationStatus,
+    RemoteActionResult,
+    RemoteActionSpec,
+    TirePressure,
+    Vehicle,
+    VehicleStatus,
+    WindowStatus,
+)
+
+__all__ = [
+    "__version__",
+    "BatteryStatus",
+    "ClimateStatus",
+    "ConnectivityStatus",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_LANGUAGE",
+    "DoorStatus",
+    "DrivingStatus",
+    "IgnitionStatus",
+    "LeapmotorAccountCertError",
+    "LeapmotorApiClient",
+    "LeapmotorApiError",
+    "LeapmotorAuthError",
+    "LeapmotorMissingAppCertError",
+    "LocationStatus",
+    "REMOTE_ACTION_SPECS",
+    "REMOTE_CTL_AC_SWITCH",
+    "REMOTE_CTL_BATTERY_PREHEAT",
+    "REMOTE_CTL_FIND_CAR",
+    "REMOTE_CTL_LOCK",
+    "REMOTE_CTL_QUICK_COOL",
+    "REMOTE_CTL_QUICK_HEAT",
+    "REMOTE_CTL_SUNSHADE",
+    "REMOTE_CTL_SUNSHADE_CLOSE",
+    "REMOTE_CTL_SUNSHADE_OPEN",
+    "REMOTE_CTL_TRUNK",
+    "REMOTE_CTL_TRUNK_CLOSE",
+    "REMOTE_CTL_TRUNK_OPEN",
+    "REMOTE_CTL_UNLOCK",
+    "REMOTE_CTL_WINDSHIELD_DEFROST",
+    "REMOTE_CTL_WINDOWS",
+    "REMOTE_CTL_WINDOWS_CLOSE",
+    "REMOTE_CTL_WINDOWS_OPEN",
+    "RemoteActionResult",
+    "RemoteActionSpec",
+    "TirePressure",
+    "Vehicle",
+    "VehicleStatus",
+    "WindowStatus",
+    "normalize_vehicle",
+]