pyopensky 2.10__tar.gz → 2.12__tar.gz

pyopensky-2.12/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  # - package-ecosystem: "pip"
+  #   directory: "/"
+  #   schedule:
+  #     interval: "monthly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

pyopensky-2.12/.github/renovate.json5

@@ -0,0 +1,6 @@
+{
+  $schema: "https://docs.renovatebot.com/renovate-schema.json",
+  lockFileMaintenance: {
+    enabled: true,
+  },
+}

pyopensky-2.12/.github/workflows/build-docs.yml

@@ -0,0 +1,56 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+
+    env:
+      PYTHON_VERSION: "3.12"
+      UV_CACHE_DIR: /tmp/.uv-cache
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+
+      - name: Cache folder for uv
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.uv-cache
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+            uv-${{ runner.os }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --dev
+
+      - name: Build pages
+        working-directory: docs
+        run: |
+          uv run make html
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci
+
+      - name: Deploy pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/html

pyopensky-2.12/.github/workflows/pypi_publish.yml

@@ -0,0 +1,39 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+
+      - name: Cache folder for uv
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.uv-cache
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+            uv-${{ runner.os }}
+
+      - name: Build packages
+        run: uvx hatch build
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci
+
+      - name: Publish a Python distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_PASSWORD }}

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

