Merge pull request #28 from briling/python-api

Improve the api for integration with python

* possibility to print to a variable
* possibility to pass a molecule to main
* possibility to read from stdin
* build manylinux wheels

Author: briling

.github/CHANGELOG.md

@@ -5,25 +5,27 @@
 * Add partial extended xyz support (https://github.com/briling/v/pull/18)
 * Add `j` hotkey to jump to a frame inside and CLI option `frame:%d` to start with a specific frame (https://github.com/briling/v/pull/5)
 * Add `bmax` CLI argument for max. bond length (920202b)
-* Python integration (#22, see https://github.com/aligfellow/xyzrender)
+* Add `com` and `exitcom` CLI argument for `gui:0` and on-exit command sequences, respectively
+* Python integration (#28, see https://github.com/aligfellow/xyzrender)
 
 ### Improvements
 * New colors by @iribirii (https://github.com/briling/v/pull/2, https://github.com/briling/v/pull/13, https://github.com/briling/v/pull/15)
 * Remove case sensitivity of xyz file inputs (https://github.com/briling/v/pull/9)
 * Add CLI option to disable centering of molecules (https://github.com/briling/v/pull/14)
 * Disable default rotation wrt inertia axis for z-matrix input and add a CLI option to force it (https://github.com/briling/v/pull/14)
+* Read molecules from the standard input
 
 ### Fixes
 * Exit correctly when window closed (https://github.com/briling/v/pull/10)
 * Fix chiral z-matrix input (https://github.com/briling/v/pull/14)
 * Fix NaNs when compute dihedrals (https://github.com/briling/v/pull/14)
 
 ### Still have to be done:
-* documentation for the python bindings
 * finish colors (#15)
 * ? extended xyz (#16, #17)
 * ? fix `readmore` bug (#7)
 * ? high-symmetry determination bugs (#21)
 * ? how to build on mac
 
 **Full Changelog**: https://github.com/briling/v/compare/v2.0...v3.0rc3
+

.github/workflows/lint.yml

@@ -0,0 +1,26 @@
+name: Lint Python with Ruff
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  lint:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install Ruff
+        run: pip install ruff
+      - name: Run Ruff
+        run: ruff check vmol/ examples/
+        working-directory: ./python

.github/workflows/manual-build.yml

@@ -0,0 +1,8 @@
+name: build
+
+on:
+  workflow_dispatch:
+
+jobs:
+  wheels:
+    uses: ./.github/workflows/wheels.yml

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 name: release
 
-on: # triggered by push tagged commits to main
+on: # triggered by push tagged commits
   push:
     tags:
       - 'v*'
@@ -12,44 +12,7 @@ permissions:
 jobs:
 
   build_wheels:
-    name: Build wheels on ${{ matrix.os }} for python ${{ matrix.py }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest]
-        py: ['3.11', '3.12', '3.13']
-
-    steps:
-
-      - name: install X11 dependencies
-        if: ${{ runner.os == 'Linux' }}
-        run: |
-          sudo apt-get update
-          sudo apt install -y libx11-dev libxpm-dev x11proto-dev
-
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-python@v6
-        with:
-          python-version: ${{ matrix.py }}
-
-      - name: install python
-        run: pip install setuptools
-
-      - name: build wheels
-        working-directory: ./python
-        run: python setup.py bdist_wheel
-        ## we don't need the wheel name actually, the artifact name just has to be unique
-        #run: python setup.py bdist_wheel | grep "creating 'dist" | sed -n "s/^creating 'dist\//WHEEL_NAME='/;s/\s.*$//p" >> "$GITHUB_ENV"
-
-      - uses: actions/upload-artifact@v6
-        with:
-          path: ./python/dist/*.whl
-          name: ${{ matrix.os }}.${{ matrix.py }}
-
+    uses: ./.github/workflows/wheels.yml
 
   build_exe:
     name: Build the executable file and shared library for ${{ matrix.os }}
@@ -79,6 +42,7 @@ jobs:
             ./v
             ./v.so
           name: ${{ matrix.os }}.exe
+          if-no-files-found: error
 
 
   release:
@@ -89,10 +53,6 @@ jobs:
       contents: write
 
     steps:
-      - name: Check out the repo
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - uses: actions/download-artifact@v4
         with:

.github/workflows/wheels.yml

@@ -0,0 +1,72 @@
+name: Build wheels
+
+on:
+  workflow_call:
+    inputs:
+      package-dir:
+        type: string
+        required: false
+        default: ./python
+      output-dir:
+        type: string
+        required: false
+        default: wheelhouse
+      cibw-build:
+        type: string
+        required: false
+        default: ""
+      cibw-skip:
+        type: string
+        required: false
+        default: "*-musllinux_*"
+      upload-artifact:
+        type: boolean
+        required: false
+        default: true
+
+jobs:
+  build_wheels:
+    name: Build wheels
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Export git metadata
+        shell: bash
+        run: |
+          set -euo pipefail
+          echo "VMOL_GIT_HASH=${{ github.sha }}" >> "$GITHUB_ENV"
+          echo "VMOL_GIT_BRANCH=${{ github.ref_name }}" >> "$GITHUB_ENV"
+          echo "VMOL_GIT_DESCRIBE=$(git describe --tags --dirty 2>/dev/null || true)" >> "$GITHUB_ENV"
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install cibuildwheel
+        run: python -m pip install cibuildwheel==3.4.0
+
+      - name: Build wheels
+        run: python -m cibuildwheel "${{ inputs.package-dir }}" --output-dir "${{ inputs.output-dir }}"
+        env:
+          CIBW_BUILD: ${{ inputs.cibw-build }}
+          CIBW_SKIP: ${{ inputs.cibw-skip }}
+          CIBW_BEFORE_ALL_LINUX: |
+            if [ -f /etc/alpine-release ]; then # musllinux (Alpine)
+              apk add --no-cache libx11-dev libxpm-dev pkgconf
+            else # manylinux (AlmaLinux)
+              /usr/bin/dnf -y install libX11-devel libXpm-devel pkgconf-pkg-config
+            fi
+
+      - name: Upload wheels
+        if: ${{ inputs.upload-artifact }}
+        uses: actions/upload-artifact@v6
+        with:
+          name: vmol-wheels-${{ runner.os }}-${{ github.ref_name }}-${{ github.run_number }}
+          path: ${{ inputs.output-dir }}/*.whl
+          if-no-files-found: error

.gitignore

@@ -9,3 +9,4 @@
 vmol.egg-info/
 python/build
 python/dist
+python/src

README.md

@@ -18,6 +18,14 @@ A simple X11 molecular viewer.
 - [`.xyz`](https://en.wikipedia.org/wiki/XYZ_file_format) files
 - [extended `.xyz`](https://github.com/libAtoms/extxyz) files (currently the extra columns are ignored)
 
+## Python package (wrapper / API) available
+
+See python package page
+[here.](python/README.md)
+
+Provides wrapper scripts with a simple installation and
+allows to open unsupported file formats with `cclib`.
+
 ## Download [↑](#download)
 ```
 wget https://github.com/briling/v/releases/download/v2.0/v.2.0 -O v
@@ -40,6 +48,8 @@ make v
 ```
 ./v file [file2 ... fileN] [options]
 ```
+A filename `-` stands for the standard input.
+
 Show the reference:
 ```
 ./v
@@ -66,8 +76,10 @@ Show the reference:
 | `shell:b%lf,%lf`                            | spheres radii in a.u.                                    |
 | `shell:%lf,%lf`                             | spheres radii in Å                                       |
 | `center:%d`                                 | origin is geometric center (`1`, default) / center of mass (`2`) / as is (`0`) |
-| `inertia:1`                                 | rotate molecules wrt axis of inertia                     |
+| `inertia:%d`                                | if rotate molecules wrt axis of inertia (`1`) or not (`0`, default) |
 | `gui:%d`                                    | normal (default `1`) / headless (`0`) mode               |
+| `com:%s`                                    | command sequence for `gui:0`                             |
+| `exitcom:%s`                                | command sequence to run on exit (same as for `gui:0`)    |
 
 </details>
 
@@ -116,12 +128,20 @@ One can also use the mouse to rotate the molecule and zoom in/out.
 
 <details open><summary><strong>Headless mode (in development)</strong></summary>
 
-If run in the headless mode with `gui:0`, the symbols from stdio are processed 
+If run in the headless mode with `gui:0`, the symbols from the standard input are processed 
 as if the corresponding keys were pressed in the normal mode.
-Right now, only `p`, `x`, `z`, and `.` are available. For example,
+Right now, only `p`, `x`, `z`, and `.` are available.
+Command-line option `com:%s` overrides the standard input.
+These examples are equivalent:
 ```
 > echo . | ./v mol/mol0001.xyz gui:0
 D*h
+
+> ./v mol/mol0001.xyz gui:0 com:.
+D*h
+
+> cat mol/mol0001.xyz | ./v - gui:0 com:.
+D*h
 ```
 
 </details>

makefile

@@ -49,7 +49,7 @@ INCL=$(SRCDIRS:%=-I./%)
 allsrc=$(shell find $(SRCDIR) -type f -name '*.c')
 allobj=$(allsrc:$(SRCDIR)/%.c=$(OBJDIR)/%.o)
 allpic=$(allsrc:$(SRCDIR)/%.c=$(PICDIR)/%.o)
-allmmd=$(allsrc:$(SRCDIR)/%.c=$(OBJDIR)/%.d)
+allmmd=$(shell find $(OBJDIR) -type f -name '*.d')
 
 OBJDIRS=$(SRCDIRS:$(SRCDIR)%=$(OBJDIR)%)
 PICDIRS=$(SRCDIRS:$(SRCDIR)%=$(PICDIR)%)