pyopensky 2.15__tar.gz → 2.17__tar.gz

pyopensky-2.17/.gitattributes

@@ -0,0 +1,4 @@
+# Ensure consistent line endings across platforms
+# uv.lock must hash identically on Linux, macOS and Windows so that
+# the GitHub Actions cache key is the same on all runners.
+uv.lock text eol=lf

{pyopensky-2.15 → pyopensky-2.17}/.github/workflows/build-docs.yml

@@ -15,7 +15,7 @@ jobs:
       UV_CACHE_DIR: /tmp/.uv-cache
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
@@ -23,13 +23,13 @@ jobs:
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7.0.0
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
 
       - name: Cache folder for uv
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: /tmp/.uv-cache
           key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}

{pyopensky-2.15 → pyopensky-2.17}/.github/workflows/pypi_publish.yml

@@ -9,16 +9,16 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up uv
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7.0.0
 
       - name: Cache folder for uv
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: /tmp/.uv-cache
           key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}

pyopensky-2.17/.github/workflows/run_tests.yml

@@ -0,0 +1,123 @@
+name: tests
+
+on:
+  push:
+  pull_request_target:
+  schedule: # keep the cache warm
+    - cron: "42 3 * * 0" # every Sunday morning
+  workflow_dispatch:
+
+jobs:
+  lint:
+    name: lint and format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+
+      - run: uv sync --dev --extra rs1090 --extra cartes
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv cache prune --ci
+
+  typing:
+    name: type checking
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+
+      - run: uv sync --dev --extra rs1090 --extra cartes
+      - run: uv run ty check src tests
+      - run: uv cache prune --ci
+
+  fill_cache:
+    name: fill trino cache
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+
+      - uses: actions/cache@v6
+        id: cache
+        with:
+          path: cache_opensky
+          enableCrossOsArchive: true
+          key: opensky-${{ hashFiles('uv.lock') }}
+
+      - run: uv sync --dev --extra rs1090 --extra cartes
+
+      - name: Fill cache with Trino queries
+        if: steps.cache.outputs.cache-hit != 'true'
+        env:
+          OPENSKY_USERNAME: ${{ secrets.OPENSKY_USERNAME }}
+          OPENSKY_PASSWORD: ${{ secrets.OPENSKY_PASSWORD }}
+          OPENSKY_CACHE: ${{ github.workspace }}/cache_opensky
+        run: uv run pytest tests/test_trino.py tests/test_rebuild.py
+
+      - run: uv cache prune --ci
+
+  tests:
+    name: python-${{ matrix.python-version }} on ${{ matrix.os }}
+    needs: fill_cache
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+          # `trino` (v0.336.0) depends on `orjson` (v3.11.5)
+          # which does not support Python 3.14t
+          # https://github.com/ijl/orjson/issues/591#issuecomment-3160351169
+          # - "3.14t"
+        exclude:
+          # greenlet v3.2.4 is not available for Python 3.14t on Windows
+          # and fails to compile there. Not much we can do about that right now.
+          - os: windows-latest
+            python-version: "3.14t"
+        include:
+          - os: ubuntu-latest
+            python-version: "3.13"
+            rest: true
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+
+      - uses: actions/cache@v6
+        with:
+          path: cache_opensky
+          enableCrossOsArchive: true
+          key: opensky-${{ hashFiles('uv.lock') }}
+
+      - run: uv sync --dev --python ${{ matrix.python-version }} --extra rs1090 --extra cartes
+
+      - name: Run tests
+        env:
+          OPENSKY_CACHE: ${{ github.workspace }}/cache_opensky
+        run: uv run pytest ${{ ! matrix.rest && '--ignore=tests/test_rest.py' || '' }}
+
+      - run: uv cache prune --ci

