ha-opensky-core 0.1.0__tar.gz

ha_opensky_core-0.1.0/LICENSE

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

ha_opensky_core-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: ha-opensky-core
+Version: 0.1.0
+Summary: Standalone OpenSky OAuth client and aircraft analysis library
+Author: stego020472
+License-Expression: MIT
+Keywords: opensky,opensky-network,aviation,aircraft,ads-b,oauth,home-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.0
+Dynamic: license-file
+
+# ha-opensky-core
+
+Standalone Python library for accessing the OpenSky Network API using OAuth authentication and for performing aircraft, airport and approach analysis.
+
+The library is designed to be usable independently of Home Assistant. Home Assistant-specific functionality is implemented separately in the `ha-opensky-oauth` integration.
+
+## Features
+
+* OpenSky Network OAuth authentication
+* Search aircraft within a geographic area
+* Aircraft data models using metric units
+* Aircraft metadata lookup
+* Aircraft photo lookup and fallback providers
+* Airport and runway database
+* Airport and runway analysis
+* Aircraft approach detection and tracking
+* Approach entry and exit transitions
+* Reusable `ApproachService` boundary for frontend applications
+
+## Installation
+
+```bash
+pip install ha-opensky-core
+```
+
+## Basic usage
+
+```python
+from opensky.client import OpenSkyClient
+from opensky.models import SearchArea
+
+area = SearchArea(
+    latitude=50.901,
+    longitude=4.484,
+    radius_km=20,
+)
+
+client = OpenSkyClient(...)
+
+aircraft = client.get_aircraft(area)
+
+for item in aircraft:
+    print(item.icao24, item.callsign)
+```
+
+The exact authentication and client configuration depends on the OpenSky OAuth credentials available to the application.
+
+## Airport database
+
+The package contains the airport and runway databases required by the airport analysis functionality.
+
+```python
+from opensky.airport import AirportDatabase
+
+db = AirportDatabase()
+
+print(db.count())
+
+airport = db.require("EBBR")
+print(airport.name)
+```
+
+## Architecture
+
+`ha-opensky-core` contains the reusable OpenSky functionality and has no dependency on Home Assistant.
+
+The architecture is intentionally split into two layers:
+
+```text
+┌──────────────────────────────────────┐
+│       Home Assistant integration     │
+│        ha-opensky-oauth              │
+└──────────────────┬───────────────────┘
+                   │
+                   ▼
+┌──────────────────────────────────────┐
+│          ha-opensky-core             │
+│                                      │
+│  OAuth / API / Aircraft / Metadata   │
+│  Airports / Runways / Approaches     │
+└──────────────────┬───────────────────┘
+                   │
+                   ▼
+          OpenSky Network API
+```
+
+This allows the core library to be tested and used independently of Home Assistant.
+
+## Development
+
+Clone the repository and create a virtual environment:
+
+```bash
+python -m venv .venv
+```
+
+Activate the environment and install the package in editable mode:
+
+```bash
+python -m pip install -e .
+```
+
+Run the available test and diagnostic scripts with:
+
+```bash
+python -m scripts.test_oauth
+python -m scripts.test_metadata
+python -m scripts.test_airports
+```
+
+## Requirements
+
+* Python 3.13 or newer
+* OpenSky Network OAuth credentials for authenticated API access
+
+## Status
+
+This project is currently in alpha development.
+
+The API may change between releases.
+
+## License
+
+MIT License.

ha_opensky_core-0.1.0/README.md

