pypvfs

pypvfs is the PyPI package name for Pinnacle Technology PVFS — a virtual filesystem format used for physiological recordings. It is not the historical HPC “Parallel Virtual File System” or other unrelated uses of the “PVFS” acronym.

Install from PyPI, then import the pvfs_tools package:

pip install pypvfs

from pvfs_tools.Core.pvfs_data_file import PvfsDataFile

pvfs_tools provides:

• pvfs_tools.Core — low-level PVFS access via ctypes and bundled native libraries (pvfs.dll / pvfs_wrapper.dll on Windows, libpvfs.so / libpvfs_wrapper.so on Linux).
• pvfs_tools.Database — higher-level helpers for experiment databases (SQLAlchemy-backed).

Runtime dependencies are listed in pyproject.toml (numpy, pydantic, SQLAlchemy, Pillow).

Supported platforms (PyPI wheels)

Published wheels target 64-bit x86 only:

Wheels are tagged py3-none-…: one wheel per OS covers Python 3.10+ on that OS (the native code does not link against libpython).

There is no published wheel today for macOS, Linux ARM, musl (Alpine), or 32-bit Windows. On those environments, install from the sdist or a git checkout so the native libraries are built locally (see below).

Optional extras

Examples:

pip install "pypvfs[video]"
pip install "pypvfs[examples]"
pip install -e ".[test]"   # from a clone: editable install + tests

Native library and building from source

From a wheel: native libraries are already built and installed under pvfs_tools.Core. No compiler is required.

From source (sdist or git clone): the build uses scikit-build-core and CMake to compile pvfs.cpp and pvfs_wrapper.cpp. You need:

• CMake ≥ 3.15 (often pulled into the build environment automatically)
• A C++17 toolchain (g++ / clang++ on Linux, MSVC on Windows)

pip install ".[test]"
pytest

Note on pip install -e . — scikit-build-core's editable mode loads Python files from src/pvfs_tools/, but CMake-built .dll / .so files live in the build/ directory. pvfs_binding.py looks for the native library next to itself, so an editable install will fail with “native library could not be loaded”. Use a regular install (or rebuild between edits) when you need the native code.

Examples (bundled in the wheel)

Runnable scripts are installed under pvfs_tools.examples. After pip install pypvfs you can use the pypvfs-examples command on your PATH, or run modules with python -m:

pypvfs-examples --list
python -m pvfs_tools.examples.pvfs_create_cli --help

The same .py files also live under examples/ in the repository for browsing in GitHub.

Documentation and source

• PyPI shows this README; the BSD 3-Clause license text is included in package metadata (see the LICENSE file in the installed .dist-info / sdist).
• Library usage (detailed): docs/USAGE.md — workflows, APIs, and patterns; not in the wheel; browse on GitHub or in a clone. Written to match tests/test_pvfs.py.
• Source and issues: github.com/Pinnacle-Technology-Inc/pypvfs (also set as Repository / Documentation in pyproject.toml for pip show / PyPI links).
• Releases (maintainers): see docs/RELEASE.md in the repo — not installed into site-packages.

Publishing (maintainers)

Routine releases use GitHub Actions and PyPI trusted publishing (OIDC), not ad-hoc twine from a laptop.

1. Bump version in pyproject.toml and commit.
2. Create and push a tag whose name starts with v (e.g. git tag v1.0.6 && git push origin v1.0.6).
3. Confirm the Publish to PyPI workflow ran for that tag (or run it manually from the Actions tab).

That workflow uses cibuildwheel on Linux and Windows to build the platform wheels and uploads wheels plus the sdist. Details: docs/RELEASE.md.