Python API
FOSU is in active development; its API may change without compatibility shims.
Parsing returns eager objects and lists, detached from native memory. All records
are read-only native objects with eager Python fields, declared and typed in
_model.py. Attribute reads do not allocate numeric values. Lists remain ordinary
mutable Python lists.
Install and use
Requires CPython 3.10+. Stable-ABI wheels target glibc and musl Linux on x86-64 and AArch64, plus macOS 11+ on Intel and Apple Silicon. One wheel per platform supports every compatible CPython version. Windows x86-64 is supported both natively and through the Linux x86-64 wheel under WSL.
python -m pip install fosu
Installing from a source checkout requires a C++20 compiler. An ordinary
isolated pip install . provisions CMake and Ninja when needed; Unix Makefiles
are also supported when Ninja is unavailable. --no-build-isolation makes the
caller responsible for all build tools.
import fosu
beatmap = fosu.parse_file("map.osu")
for note in beatmap.hit_objects:
if isinstance(note, fosu.Slider):
print(note.time, note.length, note.control_points)
parse_file(path) accepts strings, bytes, and os.PathLike.
parse(data) accepts buffer-protocol objects, including bytes, bytearray,
memoryview, and arrays. Non-bytes buffers are copied to an immutable snapshot;
encode text explicitly.
File failures raise OSError; other parse failures, including invalid
options and inputs too large to allocate, raise ValueError. Native parsing
releases the GIL; Python value construction holds it. Malformed records are
skipped and counted in beatmap.stats.malformed_lines; success does not
certify playability.
parse and parse_file allocate native memory for each call. To parse many
maps, reuse a fosu.Parser, which keeps that memory until the parser is
garbage-collected:
parser = fosu.Parser()
maps = [parser.parse_file(path) for path in paths]
Its parse and parse_file methods take the same arguments as the module
functions. Results are detached, so later calls never change earlier results.
One parser handles one call at a time; a concurrent call raises
RuntimeError. Use one parser per thread.
Performance
FOSU 0.6.0 (cf9350e), measured on 2026-10-04 using CPython 3.12.14 on an
Intel Core i7-8700 under Linux/WSL2. All rows use the same 1,004 mutually accepted
all-mode maps. Times include eager result construction and release; lower is
better. Warm-file measurements include opening and reading page-cached files.
| Python interface | Resident bytes (µs/map) | Warm file (µs/map) |
|---|---|---|
FOSU AVX2, reused fosu.Parser |
164.3 | 174.1 |
FOSU scalar, reused fosu.Parser |
223.7 | 233.0 |
FOSU AVX2, fosu.parse per call |
269.5 | 279.9 |
FOSU scalar, fosu.parse per call |
328.3 | 340.0 |
| OsuPyParser 1.0.7 | Unsupported | 4,477.7 |
A fosu.Parser keeps its memory between calls. The module functions create a
new parser per call, which also reserves that memory and takes a page fault on
the first write to each page; keep a Parser when parsing many maps.
Figures are medians of complete passes, not fastest individual parses. Six passes per API were collected; passes more than 5% above their API's unfiltered median are excluded as presumed interference; one was excluded from this table. The parsers expose different models: OsuPyParser also performs derived-statistic work. See the comparison and measured variation for result contracts, or the feature-cost tables for slider geometry, gameplay, mods, and ARM measurements.
Section selection
listing = fosu.parse_file(
"map.osu",
sections=fosu.Sections.METADATA | fosu.Sections.DIFFICULTY,
)
Both entry points accept keyword-only sections, defaulting to Sections.ALL.
Members are GENERAL, EDITOR, METADATA, DIFFICULTY, EVENTS,
TIMING_POINTS, COLOURS, and HIT_OBJECTS. Combine them with |.
Skipped sections retain defaults and empty lists; Sections(0) selects none.
Unsupported mask bits are rejected.
Include GENERAL for mode-dependent difficulty rules (such as mania CircleSize)
and EVENTS for break-dependent combo rules. Only selected sections contribute
malformed-line counts.
Results and important distinctions
The model classes in _model.py define the fields and convenience methods. Shared fields use C++ names. Important Python-specific behavior:
hit_objectscontainsCircle,Slider,Spinner, orHoldNote, in stable timestamp order. Narrow the union withisinstance.- Times are milliseconds. Slider endpoints are
0by default. Passcalculate_slider_end_times=Truetoparseorparse_fileto calculate them using curve distance, timing and repeats. Do not use slider endpoints unless calculation was requested. Accessing the field never computes or caches anything. Other object types still have numeric endpoints. Omitted sections use their default settings. Hit samples and slider edge fields remain text. - Slider
control_pointsincludes the head position, unlike the native point range.curve_segmentspreserves modern segment boundaries and explicit B-spline degrees.slides=2means forward and back. tag_listandbookmark_listare parsed conveniences alongside thetagsandbookmarkstext fields.- IDs and preview time map the
-1sentinel toNone. - Strings decode with UTF-8
surrogateescape, preserving undecodable bytes. - Inherited timing-point NaN beat lengths are preserved; consumers must not treat them as ordinary slider velocities.
Records support equality, repr, deepcopy, and pickle. They are not dataclasses:
dataclasses.asdict and dataclasses.replace do not apply. Public record classes
cannot be subclassed, and attributes cannot be assigned or deleted. Constructors
accept positional or keyword arguments and retain the supplied values without
runtime type validation. Parsed numeric fields are always eagerly converted to
their documented Python types.
List contents can be changed without affecting the input or another parse result. Such changes do not recompute derived data. All records participate in cyclic garbage collection, including cycles consumers create through lists or values passed to constructors.
Pass calculate_slider_paths=True to retain each slider's path (otherwise
None). fosu.slider_position_at(slider.path, progress) is a pure query over
that polyline, with progress clamped to [0, 1]. Returned PathPoint coordinates
are relative to the head; add the slider's x/y for playfield coordinates.
Paths alone do not calculate end times. Requesting both reuses their distance.
Native code exposes the same query and Beatmap.slider_paths, indexed by slider.
calculate_slider_events=True additionally populates slider.events with
HEAD, TICK, REPEAT, LEGACY_LAST_TICK, and TAIL records in official
generator order, grouped by slider-span traversal. This is not necessarily
timestamp order: a legacy last tick may be timed before a late tick or the
repeat beginning its final span. The legacy event is the effective historical
tail judgement, not an additional score or combo event; the real TAIL and
slider end_time remain unchanged. This option includes path and end-time
calculation. Each record has time, span index/start time, path progress, and a
position relative to the head. Native code exposes Beatmap.slider_events,
indexed by slider. Without the option, events are empty. These are path events
using the decoded slider's timing, not a converted ruleset's nested hitobjects:
no samples or catch conversion.
Expansion beyond 1,048,576 events per map fails the parse with ValueError
rather than silently dropping events.
apply_stacking=True applies unmodded osu!standard stacking after parsing,
including the pre-v6 algorithm. Hit-object x/y and absolute slider control points
are adjusted before returning. obj.raw_position() subtracts the stacking offset
from the current x/y, or returns x/y when stacking is absent. It can have small
floating-point rounding differences. Coordinates are floats in both interfaces,
including when stacking is disabled. Each object also retains stack_height and stack_offset
in its Stacking value for inspection; do not add the offset again.
Relative path/event positions remain unchanged: add them to the adjusted head.
It includes path and end-time calculation, but not events. Native results use
Beatmap.stacking, indexed by hit object. Other modes are unchanged; Python
stacking is None when not calculated. Include GENERAL, DIFFICULTY,
TIMING_POINTS and HIT_OBJECTS when selecting sections for meaningful results.
mods= accepts combined Mods values. EZ and HR adjust difficulty settings for
osu!standard and osu!taiko; HR also reflects standard hit objects and slider
control points vertically. EZ/HR require GENERAL and DIFFICULTY in sections.
They are not yet supported for osu!catch or osu!mania because those modes require
converted fruit offsets or resolved hit windows; support is planned. DT,
NIGHTCORE, and HT support every mode and divide gameplay timeline values by
1.5, 1.5, and 0.75 respectively. This includes hit objects, calculated slider
events, timing-point offsets and uninherited beat lengths, and breaks. General
and Editor timestamp metadata remains in source-map time.
See compatibility for supported behavior and limitations; there is no ruleset conversion.
CPU selection
fosu.backend reports "avx2", "neon", or "scalar".
Set FOSU_BACKEND=auto|scalar|avx2|neon before importing to select an engine.
Unsupported explicit requests raise ImportError; selection stays fixed for
the loaded extension. See
development checks.
Metadata
Release files for fosu 0.6.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 | Actions |
|---|---|---|---|---|
| fosu-0.6.0.tar.gz | 248.4 kB | With provenance | Details for fosu-0.6.0.tar.gz |
Built distributions (wheels)
Total release size: 2.2 MB
Release files / fosu-0.6.0.tar.gz
| Download URL | fosu-0.6.0.tar.gz |
|---|---|
| Size | 248.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
30ca910aa7a974d7e77b00f738b930fad01575d36219d66b7e9f5e1e2b867236
|
|
BLAKE2b-256 checksum How to use checksums |
b0b9ab1c93b4451a398b990873b5c6b7e5fa9a97eaac20049d6ebb404c4bec1e
|
| 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 4, 2026.
Transparency logRelease files / fosu-0.6.0-cp310-abi3-win_amd64.whl
| Download URL | fosu-0.6.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 340.5 kB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
af39f862d29c312f32bc6eb983a5567cba81b934218708e7b3618e4adeb74d74
|
|
BLAKE2b-256 checksum How to use checksums |
ec2962555aca9eceb06e219f629d636cc8e46b6f7df915256f565381054661bf
|
| 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 4, 2026.
Transparency logRelease files / fosu-0.6.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | fosu-0.6.0-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 328.2 kB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
0dd139b96f11d8000f7a85bfd7c0685a22acb334024b9e5ffee6b97586b16d9e
|
|
BLAKE2b-256 checksum How to use checksums |
4ed127e70c95abec5c2654829abb79a2951c5852a13841e4ebd082ae66e1e86b
|
| 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 4, 2026.
Transparency logRelease files / fosu-0.6.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | fosu-0.6.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 349.2 kB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
d4ecea15b35a7e526c010b8fcabd67fa9fe887f87e8f5471724de837f99ab9c8
|
|
BLAKE2b-256 checksum How to use checksums |
59b7bc8ed5f6004fbe3868889d9f931253942384761591d5eb1f8568bc7cb048
|
| 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 4, 2026.
Transparency logRelease files / fosu-0.6.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl
| Download URL | fosu-0.6.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 329.6 kB |
| Tags | CPython 3.10 Linux glibc 2.26+ x86-64 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
76b048443132a3128b9a7b74f44ceca96ee409dc2b5f8c7c332a72ea89d1eaab
|
|
BLAKE2b-256 checksum How to use checksums |
1805891322fd78e759f51a69e825365c7dc09d645d244b919f42a8084a4f5d7f
|
| 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 4, 2026.
Transparency logRelease files / fosu-0.6.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
| Download URL | fosu-0.6.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 349.5 kB |
| Tags | CPython 3.10 Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
63169d45ab7fbe19fe1caa34ef159c7f80da08f34f4f81d3ae0ca4fde3638896
|
|
BLAKE2b-256 checksum How to use checksums |
ad79b8190efa805c97223e9fa3cf0e519192082db23292976848ff3e530ca4db
|
| 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 4, 2026.
Transparency logRelease files / fosu-0.6.0-cp310-abi3-macosx_11_0_x86_64.whl
| Download URL | fosu-0.6.0-cp310-abi3-macosx_11_0_x86_64.whl |
|---|---|
| Size | 156.1 kB |
| Tags | CPython 3.10 abi3 macOS 11.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
42b0433ae0e55e7b895f0d18e09fa0ce246b67e73718ec97a1c32c7efcccfe14
|
|
BLAKE2b-256 checksum How to use checksums |
98eb2da6ba343d289648e69d02a6c7a87191c903a5f90f45a7cc88d11257fefd
|
| 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 4, 2026.
Transparency logRelease files / fosu-0.6.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | fosu-0.6.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 146.2 kB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e26a25603480b630a78a72ee1c47898e641c77b4d521d6ad6a4016f165555bf6
|
|
BLAKE2b-256 checksum How to use checksums |
4a5af11f61aa8713cb52a9f3c0d51db5f2a2d74c1577c08af97bc061bf8da6a8
|
| 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 4, 2026.
Transparency logSecurity for fosu 0.6.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 8 files in this release have been uploaded with provenance metadata.
Attestation for fosu-0.6.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 4, 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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.