pyopensky-2.17/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: pyopensky
+Version: 2.17
+Summary: A Python interface for OpenSky database
+Project-URL: Repository, https://github.com/open-aviation/pyopensky/
+Author-email: Xavier Olive <git@xoolive.org>, Junzi Sun <j.sun-1@tudelft.nl>
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: appdirs>=1.4.4
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: minio>=7.2.8
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: pyarrow>=17.0.0
+Requires-Dist: pyjwt>=2.9.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: stamina>=25.1.0
+Requires-Dist: tqdm>=4.66.5
+Requires-Dist: trino[sqlalchemy]>=0.329.0
+Requires-Dist: typing-extensions>=4.12.2
+Requires-Dist: tzdata>=2024.2
+Provides-Extra: cartes
+Requires-Dist: cartes>=0.8.5; (python_version >= '3.10') and extra == 'cartes'
+Provides-Extra: pymodes
+Requires-Dist: pymodes>=2.18; extra == 'pymodes'
+Provides-Extra: rs1090
+Requires-Dist: rs1090>=0.3.8; extra == 'rs1090'
+Description-Content-Type: text/markdown
+
+# pyopensky
+
+The `pyopensky` Python library provides functions to download data from the OpenSky Network live API and historical databases. It aims at making ADS-B and Mode S data from OpenSky easily accessible in the Python programming environment.
+
+**Key features:**
+
+- Access to **live** aircraft state vectors and flight information via REST API
+- Query **historical** ADS-B and Mode S data from the Trino database
+- Decode and rebuild flight trajectories from raw messages
+- Support for spatial and temporal filtering
+- Built-in caching for efficient data retrieval
+- Integration with pandas DataFrames for easy data analysis
+
+Full documentation on <https://mode-s.org/pyopensky/>
+
+## Installation
+
+```sh
+pip install pyopensky
+```
+
+or add it in your project with
+
+```sh
+uv add pyopensky
+```
+
+The library is also available on conda-forge, although this approach is no longer recommended:
+
+```sh
+conda install -c conda-forge pyopensky
+```
+
+## Credentials
+
+Access to the OpenSky Network historical database requires authentication. See details in the [documentation](https://open-aviation.github.io/pyopensky/credentials.html) on how to:
+
+- Apply an OpenSky Network account
+- Configure your credentials for API access
+- Set up authentication for the Trino database
+
+## Usage
+
+### 1. REST API
+
+> [!IMPORTANT]
+> Do NOT use REST API for historical data, use trino instead!
+
+Access **live** and recent flight data.
+
+#### Functions
+
+```python
+from pyopensky.rest import REST
+
+rest = REST()
+
+rest.states()
+rest.tracks(icao24)
+rest.routes(callsign)
+rest.aircraft(icao24, begin, end)
+rest.arrival(airport, begin, end)
+rest.departure(airport, begin, end)
+```
+
+#### Examples
+
+```python
+from pyopensky.rest import REST
+
+rest = REST()
+
+# Get current state vectors for all aircraft
+rest.states()
+
+# Get trajectory for a specific aircraft
+rest.tracks(icao24="3c6444")
+
+# Get route information for a callsign
+rest.routes(callsign="AFR292")
+
+# Get flights for a specific aircraft in a time range
+# NOTE: do NOT use REST for historical data, use trino instead!!
+rest.aircraft(icao24="3c6444", begin="2024-01-01", end="2024-01-02")
+
+# Get arrivals at an airport
+# NOTE: do NOT use REST for historical data, use trino instead!!
+rest.arrival(airport="EHAM", begin="2024-01-01 12:00", end="2024-01-01 13:00")
+
+# Get departures from an airport
+# NOTE: do NOT use REST for historical data, use trino instead!!
+rest.departure(airport="LFPG", begin="2024-01-01 12:00", end="2024-01-01 13:00")
+```
+
+### 2. Trino Interface
+
+Query **historical** ADS-B and Mode S data with advanced selection and processing.
+
+Functions
+
+```python
+from pyopensky.trino import Trino
+
+trino = Trino()
+# full description of the whole set of parameters in the documentation
+trino.flightlist(start, stop, *, airport, callsign, icao24)
+trino.rawdata(start, stop, *, callsign, icao24, bounds)
+trino.history(start, stop, *, callsign, icao24, bounds)
+trino.rebuild(start, stop, *, icao24, bounds)
+```
+
+> [!IMPORTANT]
+> Refer to the [documentation](https://mode-s.org/pyopensky) for advanced usage and parameter details.

pyopensky-2.17/agents.md

@@ -0,0 +1,21 @@
+# Agent development guide
+
+## Setup commands
+
+- Run `uv sync --dev --extra rs1090 --extra cartes`
+
+## Coding style
+
+- Run `uv run ruff check` and `uv run ruff format` to check and format code
+- Run `uv run ty check src/ tests/` to check types
+
+## Documentation commands
+
+- Build documentation: run `uv run make html` from the docs/ folder
+- Only capitalize the first letter of the titles and headings, unless there are proper nouns
+
+## Commit rules
+
+- **NEVER COMMIT ANYTHING WITHOUT EXPLICIT APPROVAL**: encourage the developer to check the code before committing
+- **DO NOT COMMIT DIRECTLY TO THE MAIN BRANCH**
+- Create a feature branch from main for your changes

{pyopensky-2.15 → pyopensky-2.17}/docs/source/credentials.rst

@@ -5,9 +5,9 @@ Apply for access
 ----------------
 
 Access to the Trino database will be granted provided you meet the `conditions
-defined by The OpenSky Network <https://opensky-network.org/about/faq#q5>`_. Please create an account on
-https://trino.opensky-network.org, and then apply at https://opensky-network.org/data/apply
-with your Trino username to request for activation.
+defined by The OpenSky Network <https://opensky-network.org/about/faq>`_. Please create an account on
+https://trino.opensky-network.org, and then apply at https://opensky-network.org/my-opensky/request-data
+to request activation.
 
 Configuration
 -------------

{pyopensky-2.15 → pyopensky-2.17}/docs/source/index.rst

@@ -26,5 +26,8 @@ use in your future studies. All functions return pandas :class:`~pandas.DataFram
 
    installation
    credentials
-   api_reference
+   rest
+   trino
+   trino_advanced
+   rebuild
 

pyopensky-2.17/docs/source/rebuild.rst

@@ -0,0 +1,210 @@
+Rebuilding trajectories
+=======================
+
+The :class:`~pyopensky.rebuild.Rebuild` class provides functionality for reconstructing aircraft trajectories from raw ADS-B and Mode S messages.
+
+When to use the rebuild functionality
+--------------------------------------
+
+There are two main use cases for the ``Rebuild`` class:
+
+1. **Merge different data sources to rebuild a state vector table**: Combine position, velocity, identification, and rollcall data that are stored in separate database tables into a single trajectory dataframe.
+
+2. **Redecode raw messages**: Apply custom decoding logic to raw messages for more precise position calculations, BDS register extraction, or custom validation.
+
+Rebuilding without custom decoding
+-----------------------------------
+
+If you only need to merge data from different sources and trust the database-decoded values, use the ``rebuild()`` method without specifying a decoder:
+
+.. code-block:: python
+
+    from pyopensky.trino import Trino
+    from pyopensky.rebuild import Rebuild
+
+    trino = Trino()
+    rebuild = Rebuild(trino)
+
+    # Fetch and merge position, velocity, identification data
+    df = rebuild.rebuild(
+        start="2023-01-03 16:00",
+        stop="2023-01-03 20:00",
+        icao24="400A0E"
+    )
+
+This returns a dataframe with columns from all three sources merged on ``icao24`` and ``mintime`` with a 5-second tolerance.
+
+Rebuilding with custom decoding
+--------------------------------
+
+When you need more control over position decoding or want to extract additional data from raw messages, specify a decoder:
+
+.. code-block:: python
+
+    from pyopensky.trino import Trino
+    from pyopensky.rebuild import Rebuild
+
+    trino = Trino()
+    rebuild = Rebuild(trino)
+
+    # Redecode position data with PyModesDecoder
+    df = rebuild.rebuild(
+        start="2023-01-03 16:00",
+        stop="2023-01-03 20:00",
+        icao24="400A0E",
+        decoder="pymodes"  # Use string-based decoder selection
+    )
+
+The decoder will process the raw messages and apply custom logic for CPR position decoding, validation, and filtering.
+
+Available decoders
+------------------
+
+PyModes decoder
+~~~~~~~~~~~~~~~
+
+The :class:`~pyopensky.decoders.PyModesDecoder` uses the `pyModeS <https://github.com/junzis/pyModeS>`_ library for decoding.
+
+**Features:**
+
+- CPR position decoding with odd/even frame pairing
+- Reference position validation to filter outliers
+- BDS register decoding (BDS 4,0, BDS 5,0, BDS 6,0)
+- Pure Python implementation
+
+**Installation:**
+
+.. code-block:: bash
+
+    pip install 'pyopensky[pymodes]'
+
+**Usage:**
+
+.. code-block:: python
+
+    from pyopensky.decoders import PyModesDecoder
+    from pyopensky.rebuild import Rebuild
+    from pyopensky.trino import Trino
+
+    trino = Trino()
+    rebuild = Rebuild(trino)
+
+    # Using string-based selection
+    df = rebuild.redecode_position(
+        start="2023-01-03 16:00",
+        stop="2023-01-03 20:00",
+        icao24="400A0E",
+        decoder="pymodes"
+    )
+
+    # Or instantiate the decoder directly
+    decoder = PyModesDecoder()
+    df = rebuild.redecode_position(
+        start="2023-01-03 16:00",
+        stop="2023-01-03 20:00",
+        icao24="400A0E",
+        decoder=decoder
+    )
+
+Rs1090 decoder
+~~~~~~~~~~~~~~
+
+The :class:`~pyopensky.decoders.Rs1090Decoder` uses the Rust-based `rs1090 <https://github.com/xoolive/rs1090>`_ library for faster decoding.
+
+**Features:**
+
+- High-performance Rust implementation
+- Same decoding logic as PyModesDecoder
+- Significantly faster for large datasets
+
+**Installation:**
+
+.. code-block:: bash
+
+    pip install 'pyopensky[rs1090]'
+
+**Usage:**
+
+.. code-block:: python
+
+    from pyopensky.rebuild import Rebuild
+    from pyopensky.trino import Trino
+
+    trino = Trino()
+    rebuild = Rebuild(trino)
+
+    # Using string-based selection
+    df = rebuild.redecode_position(
+        start="2023-01-03 16:00",
+        stop="2023-01-03 20:00",
+        icao24="400A0E",
+        decoder="rs1090"
+    )
+
+Custom decoder
+~~~~~~~~~~~~~~
+
+You can implement your own decoder by subclassing :class:`~pyopensky.decoders.Decoder`:
+
+.. code-block:: python
+
+    from pyopensky.decoders import Decoder
+    import pandas as pd
+
+    class MyCustomDecoder(Decoder):
+        def decode_position(self, df: pd.DataFrame) -> pd.DataFrame:
+            # Custom position decoding logic
+            return df
+
+        def decode_velocity(self, df: pd.DataFrame) -> pd.DataFrame:
+            # Custom velocity decoding logic
+            return df
+
+        def decode_identification(self, df: pd.DataFrame) -> pd.DataFrame:
+            # Custom identification decoding logic
+            return df
+
+        def decode_rollcall(self, df: pd.DataFrame) -> pd.DataFrame:
+            # Custom rollcall decoding logic
+            return df
+
+    # Use your custom decoder
+    decoder = MyCustomDecoder()
+    df = rebuild.rebuild(
+        start="2023-01-03 16:00",
+        stop="2023-01-03 20:00",
+        icao24="400A0E",
+        decoder=decoder
+    )
+
+Performance considerations
+---------------------------
+
+**When to use PyModesDecoder vs Rs1090Decoder:**
+
+- Use ``PyModesDecoder`` for small to medium datasets (< 1M messages) or when you need to inspect the decoding logic
+- Use ``Rs1090Decoder`` for large datasets (> 1M messages) where performance is critical
+- Both decoders produce equivalent results, Rs1090Decoder is simply faster
+
+**Database vs custom decoding:**
+
+- Database-decoded positions are already validated and filtered by OpenSky
+- Custom decoding gives you full control over CPR frame pairing and outlier filtering
+- Use custom decoding when you need BDS register data or have specific validation requirements
+
+**Merge tolerance:**
+
+All merges use a 5-second tolerance by default. This means:
+
+- Position and velocity data must be within 5 seconds to be merged
+- Identification data must be within 5 seconds of position data
+- Rollcall data must be within 5 seconds of position data
+
+This tolerance balances data completeness with temporal accuracy.
+
+
+.. autoclass:: pyopensky.rebuild.Rebuild
+    :members:
+    :inherited-members:
+    :no-undoc-members:
+    :show-inheritance: