Modernize packaging, CI and PyPI release workflow

.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+  # Called by release.yml so nothing is published without passing these jobs.
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - run: uv run ruff check
+
+  test:
+    name: test (${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+        include:
+          - os: windows-latest
+            python-version: "3.15"
+          - os: macos-latest
+            python-version: "3.15"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      - name: Smoke-test the wheel
+        run: uv run --isolated --no-project --with dist/*.whl python -c "import comtrade; print(comtrade.__version__)"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/

.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+# Publishing a GitHub Release (tag = version in comtrade.py, e.g. "0.1.3")
+# runs CI and uploads the built sdist and wheel to PyPI via Trusted Publishing.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/comtrade/${{ github.event.release.tag_name }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - name: Check the release tag matches the package version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          ls dist/
+          if [ ! -f "dist/comtrade-${TAG#v}.tar.gz" ]; then
+            echo "::error::Release tag '$TAG' does not match __version__ in comtrade.py"
+            exit 1
+          fi
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

.gitignore

@@ -164,3 +164,6 @@ cython_debug/
 #.idea/
 
 # End of https://www.toptal.com/developers/gitignore/api/python
+
+# uv (library: dev dependencies are resolved fresh, not locked)
+uv.lock

README.md

@@ -21,9 +21,9 @@ Or just copy `comtrade.py` from this repository.
 
 ### Requirements
 
-- Python 3.6 or newer
-- (optional) numpy for speed improvement
-- (optional) pandas for data frame support
+- Python 3.11 or newer
+- (optional) numpy for speed improvement: `pip install "comtrade[numpy]"`
+- (optional) pandas for data frame support: `pip install "comtrade[pandas]"`
 
 
 ## How to Use
@@ -73,6 +73,8 @@ The module function `load` must be called with the `CFF` file path specified.
 
 `Comtrade.analog` and `Comtrade.status` lists stores analog and status channel sample lists respectively. These can be accessed through zero-based indexes, i.e., `Comtrade.analog[0]`. The list `Comtrade.time` stores each sample time in seconds.
 
+Analog channels may have a time skew (in microseconds) from the start of the sample period, which is not included in `Comtrade.time`. The list `Comtrade.analog_time` stores the time values of each analog channel, with its skew, in seconds, i.e., `Comtrade.analog_time[0]` for `Comtrade.analog[0]`.
+
 More information can be accessed through `Comtrade.cfg` object, which stores data such as detailed channel information.
 
 Data of additional sections, such as HDR and INF, can be accessed through `hdr` and `inf` properties, respectively.
@@ -121,17 +123,16 @@ Feel free to pull requests implementing one of these unsupported features or fix
 | Timestamp multiplication factor                       |      |  x   | x    | x    | x               |
 | Time code and local code                              |      |      |      | x    | x               |
 | Time quality of the samples                           |      |      |      | x    | x               |
-| Analog channel time skew                              |      |  x   | x    | x    | Partial         |
+| Analog channel time skew                              |      |  x   | x    | x    | x               |
 | Analog channel primary and secondary VT or CT ratio   |      |  x   | x    | x    | x               |
 | Status channel phase and monitored circuit            |      |  x   | x    | x    | x               |
-| Multiple sample rates                                 | x    |  x   | x    | x    | Partial         |
+| Multiple sample rates                                 | x    |  x   | x    | x    | x               |
 | Nanoseconds scale                                     |      |      | x    | x    | x               |
 
 
 ### Unsupported features
 
 * Nanoseconds time base within Python's `datetime` objects (such as `start_timestamp` and `trigger_timestamp` properties). It warns the user but doesn't use it, truncating the numbers.
-* Use of multiple sample rates in time calculations for binary data.
 
 
 ### Additional settings and features
@@ -145,7 +146,9 @@ in `Comtrade` object constructor:
 obj = Comtrade(use_numpy_arrays=True)
 ```
 
-It may improve performance for computations after loading data.
+It may improve performance for computations after loading data. It also speeds up loading binary
+DAT files (`BINARY`, `BINARY32` and `FLOAT32` formats), which are converted with vectorized numpy
+operations.
 
 
 #### Replace missing data with `float('nan')`
@@ -183,12 +186,28 @@ Feel free to report any bugs you find. You are welcome to fork and submit pull r
 
 ## Development
 
-To run tests, use Python's `unittest`. From a clone of the GitHub repository, run the command:
+From a clone of the GitHub repository, run the tests and the linter with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv run pytest
+uv run ruff check
+```
+
+Or, with pip 25.1 or newer:
 
 ```sh
-python3 -m unittest ./tests/tests.py
+python -m pip install -e . --group dev
+python -m pytest
 ```
 
+### Releasing
+
+1. Update `__version__` in `comtrade.py` and push the commit to `master`.
+2. Publish a GitHub release tagged with that same version, e.g. `gh release create 0.1.3 --generate-notes`.
+
+The `Release` workflow then runs CI and uploads the sdist and wheel to PyPI using
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/), so no API token is needed.
+
 ## License
 
 The module is available at [GitHub](https://github.com/dparrini/python-comtrade) under the MIT license.