oxidmol 0.1.1__tar.gz

oxidmol-0.1.1/.claude/commands/check.md

@@ -0,0 +1,24 @@
+---
+description: Run every check that CI runs (Rust and Python), without the GPU and app launch steps
+---
+
+Run these from the repository root in the activated virtual environment and report the result of each one.
+Do not stop at the first failure: run all of them, then summarize what failed and why.
+
+```bash
+source .venv/bin/activate
+cargo fmt -- --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+uv run --no-sync maturin develop
+ruff format --check python/
+ruff check python/
+mypy python/
+QT_QPA_PLATFORM=offscreen pytest -m "not gpu"
+```
+
+Notes:
+- `cargo test` needs the activated `.venv`, otherwise it fails to link with `-lpython3.9`.
+- GPU tests print `skipping: no GPU adapter available` and still pass on machines without a GPU.
+  Say so in the summary if you see it.
+- Fix only what the user asked for. If a check fails for an unrelated reason, report it instead of fixing it.

oxidmol-0.1.1/.github/workflows/CI.yml

@@ -0,0 +1,92 @@
+# Tests and lint. Wheels and the PyPI upload live in publish.yml, which calls this workflow first.
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    paths-ignore:
+      - '**.md'
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+# a new push cancels the previous run on the same branch/PR (never cancel runs for tags)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+env:
+  CARGO_INCREMENTAL: 0
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      matrix:
+        python-version: ['3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install system dependencies
+        run: sudo apt-get install -y libegl1 libgles2 libdbus-1-3
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --group dev --no-install-project
+      - name: Run Rust tests
+        run: cargo test
+      - name: Build Python extension
+        run: uv run --no-sync maturin develop
+      - name: Run Python tests
+        run: uv run --no-sync pytest -m "not gpu"
+        env:
+          QT_QPA_PLATFORM: offscreen
+
+  lint:
+    name: Lint and Format Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install Python dependencies
+        run: uv sync --group dev --no-install-project
+      - name: Check Rust formatting
+        run: cargo fmt -- --check
+      - name: Run Clippy
+        run: cargo clippy --all-targets -- -D warnings
+      - name: Check Python formatting
+        run: uv run --no-sync ruff format --check python/
+      - name: Run Python linting
+        run: uv run --no-sync ruff check python/
+      - name: Run mypy
+        run: uv run --no-sync mypy python/

oxidmol-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,178 @@
+# Builds the wheels and the sdist and uploads them to PyPI.
+# Runs for version tags (created by release-plz) and manually; a manual run builds everything but never uploads.
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# never cancel a release that is running
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  CARGO_INCREMENTAL: 0
+  CARGO_TERM_COLOR: always
+
+jobs:
+  checks:
+    name: Checks
+    uses: ./.github/workflows/CI.yml
+
+  linux:
+    name: Wheels (manylinux ${{ matrix.platform.target }})
+    runs-on: ${{ matrix.platform.runner }}
+    timeout-minutes: 30
+    needs: [checks]
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: aarch64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.platform.target }}
+          path: dist
+
+  musllinux:
+    runs-on: ${{ matrix.platform.runner }}
+    timeout-minutes: 30
+    needs: [checks]
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: aarch64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          manylinux: musllinux_1_2
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-musllinux-${{ matrix.platform.target }}
+          path: dist
+
+  windows:
+    runs-on: ${{ matrix.platform.runner }}
+    timeout-minutes: 30
+    needs: [checks]
+    strategy:
+      matrix:
+        platform:
+          - runner: windows-latest
+            target: x64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          architecture: ${{ matrix.platform.target }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows-${{ matrix.platform.target }}
+          path: dist
+
+  macos:
+    runs-on: ${{ matrix.platform.runner }}
+    timeout-minutes: 30
+    needs: [checks]
+    strategy:
+      matrix:
+        platform:
+          - runner: macos-14
+            target: aarch64
+          - runner: macos-14
+            target: x86_64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.platform.target }}
+          path: dist
+
+  sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: [checks]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: [linux, musllinux, windows, macos, sdist]
+    if: startsWith(github.ref, 'refs/tags/')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/oxidmol
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

