Skip to content

Limits and compatibility

BielSort remains correct outside its fast path because it delegates to Timsort. The distinction is about expected performance and supported binary platforms, not about producing a different sorted order.

Compatibility matrix

Area Current support
Python implementation CPython only
Python versions 3.9–3.14
Fast-path values exact int in signed 64-bit range
Stable sorting yes, every path
key= and reverse= yes, through Timsort
New-list API any compatible iterable
In-place API exact list
Runtime dependencies none
License MIT

Prebuilt wheels

The 0.1.0 release provides 36 wheels plus a source distribution.

Operating system Architectures
Linux x86-64, manylinux and musllinux variants
Windows x86, x86-64
macOS Intel x86-64, Apple Silicon arm64

Other platforms may build from source but are not part of the validated wheel matrix. A source build needs a compatible C compiler and CPython development headers.

What uses the native fast path?

The accelerated Counting and Radix paths require all of the following:

  • natural ascending order (key=None, reverse=False);
  • exact Python int objects, not subclasses;
  • every value fitting between -(2**63) and 2**63 - 1;
  • enough elements and a distribution that makes native work worthwhile.

Even compatible integers may use Timsort when the input is small, already ordered, or nearly monotonic.

What falls back to Timsort?

  • strings and floats;
  • mixed or general Python objects;
  • integer subclasses;
  • arbitrary-size Python integers outside signed 64-bit range;
  • calls using key= or reverse=;
  • small, ordered, and nearly ordered inputs.

Fallback is part of BielSort's design. It preserves Python behavior in cases where the native specializations do not offer a clear advantage.

Memory

Counting and Radix Sort allocate native buffers proportional to input size. Measured favorable workloads used more peak memory than sorted() and list.sort(), even after the Counting Sort memory optimization.

If memory is more constrained than latency, benchmark peak RSS as well as execution time before adopting BielSort.

CPython-specific implementation

The native extension uses the CPython C API and manipulates CPython list and integer objects. PyPy and other Python implementations are not currently supported.

Threading and the GIL

The new-list native path can release the GIL during private buffer movement. The in-place native path keeps the GIL because it mutates a list owned by the caller. BielSort does not promise parallel sorting of one list.

Pre-1.0 stability

The four canonical function names are stable for the 0.1 series. Performance heuristics and diagnostic wording may evolve before 1.0. Keep correctness independent of the exact string returned by a diagnostic API.

Decision guide

  • the data is already a large list[int];
  • values fit in signed 64-bit range;
  • the list is not usually nearly sorted;
  • end-to-end latency matters;
  • extra native memory is acceptable;
  • benchmarks on real data confirm an advantage.
  • inputs are small or nearly ordered;
  • values are general Python objects;
  • code depends heavily on key= or reverse=;
  • portability beyond CPython is required;
  • minimizing auxiliary memory is more important;
  • there is no measured bottleneck to solve.
  • data is naturally an array rather than a Python list;
  • vectorized numerical processing continues after sorting;
  • conversion back to Python objects is unnecessary.

Report a problem