floatium 0.11.0__tar.gz

floatium-0.11.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test / py${{ matrix.python }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+        python: ["3.12", "3.13", "3.14", "3.14t", "3.15", "3.15t"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          allow-prereleases: true
+
+      - name: Install build deps and package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[test]"
+
+      - name: Show info
+        run: |
+          python -c "import floatium; print(floatium.info())"
+
+      - name: Run unit + parity + edge tests
+        run: |
+          python -m pytest tests -x --tb=short --ignore=tests/cpython_suite
+
+      - name: Run vendored CPython tests (if any)
+        run: |
+          python -m pytest tests/cpython_suite --tb=short || true
+        shell: bash

floatium-0.11.0/.github/workflows/cpython-suite.yml

@@ -0,0 +1,44 @@
+name: cpython-suite
+
+# Runs CPython's own stdlib regression tests against a floatium-patched
+# interpreter (Track A of the test strategy — see tests/cpython_suite/README.md).
+# If this workflow reports a failure, that's a real behavioral divergence
+# from stock CPython — the output should go into DIFFERENCES.md.
+#
+# Kept separate from ci.yml because each test run takes ~1 minute per
+# Python version and we don't want to block ordinary PRs on it.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+  schedule:
+    - cron: "0 7 * * 1"     # weekly Monday at 07:00 UTC
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  stdlib-tests:
+    name: stdlib / py${{ matrix.python }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+        python: ["3.12", "3.13", "3.14", "3.14t", "3.15", "3.15t"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          allow-prereleases: true
+
+      - run: python -m pip install --upgrade pip && python -m pip install .
+
+      - name: Run CPython stdlib tests with FLOATIUM_AUTOPATCH=1
+        shell: bash
+        run: |
+          python tools/run_stdlib_tests.py

floatium-0.11.0/.github/workflows/wheels.yml

@@ -0,0 +1,75 @@
+name: wheels
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1"     # nightly sanity build
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with: { python-version: "3.12" }
+      - run: |
+          python -m pip install --upgrade pip build
+          python -m build --sdist --outdir dist
+      - uses: actions/upload-artifact@v5
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  build-wheels:
+    name: wheels / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+          - os: ubuntu-24.04-arm
+          - os: macos-14      # arm64
+          - os: windows-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: pypa/cibuildwheel@v2.21
+        env:
+          # Keep most config in pyproject.toml; these flags are the ones
+          # cibuildwheel 2.21 requires at the env level to opt into
+          # free-threaded and prerelease CPython builds.
+          CIBW_BUILD_VERBOSITY: 1
+          CIBW_FREE_THREADED_SUPPORT: "True"
+          CIBW_PRERELEASE_PYTHONS: "True"
+
+      - uses: actions/upload-artifact@v5
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  publish:
+    name: publish to PyPI
+    needs: [build-wheels, build-sdist]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/floatium
+    permissions:
+      id-token: write         # trusted-publisher flow
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          path: dist
+          pattern: "{wheels-*,sdist}"
+          merge-multiple: true
+      - name: List artifacts
+        run: ls -la dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

floatium-0.11.0/.gitignore

@@ -0,0 +1,15 @@
+build/
+dist/
+wheelhouse/
+*.egg-info/
+__pycache__/
+*.pyc
+*.so
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+bench/results/*.json
+!bench/results/.gitkeep
+.venv/
+venv/

floatium-0.11.0/CMakeLists.txt

@@ -0,0 +1,131 @@
+cmake_minimum_required(VERSION 3.20)
+project(floatium LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# --- Backend selection ------------------------------------------------------
+# Format backend: fmt_opt (default — fmt for repr/exp, Ryu d2fixed for fixed),
+#                 fmt (plain fmt for everything, for A/B measurement),
+#                 stock (CPython dtoa baseline), all.
+# Parse backend:  fast_float (default), stock, all.
+#
+# With "all", every backend is compiled in and the active one is chosen at
+# runtime via env vars FLOATIUM_FORMAT_BACKEND / FLOATIUM_PARSE_BACKEND.
+set(FLOATIUM_FORMAT_BACKEND "fmt_opt" CACHE STRING "Format backend: fmt_opt, fmt, stock, all")
+set(FLOATIUM_PARSE_BACKEND  "fast_float" CACHE STRING "Parse backend: fast_float, stock, all")
+set_property(CACHE FLOATIUM_FORMAT_BACKEND PROPERTY STRINGS fmt_opt fmt stock all)
+set_property(CACHE FLOATIUM_PARSE_BACKEND  PROPERTY STRINGS fast_float stock all)
+
+# --- Python -----------------------------------------------------------------
+# scikit-build-core passes Python3_EXECUTABLE via the FindPython hint file.
+find_package(Python3 REQUIRED COMPONENTS Interpreter Development.Module)
+
+# --- Sources ----------------------------------------------------------------
+set(FLOATIUM_SRCS
+    src/ext.cc
+    src/slots.cc
+    src/format_short.cc
+    src/backends/registry.cc
+    src/cpython_adapter/fast_float_strtod.cc
+)
+
+# Compile-in backends based on selection. Default selection is made in
+# backends/registry.cc at runtime via FLOATIUM_DEFAULT_FORMAT_BACKEND etc.
+if(FLOATIUM_FORMAT_BACKEND STREQUAL "fmt" OR FLOATIUM_FORMAT_BACKEND STREQUAL "all")
+    list(APPEND FLOATIUM_SRCS
+        src/backends/fmt_format.cc
+        src/cpython_adapter/fmt_dtoa.cc
+    )
+    set(FLOATIUM_HAS_FMT_FORMAT 1)
+endif()
+if(FLOATIUM_FORMAT_BACKEND STREQUAL "fmt_opt" OR FLOATIUM_FORMAT_BACKEND STREQUAL "all")
+    list(APPEND FLOATIUM_SRCS
+        src/backends/fmt_opt_format.cc
+        src/cpython_adapter/fmt_opt_dtoa.cc
+        third_party/ryu/d2fixed.c
+    )
+    set(FLOATIUM_HAS_FMT_OPT_FORMAT 1)
+endif()
+if(FLOATIUM_FORMAT_BACKEND STREQUAL "stock" OR FLOATIUM_FORMAT_BACKEND STREQUAL "all")
+    list(APPEND FLOATIUM_SRCS src/backends/stock_format.cc)
+    set(FLOATIUM_HAS_STOCK_FORMAT 1)
+endif()
+if(FLOATIUM_PARSE_BACKEND STREQUAL "fast_float" OR FLOATIUM_PARSE_BACKEND STREQUAL "all")
+    list(APPEND FLOATIUM_SRCS src/backends/fast_float_parse.cc)
+    set(FLOATIUM_HAS_FAST_FLOAT_PARSE 1)
+endif()
+if(FLOATIUM_PARSE_BACKEND STREQUAL "stock" OR FLOATIUM_PARSE_BACKEND STREQUAL "all")
+    list(APPEND FLOATIUM_SRCS src/backends/stock_parse.cc)
+    set(FLOATIUM_HAS_STOCK_PARSE 1)
+endif()
+
+# Always compile fmt's format TU when fmt_opt is selected — fmt_opt_dtoa.cc
+# still uses fmt for modes 0/2 and for the negative-ndigits fallback.
+# fmt_format.cc's sources are already included above in the "fmt" branch;
+# when only fmt_opt is selected we still need fmt_dtoa.cc's headers to be
+# available to fmt_opt_dtoa.cc via FMT_HEADER_ONLY.
+
+python3_add_library(_ext MODULE ${FLOATIUM_SRCS} WITH_SOABI)
+
+target_include_directories(_ext PRIVATE
+    src
+    src/common
+    third_party/fmt
+    third_party/fast_float
+    third_party/ryu
+)
+
+# Match the build flags the CPython fmt-fastfloat branch uses for the
+# vendored C++ code. -fno-exceptions / -fno-rtti keep the libstdc++ footprint
+# minimal and avoid any dependency on C++ runtime type info.
+if(NOT MSVC)
+    target_compile_options(_ext PRIVATE
+        $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
+        $<$<COMPILE_LANGUAGE:CXX>:-fno-rtti>
+        -fvisibility=hidden
+        -Wall
+        -Wextra
+        -Wno-unused-parameter
+    )
+else()
+    target_compile_options(_ext PRIVATE
+        $<$<COMPILE_LANGUAGE:CXX>:/EHs-c->      # disable C++ exceptions
+        $<$<COMPILE_LANGUAGE:CXX>:/GR->         # disable RTTI
+        $<$<COMPILE_LANGUAGE:CXX>:/utf-8>       # fmt's base.h static_asserts against CP-1252 sources
+        /W3
+        /wd4100      # unreferenced formal parameter
+    )
+endif()
+
+# Configure-time feature flags surfaced to C++
+# The FLOATIUM_DEFAULT_*_BACKEND macro selects the backend picked when
+# install() is called with no kwargs. "all" builds every backend into the
+# wheel but still need a single default; prefer the optimized fmt-based one.
+set(FLOATIUM_DEFAULT_FORMAT "${FLOATIUM_FORMAT_BACKEND}")
+if(FLOATIUM_DEFAULT_FORMAT STREQUAL "all")
+    set(FLOATIUM_DEFAULT_FORMAT "fmt_opt")
+endif()
+set(FLOATIUM_DEFAULT_PARSE "${FLOATIUM_PARSE_BACKEND}")
+if(FLOATIUM_DEFAULT_PARSE STREQUAL "all")
+    set(FLOATIUM_DEFAULT_PARSE "fast_float")
+endif()
+
+target_compile_definitions(_ext PRIVATE
+    $<$<BOOL:${FLOATIUM_HAS_FMT_FORMAT}>:FLOATIUM_HAS_FMT_FORMAT=1>
+    $<$<BOOL:${FLOATIUM_HAS_FMT_OPT_FORMAT}>:FLOATIUM_HAS_FMT_OPT_FORMAT=1>
+    $<$<BOOL:${FLOATIUM_HAS_STOCK_FORMAT}>:FLOATIUM_HAS_STOCK_FORMAT=1>
+    $<$<BOOL:${FLOATIUM_HAS_FAST_FLOAT_PARSE}>:FLOATIUM_HAS_FAST_FLOAT_PARSE=1>
+    $<$<BOOL:${FLOATIUM_HAS_STOCK_PARSE}>:FLOATIUM_HAS_STOCK_PARSE=1>
+    FLOATIUM_DEFAULT_FORMAT_BACKEND="${FLOATIUM_DEFAULT_FORMAT}"
+    FLOATIUM_DEFAULT_PARSE_BACKEND="${FLOATIUM_DEFAULT_PARSE}"
+)
+
+install(TARGETS _ext DESTINATION floatium)
+
+# .pth files must sit directly in site-packages (the purelib/platlib root)
+# to be processed by site.py. scikit-build-core maps `DESTINATION .` to
+# the wheel's platlib root, which becomes site-packages/ after install.
+install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/floatium.pth DESTINATION .)

floatium-0.11.0/DIFFERENCES.md

@@ -0,0 +1,88 @@
+# Behavioral differences vs. stock CPython
+
+The primary success metric for floatium is that CPython's own regression
+tests pass unchanged when run against a patched interpreter (Track A in
+the test strategy). This file records every observed divergence so the
+PEP discussion has them on the table up front.
+
+## Last verified
+
+- Interpreter: Python 3.15.0a3 (free-threaded debug build)
+- floatium commit: initial (v0.1.0.dev0)
+- Upstream CPython commit (fmt-fastfloat branch): `46e18aa3d5b`
+
+## Summary: zero divergences
+
+```
+$ python tools/run_stdlib_tests.py
+== Tests result: SUCCESS ==
+All 12 tests OK.
+Total tests: run=1,616 skipped=210
+```
+
+Default test set:
+`test_float`, `test_strtod`, `test_fstring`, `test_format`, `test_complex`,
+`test_json`, `test_struct`, `test_string`, `test_decimal`, `test_math`,
+`test_cmath`, `test_statistics`.
+
+In addition, the 499-entry byte-identical parity matrix in
+`tests/test_parity.py` (repr, str, format across ~50 format specs × 23
+curated values) passes 100%.
+
+## Known limitations (not divergences)
+
+These are cases where floatium is **intentionally unable** to intercept
+behavior, not cases where it produces different output. Documented here
+so they're visible when the PEP case is made.
+
+### 1. `"%g" % x` is not patched
+
+The `%` operator for strings (`printf`-style formatting) calls
+`PyOS_double_to_string` directly from `Python/unicodeobject.c:formatfloat`.
+That symbol lives inside `libpython` and is not reachable from a
+pip-installed extension without `LD_PRELOAD` / symbol interposition.
+
+Impact: `"%g" % 0.1` uses the stock dtoa in a floatium-patched process.
+This is a consequence of floatium being a **demo**; the actual PEP would
+modify `pystrtod.c` / `PyOS_double_to_string` directly and cover this
+path. See the companion CPython `fmt-fastfloat` branch for the in-tree
+implementation that covers it.
+
+### 2. `float("1_000.5")` falls through to the original `tp_new`
+
+`fast_float::from_chars` does not handle PEP 515 underscore separators,
+so `floatium_float_new` checks for `_` in the input and delegates to the
+saved `float_new` when present. Output is bit-identical to stock (we
+literally invoke the original), but this path does not benefit from
+fast_float's speed. The in-tree CPython implementation strips
+underscores before calling fast_float and therefore does benefit.
+
+### 3. `float("inf")`, `float("nan")` fall through
+
+The `fast_float_strtod` wrapper sets `no_infnan` so these literals are
+rejected by the parse backend and the original `tp_new` handles them.
+This preserves CPython's exact casing rules (`Infinity`, `INF`, `nan`,
+etc.) at the cost of a small fast-path miss on these strings. Parity is
+identical.
+
+### 4. `float.__format__` with complex specs falls through
+
+`floatium_float_format` handles the common path inline
+(`[.precision]{g,G,e,E,f,F}`) and delegates to the original descriptor
+for anything with fill/align/width/`#`/`,`/`_`/etc. Output is
+bit-identical because the fallback invokes the saved bound method.
+Complex specs therefore run at stock speed.
+
+## When you find a new divergence
+
+1. Add a minimal reproducer to `tests/test_parity.py` marked `xfail` with
+   the reason.
+2. Add an entry to this file's "Known divergences" section (below —
+   currently empty).
+3. Open an issue against CPython's `fmt-fastfloat` branch if the
+   divergence also exists there, or against floatium if it's specific to
+   this package's wrappers.
+
+## Known divergences
+
+None as of the last-verified date above.

floatium-0.11.0/INTERNALS.md

@@ -0,0 +1,83 @@
+# Internals
+
+Notes on how floatium is wired internally. Not needed for ordinary use;
+see the [README](README.md) first.
+
+## Introspection
+
+```python
+>>> import floatium
+>>> floatium.info()
+{'patched': True,
+ 'format_backend': 'fmt_opt',
+ 'parse_backend': 'fast_float',
+ 'available_format_backends': 'fmt_opt',
+ 'available_parse_backends': 'fast_float',
+ 'default_format_backend': 'fmt_opt',
+ 'default_parse_backend': 'fast_float'}
+```
+
+Fields:
+
+- `patched` — whether `install()` is currently active.
+- `format_backend` / `parse_backend` — which backend is active now.
+- `available_*` — what was compiled into this wheel.
+- `default_*` — what `install()` picks if no backend is requested.
+
+## Format backends
+
+Registered format backends (all produce output bit-identical to stock
+CPython):
+
+| name       | Uses                                          | When |
+|------------|-----------------------------------------------|------|
+| `fmt_opt`  | fmt Dragonbox + fmt fast subsegment + Ryu d2fixed | default |
+| `fmt`      | fmt Dragonbox + fmt `format_float` only       | A/B measurement |
+| `stock`    | calls back into `PyOS_double_to_string`       | regression baseline |
+
+`fmt_opt` is the floatium default. For each `_Py_dg_dtoa` call it picks
+per mode:
+
+- **Mode 0 (shortest, drives `repr`)** — fmt's Dragonbox via
+  `fmt::detail::dragonbox::to_decimal`.
+- **Mode 2 (significant digits, drives `%e`/`%g`)** — fmt's
+  `format_float` with `presentation_type::exp`.
+- **Mode 3 (digits past decimal, drives `%f`)** — hybrid:
+  - If `3 × precision + max(exp2, 0) ≤ 60`, stay on fmt. This keeps
+    easy cases (small magnitudes / small precision) on fmt's fast
+    subsegment path, which is ~10 ns faster per call than d2fixed for
+    those inputs.
+  - Otherwise route through Ryu `d2fixed_buffered_n`, which is
+    block-based (9 digits per `mulShift_mod1e9` step) and has no cliff.
+
+The `exp2 ≤ 60` boundary mirrors fmt's internal cutoff: fmt falls into
+Dragon4 + bigint once the value's decade plus requested precision
+exceeds the 19-digit Dragonbox first segment, at which point it is
+2-6× slower than stock dtoa. log10(2) ≈ 0.30103 gives
+exp2 ≈ 3.32 × decade, hence the integer inequality above.
+
+## Parse backend
+
+Only `fast_float` is registered on the parse side. `float(str)` is
+intercepted by swapping `PyFloat_Type.tp_new`; the wrapper UTF-8
+extracts, strips whitespace, rejects underscores / non-ASCII (those
+fall through to the original `tp_new`), null-terminates, and calls the
+backend's `strtod`.
+
+## Backend abstraction
+
+The vendored libraries sit behind a narrow C interface
+([`src/common/backend.h`](src/common/backend.h)):
+
+```c
+struct FloatiumFormatBackend { const char *name; floatium_dtoa_fn dtoa; ... };
+struct FloatiumParseBackend  { const char *name; floatium_strtod_fn strtod; };
+```
+
+Swapping fmt for Ryu shortest or Schubfach is a new file in
+`src/backends/`. Swapping `fast_float` for double-conversion is another.
+Backends are CMake-selectable at build time
+(`-DFLOATIUM_FORMAT_BACKEND=...`, values `fmt_opt`, `fmt`, `stock`,
+`all`); when built with `all` every backend is compiled in and the
+active one is chosen via the `FLOATIUM_FORMAT_BACKEND` env var at
+interpreter startup or the `format_backend=` kwarg to `install()`.

floatium-0.11.0/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 Pieter Eendebak
+
+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.
+
+---
+
+This software vendors third-party libraries under their own licenses:
+
+- third_party/fmt/       — MIT (see third_party/fmt/LICENSE)
+- third_party/fast_float/ — Apache-2.0 OR MIT OR Boost-1.0
+                            (see third_party/fast_float/LICENSE-*)
+
+- src/format_short.cc is a port of code from CPython Python/pystrtod.c
+  (PSF License), redistributed in accordance with the PSF license terms.