@@ -0,0 +1,124 @@
+# ha-opensky-core
+
+Standalone Python library for accessing the OpenSky Network API using OAuth authentication and for performing aircraft, airport and approach analysis.
+
+The library is designed to be usable independently of Home Assistant. Home Assistant-specific functionality is implemented separately in the `ha-opensky-oauth` integration.
+
+## Features
+
+* OpenSky Network OAuth authentication
+* Search aircraft within a geographic area
+* Aircraft data models using metric units
+* Aircraft metadata lookup
+* Aircraft photo lookup and fallback providers
+* Airport and runway database
+* Airport and runway analysis
+* Aircraft approach detection and tracking
+* Approach entry and exit transitions
+* Reusable `ApproachService` boundary for frontend applications
+
+## Installation
+
+```bash
+pip install ha-opensky-core
+```
+
+## Basic usage
+
+```python
+from opensky.client import OpenSkyClient
+from opensky.models import SearchArea
+
+area = SearchArea(
+    latitude=50.901,
+    longitude=4.484,
+    radius_km=20,
+)
+
+client = OpenSkyClient(...)
+
+aircraft = client.get_aircraft(area)
+
+for item in aircraft:
+    print(item.icao24, item.callsign)
+```
+
+The exact authentication and client configuration depends on the OpenSky OAuth credentials available to the application.
+
+## Airport database
+
+The package contains the airport and runway databases required by the airport analysis functionality.
+
+```python
+from opensky.airport import AirportDatabase
+
+db = AirportDatabase()
+
+print(db.count())
+
+airport = db.require("EBBR")
+print(airport.name)
+```
+
+## Architecture
+
+`ha-opensky-core` contains the reusable OpenSky functionality and has no dependency on Home Assistant.
+
+The architecture is intentionally split into two layers:
+
+```text
+┌──────────────────────────────────────┐
+│       Home Assistant integration     │
+│        ha-opensky-oauth              │
+└──────────────────┬───────────────────┘
+                   │
+                   ▼
+┌──────────────────────────────────────┐
+│          ha-opensky-core             │
+│                                      │
+│  OAuth / API / Aircraft / Metadata   │
+│  Airports / Runways / Approaches     │
+└──────────────────┬───────────────────┘
+                   │
+                   ▼
+          OpenSky Network API
+```
+
+This allows the core library to be tested and used independently of Home Assistant.
+
+## Development
+
+Clone the repository and create a virtual environment:
+
+```bash
+python -m venv .venv
+```
+
+Activate the environment and install the package in editable mode:
+
+```bash
+python -m pip install -e .
+```
+
+Run the available test and diagnostic scripts with:
+
+```bash
+python -m scripts.test_oauth
+python -m scripts.test_metadata
+python -m scripts.test_airports
+```
+
+## Requirements
+
+* Python 3.13 or newer
+* OpenSky Network OAuth credentials for authenticated API access
+
+## Status
+
+This project is currently in alpha development.
+
+The API may change between releases.
+
+## License
+
+MIT License.