oxidmol-0.1.1/.github/workflows/release-plz.yml

@@ -0,0 +1,47 @@
+name: Release
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  release-pr:
+    name: Create release PR
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: release-plz-pr
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: release-plz/action@v0.5
+        with:
+          command: release-pr
+        env:
+          GITHUB_TOKEN: ${{ secrets.RELEASE_PLZ_TOKEN || secrets.GITHUB_TOKEN }}
+
+  release:
+    name: Create tag and GitHub release
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: release-plz-release
+      cancel-in-progress: false
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: release-plz/action@v0.5
+        with:
+          command: release
+        env:
+          GITHUB_TOKEN: ${{ secrets.RELEASE_PLZ_TOKEN || secrets.GITHUB_TOKEN }}

oxidmol-0.1.1/.gitignore

@@ -0,0 +1,47 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug
+target
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# Generated by cargo mutants
+# Contains mutation testing data
+**/mutants.out*/
+
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+*.local
+
+**/.env*
+
+# intellij
+**/.idea
+
+# python
+**/venv
+**/__pycache__
+**/*.pyc
+**/*.egg-info
+build/
+.venv/
+
+# pyright
+pyrightconfig*.json
+
+# mac
+.DS_Store
+target/
+
+# unix like
+*.so
+
+# vscode
+.vscode/
+node_modules/

oxidmol-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

