Metadata-Version: 2.4
Name: ha-opensky-core
Version: 0.1.1
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.