ha_opensky_core-0.1.0/ha_opensky_core.egg-info/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: ha-opensky-core
+Version: 0.1.0
+Summary: Standalone OpenSky OAuth client and aircraft analysis library
+Author: stego020472
+License-Expression: MIT
+Keywords: opensky,opensky-network,aviation,aircraft,ads-b,oauth,home-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.0
+Dynamic: license-file
+
+# ha-opensky-core
+
+Standalone Python library for accessing the OpenSky Network API using OAuth authentication and for performing aircraft, airport and approach analysis.
+
+The library is designed to be usable independently of Home Assistant. Home Assistant-specific functionality is implemented separately in the `ha-opensky-oauth` integration.
+
+## Features
+
+* OpenSky Network OAuth authentication
+* Search aircraft within a geographic area
+* Aircraft data models using metric units
+* Aircraft metadata lookup
+* Aircraft photo lookup and fallback providers
+* Airport and runway database
+* Airport and runway analysis
+* Aircraft approach detection and tracking
+* Approach entry and exit transitions
+* Reusable `ApproachService` boundary for frontend applications
+
+## Installation
+
+```bash
+pip install ha-opensky-core
+```
+
+## Basic usage
+
+```python
+from opensky.client import OpenSkyClient
+from opensky.models import SearchArea
+
+area = SearchArea(
+    latitude=50.901,
+    longitude=4.484,
+    radius_km=20,
+)
+
+client = OpenSkyClient(...)
+
+aircraft = client.get_aircraft(area)
+
+for item in aircraft:
+    print(item.icao24, item.callsign)
+```
+
+The exact authentication and client configuration depends on the OpenSky OAuth credentials available to the application.
+
+## Airport database
+
+The package contains the airport and runway databases required by the airport analysis functionality.
+
+```python
+from opensky.airport import AirportDatabase
+
+db = AirportDatabase()
+
+print(db.count())
+
+airport = db.require("EBBR")
+print(airport.name)
+```
+
+## Architecture
+
+`ha-opensky-core` contains the reusable OpenSky functionality and has no dependency on Home Assistant.
+
+The architecture is intentionally split into two layers:
+
+```text
+┌──────────────────────────────────────┐
+│       Home Assistant integration     │
+│        ha-opensky-oauth              │
+└──────────────────┬───────────────────┘
+                   │
+                   ▼
+┌──────────────────────────────────────┐
+│          ha-opensky-core             │
+│                                      │
+│  OAuth / API / Aircraft / Metadata   │
+│  Airports / Runways / Approaches     │
+└──────────────────┬───────────────────┘
+                   │
+                   ▼
+          OpenSky Network API
+```
+
+This allows the core library to be tested and used independently of Home Assistant.
+
+## Development
+
+Clone the repository and create a virtual environment:
+
+```bash
+python -m venv .venv
+```
+
+Activate the environment and install the package in editable mode:
+
+```bash
+python -m pip install -e .
+```
+
+Run the available test and diagnostic scripts with:
+
+```bash
+python -m scripts.test_oauth
+python -m scripts.test_metadata
+python -m scripts.test_airports
+```
+
+## Requirements
+
+* Python 3.13 or newer
+* OpenSky Network OAuth credentials for authenticated API access
+
+## Status
+
+This project is currently in alpha development.
+
+The API may change between releases.
+
+## License
+
+MIT License.

ha_opensky_core-0.1.0/ha_opensky_core.egg-info/SOURCES.txt

@@ -0,0 +1,45 @@
+LICENSE
+README.md
+pyproject.toml
+ha_opensky_core.egg-info/PKG-INFO
+ha_opensky_core.egg-info/SOURCES.txt
+ha_opensky_core.egg-info/dependency_links.txt
+ha_opensky_core.egg-info/requires.txt
+ha_opensky_core.egg-info/top_level.txt
+opensky/__init__.py
+opensky/adsbfi_metadata_provider.py
+opensky/aircraft_metadata.py
+opensky/airport.py
+opensky/airport_analyzer.py
+opensky/analyzer.py
+opensky/approach.py
+opensky/approach_history.py
+opensky/approach_manager.py
+opensky/approach_report.py
+opensky/approach_repository.py
+opensky/approach_repository_memory.py
+opensky/approach_service.py
+opensky/approach_statistics.py
+opensky/approach_statistics_summary.py
+opensky/approach_summary.py
+opensky/approach_tracker.py
+opensky/auth.py
+opensky/client.py
+opensky/freshness.py
+opensky/geometry.py
+opensky/hexdb_metadata_provider.py
+opensky/metadata_normalizer.py
+opensky/models.py
+opensky/parser.py
+opensky/photo_provider.py
+opensky/planespotters_metadata_provider.py
+opensky/runway.py
+opensky/runways.py
+opensky/sqlite_approach_repository.py
+opensky/tracker.py
+opensky/data/airports.csv
+opensky/data/runways.csv
+opensky/tests/__init__.py
+opensky/tests/test_aircraft_freshness.py
+opensky/tests/test_analyzer_freshness.py
+opensky/tests/test_freshness.py

ha_opensky_core-0.1.0/ha_opensky_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ha_opensky_core-0.1.0/ha_opensky_core.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.32.0

