osu-orz 0.1.0__tar.gz

osu_orz-0.1.0/.github/scripts/select-release.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Decide whether this run publishes a release: a push to main whose pyproject.toml version has no finished release."""
+
+import json
+import os
+import re
+import subprocess
+import tomllib
+from pathlib import Path
+
+
+ROOT = Path(__file__).parents[2]
+
+
+def command(*args: str) -> str:
+    return subprocess.check_output(args, cwd=ROOT, text=True).strip()
+
+
+def main() -> None:
+    version = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]["version"]
+    if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", version):
+        raise SystemExit(f"unsupported release version: {version}")
+
+    current = tuple(map(int, version.split(".")))
+    tag = f"v{version}"
+    tags = command("git", "tag", "--list", "v[0-9]*.[0-9]*.[0-9]*").splitlines()
+    releases = [
+        tuple(map(int, value[1:].split(".")))
+        for value in tags
+        if re.fullmatch(r"v[0-9]+\.[0-9]+\.[0-9]+", value)
+    ]
+    latest = max(releases, default=(0, 0, 0))
+    tag_exists = tag in tags
+    if current < latest or (current == latest and not tag_exists):
+        raise SystemExit(f"version {version} is not newer than the latest tag")
+
+    release = subprocess.run(
+        ["gh", "release", "view", tag, "--json", "isDraft"],
+        cwd=ROOT,
+        text=True,
+        capture_output=True,
+    )
+    release_state = json.loads(release.stdout) if release.returncode == 0 else None
+    publish = (
+        os.environ["GITHUB_EVENT_NAME"] == "push"
+        and os.environ["GITHUB_REF"] == "refs/heads/main"
+        and (not tag_exists or release_state is None or release_state["isDraft"])
+    )
+    if tag_exists and publish:
+        tagged_commit = command("git", "rev-list", "-n", "1", tag)
+        if tagged_commit != os.environ["GITHUB_SHA"]:
+            raise SystemExit(f"unfinished {tag} release belongs to another commit")
+
+    with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output:
+        print(f"publish={str(publish).lower()}", file=output)
+        print(f"tag={tag}", file=output)
+
+
+if __name__ == "__main__":
+    main()

osu_orz-0.1.0/.github/workflows/python-wheels.yml

@@ -0,0 +1,142 @@
+name: Python wheels
+
+# Every push and pull request builds and tests the wheel. A push to main whose pyproject.toml version has no finished
+# release publishes it: the v{version} tag and GitHub release, then PyPI through trusted publishing.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-metadata:
+    runs-on: ubuntu-24.04
+    outputs:
+      publish: ${{ steps.release.outputs.publish }}
+      tag: ${{ steps.release.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Validate version and select release
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python .github/scripts/select-release.py
+
+  wheels:
+    name: Wheel / linux-x86_64
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: true
+          persist-credentials: false
+      - uses: pypa/cibuildwheel@v4.2.1
+      - uses: actions/upload-artifact@v4
+        with:
+          name: osu-orz-wheel-linux-x86_64
+          path: wheelhouse/*.whl
+
+  installed:
+    name: Installed / linux-x86_64 / Python ${{ matrix.python }}
+    needs: wheels
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/download-artifact@v4
+        with:
+          name: osu-orz-wheel-linux-x86_64
+          path: wheelhouse
+      - run: python -m pip install pytest
+      - run: python -m pip install --no-index --find-links wheelhouse osu-orz
+      - run: python -m pytest tests
+
+  source-install:
+    name: Source install
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: true
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - run: python -m pip install '.[test]'
+      - run: python -m pytest tests
+
+  sdist:
+    name: Source distribution
+    if: needs.release-metadata.outputs.publish == 'true'
+    needs: release-metadata
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: true
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+      - run: python -m pip install build
+      - run: python -m build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: osu-orz-sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish release artifacts
+    if: needs.release-metadata.outputs.publish == 'true'
+    needs: [release-metadata, wheels, installed, source-install, sdist]
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/osu-orz
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: osu-orz-*
+          path: dist
+          merge-multiple: true
+      - name: Create draft release and upload artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.release-metadata.outputs.tag }}
+        run: |
+          if ! gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release create "$RELEASE_TAG" --draft --generate-notes \
+              --target "$GITHUB_SHA" --title "$RELEASE_TAG" \
+              --repo "$GITHUB_REPOSITORY"
+          fi
+          gh release upload "$RELEASE_TAG" dist/* --clobber \
+            --repo "$GITHUB_REPOSITORY"
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+      - name: Publish GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.release-metadata.outputs.tag }}
+        run: gh release edit "$RELEASE_TAG" --draft=false --latest --repo "$GITHUB_REPOSITORY"

osu_orz-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+build/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+*.so

osu_orz-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "extern/osu_replay_zip"]
+	path = extern/osu_replay_zip
+	url = https://github.com/rumoi/osu_replay_zip.git

osu_orz-0.1.0/CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.18...3.31)
+project(${SKBUILD_PROJECT_NAME} LANGUAGES C CXX)
+
+find_package(Python 3.12 REQUIRED COMPONENTS Interpreter Development.Module ${SKBUILD_SABI_COMPONENT})
+find_package(nanobind CONFIG REQUIRED)
+
+set(ORZ ${CMAKE_CURRENT_SOURCE_DIR}/extern/osu_replay_zip)
+
+# the LZMA SDK decoder the codec reads replay data with
+add_library(orz_lzma STATIC ${ORZ}/Lib/LzmaDec.c)
+target_include_directories(orz_lzma PUBLIC ${ORZ}/Lib)
+set_target_properties(orz_lzma PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+nanobind_add_module(_core STABLE_ABI NB_STATIC src/osu_orz/_core.cpp)
+target_compile_features(_core PRIVATE cxx_std_20)
+target_include_directories(_core PRIVATE ${ORZ})
+target_link_libraries(_core PRIVATE orz_lzma)
+
+# files only decode where every build does its float maths exactly as written: no fused multiply-add contraction
+# (which -march=native would allow) and no fast-math. The codec refuses to build with GCC unless told contraction is off
+target_compile_options(_core PRIVATE -ffp-contract=off -fno-fast-math)
+target_compile_definitions(_core PRIVATE ORZ_FP_CONTRACT_OFF)
+
+install(TARGETS _core LIBRARY DESTINATION osu_orz)

osu_orz-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cmyui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

osu_orz-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: osu-orz
+Version: 0.1.0
+Summary: Lossless compression for osu! replays with the ORZ format
+Author: cmyui
+License-Expression: MIT
+License-File: LICENSE
+License-File: extern/osu_replay_zip/LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Archiving :: Compression
+Project-URL: Source, https://github.com/cmyui/osu-orz
+Project-URL: ORZ format, https://github.com/rumoi/osu_replay_zip
+Requires-Python: >=3.12
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Description-Content-Type: text/markdown
+
+# osu-orz
+
+Python bindings for [ORZ](https://github.com/rumoi/osu_replay_zip), a lossless compression format for osu! replays.
+
+```python
+import osu_orz
+
+orz = osu_orz.compress(osr_bytes)  # an .osr file
+assert osu_orz.decompress(orz) == osr_bytes
+
+# bare replay data (the LZMA stream osu! stores for a score) has no header, so say what it is
+orz = osu_orz.compress(replay_data, mode=osu_orz.Mode.OSU_RELAX)
+assert osu_orz.decompress(orz) == replay_data
+```
+
+## Modes
+
+`compress` reads an `.osr`'s game mode and Relax from its header. Bare replay data needs `mode` in place of the header,
+and an `.osr` must not be given one, so the two can never disagree.
+
+| `Mode` | Replay |
+|---|---|
+| `OSU`, `TAIKO`, `CATCH`, `MANIA` | the game mode, without Relax |
+| `OSU_RELAX`, `TAIKO_RELAX`, `CATCH_RELAX` | the game mode with Relax (osu!mania has none) |
+
+The values are the mode numbers ORZ files store. Autopilot replays are `OSU`: the encoder recognises the autopilot
+path from the frames itself. The mode picks the coder and its priors, so a wrong mode only makes the `.orz` bigger: the
+frames come back the same under every mode, and replay data osu! wrote comes back byte for byte.
+
+## What comes back
+
+`decompress` rebuilds the input `compress` was given:
+
+- the replay frames exactly;
+- the `.osr` fields around them exactly (header, life bar, timestamp, score id);
+- the replay data's LZMA bytes, compressed again the way osu! compresses them. Replay data osu! wrote comes back byte
+  for byte. Data written by other software comes back with the same frames, compressed like osu! would.
+
+Some replay data is stored as it is, and comes back byte for byte:
+
+- data the codec can not code as frames (not LZMA, or text that is not osu!'s frames);
+- data whose coded frames would be no smaller than its LZMA;
+- with `check_round_trip=True`, data whose coded frames do not decode back to it. `compress` then decodes what it wrote
+  before returning it, which is slower but keeps a coding bug from turning into a replay that decodes wrong.
+
+Errors raise `osu_orz.OrzError` (a `ValueError`): an `.osr` given a `mode`, anything else without one that is not an
+`.osr`, an `.orz` given to `compress`, or an `.orz` that is damaged, cut short or made by a newer format version. A
+`mode` that is not a `Mode` raises `ValueError`. Both functions release the GIL, so threads compress in parallel.
+
+`decompress(orz, skip_crc=True)` gives back what a file decodes to even when it fails its CRC check (damaged, or
+written by an incompatible build), to recover what is left of it.
+
+## Format stability
+
+ORZ is format version 0 (`osu_orz.FORMAT_VERSION`) and can still change incompatibly between releases. Until the format
+is versioned, decode an `.orz` with the osu-orz version that wrote it.
+
+## Platform
+
+Linux on x86-64 (SSE 4.2) with CPython 3.12 or newer. The codec uses x86 CRC instructions, so other architectures do
+not build yet.
+
+## Building from source
+
+```sh
+git clone --recursive https://github.com/cmyui/osu-orz
+pip install './osu-orz[test]'
+pytest osu-orz/tests
+```
+
+This needs a C++20 compiler (GCC 11 or newer, or Clang). The build compiles the codec with `-ffp-contract=off`:
+`.orz` files only decode when every build does its float maths exactly as written, so do not build it with
+`-ffast-math`.
+
+## Releasing
+
+Bump `version` in `pyproject.toml` and merge to `main`. CI then builds and tests the wheel, tags `v{version}`, makes a
+GitHub release and publishes to PyPI.
+
+## License
+
+MIT. The ORZ codec in `extern/osu_replay_zip` is MIT licensed by rumoi; wheels include both licenses.

osu_orz-0.1.0/README.md

@@ -0,0 +1,82 @@
+# osu-orz
+
+Python bindings for [ORZ](https://github.com/rumoi/osu_replay_zip), a lossless compression format for osu! replays.
+
+```python
+import osu_orz
+
+orz = osu_orz.compress(osr_bytes)  # an .osr file
+assert osu_orz.decompress(orz) == osr_bytes
+
+# bare replay data (the LZMA stream osu! stores for a score) has no header, so say what it is
+orz = osu_orz.compress(replay_data, mode=osu_orz.Mode.OSU_RELAX)
+assert osu_orz.decompress(orz) == replay_data
+```
+
+## Modes
+
+`compress` reads an `.osr`'s game mode and Relax from its header. Bare replay data needs `mode` in place of the header,
+and an `.osr` must not be given one, so the two can never disagree.
+
+| `Mode` | Replay |
+|---|---|
+| `OSU`, `TAIKO`, `CATCH`, `MANIA` | the game mode, without Relax |
+| `OSU_RELAX`, `TAIKO_RELAX`, `CATCH_RELAX` | the game mode with Relax (osu!mania has none) |
+
+The values are the mode numbers ORZ files store. Autopilot replays are `OSU`: the encoder recognises the autopilot
+path from the frames itself. The mode picks the coder and its priors, so a wrong mode only makes the `.orz` bigger: the
+frames come back the same under every mode, and replay data osu! wrote comes back byte for byte.
+
+## What comes back
+
+`decompress` rebuilds the input `compress` was given:
+
+- the replay frames exactly;
+- the `.osr` fields around them exactly (header, life bar, timestamp, score id);
+- the replay data's LZMA bytes, compressed again the way osu! compresses them. Replay data osu! wrote comes back byte
+  for byte. Data written by other software comes back with the same frames, compressed like osu! would.
+
+Some replay data is stored as it is, and comes back byte for byte:
+
+- data the codec can not code as frames (not LZMA, or text that is not osu!'s frames);
+- data whose coded frames would be no smaller than its LZMA;
+- with `check_round_trip=True`, data whose coded frames do not decode back to it. `compress` then decodes what it wrote
+  before returning it, which is slower but keeps a coding bug from turning into a replay that decodes wrong.
+
+Errors raise `osu_orz.OrzError` (a `ValueError`): an `.osr` given a `mode`, anything else without one that is not an
+`.osr`, an `.orz` given to `compress`, or an `.orz` that is damaged, cut short or made by a newer format version. A
+`mode` that is not a `Mode` raises `ValueError`. Both functions release the GIL, so threads compress in parallel.
+
+`decompress(orz, skip_crc=True)` gives back what a file decodes to even when it fails its CRC check (damaged, or
+written by an incompatible build), to recover what is left of it.
+
+## Format stability
+
+ORZ is format version 0 (`osu_orz.FORMAT_VERSION`) and can still change incompatibly between releases. Until the format
+is versioned, decode an `.orz` with the osu-orz version that wrote it.
+
+## Platform
+
+Linux on x86-64 (SSE 4.2) with CPython 3.12 or newer. The codec uses x86 CRC instructions, so other architectures do
+not build yet.
+
+## Building from source
+
+```sh
+git clone --recursive https://github.com/cmyui/osu-orz
+pip install './osu-orz[test]'
+pytest osu-orz/tests
+```
+
+This needs a C++20 compiler (GCC 11 or newer, or Clang). The build compiles the codec with `-ffp-contract=off`:
+`.orz` files only decode when every build does its float maths exactly as written, so do not build it with
+`-ffast-math`.
+
+## Releasing
+
+Bump `version` in `pyproject.toml` and merge to `main`. CI then builds and tests the wheel, tags `v{version}`, makes a
+GitHub release and publishes to PyPI.
+
+## License
+
+MIT. The ORZ codec in `extern/osu_replay_zip` is MIT licensed by rumoi; wheels include both licenses.

osu_orz-0.1.0/extern/osu_replay_zip/.gitattributes

@@ -0,0 +1,63 @@
+###############################################################################
+# Set default behavior to automatically normalize line endings.
+###############################################################################
+* text=auto
+
+###############################################################################
+# Set default behavior for command prompt diff.
+#
+# This is need for earlier builds of msysgit that does not have it on by
+# default for csharp files.
+# Note: This is only used by command line
+###############################################################################
+#*.cs     diff=csharp
+
+###############################################################################
+# Set the merge driver for project and solution files
+#
+# Merging from the command prompt will add diff markers to the files if there
+# are conflicts (Merging from VS is not affected by the settings below, in VS
+# the diff markers are never inserted). Diff markers may cause the following 
+# file extensions to fail to load in VS. An alternative would be to treat
+# these files as binary and thus will always conflict and require user
+# intervention with every merge. To do so, just uncomment the entries below
+###############################################################################
+#*.sln       merge=binary
+#*.csproj    merge=binary
+#*.vbproj    merge=binary
+#*.vcxproj   merge=binary
+#*.vcproj    merge=binary
+#*.dbproj    merge=binary
+#*.fsproj    merge=binary
+#*.lsproj    merge=binary
+#*.wixproj   merge=binary
+#*.modelproj merge=binary
+#*.sqlproj   merge=binary
+#*.wwaproj   merge=binary
+
+###############################################################################
+# behavior for image files
+#
+# image files are treated as binary by default.
+###############################################################################
+#*.jpg   binary
+#*.png   binary
+#*.gif   binary
+
+###############################################################################
+# diff behavior for common document formats
+# 
+# Convert binary document formats to text before diffing them. This feature
+# is only available from the command line. Turn it on by uncommenting the 
+# entries below.
+###############################################################################
+#*.doc   diff=astextplain
+#*.DOC   diff=astextplain
+#*.docx  diff=astextplain
+#*.DOCX  diff=astextplain
+#*.dot   diff=astextplain
+#*.DOT   diff=astextplain
+#*.pdf   diff=astextplain
+#*.PDF   diff=astextplain
+#*.rtf   diff=astextplain
+#*.RTF   diff=astextplain