pyopensky 2.16__tar.gz → 2.18__tar.gz

pyopensky-2.18/.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.16 → pyopensky-2.18}/.github/workflows/build-docs.yml

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

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

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

pyopensky-2.18/.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.3.2
+        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.3.2
+        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.3.2
+        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.3.2
+        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.16 → pyopensky-2.18}/.gitignore

@@ -33,3 +33,4 @@ var/
 *.manifest
 *.spec
 
+.secrets

{pyopensky-2.16 → pyopensky-2.18}/PKG-INFO

@@ -1,11 +1,11 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pyopensky
-Version: 2.16
+Version: 2.18
 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-Python: >=3.10
 Requires-Dist: appdirs>=1.4.4
 Requires-Dist: httpx>=0.27.2
 Requires-Dist: minio>=7.2.8
@@ -14,6 +14,7 @@ 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
@@ -137,5 +138,32 @@ trino.history(start, stop, *, callsign, icao24, bounds)
 trino.rebuild(start, stop, *, icao24, bounds)
 ```
 
+For several routes in the same time window, use one query with exact directed
+airport pairs:
+
+```python
+df = trino.history(
+    "2025-01-01",
+    "2025-01-02",
+    routes=[("KJFK", "EGLL"), ("KMIA", "EIDW"), ("LFPG", "KJFK")],
+    selected_columns=("time", "icao24", "callsign", "lat", "lon"),
+)
+```
+
+The same `routes` filter is available in `flightlist()` for metadata queries and
+`rawdata()` for raw messages.
+`history()` clips trajectories to the requested time window, including flights
+that cross midnight.
+
+Optional Trino session settings apply to all queries on a client. For selective
+flight joins whose filtered flight table fits in each worker's memory:
+
+```python
+trino = Trino(session_properties={"join_distribution_type": "BROADCAST"})
+```
+
+`Trino()` uses the server's default settings. Use `cached=False` on each call when
+benchmarking query performance.
+
 > [!IMPORTANT]
 > Refer to the [documentation](https://mode-s.org/pyopensky) for advanced usage and parameter details.

{pyopensky-2.16 → pyopensky-2.18}/agents.md

@@ -7,7 +7,7 @@
 ## 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
+- Run `uv run ty check src/ tests/` to check types
 
 ## Documentation commands
 

{pyopensky-2.16 → pyopensky-2.18}/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.16 → pyopensky-2.18}/docs/source/trino_advanced.rst

@@ -70,6 +70,155 @@ Use ``with_only_columns()`` to reduce data transfer and improve query performanc
    - Schema attribute: ``StateVectorsData4.lat``
    - Qualified string: ``"StateVectorsData4.lat"`` or ``"FlightsData4.estdepartureairport"``
 
+Configuring Trino sessions
+---------------------------
+
+Pass ``session_properties`` to ``Trino`` to configure each connection opened by
+that client. Names and values are strings. For example, a broadcast join can
+reduce CPU and worker network traffic for selective flight queries:
+
+.. code-block:: python
+
+    from pyopensky.trino import Trino
+
+    trino = Trino(
+        session_properties={"join_distribution_type": "BROADCAST"}
+    )
+    df = trino.history(
+        "2025-06-01 12:00",
+        "2025-06-01 13:00",
+        routes=[("EGLL", "KJFK"), ("LFPG", "KJFK"), ("EHAM", "KJFK")],
+        selected_columns=("time", "icao24", "callsign", "lat", "lon"),
+    )
+
+``Trino()`` uses the server's default session settings. Broadcast joins are
+optional: the filtered build table must fit in each worker's memory. For large
+flight selections, let the server choose the join strategy or choose another
+session configuration. See `Trino join distribution selection
+<https://trino.io/docs/current/optimizer/cost-based-optimizations.html#join-distribution-selection>`_.
+
+Session properties apply to ``query()``, ``history()``, ``flightlist()``, and
+``rawdata()`` on that client. The constructor copies the supplied mapping.
+Result-cache keys include configured properties, so different configurations do
+not reuse each other's results. To measure query performance, pass
+``cached=False`` to every measured call.
+
+Batching directed routes
+------------------------
+
+Use ``routes`` to retrieve several directed airport pairs in one query for the
+same time window. This avoids submitting one state-vector query per route.
+
+.. code-block:: python
+
+    from pyopensky.trino import Trino
+
+    trino = Trino()
+    routes = [
+        ("KJFK", "EGLL"),
+        ("KMIA", "EIDW"),
+        ("LFPG", "KJFK"),
+    ]
+    df = trino.history(
+        "2025-01-01",
+        "2025-01-02",
+        routes=routes,
+        selected_columns=(
+            "time", "icao24", "callsign", "lat", "lon", "baroaltitude",
+            "FlightsData4.firstseen", "FlightsData4.lastseen",
+            "FlightsData4.estdepartureairport",
+            "FlightsData4.estarrivalairport",
+        ),
+    )
+
+Each pair contains the estimated departure and arrival ICAO identifiers, in that
+order. Only the listed pairs match. For example, ``[("KJFK", "EGLL"),
+("KMIA", "EIDW")]`` does not include KJFK to EIDW or the reverse directions.
+Separate ``departure_airport`` and ``arrival_airport`` lists select every
+combination between those lists.
+
+Route identifiers match exactly; SQL wildcards are not expanded. An empty route
+list selects no flights. Repeating a pair does not duplicate its results. Other
+filters, such as ``icao24``, ``callsign``, bounds and airport filters, further
+restrict the selected routes.
+
+For long periods, loop over time windows and include all required routes in each
+call. Select the columns needed for the analysis. Actual scan savings depend on
+the Trino query plan and table layout.
+
+If only flight metadata is needed, use the same route list with
+``trino.flightlist(start, stop, routes=routes)``. With routes alone,
+``flightlist()`` filters by ``lastseen``. Setting ``departure_airport`` also
+selects its existing departure-time behavior.
+
+.. note::
+
+   ``history()`` returns state vectors within ``start`` and ``stop``. These
+   timestamps do not select flights by their departure or arrival time. A flight
+   that crosses midnight can be partial in a daily result. ``time_buffer``
+   extends the bounds around each flight's ``firstseen`` and ``lastseen`` but
+   does not extend the requested state-vector window. Each call submits one
+   query; pyopensky does not split that window automatically.
+
+Filtering flight metadata in history queries
+--------------------------------------------
+
+``history()`` accepts ``FlightsData4`` conditions alongside state-vector
+conditions. Flight columns refer to the flight table joined to the state vectors.
+A flight condition also enables this join when no airport or route is specified.
+Selecting flight columns also enables this join. Flight schema attributes can
+be used directly in ``selected_columns``.
+
+.. code-block:: python
+
+    from pyopensky.schema import FlightsData4, StateVectorsData4
+    from pyopensky.trino import Trino
+
+    df = Trino().history(
+        "2025-01-01",
+        "2025-01-02",
+        FlightsData4.estarrivalairporthorizdistance < 5000,
+        routes=[("KJFK", "EGLL"), ("LFPG", "KJFK")],
+        selected_columns=(
+            StateVectorsData4.time,
+            StateVectorsData4.icao24,
+            FlightsData4.estdepartureairport,
+            FlightsData4.estarrivalairport,
+        ),
+    )
+
+Raw messages for directed routes
+--------------------------------
+
+``rawdata()`` also accepts exact ``routes``. It joins raw messages to matching
+flights by aircraft address and the flight's ``firstseen``/``lastseen`` interval,
+then clips messages to the requested time window. FlightsData4 conditions and
+extra columns use this joined flight table.
+
+.. code-block:: python
+
+    from pyopensky.schema import FlightsData4, PositionData4
+    from pyopensky.trino import Trino
+
+    df = Trino().rawdata(
+        "2025-01-01",
+        "2025-01-02",
+        FlightsData4.estarrivalairporthorizdistance < 5000,
+        routes=[("KJFK", "EGLL"), ("LFPG", "KJFK")],
+        Table=PositionData4,
+        extra_columns=(FlightsData4.estdepartureairport,),
+    )
+
+An empty route list selects no messages. Repeated pairs do not duplicate results.
+Airport filters and ``icao24`` further restrict the selected routes. Flight
+conditions or flight extra columns enable a flight join even without an airport
+or route argument.
+
+``rawdata()`` supports one selection mode per call: flight metadata (airports,
+routes, flight conditions or flight extra columns), geographic bounds, or
+callsign. These modes cannot be combined. Conditions on the raw table can
+further restrict any mode. Its existing raw-column output is preserved.
+
 
 Spatial queries with bounds
 ---------------------------