ha_opensky_core-0.1.0/ha_opensky_core.egg-info/top_level.txt

@@ -0,0 +1 @@
+opensky

ha_opensky_core-0.1.0/opensky/adsbfi_metadata_provider.py

@@ -0,0 +1,176 @@
+"""
+ADSB.fi aircraft metadata provider.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import requests
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+ADSBFI_AIRCRAFT_URL = (
+    "https://opendata.adsb.fi/api/v2/hex/{icao24}"
+)
+
+ADSBFI_USER_AGENT = (
+    "ha-opensky-oauth/1.0 "
+    "(https://github.com/stego020472/ha-opensky-oauth)"
+)
+
+
+@dataclass(slots=True)
+class AdsbFiMetadata:
+    """Aircraft metadata returned by ADSB.fi."""
+
+    registration: str | None = None
+    aircraft_type: str | None = None
+    icao_type: str | None = None
+    manufacturer: str | None = None
+
+
+class AdsbFiMetadataProvider:
+    """
+    Retrieve aircraft metadata from ADSB.fi.
+
+    ADSB.fi is used as a metadata fallback when the
+    primary metadata providers do not have sufficient
+    information.
+    """
+
+    def __init__(
+        self,
+        timeout: float = 10.0,
+    ) -> None:
+        """Initialize the provider."""
+
+        self.timeout = timeout
+
+    def get(
+        self,
+        icao24: str | None = None,
+    ) -> AdsbFiMetadata | None:
+        """
+        Retrieve aircraft metadata using ICAO24.
+        """
+
+        if not icao24:
+            return None
+
+        icao24 = icao24.strip().lower()
+
+        if not icao24:
+            return None
+
+        url = ADSBFI_AIRCRAFT_URL.format(
+            icao24=icao24,
+        )
+
+        return self._request(url)
+
+    def _request(
+        self,
+        url: str,
+    ) -> AdsbFiMetadata | None:
+        """Request and parse an ADSB.fi response."""
+
+        try:
+            response = requests.get(
+                url,
+                headers={
+                    "User-Agent": ADSBFI_USER_AGENT,
+                },
+                timeout=self.timeout,
+            )
+
+        except requests.exceptions.Timeout:
+            _LOGGER.debug(
+                "ADSB.fi request timed out: %s",
+                url,
+            )
+            return None
+
+        except requests.exceptions.ConnectionError:
+            _LOGGER.debug(
+                "Unable to connect to ADSB.fi: %s",
+                url,
+            )
+            return None
+
+        except requests.exceptions.RequestException as exc:
+            _LOGGER.debug(
+                "ADSB.fi request failed: %s",
+                exc,
+            )
+            return None
+
+        if response.status_code != 200:
+            _LOGGER.debug(
+                "ADSB.fi returned HTTP %s",
+                response.status_code,
+            )
+            return None
+
+        try:
+            data = response.json()
+
+        except ValueError:
+            _LOGGER.debug(
+                "ADSB.fi returned invalid JSON"
+            )
+            return None
+
+        if not isinstance(data, dict):
+            return None
+
+        aircraft = data.get("ac")
+
+        if not isinstance(aircraft, list):
+            return None
+
+        if not aircraft:
+            return None
+
+        first_aircraft = aircraft[0]
+
+        if not isinstance(
+            first_aircraft,
+            dict,
+        ):
+            return None
+
+        return AdsbFiMetadata(
+            registration=self._string(
+                first_aircraft.get("r")
+            ),
+            aircraft_type=self._string(
+                first_aircraft.get("desc")
+            ),
+            icao_type=self._string(
+                first_aircraft.get("t")
+            ),
+            manufacturer=None,
+        )
+
+    @staticmethod
+    def _string(
+        value: object,
+    ) -> str | None:
+        """Return a cleaned string or None."""
+
+        if not isinstance(
+            value,
+            str,
+        ):
+            return None
+
+        value = value.strip()
+
+        if not value:
+            return None
+
+        return value