OSF — Python Implementation

Status

Target Platform

Data analytics, scientific computing, and AI/ML pipelines. The Python bindings are the primary entry point for data exploration and the foundation for ecosystem integrations (Arrow, PyTorch, TensorFlow, LangChain).

The crate sits on top of the Rust osf-core library via PyO3 — see DECISIONS §18. One codebase, two audiences.

Status

In progress. Reader, manager, and writer bindings are functional; the Python wheel builds via maturin with abi3 so a single artefact covers Python 3.9 / 3.10 / 3.11 / 3.12 / 3.13.

Capability	State
`osf.load(path)` — read OSF or OSFZ	✅
`osf.save(mgr, path)` — write OSF5	✅
`DataManager.channel(name)` (DECISIONS §10)	✅
`DataManager.channels` / `channel_by_index`	✅
Channel `samples()` → NumPy array (numeric / GPS)	✅
Channel `samples()` → `list[str]` / `list[bytes]`	✅
Channel `timestamps_ns()` → NumPy `int64`	✅
Channel `segments` for equidistant channels	✅
`WriterBuilder` with chainable setters	✅
Transparent OSFZ (gzip + zlib) on read	✅
Type stubs (`*.pyi`) for IDE support	✅
pandas `DataFrame` convenience	Pending (session 7b)
CI + wheel-build matrix + PyPI publishing	✅ (`pip install osfdata`)

Distribution name vs. import name

PyPI: pip install osfdata
Python: import osf

The split follows the established Python convention (scikit-learn imports as sklearn, PyYAML imports as yaml, beautifulsoup4 imports as bs4). The PyPI name osf is registered to an unrelated 2015 package; osfdata is the Optimeas distribution.

Installation

PyPI (recommended)

pip install osfdata

The PyPI distribution name is osfdata (the short name osf is taken by an unrelated 2015 package); the Python import name is osf for brevity. Wheels are published with abi3 for Python 3.9–3.13 on Linux (x86_64 + aarch64), macOS arm64, and Windows x64; other platforms build from the sdist and need a local Rust toolchain.

Development build (source checkout)

Build the native extension from a source checkout — the right path for local Rust-side hacking or an unsupported platform.

git clone https://github.com/optimeas/osf
cd osf/implementations/python

# Create a virtual environment.
uv venv
.venv/Scripts/Activate.ps1            # Windows PowerShell
# source .venv/bin/activate           # Linux / macOS

# Install build + test tooling.
uv pip install maturin pytest

# Build the native extension and install it editably into the venv.
maturin develop --release

# Run the test suite.
pytest tests/

maturin develop produces an editable install — code changes to python/osf/*.py and python/osf/*.pyi are picked up immediately; Rust changes need another maturin develop.

For a complete walkthrough of the toolchain, build process, and release pipeline, see BUILD.md and RELEASE.md. They explain the PyO3 + maturin stack from local setup through the Trusted-Publishing release to PyPI, intended for developers new to Python's packaging conventions.

Quick start

import osf
import numpy as np

# Reader: convenience path
mgr = osf.load("examples/steam_loco.osf")
print(f"Channels: {len(mgr)}")
print(f"Compressed: {mgr.stats.compressed}")
print(mgr.stats)

# Channel access by name (DECISIONS §10)
ch = mgr.channel("GPS.PosFixMode")
print(f"{ch.name}: {ch.data_type}, {ch.sample_count} samples")

arr = ch.samples()           # NumPy float64 array
ts = ch.timestamps_ns()      # NumPy int64 array

# Equidistant segments are first-class
for seg in ch.segments:
    print(f"  start={seg.start_timestamp_ns} rate={seg.sample_rate_hz} n={seg.sample_count}")

# Writer: convenience path — round-trip an existing manager
osf.save(mgr, "out.osf")

# Writer: builder path — construct from scratch
b = osf.WriterBuilder().creator("my-app").tag("preview")
idx = b.add_channel(
    name="Sensor.Temp",
    data_type="double",
    channel_type="scalar",
    physical_unit="°C",
)
b.add_equidistant_segment(
    idx,
    start_ns=1_700_000_000_000_000_000,
    sample_rate_hz=1.0,
    values=np.array([18.4, 18.5, 18.6], dtype=np.float64),
)
b.write_to_file("synthetic.osf")

Both osf.load() and osf.save() always emit OSF5 (DECISIONS §6), so an OSF4 source file becomes an OSF5 target after a round-trip.

API surface

Object	Provides
`osf.load(path)`	Open and parse an OSF or OSFZ file
`osf.save(mgr, path)`	Write a `DataManager` back as OSF5
`osf.DataManager`	`channel(name)`, `channel_by_index(i)`, `channels`, `stats`, `len`
`osf.Channel`	`index`, `name`, `data_type`, `channel_type`, `samples()`, `timestamps_ns()`, `segments`
`osf.Segment`	`start_timestamp_ns`, `sample_rate_hz`, `sample_count`
`osf.ReaderStats`	`compressed`, `compression_format`, channel/block counts, sizes, elapsed
`osf.WriterBuilder`	Chainable file-info setters plus `add_channel`, `add_*_samples`, `write_to_file` (see stubs)
`osf.OsfError`	Single exception class for all reader / writer errors

NumPy is the data type for every numeric and gpslocation channel. gpslocation arrives as a (N, 3) float64 array with columns [latitude, longitude, altitude]. string channels return list[str]; binary channels return list[bytes].

Performance

osf.load("examples/steam_loco.osf") (123 channels, ~164 k samples) measures ~3 ms on a release-build extension on the dev box — same order of magnitude as the underlying Rust read. Channel access plus NumPy array conversion adds ~0.3 ms per channel. The clone strategy (each mgr.channel(name).samples() call clones the Vec<T> once) is fast enough that an Arc<Channel> optimisation is unnecessary at this point.

Spec revision tracked

OSF specification revision 2026-05-04 (English, Deutsch). All spec-level constraints implemented in osf-core carry through automatically: removed datatypes raise OsfError, deprecated channel-level fields produce a log warning and are dropped, equidistant blocks limit to float / double, and the writer never emits OSFZ.

Dependencies

Package	Purpose
`numpy>=1.20`	Array data type for numeric channels

Build-time only:

Crate	Purpose
`pyo3 = "0.22"`	Python C-API bindings (matched pair with numpy)
`numpy = "0.22"`	Rust → NumPy ndarray conversions
`osf-core` (path)	The pure-Rust core library

pyo3 and numpy must agree on their major version per the rust-numpy README; bumping one requires bumping the other.

Next steps

pandas DataFrame convenience — build a DataFrame from a DataManager (one column per channel, optional time alignment).

CI builds the wheel matrix (Linux / macOS / Windows × Python 3.9–3.13) and the release workflow publishes to PyPI automatically on a v* tag (see RELEASE.md).

Relationship to `python-osf`

osfdata is the modern successor to the existing python-osf package. While python-osf is a pure-Python implementation supporting OSF4 reading only, osfdata provides:

Full OSF4 and OSF5 support (read and write)
Significantly higher performance via a Rust foundation
Complete data type coverage including binary, gpslocation, and unsigned integers
Compatibility with the current spec revision (2026-05-04)
Transparent OSFZ decompression (zlib + gzip)

python-osf will be deprecated in favor of osfdata once feature parity for all production use cases is verified.

License

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

osfdata-1.1.0.tar.gz (176.5 kB view details)

Uploaded Jul 29, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

osfdata-1.1.0-cp39-abi3-win_amd64.whl (458.7 kB view details)

Uploaded Jul 29, 2026 CPython 3.9+Windows x86-64

osfdata-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (624.8 kB view details)

Uploaded Jul 29, 2026 CPython 3.9+manylinux: glibc 2.17+ x86-64

osfdata-1.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (611.6 kB view details)

Uploaded Jul 29, 2026 CPython 3.9+manylinux: glibc 2.17+ ARM64

osfdata-1.1.0-cp39-abi3-macosx_11_0_arm64.whl (551.6 kB view details)

Uploaded Jul 29, 2026 CPython 3.9+macOS 11.0+ ARM64

File details

Details for the file osfdata-1.1.0.tar.gz.

File metadata

Download URL: osfdata-1.1.0.tar.gz
Upload date: Jul 29, 2026
Size: 176.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for osfdata-1.1.0.tar.gz
Algorithm	Hash digest
SHA256	`33ce2ca7a7370ab4e999336ecdb175c15925b44537cd3ab44fbde38e7953932f`
MD5	`b8d33e1f2923081b027bdd008c4b5fd0`
BLAKE2b-256	`44e50662ee531244cdae8dd26f74a1ac5d5ef76fabf2b56722ef7d34fefcdc06`

See more details on using hashes here.

Provenance

The following attestation bundles were made for osfdata-1.1.0.tar.gz:

Publisher: release.yml on optimeas/osf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: osfdata-1.1.0.tar.gz
- Subject digest: 33ce2ca7a7370ab4e999336ecdb175c15925b44537cd3ab44fbde38e7953932f
- Sigstore transparency entry: 2279818876
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: optimeas/osf@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/optimeas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Trigger Event: push

File details

Details for the file osfdata-1.1.0-cp39-abi3-win_amd64.whl.

File metadata

Download URL: osfdata-1.1.0-cp39-abi3-win_amd64.whl
Upload date: Jul 29, 2026
Size: 458.7 kB
Tags: CPython 3.9+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for osfdata-1.1.0-cp39-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`d940ca52e0f3a86f77000822a1097ba109f3e7a79d5a9b735d5f14b4d6a03439`
MD5	`c1e0c73477d5b5aa40ea98a80e11a9bd`
BLAKE2b-256	`a191d2b02750451af460ed622d7492f741ddce101df331c91f75f0523da55802`

See more details on using hashes here.

Provenance

The following attestation bundles were made for osfdata-1.1.0-cp39-abi3-win_amd64.whl:

Publisher: release.yml on optimeas/osf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: osfdata-1.1.0-cp39-abi3-win_amd64.whl
- Subject digest: d940ca52e0f3a86f77000822a1097ba109f3e7a79d5a9b735d5f14b4d6a03439
- Sigstore transparency entry: 2279818966
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: optimeas/osf@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/optimeas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Trigger Event: push

File details

Details for the file osfdata-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: osfdata-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 29, 2026
Size: 624.8 kB
Tags: CPython 3.9+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for osfdata-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`ee38244afbd56bceebcf62a8f0ca4320ba2fb77c3ea78ad393900a9b62e4d87b`
MD5	`96e7ccc8bd1b3e085963b488406ca852`
BLAKE2b-256	`48d6d91468a1643b01c98c57d641e5844e92857698eb6dfcf2b9844375932cde`

See more details on using hashes here.

Provenance

The following attestation bundles were made for osfdata-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on optimeas/osf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: osfdata-1.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: ee38244afbd56bceebcf62a8f0ca4320ba2fb77c3ea78ad393900a9b62e4d87b
- Sigstore transparency entry: 2279818940
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: optimeas/osf@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/optimeas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Trigger Event: push

File details

Details for the file osfdata-1.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: osfdata-1.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Jul 29, 2026
Size: 611.6 kB
Tags: CPython 3.9+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for osfdata-1.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`b2caa6815f50ec1fb617852db4ad734fc94e1c921302a0118a9e488e041ed6b6`
MD5	`001f1fe5ddc74c7c859f3abd2d22bf6a`
BLAKE2b-256	`397f435e7328154b7e45a41eb7f766c806276ea7b8b6eccac9dd170643df7160`

See more details on using hashes here.

Provenance

The following attestation bundles were made for osfdata-1.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on optimeas/osf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: osfdata-1.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: b2caa6815f50ec1fb617852db4ad734fc94e1c921302a0118a9e488e041ed6b6
- Sigstore transparency entry: 2279818956
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: optimeas/osf@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/optimeas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Trigger Event: push

File details

Details for the file osfdata-1.1.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: osfdata-1.1.0-cp39-abi3-macosx_11_0_arm64.whl
Upload date: Jul 29, 2026
Size: 551.6 kB
Tags: CPython 3.9+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for osfdata-1.1.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`f85f727e82bb5388ac461af500436eb41bb9ff23166aff4705dae8aa688779cb`
MD5	`fe0e6f24760c9e4ad2f83b9f16ad73c0`
BLAKE2b-256	`cf7a3a1658223ae3ad499ab7d6caeb939ab7237947346090ea0925b53252fbaf`

See more details on using hashes here.

Provenance

The following attestation bundles were made for osfdata-1.1.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on optimeas/osf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: osfdata-1.1.0-cp39-abi3-macosx_11_0_arm64.whl
- Subject digest: f85f727e82bb5388ac461af500436eb41bb9ff23166aff4705dae8aa688779cb
- Sigstore transparency entry: 2279818912
- Sigstore integration time: Jul 29, 2026
Source repository:
- Permalink: optimeas/osf@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/optimeas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@9d2f5f7ee4f2be9f29011b62bdfa02610cdc2bfa
- Trigger Event: push

Release history Release notifications | RSS feed

This release

1.1.0

Jul 29, 2026

osfdata 1.1.0

OSF — Python Implementation

Target Platform

Status

Distribution name vs. import name

Installation

PyPI (recommended)

Development build (source checkout)

Quick start

API surface

Performance

Spec revision tracked

Dependencies

Next steps

Relationship to python-osf

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed

Relationship to `python-osf`