@@ -181,7 +330,8 @@ Filter by sensor serial numbers to get data from specific ground stations:
 Extending temporal range for airport queries
 --------------------------------------------
 
-Use ``time_buffer`` to include aircraft that departed/arrived slightly outside the time window:
+Use ``time_buffer`` to include state vectors just before a flight's ``firstseen``
+or after its ``lastseen``, within the requested time window:
 
 .. code-block:: python
 
@@ -189,7 +339,7 @@ Use ``time_buffer`` to include aircraft that departed/arrived slightly outside t
     
     trino = Trino()
     
-    # Get flights with 30-minute buffer before/after time window
+    # Allow samples up to 30 minutes before/after each flight's time bounds
     df = trino.history(
         start="2024-03-16 09:00",
         stop="2024-03-16 11:00",
@@ -197,7 +347,8 @@ Use ``time_buffer`` to include aircraft that departed/arrived slightly outside t
         time_buffer="30m",  # Also accepts "1h", "45min", etc.
     )
 
-This is useful when you want complete flight trajectories that may start or end outside your time range.
+The result remains clipped to 09:00 through 11:00. To retrieve samples outside
+that window, extend ``start`` or ``stop`` explicitly.
 
 Filtering with boolean expressions
 ----------------------------------

{pyopensky-2.16 → pyopensky-2.18}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "pyopensky"
-version = "2.16"
+version = "2.18"
 description = "A Python interface for OpenSky database"
 authors = [{ name = "Xavier Olive", email = "git@xoolive.org" }, { name = "Junzi Sun", email = "j.sun-1@tudelft.nl" }]
 license = "MIT"
 readme = "readme.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
   "appdirs >= 1.4.4",
   "httpx >= 0.27.2",
