pyopensky 2.14__tar.gz → 2.16__tar.gz

{pyopensky-2.14 → pyopensky-2.16}/.github/workflows/build-docs.yml

@@ -15,7 +15,7 @@ jobs:
       UV_CACHE_DIR: /tmp/.uv-cache
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         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@v6
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
 
       - name: Cache folder for uv
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: /tmp/.uv-cache
           key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}

{pyopensky-2.14 → pyopensky-2.16}/.github/workflows/pypi_publish.yml

@@ -9,16 +9,16 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - 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@v6
 
       - name: Cache folder for uv
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: /tmp/.uv-cache
           key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}

{pyopensky-2.14 → pyopensky-2.16}/.github/workflows/run_tests.yml

@@ -10,7 +10,6 @@ on:
 jobs:
   deploy:
     name: python-${{ matrix.python-version }} on ${{ matrix.os }}
-
     strategy:
       matrix:
         os:
@@ -23,6 +22,16 @@ jobs:
           - "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"
 
       fail-fast: false
 
@@ -32,17 +41,17 @@ jobs:
       UV_CACHE_DIR: /tmp/.uv-cache
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
 
       - name: Cache folder for data
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         id: cache-folder
         with:
           path: |
@@ -51,13 +60,17 @@ jobs:
           key: opensky-${{ hashFiles('uv.lock') }}
 
       - name: Install the project
-        run: uv sync --all-extras --dev --python ${{ matrix.python-version }}
+        run: uv sync --dev --python ${{ matrix.python-version }} --extra rs1090 --extra cartes
 
       - name: Linting and formatting
         run: |
           uv run ruff check
           uv run ruff format --check
 
+      - name: Type checking
+        if: ${{ matrix.python-version != '3.9' }}
+        run: uvx ty check src tests
+
       - name: Run tests
         if: ${{ (matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest') || steps.cache-folder.outputs.cache-hit == 'true' }}
         env:

pyopensky-2.16/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: pyopensky
+Version: 2.16
+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.9
+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: 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.16/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 `uvx 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.14 → pyopensky-2.16}/docs/source/credentials.rst

@@ -20,9 +20,13 @@ is created, including the following content:
     [default]
     username =
     password =
+    client_id =
+    client_secret =
 
-If you use the same login for the OpenSky website (therefore the REST API) and 
-for Trino (it will be unified one day), just fill it here.
+
+The username and password is used to access the Trino database, while the
+client ID and client secret are used to access the OpenSky REST API. 
+Log in to your OpenSky account and visit the `Account <https://opensky-network.org/my-opensky/account>`_ page in order to create a new API client and retrieve your ``client_id`` and ``client_secret``.
 
 You will identify the folder where the ``settings.conf`` file is located:
 
@@ -32,26 +36,6 @@ You will identify the folder where the ``settings.conf`` file is located:
 
     print(opensky_config_dir)
 
-
-Different credentials per service
----------------------------------
-
-If you want to specify different credentials for the REST API and for the Trino 
-database, use the following sections in the configuration file.
-
-.. code::
-
-    [opensky]  # REST API
-    username =
-    password =
-
-    [trino]  # Trino database
-    username =
-    password =
-
-If these sections are commented, the library will use the credentials from the
-[default] section.
-
 Fallback configuration
 ----------------------
 
@@ -61,5 +45,5 @@ following steps are performed in order:
 - try to get the credentials from the `traffic <https://traffic-viz.github.io>`_
   configuration file;
 - get the credentials from ``$OPENSKY_USERNAME`` and ``$OPENSKY_PASSWORD``
-  environment variables;
-- open a browser and log in on a dedicated webpage.
+  environment variables (``$OPENSKY_CLIENT_ID`` and ``$OPENSKY_CLIENT_SECRET`` for the API client);
+- open a browser and log in on a dedicated webpage (for Trino).

{pyopensky-2.14 → pyopensky-2.16}/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.16/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: