vosfs
vosfs is an asynchronous fsspec
filesystem for OpenCADC Cavern VOSpace. It registers the vos protocol so
fsspec-aware tools can read, write, inspect, and manage VOSpace files and
directories. Supported tools include pandas, NumPy, Dask, Zarr, and PyArrow.
Supported host platforms are Linux and macOS. Other platforms are untested and unsupported.
Install
uv add "git+https://github.com/opencadc/fsspec-tools@main#subdirectory=libs/vosfs"
Quick start
The synchronous fsspec API uses async network I/O internally. To authenticate,
set VOSFS_CERT_FILE to a combined proxy-certificate and private-key PEM file:
export VOSFS_CERT_FILE=/absolute/path/to/cadcproxy.pem
import fsspec
fs = fsspec.filesystem("vos", endpoint_url="https://staging.canfar.net/arc")
try:
print(fs.ls("/home/<cadc-username>"))
finally:
fs.close()
Capabilities
| fsspec operation | Support |
|---|---|
ls, info, exists, walk, find, glob |
Listing and metadata |
cat_file, cat_ranges |
Response-validated HTTP ranges with whole-object fallback |
get, open("rb") |
Whole-object downloads; open stages to disk by default and uses ranges when block_size or cache_type is supplied |
pipe_file, put, open("wb") |
Whole-object staged writes |
mkdir, makedirs, rm, rmdir |
Namespace creation and deletion |
cp |
Client-side copy; an internal same-authority LinkNode materializes target bytes, while an external or non-VOS LinkNode raises NotImplementedError before mutation |
mv |
Same-service moveNode job when available; otherwise copy, verify, then delete. LinkNode moves raise NotImplementedError before mutation |
| Append/update modes, FUSE | Unsupported |
vosfs targets the OpenCADC VOSpace profile only; it does not claim generic
IVOA VOSpace 2.1 conformance. The full capability contract and fsspec support
matrix are in
docs/design/trd.md.
Documentation
The vosfs documentation contains the user
guide, recipes,
troubleshooting, the public API reference, and
the fss-cli integration guide.
The design contract for fss-cli lives in
libs/fss-cli/docs/design/ and the architecture
decisions in docs/adr/.
See CONTRIBUTING.md to work on the project. Public
documentation source lives under docs/user/;
validate it locally from the repository root with:
uv run --all-packages zensical build --strict --clean
License
Copyright (c) 2026 National Research Council of Canada / Government of Canada.
vosfs is distributed under the terms of the
GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
vosfs 0.11.0 and earlier releases were published under the BSD 3-Clause
License.
1 maintainer
Metadata
1 maintainer
Release files for vosfs 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| vosfs-0.12.0.tar.gz | 73.2 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vosfs-0.12.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 153.4 kB
Release files / vosfs-0.12.0.tar.gz
| Download URL | vosfs-0.12.0.tar.gz |
|---|---|
| Size | 73.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
659152d3d2267f856d68d484a0332fc2c62ba2d1792e839a64a6c730ff353931
|
|
BLAKE2b-256 checksum How to use checksums |
5076b99fe0d6d07109baeb2b8a1e7c79c75d7a343f87ec176991c7c77e107398
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logRelease files / vosfs-0.12.0-py3-none-any.whl
| Download URL | vosfs-0.12.0-py3-none-any.whl |
|---|---|
| Size | 80.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e0557bdf902713daefed2b497192129e858d1d88c466134c4cd37594738033b9
|
|
BLAKE2b-256 checksum How to use checksums |
d83e8ba4e5499845bed5945c82b332a4c43c032328c1b39bced341f25998b5bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logSecurity for vosfs 0.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for vosfs-0.12.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