@@ -0,0 +1,82 @@
+name: tests
+
+on:
+  push:
+  pull_request_target:
+  schedule: # This is useful for keeping the cache fit and ready
+    - cron: "42 3 * * 0" # Every Sunday morning when I am fast asleep :)
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: python-${{ matrix.python-version }} on ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        python-version:
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+      fail-fast: false
+
+    runs-on: ${{ matrix.os }}
+
+    env:
+      UV_CACHE_DIR: /tmp/.uv-cache
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        if: ${{ matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' }}
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Set up uv
+        if: ${{ matrix.os == 'windows-latest' }}
+        run: irm https://astral.sh/uv/install.ps1 | iex
+        shell: powershell
+
+      - name: Cache folder for uv
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.uv-cache
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+            uv-${{ runner.os }}
+
+      - name: Cache folder for data
+        uses: actions/cache@v4
+        id: cache-folder
+        with:
+          path: |
+            ${{ github.workspace }}/cache_opensky
+          key: opensky-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+
+      - name: Install the project
+        run: uv sync --all-extras --dev --python ${{ matrix.python-version }}
+
+      - name: Linting and formatting
+        run: |
+          uv run ruff check
+          uv run ruff format --check
+
+      - name: Run tests
+        if: ${{ matrix.python-version == '3.12' || steps.cache-folder.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
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

{pyopensky-2.10 → pyopensky-2.12}/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.3
 Name: pyopensky
-Version: 2.10
+Version: 2.12
 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
@@ -15,6 +14,7 @@ Requires-Dist: pyjwt>=2.9.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.1; extra == 'cartes'
 Provides-Extra: decoding

pyopensky-2.12/docs/.gitignore

@@ -0,0 +1 @@
+build/

pyopensky-2.12/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

pyopensky-2.12/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

pyopensky-2.12/docs/source/_static/main_stylesheet.css

@@ -0,0 +1,17 @@
+a.reference code.literal span {
+  font-family: Lato, proxima-nova, Helvetica Neue, Arial, sans-serif;
+  font-size: 16px;
+  font-weight: 500;
+  color: #2980b9;
+}
+.rst-content .document a {
+  text-decoration: underline;
+  text-underline-offset: 2pt;
+}
+.rst-content .document a code {
+    padding: 0
+}
+.rst-content code {
+    border: none;
+    background: none;
+}

pyopensky-2.12/docs/source/api_reference.rst

@@ -0,0 +1,8 @@
+API reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   rest
+   trino

pyopensky-2.12/docs/source/conf.py

@@ -0,0 +1,47 @@
+from typing import Any
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import pyopensky
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "pyopensky"
+copyright = "2023, Xavier Olive, Junzi Sun"
+author = "Xavier Olive, Junzi Sun"
+release = pyopensky.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
+    "sphinx_autodoc_typehints",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/dev", None),
+    "traffic": ("https://traffic-viz.github.io", None),
+}
+
+
+def setup(app: Any) -> None:
+    # Specific stylesheet
+    app.add_css_file("main_stylesheet.css")

pyopensky-2.12/docs/source/credentials.rst

@@ -0,0 +1,65 @@
+Credentials
+===========
+
+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.
+
+Configuration
+-------------
+
+The first time you use the library, a configuration file named ``settings.conf``
+is created, including the following content:
+
+.. code::
+
+    [default]
+    username =
+    password =
+
+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.
+
+You will identify the folder where the ``settings.conf`` file is located:
+
+.. code:: python
+
+    from pyopensky.config import opensky_config_dir
+
+    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
+----------------------
+
+If no username and password are specified in the `pyopensky` configuration file, the
+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.

pyopensky-2.12/docs/source/index.rst

@@ -0,0 +1,30 @@
+pyopensky
+=========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+Source code on `github <https://github.com/open-aviation/pyopensky>`_
+
+The pyopensky library provides function to easily download data from
+`The OpenSky Network <https://opensky-network.org/>`_ databases. This minimal 
+library is ideal for quickly downloading and locally saving data that you will
+use in your future studies. All functions return pandas :class:`~pandas.DataFrame`.
+
+.. hint::
+
+   If Python is your language of choice in general, and you are interested in
+   analysing aircraft trajectories, please refer to the following `section in
+   the traffic <https://traffic-viz.github.io/data_sources/opensky_db.html>`_
+   library. traffic wraps the same pyopensky queries and returns
+   :class:`~traffic.core.Traffic` and :class:`~traffic.core.Flight` objects.
+   
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   installation
+   credentials
+   api_reference
+

pyopensky-2.12/docs/source/installation.rst

@@ -0,0 +1,27 @@
+Installation
+============
+
+pyopensky is available through pip:
+
+.. code::
+
+    pip install pyopensky
+
+The library is also available on conda-forge:
+
+.. code::
+
+    conda install -c conda-forge pyopensky
+
+Development mode (with uv):
+
+.. code::
+
+    curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux and MacOS
+    irm https://astral.sh/uv/install.ps1 | iex  # Windows
+    uv sync --dev
+
+.. hint::
+
+    pyopensky is automatically installed as a dependency of the `traffic
+    <https://traffic-viz.github.io>`_ library.

pyopensky-2.12/docs/source/rest.rst

@@ -0,0 +1,8 @@
+The REST API
+------------
+
+.. autoclass:: pyopensky.rest.REST
+    :members:
+    :inherited-members:
+    :no-undoc-members:
+    :show-inheritance:

pyopensky-2.12/docs/source/trino.rst

@@ -0,0 +1,8 @@
+The Trino database
+-------------------
+
+.. autoclass:: pyopensky.trino.Trino
+    :members:
+    :inherited-members:
+    :no-undoc-members:
+    :show-inheritance:

{pyopensky-2.10 → pyopensky-2.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyopensky"
-version = "2.10"
+version = "2.12"
 description = "A Python interface for OpenSky database"
 authors = [
   { name = "Xavier Olive", email = "git@xoolive.org" },
@@ -19,6 +19,7 @@ dependencies = [
   "tqdm >= 4.66.5",
   "trino[sqlalchemy] >= 0.329.0",
   "typing-extensions >= 4.12.2",
+  "tzdata>=2024.2",
 ]
 
 [project.urls]
@@ -32,9 +33,6 @@ decoding = ["pymodes>=2.18", "rs1090>=0.3.8"]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
-[tool.hatch.build.targets.sdist]
-include = ["license.txt", "py.typed"]
-
 [tool.uv]
 dev-dependencies = [
   "pre-commit >= 3.8.0",

pyopensky-2.12/scripts/decode_pymodes.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pyModeS as pms
+
+import pandas as pd
+
+
+def decode_row(row: pd.Series) -> dict[str, Any]:
+    bds = row["bds"]
+    msg = row["rawmsg"]
+
+    decoded = {
+        "time": row["mintime"],
+        "icao24": row["icao24"],
+        "bds": bds,
+        "rawmsg": row["rawmsg"],
+        "altitude": row["altitude"],
+        "squawk": row["squawk"],
+    }
+
+    if bds == "BDS40":
+        selalt40mcp = pms.commb.selalt40mcp(msg)
+        selalt40fms = pms.commb.selalt40fms(msg)
+        p40baro = pms.commb.p40baro(msg)
+
+        decoded.update(
+            {
+                "selalt40mcp": selalt40mcp,
+                "selalt40fms": selalt40fms,
+                "p40baro": p40baro,
+            }
+        )
+
+    if bds == "BDS50":
+        roll50 = pms.commb.roll50(msg)
+        trk50 = pms.commb.trk50(msg)
+        rtrk50 = pms.commb.rtrk50(msg)
+        gs50 = pms.commb.gs50(msg)
+        tas50 = pms.commb.tas50(msg)
+
+        decoded.update(
+            {
+                "roll50": roll50,
+                "trk50": trk50,
+                "rtrk50": rtrk50,
+                "gs50": gs50,
+                "tas50": tas50,
+            }
+        )
+
+    if bds == "BDS60":
+        ias60 = pms.commb.ias60(msg)
+        hdg60 = pms.commb.hdg60(msg)
+        mach60 = pms.commb.mach60(msg)
+        vr60baro = pms.commb.vr60baro(msg)
+        vr60ins = pms.commb.vr60ins(msg)
+
+        decoded.update(
+            {
+                "ias60": ias60,
+                "hdg60": hdg60,
+                "mach60": mach60,
+                "vr60baro": vr60baro,
+                "vr60ins": vr60ins,
+            }
+        )
+    return decoded
+
+
+def decode(df: pd.DataFrame) -> pd.DataFrame:
+    commb = (
+        df.assign(DF=lambda df: df["rawmsg"].apply(pms.df))
+        .query("DF in [20, 21]")
+        .assign(bds=lambda df: df["rawmsg"].apply(pms.bds.infer))
+        .query('bds in ["BDS40", "BDS50", "BDS60"]')
+        .drop_duplicates(["icao24", "mintime"])
+    )
+
+    altcode = commb.loc[commb.DF == 20, "rawmsg"].apply(pms.altcode)
+    commb.loc[commb.DF == 20, "altitude"] = altcode
+
+    idcode = commb.loc[commb.DF == 21, "rawmsg"].apply(pms.idcode)
+    commb.loc[commb.DF == 21, "squawk"] = idcode
+
+    return pd.DataFrame.from_records(
+        decode_row(row) for _i, row in commb.sort_values("mintime").iterrows()
+    )

pyopensky-2.12/scripts/decode_rs1090.py

@@ -0,0 +1,31 @@
+# ruff: noqa: E741
+
+import sys
+
+import rs1090
+
+import pandas as pd
+
+if sys.version_info < (3, 12):
+    from typing import Iterator, Tuple, TypeVar
+
+    T = TypeVar("T", covariant=True)
+
+    def batched(
+        iterable: Iterator[Tuple[T, ...]], n: int = 1
+    ) -> Iterator[Tuple[T, ...]]:
+        l = len(iterable)  # type: ignore
+        for ndx in range(0, l, n):
+            yield iterable[ndx : min(ndx + n, l)]  # type: ignore
+
+else:
+    from itertools import batched
+
+
+def decode(df: pd.DataFrame) -> pd.DataFrame:
+    decoded = rs1090.decode(df["rawmsg"], df["mintime"])
+
+    # 5000 is (empirically) the fastest batch size I found
+    df = pd.concat(pd.DataFrame.from_records(d) for d in batched(decoded, 5000))
+    df = df.assign(timestamp=pd.to_datetime(df.timestamp, unit="s", utc=True))
+    return df

pyopensky-2.12/src/pyopensky/__init__.py

@@ -0,0 +1,13 @@
+import sys
+from importlib.metadata import version
+
+from .tzdata import download_tzdata_windows
+
+__version__ = version("pyopensky")
+
+# Despite the 'win32' string, this value is returned on all versions of Windows,
+# including both 32-bit and 64-bit. The 'win32' identifier is a historical
+# artifact that has been retained for compatibility with older versions of
+# Python.
+if sys.platform == "win32":
+    download_tzdata_windows(year=2022)