Skip to main content

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. A map the target client would not load raises fosu.MapLoadError, a ValueError whose line is the 1-based line responsible. Native parsing releases the GIL; Python value construction holds it. Other malformed records are skipped and counted in beatmap.stats.malformed_lines; success does not certify playability.

Every parse function takes keyword-only client: "stable", the default, or "lazer", whose behaviour to follow where the two read a map differently. For example, stable refuses a map with a hit object it cannot read, which lazer skips, and reads the version from the first line only. See the target client rules.

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 commit 9620bc6 (after 0.7.0), measured on 2026-10-06 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 165.7 176.2
FOSU scalar, reused fosu.Parser 226.0 240.3
FOSU AVX2, fosu.parse per call 274.9 280.1
FOSU scalar, fosu.parse per call 332.7 354.0
OsuPyParser 1.0.7 Unsupported 4,544.3

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 the fastest of six complete passes per API, not fastest individual parses: every pass keeps the garbage collection its parsing causes. 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_objects contains Circle, Slider, Spinner, or HoldNote, in stable timestamp order. Narrow the union with isinstance.
  • Times are milliseconds. Slider endpoints are 0 by default. Pass calculate_slider_end_times=True to parse or parse_file to 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_points includes the head position, unlike the native point range. curve_segments preserves lazer mode's segment boundaries and explicit B-spline degrees; stable mode has none. slides=2 means forward and back.
  • tag_list and bookmark_list are parsed conveniences alongside the tags and bookmarks text fields.
  • IDs and preview time map the -1 sentinel to None. A map without a BeatmapID has 0 in stable mode, as in stable, and None in lazer mode.
  • 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.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fosu 0.8.0
File Size Uploaded Provenance Actions
fosu-0.8.0.tar.gz 278.8 kB With provenance Details for fosu-0.8.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fosu 0.8.0
File Actions
fosu-0.8.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for fosu-0.8.0-cp310-abi3-win_amd64.whl
fosu-0.8.0-cp310-abi3-musllinux_1_2_x86_64.whl CPython 3.10 abi3 Linux musl 1.2+ x86-64 Details for fosu-0.8.0-cp310-abi3-musllinux_1_2_x86_64.whl
fosu-0.8.0-cp310-abi3-musllinux_1_2_aarch64.whl CPython 3.10 abi3 Linux musl 1.2+ ARM64 Details for fosu-0.8.0-cp310-abi3-musllinux_1_2_aarch64.whl
fosu-0.8.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64, Linux glibc 2.26+ x86-64 Details for fosu-0.8.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl
fosu-0.8.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.26+ ARM64, Linux glibc 2.28+ ARM64 Details for fosu-0.8.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
fosu-0.8.0-cp310-abi3-macosx_11_0_x86_64.whl CPython 3.10 abi3 macOS 11.0+ x86-64 Details for fosu-0.8.0-cp310-abi3-macosx_11_0_x86_64.whl
fosu-0.8.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for fosu-0.8.0-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 2.7 MB

Release files / fosu-0.8.0.tar.gz

Download URL fosu-0.8.0.tar.gz
Size 278.8 kB
Tags Source
SHA-256 checksum
How to use checksums
2223da0072aa291de31d78a79ba161648dce8dab830398a87da4fcb1decf2302
BLAKE2b-256 checksum
How to use checksums
12717e4f7182533daebf19d5cf7b739c5ac08e803e2559a8c3543f55d06f8ab2
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 8, 2026.

Transparency log

Release files / fosu-0.8.0-cp310-abi3-win_amd64.whl

Download URL fosu-0.8.0-cp310-abi3-win_amd64.whl
Size 370.0 kB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
2c315a4ec39a8a0625fc32bd419f7a44c69a9cec5fdb3085045745d2332402cc
BLAKE2b-256 checksum
How to use checksums
315e6851d9cf869393b5ba18ba93c8f1f855d91d5b29259bea0c4da19d97250a
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 8, 2026.

Transparency log

Release files / fosu-0.8.0-cp310-abi3-musllinux_1_2_x86_64.whl

Download URL fosu-0.8.0-cp310-abi3-musllinux_1_2_x86_64.whl
Size 406.0 kB
Tags CPython 3.10 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
4d4f674f653e465ac2c587dce11f5f5d6c6bafb366a73a53f878b0475f433fe2
BLAKE2b-256 checksum
How to use checksums
a04ece4e2034fb7b40e59d8f99a91fe9e66bbd9fefa4bda72998d0a50c7fa29b
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 8, 2026.

Transparency log

Release files / fosu-0.8.0-cp310-abi3-musllinux_1_2_aarch64.whl

Download URL fosu-0.8.0-cp310-abi3-musllinux_1_2_aarch64.whl
Size 428.6 kB
Tags CPython 3.10 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
11bfede1910284b8ff4df4f74d72f4ecc7286f73f83c5b19588db90be1ef5eb8
BLAKE2b-256 checksum
How to use checksums
67ce0582d8f88b2c8d38d215dcb59f909f99f6a9aaf19f4d1d705f5c2dd98079
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 8, 2026.

Transparency log

Release files / fosu-0.8.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl

Download URL fosu-0.8.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl
Size 407.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
2872f0e1c2ea83182f084b60e8317f268abf9d8cbdf02872e801c8dc52cdc5ac
BLAKE2b-256 checksum
How to use checksums
4e3c5e99f38fd946678a472b72cc6b859e94c546d0f61870c2ded85bafa68bad
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 8, 2026.

Transparency log

Release files / fosu-0.8.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl

Download URL fosu-0.8.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Size 430.2 kB
Tags CPython 3.10 Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
b4d7cdb19a681e8f4ef4e1707f1aadf15e9aca6a366bb4f4207fd2d760a922d5
BLAKE2b-256 checksum
How to use checksums
8c7dc84eb59e2c9043954992f5890062035920f22639cb95b828294d6e62b944
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 8, 2026.

Transparency log

Release files / fosu-0.8.0-cp310-abi3-macosx_11_0_x86_64.whl

Download URL fosu-0.8.0-cp310-abi3-macosx_11_0_x86_64.whl
Size 180.7 kB
Tags CPython 3.10 abi3 macOS 11.0+ x86-64
SHA-256 checksum
How to use checksums
861fa85eadf45b2e126ec6f243c755d3d04b49211c69d84da3085f29caccfec4
BLAKE2b-256 checksum
How to use checksums
3dc114ad8307ec63d817936743ca91817e9cfe205c63386f533b53f11a2cae01
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 8, 2026.

Transparency log

Release files / fosu-0.8.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL fosu-0.8.0-cp310-abi3-macosx_11_0_arm64.whl
Size 166.1 kB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
2c7158f8b16bfea710214a0ff2e8dc1ef2f8be22693cae6d18b209b962dd82db
BLAKE2b-256 checksum
How to use checksums
1055c3618e8e797cd59802ecf3b8634b7430c99562d5f1a40c3f0efc559d4fc9
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 8, 2026.

Transparency log

Security for fosu 0.8.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.

Select from 8 files

Attestation for fosu-0.8.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 8, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page