Python bindings

.github/workflows/python.yml

@@ -0,0 +1,119 @@
+name: python
+
+on:
+  push:
+  pull_request:
+  release:
+    types: [created]
+
+jobs:
+  macos:
+    runs-on: macos-latest
+    continue-on-error: true
+    strategy:
+      matrix:
+        py_ver: ['3.8', '3.9', '3.10']
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.py_ver }}
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-apple-darwin
+      - name: Build
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x86_64-apple-darwin
+          args: --release -i python${{ matrix.py_ver }} --all-features -m rinex/Cargo.toml --out dist --sdist
+      - name: Test wheel
+        run: |
+          pip install rinex --no-index --find-links dist --force-reinstall
+          python -c "import rinex"
+      - name: Prepare for upload
+        run: tar czvf rinex.tar.gz dist/*.whl
+      - name: Github Release
+        uses: svenstaro/upload-release-action@v2
+        if: "startsWith(github.ref, 'refs/tags/')"
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          asset_name: rinex-python${{ matrix.pyver }}-apple-darwin.tar.gz
+          file: rinex.tar.gz
+          tag: ${{ github.ref }}
+
+  windows:
+    runs-on: windows-latest
+    continue-on-error: true
+    strategy:
+      matrix:
+        target: [x64, x86]
+        py_ver: ['3.8', '3.9', '3.10']
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.py_ver }}
+          architecture: ${{ matrix.target }}
+      - name: Build
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --all-features -m rinex/Cargo.toml --out dist
+      - name: Test wheel
+        run: |
+          pip install rinex --no-index --find-links dist --force-reinstall
+          python -c "import rinex"
+      - name: Prepare for upload
+        run: |
+          Compress-Archive dist/*.whl rinex.zip
+          dir
+      - name: Github Release
+        uses: svenstaro/upload-release-action@v2
+        if: "startsWith(github.ref, 'refs/tags/')"
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          asset_name: rinex-python${{ matrix.pyver }}-windows-${{ matrix.target }}.zip
+          file: rinex.zip
+          tag: ${{ github.ref }}
+
+  linux:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      matrix:
+        target: [x64]
+        py_ver: ['3.8', '3.9', '3.10']
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@stable 
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.py_ver }}
+          architecture: ${{ matrix.target }}
+      - name: Build
+        uses: PyO3/maturin-action@main
+        with:
+          target: x64 
+          manylinux: auto
+          args: --release -i python${{ matrix.py_ver }} --all-features -m rinex/Cargo.toml -o dist
+      - name: Build
+        run: |
+          pip3 install rinex --no-index --find-links dist --force-reinstall
+          python -c "import rinex"
+      - name: Test wheel
+        run: |
+          pip install rinex --no-index --find-links dist --force-reinstall
+          python -c "import rinex"
+      - name: Prepare for upload
+        run: |
+          tar czvf rinex.tar.gz dist/*.whl
+          ls -lah rinex.tar.gz
+      - name: Github Release
+        uses: svenstaro/upload-release-action@v2
+        if: "startsWith(github.ref, 'refs/tags/')"
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          asset_name: rinex-python${{ matrix.pyver }}-linux-${{ matrix.target }}.tar.gz
+          file: rinex.tar.gz
+          tag: ${{ github.ref }}

.github/workflows/release.yml

@@ -2,6 +2,10 @@ name: release
 on:
   release:
     types: [created]
+  pull_request:
+
+env:
+  PKG_CONFIG_PATH: "/usr/lib/pkgconfig"
 
 env:
   PKG_CONFIG_PATH: "/usr/lib/pkgconfig"

README.md

@@ -12,6 +12,7 @@ RINEX
 Rust tool suites to parse, analyze and process `RINEX` files
 
 * [`rinex`](rinex/) is the core library 
+
 * [`rinex-cli`](rinex-cli/) is a command line application based on the core library.  
 It can be used to process RINEX files or perform operations similar to `teqc`.   
 The application is auto-generated for a few architectures, download it from the 
@@ -28,6 +29,14 @@ and [rinex](rinex/) crates.
 
 By default, all timestamps are in UTC with leap seconds correctly managed.
 
+:warning: Years encoded on two digits in files generated prior Jan 1 2000,
+get falsely offset to the 21st century. This only applies to OBS(V2)
+and NAV(V2) files generated prior year 2000.
+
+## `RINEX` in Python
+
+Refer to the [python package](doc/python.md) to understand how to build the python3 wheel.
+
 ## Supported `RINEX` types
 
 | Type                       | Parser            | Writer              |  CLI                 | UBX                  |           Notes          |
@@ -91,6 +100,9 @@ select a SBAS for a given location on Earth.
 * `--flate2`  
 allow native parsing of .gz compressed RINEX files. Otherwise, user must uncompress manually the `.gz` extension first.
 
+* `--pyo3` (experimental)
+Add Python bindings via `PyO3`. To build the Python package, you must first install maturin and then build it with the pyo3 feature flag. For example, `maturin build -F pyo3`. Maturin will then build and place the resulting .whl file in `/target/wheels/`, after which you can install the package with `pip install rinex`.
+
 ## Benchmark
 
 Test           | Results 

doc/python.md

@@ -0,0 +1,25 @@
+Python3 wheel
+=============
+
+Install requirements: python3 (>3.8) and maturin 
+
+Then build the python bindings: use `maturin` to build the crate
+with the `pyo3` feature
+
+```bash
+cd rinex/
+maturin build -F pyo3
+```
+
+A pip3 wheel is generated for your architecture.   
+Use pip3 to install the library
+
+```bash
+pip3 install --force-reinstall rinex/target/wheels/rinex-xxx.whl
+```
+
+Now move on to the provided examples, run the basics with
+
+```bash
+python3 rinex/examples/python/basic.py
+```

rinex/Cargo.toml

@@ -15,6 +15,7 @@ rust-version = "1.61"
 [features]
 default = [] # no features by default
 sbas = ["geo", "wkt"]
+pyo3 = ["dep:pyo3", "hifitime/python"]
 tests = [] # used to import shared test methods
 
 [build-dependencies]
@@ -37,7 +38,8 @@ geo = { version = "0.26", optional = true }
 wkt = { version = "0.10.0", default-features = false, optional = true }
 serde = { version = "1.0", optional = true, default-features = false, features = ["derive"] }
 flate2 = { version = "1.0.24", optional = true, default-features = false, features = ["zlib"] }
-hifitime = { version = "3.8", features = ["serde", "std"] }
+pyo3 = { version = "0.19", default-features = false, features = ["extension-module"], optional = true}
+hifitime = { git = "https://github.com/nyx-space/hifitime", branch = "master", features = ["serde", "std"] }
 horrorshow = { version = "0.8" }
 statrs = "0.16"
 

rinex/examples/python/basic.py

@@ -0,0 +1,36 @@
+from rinex import * 
+
+# rinex::prelude basic examples,
+# This example program depicts how you can interact with
+# all the basic structures from the rust crate
+
+def parser_example(fp):
+    # parse a RINEX file
+    rinex = Rinex(fp)
+    # use header section 
+    print("is_crinex: ", rinex.header.is_crinex())
+    print("header : \n{:s}".format(str(rinex.header)))
+    # use record section
+    print(rinex.record)
+
+def rinex_manual_constructor():
+    # Manual construction example.
+    # This is handy in data production contexts
+    header = Header.basic_obs()
+    print(header.is_crinex())
+
+def sv_example():
+    pass
+
+def constellation_example():
+    pass
+
+def epoch_example():
+    print("Epoch.system_now(): ", Epoch.system_now())
+
+if __name__ == "__main__":
+    parser_example("../test_resources/OBS/V3/DUTH0630.22O")
+    epoch_example()
+    sv_example()
+    rinex_manual_constructor()
+    constellation_example()

rinex/examples/python/observation.py

@@ -0,0 +1,11 @@
+from rinex import * 
+
+if __name__ == "__main__":
+    crinex = Crinex()
+    assert(crinex.version.major == 3)
+    assert(crinex.version.minor == 0)
+
+    observation = ObservationData(10.0)
+    assert(observation.obs == 10.0)
+    assert(observation.snr == None)
+    assert(observation.lli == None)

rinex/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["maturin>=0.14"]
+build-backend = "maturin"
+
+[project]
+name = "rinex"
+requires-python = ">=3.8"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+

rinex/src/constellation/augmentation.rs

@@ -2,13 +2,17 @@
 //! mainly used for high precision positioning
 use strum_macros::EnumString;
 
+#[cfg(feature = "pyo3")]
+use pyo3::prelude::*;
+
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 
-#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, EnumString)]
-#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 /// GNSS Augmentation systems,
 /// must be used based on current location
+#[cfg_attr(feature = "pyo3", pyclass)]
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, EnumString)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum Augmentation {
     /// Augmentation Unknown
     Unknown,

rinex/src/constellation/mod.rs

@@ -10,6 +10,9 @@ pub use augmentation::selection_helper;
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 
+#[cfg(feature = "pyo3")]
+use pyo3::prelude::*;
+
 #[derive(Error, Clone, Debug, PartialEq)]
 /// Constellation parsing & identification related errors
 pub enum Error {
@@ -47,6 +50,15 @@ pub enum Constellation {
     Mixed,
 }
 
+#[cfg(feature = "pyo3")]
+#[cfg_attr(feature = "pyo3", pyclass)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum PyConstellation {
+    GPS,
+    Glonass,
+    Geo,
+}
+
 impl std::fmt::Display for Constellation {
     fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
         f.write_str(self.to_3_letter_code())
@@ -185,6 +197,50 @@ impl std::str::FromStr for Constellation {
     }
 }
 
+#[cfg(feature = "pyo3")]
+impl IntoPy<PyObject> for Constellation {
+    fn into_py(self, py: Python<'_>) -> PyObject {
+        let pyc: PyConstellation = self.into();
+        pyc.into_py(py)
+    }
+}
+
+#[cfg(feature = "pyo3")]
+impl From<Constellation> for PyConstellation {
+    fn from(c: Constellation) -> Self {
+        match c {
+            Constellation::SBAS(_) => Self::Geo,
+            Constellation::GPS => Self::GPS,
+            Constellation::Glonass => Self::Glonass,
+            _ => panic!("gnss not supported yet"),
+        }
+    }
+}
+
+#[cfg(feature = "pyo3")]
+impl From<PyConstellation> for Constellation {
+    fn from(c: PyConstellation) -> Self {
+        match c {
+            PyConstellation::GPS => Self::GPS,
+            PyConstellation::Glonass => Self::Glonass,
+            PyConstellation::Geo => Self::Geo,
+        }
+    }
+}
+
+/*#[cfg(feature = "pyo3")]
+use crate::prelude::Sv;
+#[cfg(feature = "pyo3")]
+impl From<&PyCell<Sv>> for Constellation {
+    fn from(cell: &PyCell<Sv>) -> Self {
+        if let Ok(sv) = cell.extract::<Sv>() {
+            sv.constellation
+        } else {
+            Self::default()
+        }
+    }
+}*/
+
 #[cfg(test)]
 mod tests {
     use super::*;

rinex/src/epoch/flag.rs

@@ -10,10 +10,14 @@ pub enum Error {
     UnknownFlag,
 }
 
+#[cfg(feature = "pyo3")]
+use pyo3::prelude::*;
+
 /// `EpochFlag` validates an epoch,
 /// or describes possible events that occurred
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[cfg_attr(feature = "pyo3", pyclass)]
 pub enum EpochFlag {
     /// Epoch is sane
     Ok,
@@ -37,10 +41,11 @@ impl Default for EpochFlag {
     }
 }
 
+#[cfg_attr(feature = "pyo3", pymethods)]
 impl EpochFlag {
     /// Returns True if self is a valid epoch
-    pub fn is_ok(self) -> bool {
-        self == Self::Ok
+    pub fn is_ok(&self) -> bool {
+        *self == Self::Ok
     }
 }