@@ -15,6 +15,7 @@ dependencies = [
   "pyarrow >= 17.0.0",
   "pyjwt >= 2.9.0",
   "python-dotenv>=1.0.1",
+  "stamina>=25.1.0",
   "tqdm >= 4.66.5",
   "trino[sqlalchemy] >= 0.329.0",
   "typing-extensions >= 4.12.2",
@@ -35,8 +36,6 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
-  "pre-commit >= 3.8.0",
-  "mypy >= 1.11.2",
   "ruff >= 0.6.3",
   "pytest >= 8.3.2",
   "ipykernel >= 7.1.0; python_version>='3.10'",
@@ -44,6 +43,7 @@ dev = [
   "sphinx-design >= 0.6.1; python_version>'3.11'",
   "sphinx-rtd-theme >= 2.0.0; python_version>'3.11'",
   "sphinx-autodoc-typehints >= 2.3.0; python_version>'3.11'",
+  "ty>=0.0.17",
 ]
 
 [tool.ruff]
@@ -58,21 +58,21 @@ lint.select = [
   "RUF",
 ]
 line-length = 80
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint.isort]
 known-first-party = ["numpy", "pandas"]
 
-[tool.mypy]
-python_version = "3.9"
-platform = "posix"
-color_output = true
-pretty = true
-show_column_numbers = true
-strict = true
-check_untyped_defs = true
-ignore_missing_imports = true
-warn_no_return = true
-warn_redundant_casts = true
-warn_unused_configs = true
-warn_unused_ignores = true
+[tool.ty.src]
+exclude = ["src/pyopensky/decoders/pymodes.py"]
+
+[[tool.ty.overrides]]
+# SQLAlchemy models expose their columns dynamically. Ty cannot verify these
+# attributes for the heterogeneous raw-message table union.
+include = ["src/pyopensky/rest.py", "src/pyopensky/trino.py"]
+rules = { "unresolved-attribute" = "ignore" }
+
+[tool.pytest.ini_options]
+log_cli = true
+log_cli_level = "DEBUG"
+log_cli_format = "%(levelname)s %(name)s:%(filename)s:%(lineno)d %(message)s"

{pyopensky-2.16 → pyopensky-2.18}/readme.md

@@ -109,5 +109,32 @@ trino.history(start, stop, *, callsign, icao24, bounds)
 trino.rebuild(start, stop, *, icao24, bounds)
 ```
 
+For several routes in the same time window, use one query with exact directed
+airport pairs:
+
+```python
+df = trino.history(
+    "2025-01-01",
+    "2025-01-02",
+    routes=[("KJFK", "EGLL"), ("KMIA", "EIDW"), ("LFPG", "KJFK")],
+    selected_columns=("time", "icao24", "callsign", "lat", "lon"),
+)
+```
+
+The same `routes` filter is available in `flightlist()` for metadata queries and
+`rawdata()` for raw messages.
+`history()` clips trajectories to the requested time window, including flights
+that cross midnight.
+
+Optional Trino session settings apply to all queries on a client. For selective
+flight joins whose filtered flight table fits in each worker's memory:
+
+```python
+trino = Trino(session_properties={"join_distribution_type": "BROADCAST"})
+```
+
+`Trino()` uses the server's default settings. Use `cached=False` on each call when
+benchmarking query performance.
+
 > [!IMPORTANT]
 > Refer to the [documentation](https://mode-s.org/pyopensky) for advanced usage and parameter details.