skoda-public-api 1.1.1__tar.gz

skoda_public_api-1.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mobility Lab @ VSB - Technical University of Ostrava
+
+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.

skoda_public_api-1.1.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: skoda-public-api
+Version: 1.1.1
+Summary: Asynchronous Python library for the Škoda public API
+Author: Mobility Lab, VŠB-TUO
+Author-email: TomVSB <tomas.mrovec@vsb.cz>, net0045 <stepan.netolicky@vsb.cz>, mag0051 <david.magyarics@vsb.cz>
+Maintainer-email: mag0051 <david.magyarics@vsb.cz>, TomVSB <tomas.mrovec@vsb.cz>
+Project-URL: Homepage, https://github.com/mobility-lab-vsb/skoda-public-api
+Project-URL: Bug Tracker, https://github.com/mobility-lab-vsb/skoda-public-api/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: pydantic>=2.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Requires-Dist: aresponses>=3.0.0; extra == "test"
+Provides-Extra: cli
+Requires-Dist: asyncclick~=8.1; extra == "cli"
+Requires-Dist: coloredlogs~=15.0; extra == "cli"
+Requires-Dist: pygments~=2.18; extra == "cli"
+Requires-Dist: pyyaml~=6.0; extra == "cli"
+Dynamic: license-file
+
+# skoda-public-api
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+Asynchronous Python library for the Škoda public API, developed by [Mobility Lab @ VSB](https://github.com/mobility-lab-vsb) — Technical University of Ostrava. It provides typed access to connected-vehicle data (status, odometer, charging, climate, fuel, parking position) and remote vehicle control (climate, charging, ventilation) for Škoda vehicles.
+
+It is built on [`aiohttp`](https://docs.aiohttp.org/) and [`pydantic`](https://docs.pydantic.dev/), and ships both as a library and as a standalone CLI (`skodactl`).
+
+This version targets **API v1** of the [Škoda public API](https://public.api.connect.skoda-auto.cz/docs).
+
+## Installation
+
+```sh
+pip install skoda-public-api
+```
+
+## As a library
+
+```python
+import asyncio
+
+from aiohttp import ClientSession
+
+from skoda_public_api.api_layer.open_api_client import OpenAPIClient
+
+
+async def main() -> None:
+    async with ClientSession() as session:
+        client = OpenAPIClient(api_key="XXX", session=session)
+
+        vehicle = await client.get_vehicle("TMBJX7NY4PM054321")
+        print(vehicle.vehicle.name)
+
+        charging = await client.get_charging("TMBJX7NY4PM054321")
+        print(charging.status.battery.state_of_charge_in_percent)
+
+
+asyncio.run(main())
+```
+
+Every response is a typed `pydantic` model — see [`src/skoda_public_api/models`](src/skoda_public_api/models) for the full data model, and [`src/skoda_public_api/api_layer/open_api_client.py`](src/skoda_public_api/api_layer/open_api_client.py) for the full list of available reads (vehicle status, odometer, charging, air conditioning, auxiliary heating, active ventilation, fuel status, parking position, charging profiles) and remote actions (start/stop charging, climate, auxiliary heating, active ventilation, window heating, charge limit, target temperature).
+
+## As CLI
+
+The library ships with a command line interface called `skodactl`, which is useful for manually
+testing the API endpoints. Install it together with the CLI dependencies:
+
+```sh
+pip install "skoda-public-api[cli]"
+```
+
+You authenticate with your API key, either via the `--api-key` option or the `SKODA_API_KEY`
+environment variable, and address a vehicle by its VIN:
+
+```sh
+skodactl --api-key XXX get-vehicle TMBJX7NY4PM054321
+```
+
+By default, the CLI talks to the production endpoint. Point it at the public test endpoint with
+`--endpoint test`, switch to YAML output with `--format yaml`, or log HTTP requests and responses
+with `--trace`:
+
+```sh
+skodactl --api-key XXX --endpoint test get-vehicle-status TMBJX7NY4PM054321
+SKODA_API_KEY=XXX skodactl --format yaml --trace get-charging TMBJX7NY4PM054321
+```
+
+Remote operations can be started as well:
+
+```sh
+skodactl --api-key XXX start-air-conditioning TMBJX7NY4PM054321 --temperature 21
+```
+
+Run `skodactl --help` for the full list of commands and options.
+
+## Development
+
+Clone the repository and install it in editable mode together with the test dependencies:
+
+```sh
+pip install -e ".[test,cli]"
+pytest
+```
+
+## License
+
+Distributed under the MIT License. See [`LICENSE`](LICENSE) for details.

skoda_public_api-1.1.1/README.md

@@ -0,0 +1,88 @@
+# skoda-public-api
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+
+Asynchronous Python library for the Škoda public API, developed by [Mobility Lab @ VSB](https://github.com/mobility-lab-vsb) — Technical University of Ostrava. It provides typed access to connected-vehicle data (status, odometer, charging, climate, fuel, parking position) and remote vehicle control (climate, charging, ventilation) for Škoda vehicles.
+
+It is built on [`aiohttp`](https://docs.aiohttp.org/) and [`pydantic`](https://docs.pydantic.dev/), and ships both as a library and as a standalone CLI (`skodactl`).
+
+This version targets **API v1** of the [Škoda public API](https://public.api.connect.skoda-auto.cz/docs).
+
+## Installation
+
+```sh
+pip install skoda-public-api
+```
+
+## As a library
+
+```python
+import asyncio
+
+from aiohttp import ClientSession
+
+from skoda_public_api.api_layer.open_api_client import OpenAPIClient
+
+
+async def main() -> None:
+    async with ClientSession() as session:
+        client = OpenAPIClient(api_key="XXX", session=session)
+
+        vehicle = await client.get_vehicle("TMBJX7NY4PM054321")
+        print(vehicle.vehicle.name)
+
+        charging = await client.get_charging("TMBJX7NY4PM054321")
+        print(charging.status.battery.state_of_charge_in_percent)
+
+
+asyncio.run(main())
+```
+
+Every response is a typed `pydantic` model — see [`src/skoda_public_api/models`](src/skoda_public_api/models) for the full data model, and [`src/skoda_public_api/api_layer/open_api_client.py`](src/skoda_public_api/api_layer/open_api_client.py) for the full list of available reads (vehicle status, odometer, charging, air conditioning, auxiliary heating, active ventilation, fuel status, parking position, charging profiles) and remote actions (start/stop charging, climate, auxiliary heating, active ventilation, window heating, charge limit, target temperature).
+
+## As CLI
+
+The library ships with a command line interface called `skodactl`, which is useful for manually
+testing the API endpoints. Install it together with the CLI dependencies:
+
+```sh
+pip install "skoda-public-api[cli]"
+```
+
+You authenticate with your API key, either via the `--api-key` option or the `SKODA_API_KEY`
+environment variable, and address a vehicle by its VIN:
+
+```sh
+skodactl --api-key XXX get-vehicle TMBJX7NY4PM054321
+```
+
+By default, the CLI talks to the production endpoint. Point it at the public test endpoint with
+`--endpoint test`, switch to YAML output with `--format yaml`, or log HTTP requests and responses
+with `--trace`:
+
+```sh
+skodactl --api-key XXX --endpoint test get-vehicle-status TMBJX7NY4PM054321
+SKODA_API_KEY=XXX skodactl --format yaml --trace get-charging TMBJX7NY4PM054321
+```
+
+Remote operations can be started as well:
+
+```sh
+skodactl --api-key XXX start-air-conditioning TMBJX7NY4PM054321 --temperature 21
+```
+
+Run `skodactl --help` for the full list of commands and options.
+
+## Development
+
+Clone the repository and install it in editable mode together with the test dependencies:
+
+```sh
+pip install -e ".[test,cli]"
+pytest
+```
+
+## License
+
+Distributed under the MIT License. See [`LICENSE`](LICENSE) for details.

skoda_public_api-1.1.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skoda-public-api"
+version = "1.1.1"
+authors = [
+  { name = "Mobility Lab, VŠB-TUO" },
+  { name = "TomVSB", email = "tomas.mrovec@vsb.cz" },
+  { name="net0045", email="stepan.netolicky@vsb.cz" },
+  { name="mag0051", email="david.magyarics@vsb.cz" },
+]
+maintainers = [
+  { name="mag0051", email="david.magyarics@vsb.cz" },
+  { name = "TomVSB", email = "tomas.mrovec@vsb.cz" },
+]
+description = "Asynchronous Python library for the Škoda public API"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Framework :: AsyncIO",
+]
+dependencies = [
+    "aiohttp>=3.9.0",
+    "pydantic>=2.5.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/mobility-lab-vsb/skoda-public-api"
+"Bug Tracker" = "https://github.com/mobility-lab-vsb/skoda-public-api/issues"
+
+[project.scripts]
+skodactl = "skoda_public_api.cli:cli"
+
+[tool.pytest.ini_options]
+pythonpath = ["src/skoda_public_api"]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=9.0.0",
+    "pytest-asyncio>=0.23.0",
+    "aresponses>=3.0.0",
+]
+cli = [
+    "asyncclick ~=8.1",
+    "coloredlogs ~=15.0",
+    "pygments ~=2.18",
+    "pyyaml ~=6.0",
+]

skoda_public_api-1.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skoda_public_api-1.1.1/src/skoda_public_api/api_layer/const.py

@@ -0,0 +1,25 @@
+from enum import StrEnum
+
+SANDBOX_BASE_URL = "https://developer.sandbox.connect.skoda-auto.cz"
+PRODUCTION_BASE_URL = "https://developer.connect.skoda-auto.cz"
+TEST_BASE_URL = "https://public.test-api.connect.skoda-auto.cz"
+BETA_URL = "https://public.api.connect.skoda-auto.cz"
+
+
+class Endpoints(StrEnum):
+    PRODUCTION = "production"
+    SANDBOX = "sandbox"
+    TEST = "test"
+    BETA = "beta"
+
+    @property
+    def url(self) -> str:
+        return ENDPOINT_URLS[self]
+
+
+ENDPOINT_URLS = {
+    Endpoints.PRODUCTION: PRODUCTION_BASE_URL,
+    Endpoints.SANDBOX: SANDBOX_BASE_URL,
+    Endpoints.TEST: TEST_BASE_URL,
+    Endpoints.BETA: BETA_URL,
+}

skoda_public_api-1.1.1/src/skoda_public_api/api_layer/exceptions.py

@@ -0,0 +1,41 @@
+from typing import Optional
+
+
+class OpenApiError(Exception):
+    """Obecná chyba při komunikaci se Škoda API."""
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class OpenApiAuthenticationError(OpenApiError):
+    """Error 401 - Invalid or Expired X-API-Key."""
+    def __init__(self, message: str = "Invalid or expired X-API-Key.") -> None:
+        super().__init__(message, status_code=401)
+
+
+class OpenApiForbiddenError(OpenApiError):
+    """Error 403 - Forbidden access to the requested resource."""
+    def __init__(self, message: str = "Access to the requested resource is forbidden.") -> None:
+        super().__init__(message, status_code=403)
+
+
+class OpenApiVehicleNotFoundError(OpenApiError):
+    """Error 404 - Vehicle with this VIN does not exist."""
+    def __init__(self, message: str = "Vehicle with this VIN does not exist.") -> None:
+        super().__init__(message, status_code=404)
+
+class OpenApiUnsupportedError(OpenApiError):
+    """Error 422 - Unsupported operation."""
+    def __init__(self, message: str = "Vehicle does not support this operation") -> None:
+        super().__init__(message, status_code=422)
+
+class OpenApiRateLimitError(OpenApiError):
+    """Error 429 - Rate limit exceeded or weak 12V battery."""
+    def __init__(self, message: str = "Rate limit exceeded or weak 12V battery.") -> None:
+        super().__init__(message, status_code=429)
+
+class OpenApiServerError(OpenApiError):
+    """Error 500 - Server error or timeout."""
+    def __init__(self, message: str, status_code: int = 500) -> None:
+        super().__init__(message, status_code=status_code)

skoda_public_api-1.1.1/src/skoda_public_api/api_layer/open_api_client.py

@@ -0,0 +1,202 @@
+import logging
+from typing import Any, Optional, List
+from aiohttp import ClientSession
+from .const import BETA_URL
+from .rest_api import PostEndpointResult, SkodaRestAPI
+from ..models.vehicle import VehicleResponse, Odometer
+from ..models.vehicle_status import VehicleStatus
+from ..models.active_ventilation import ActiveVentilation
+from ..models.air_conditioning import AirConditioning
+from ..models.parking_position import ParkingPosition
+from ..models.auxiliary_heating import AuxiliaryHeating
+from ..models.charging import Charging
+from ..models.driving_range import FuelStatus
+from ..models.charging_profiles import ChargingProfiles
+from ..models.configurations import StartAirConditioningConfiguration, StartAuxiliaryHeatingConfiguration, ConfigurationTargetTemperature
+
+class OpenAPIClient:
+    """Client for interacting with rest API and used in HomeAssistant."""
+
+    def __init__(self, api_key: str, session: ClientSession, base_url: str = BETA_URL) -> None:
+       self.rest_api = SkodaRestAPI(api_key=api_key, session=session, base_url=base_url)
+       self.last_headers: dict[str, Any] = {}
+
+    @property
+    def api_key_expires_at(self) -> Optional[str]:
+        """Return the expiration timestamp of the API key."""
+        return self.last_headers.get("x-api-key-expires-at")
+
+    @property
+    def rate_limit_remaining(self) -> Optional[int]:
+        """Return remaining requests quota."""
+        val = self.last_headers.get("ratelimit-remaining")
+        return int(val) if val is not None else None
+
+    @property
+    def rate_limit_reset(self) -> Optional[int]:
+        """Return the time when the rate limit will be reset."""
+        val = self.last_headers.get("ratelimit-reset")
+        return int(val) if val is not None else None
+
+    async def get_vehicle(self, vin: str, include: Optional[List[str]] = None) -> VehicleResponse:
+        """Get the actual vehicle data and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_vehicle(vin, include=include)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+    
+    async def get_vehicle_status(self, vin: str) -> Optional[VehicleStatus]:
+        endpoint_result = await self.rest_api.get_vehicle_status(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+    
+    async def get_air_conditioning(self, vin: str) -> AirConditioning:
+        """Get the actual vehicle status and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_air_conditioning(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+    
+    async def get_parking_positions(self, vin: str) -> ParkingPosition:
+        """Get the actual vehicle status and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_parking_positions(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+    
+    async def get_auxiliary_heating(self, vin: str) -> AuxiliaryHeating:
+        """Get the actual vehicle status and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_auxiliary_heating(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+    
+    async def get_odometer(self, vin: str) -> Odometer:
+        """Get the actual vehicle status and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_odometer(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+    
+    async def get_charging(self, vin: str) -> Charging:
+        """Get the actual vehicle status and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_charging(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+    
+    async def get_active_ventilation(self, vin: str) -> ActiveVentilation:
+        """Get the actual active ventilation and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_active_ventilation(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+
+    async def get_fuel_status(self, vin: str) -> FuelStatus:
+        """Get the actual fuel status and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_fuel_status(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+
+    async def get_charging_profiles(self, vin: str) -> ChargingProfiles:
+        """Get the actual charging profiles and return the parsed Pydantic model."""
+        endpoint_result = await self.rest_api.get_charging_profiles(vin)
+        self.last_headers = endpoint_result.headers
+        return endpoint_result.result
+    
+    
+    async def start_air_conditioning(self, vin: str, temperature: float, unit: str = "CELSIUS", without_external_power: bool = True) -> PostEndpointResult:
+        """Starts the air conditioning for the vehicle with the given VIN."""
+        config = StartAirConditioningConfiguration(
+            target_temperature=ConfigurationTargetTemperature(
+                value=temperature,
+                unit=unit,
+            ),
+            air_conditioning_without_external_power=without_external_power,
+        )
+        return await self.rest_api.start_air_conditioning(vin, config)
+    
+    async def stop_air_conditioning(self, vin: str) -> PostEndpointResult:
+        """Stops the air_conditioning of the vehicle and return None if it was succesfull else catch an exception in HomeAssistant"""
+        return await self.rest_api.stop_air_conditioning(vin)
+
+    async def start_auxiliary_heating(self, vin: str, spin: str, duration_in_seconds: int = 120, start_mode: str = "HEATING", target_temperature: Optional[float] = None, unit: str = "CELSIUS") -> PostEndpointResult:
+        """Starts the auxiliary heating for the vehicle with the given VIN."""
+        temp_obj = None
+        if target_temperature is not None:
+            temp_obj = ConfigurationTargetTemperature(
+                value=target_temperature,
+                unit=unit,
+            )
+
+        config = StartAuxiliaryHeatingConfiguration(
+            spin=spin,
+            duration_in_seconds=duration_in_seconds,
+            start_mode=start_mode,
+            target_temperature=temp_obj,
+        )
+        return await self.rest_api.start_auxiliary_heating(vin, config)
+
+    async def stop_auxiliary_heating(self, vin: str) -> PostEndpointResult:
+        """Stops the auxiliary_heating of the vehicle and return None if it was succesfull else catch an exception in HomeAssistant"""
+        return await self.rest_api.stop_auxiliary_heating(vin)
+    
+    async def start_active_ventilation(self, vin: str) -> PostEndpointResult:
+        """Starts the active_ventilation for the vehicle with the given VIN."""
+        return await self.rest_api.start_active_ventilation(vin)
+
+    async def stop_active_ventilation(self, vin: str) -> PostEndpointResult:
+        """Stops the active_ventilation of the vehicle and return None if it was succesfull else catch an exception in HomeAssistant"""
+        return await self.rest_api.stop_active_ventilation(vin)
+
+    async def start_charging(self, vin: str) -> PostEndpointResult:
+        """Starts the charging process for the vehicle with the given VIN."""
+        return await self.rest_api.start_charging(vin)
+
+    async def stop_charging(self, vin: str) -> PostEndpointResult:
+        """Stops the charging process for the vehicle with the given VIN."""
+        return await self.rest_api.stop_charging(vin)
+
+    async def connect(self):
+        """TODO: Implementation of connect mechanism."""
+        pass
+    
+    async def disconnect(self) -> None:
+        """TODO: Implementation of disconnect mechanism."""
+        pass
+    
+    async def verify_spin(self, spin: str) -> bool:
+        """TODO: Implementation of SPIN verification."""
+        pass
+
+    """
+    ======= NOT IMPLEMENTED FUNCTIONS - CAN BE USED SOMETIME IN THE FUTURE =======
+    """
+    async def refresh_auxiliary_heating(self, vin: str) -> None:
+        """Refreshes the auxiliary heating status of the vehicle with the given VIN."""
+        pass
+
+    async def set_reduced_current_limit(self, vin: str) -> None:
+        """Sets the charging current limit (e.g., to REDUCED or MAXIMUM) for the vehicle with the given VIN."""
+        pass
+
+    async def set_seats_heating(self, vin: str) -> None:
+        """Configures the seats heating settings for the vehicle with the given VIN."""
+        pass
+
+    async def start_window_heating(self, vin: str) -> None:
+        """Starts the electric window heating for the vehicle with the given VIN."""
+        pass
+
+    async def stop_window_heating(self, vin: str) -> None:
+        """Stops the window heating of the vehicle and return None if it was succesfull else catch an exception in HomeAssistant."""
+        pass
+
+    async def set_windows_heating(self, vin: str) -> None:
+        """Configures the front and rear windows heating settings for the vehicle with the given VIN."""
+        pass
+
+    async def set_auto_unlock_plug(self, vin: str) -> None:
+        """Sets the automatic unlocking behavior of the charging plug (e.g., PERMANENT or OFF) for the vehicle with the given VIN."""
+        pass
+    async def set_charge_limit(self, vin: str, limit: int) -> None:
+        """Sets the maximum charging limit in percent for the vehicle with the given VIN."""
+        pass
+
+    async def set_target_temperature(self, vin: str, temperature: float) -> None:
+        """Sets the target temperature for AC or auxiliary heating for the vehicle with the given VIN."""
+        pass
+    # TODO: Add more methods for other endpoints as needed