oxidmol-0.1.1/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+### Bug Fixes
+
+- Setting correct workflow.yaml ([60bbd73](https://github.com/ye11owSub/oxidmol/commit/60bbd735146e003954b0112be1f46a85373cfdbd))

oxidmol-0.1.1/CLAUDE.md

@@ -0,0 +1,75 @@
+# OxidMol: working notes for Claude
+
+A PyMOL-inspired molecule viewer. The renderer is written in Rust on wgpu and exposed to Python through PyO3 as the module `oxidmol.lsd`; the UI is PySide6.
+
+## Commands
+
+```bash
+source .venv/bin/activate                  # REQUIRED before cargo test, see "Pitfalls"
+uv sync --group dev --no-install-project   # dependencies without building Rust (same as CI)
+uv run --no-sync maturin develop           # build the extension into .venv (after every Rust change)
+
+cargo fmt -- --check
+cargo clippy --all-targets -- -D warnings  # warnings are errors in CI
+cargo test                                 # Rust tests, including the GPU tests
+
+ruff format --check python/ && ruff check python/ && mypy python/
+QT_QPA_PLATFORM=offscreen pytest -m "not gpu"   # what CI runs
+pytest -m gpu                                    # needs a display and a GPU
+
+oxidmol                                    # run the app (RUST_LOG=warn hides the naga/wgpu debug noise)
+```
+
+`/check` runs all of the above except the GPU and app launch steps. Run it before finishing a task: CI fails on any of them.
+
+## Layout
+
+```
+src/
+  lib.rs              PyO3 module `lsd`, logging setup
+  core/               Molecule, Chain/Residue/Atom, FlatAtom, sphere mesh; PDB/mmCIF loading (pdbtbx)
+  renderer/
+    state.rs          State = GpuContext (window + surface) + Scene
+    gpu_context.rs    instance/surface/adapter/device; everything returns Result<_, WgpuError>
+    scene.rs          Scene: camera, pipeline, depth, objects; render() into any TextureView
+    pipeline.rs       PipelineBuilder (takes the shader as a WGSL string)
+    scene_pipeline.rs builds the main pipeline; the shader is embedded with include_str!
+    test_support.rs   (tests only) windowless device, pixel readback, validation error scope
+  python/             PyO3 wrappers: WgpuRenderer, PyMolecule
+  utils/              errors, qt_window.rs (QWidget.winId() -> raw-window-handle), logging
+  shaders/shader.wgsl
+python/oxidmol/
+  app.py, settings.py
+  ui/                 main_window, scene (WgpuWidget), object_panel, command_bar, menu/, theme.py
+  dsl/                command grammar (lark) and transformer
+  utils/              loading, cache, fetch
+  lsd/__init__.pyi    type stubs for the Rust module
+tests/data/           PDB/CIF files used by tests
+```
+
+## Pitfalls
+
+- **`cargo test` does not link without the `.venv` activated** (`-lpython3.9`, it picks up Xcode's Python). Always `source .venv/bin/activate` first.
+- **Rebuild with `maturin develop` after every Rust change**, otherwise the Python tests and the app use the old extension.
+- **wgpu 30 requires a display handle on the instance**, even on Metal (`MissingDisplayHandle` otherwise). It is passed through `QtDisplayHandle`.
+- **Use the `directx` projection, not `vulkan`.** The wgpu NDC is Z in [0, 1] with Y up; `vulkan` flips the image. There is no OpenGL-to-wgpu matrix any more.
+- **GPU tests are skipped silently when there is no adapter, and a skip is a pass.** `OXIDMOL_REQUIRE_GPU=1` turns the skip into a failure. CI runners most likely have no GPU.
+- **The windowless GPU tests do not cover the window.** `GpuContext` and the surface are only checked by launching the app and by the `gpu`-marked widget test.
+- **Renderer errors are `RuntimeError`, not panics.** Catch `Exception` in Python, not `BaseException`.
+- **Linux: only X11/XWayland.** Native Wayland is not supported yet. Manual testing so far was done on macOS only; Linux and Windows are not tested by hand.
+- **PySide6 is capped at `<6.12`** because 6.12 has no wheels for macOS 13. Do not upgrade it without checking that the platform support has changed.
+- **`approx` stays on 0.5** (0.6 is still a release candidate). `pollster` was replaced with `tokio` (feature `rt`).
+- **Every molecule load adds an object instead of replacing the previous one.** Known, not fixed.
+- **The extension uses the stable ABI (`pyo3/abi3-py312`)**: one wheel per platform works for every Python >= 3.12. After switching Python versions or build modes, delete stale `python/oxidmol/lsd.*.so` files: an old `lsd.cpython-*.so` is imported before `lsd.abi3.so`.
+- **Releases**: release-plz runs in git-only mode (versions come from git tags, nothing goes to crates.io). A new `v*` tag starts `publish.yml`: it re-runs `CI.yml` through `workflow_call`, builds the wheels and uploads them to PyPI.
+- Workflows: `CI.yml` (tests and lint on push and PR, also called by `publish.yml`), `publish.yml` (wheels, sdist and PyPI upload for tags; a manual run builds but never uploads), `release-plz.yml` (version PRs, tags). They were generated by `maturin generate-ci` once and are now edited by hand, do not regenerate them.
+- The README and the module description in `lib.rs` say "PyQt6" although the project uses PySide6 (not fixed).
+
+## Conventions
+
+- Rust 2021, `cargo fmt`, no clippy warnings. Use a targeted `#[allow(dead_code)]` for intentionally unused code (the idiom already exists in the project).
+- `unsafe` needs a `SAFETY:` comment that states the guarantee.
+- Python: ruff (line length 120, rule set in `pyproject.toml`), strict-like mypy (`disallow_untyped_defs`); type the Qt event arguments (`QShowEvent` etc.).
+- UI: styles live only in `ui/theme.py` (palette plus one `STYLESHEET`). Widgets get an `objectName` and no inline QSS. The exception is the per-object dot color in `object_panel.py`, which is dynamic. Get the monospace font from `theme.mono_font()`, never by family name.
+- Tests: Rust tests sit next to the code (`#[cfg(test)]`); Python tests are in `python/oxidmol/tests` with the `ui` and `gpu` markers declared in `pyproject.toml`. Check a new test against a deliberate breakage: break the code temporarily and make sure the test fails.
+- Commits: `release-plz` and `git-cliff` build the changelog from conventional commits only (`feat:`, `fix:`, `refactor:`, `perf:` ...); other commits are filtered out (`filter_unconventional = true`). Do not commit unless asked.