API reference¶

The canonical public package is bielsort:

import bielsort

The four canonical functions mirror the two common Python sorting styles and add optional diagnostic variants.

At a glance¶

Function	Changes input?	Return value	Intended comparison
`sort()`	No	new `list`	`sorted()`
`sort_in_place()`	Yes	`None`	`list.sort()`
`sort_with_strategy()`	No	`(list, str)`	diagnostics
`sort_in_place_with_strategy()`	Yes	`str`	diagnostics

All four operations are stable: elements that compare equal retain their original relative order.

`sort`¶

bielsort.sort(iterable, *, key=None, reverse=False)

Return a new sorted list and leave the input unchanged.

Parameters

iterable: any iterable accepted by the implementation, including lists, tuples, and generators;
key: optional one-argument key function;
reverse: sort in descending order when True.

Returns

A new list containing the sorted elements.

import bielsort

source = (5, -2, 8, 5)
result = bielsort.sort(source)

assert result == [-2, 5, 5, 8]

When key is not None or reverse is true, the function deliberately uses sorted() to preserve Python's behavior.

`sort_in_place`¶

bielsort.sort_in_place(values, *, key=None, reverse=False)

Sort a list in place, preserve its identity, and return None.

Parameters

values: the list to mutate;
key: optional one-argument key function;
reverse: sort in descending order when True.

Returns

None, matching list.sort().

import bielsort

values = [5, -2, 8, 5]
identity = id(values)

result = bielsort.sort_in_place(values)

assert values == [-2, 5, 5, 8]
assert id(values) == identity
assert result is None

Passing a non-list value is an error for the in-place API.

`sort_with_strategy`¶

bielsort.sort_with_strategy(iterable, *, key=None, reverse=False)

Return a tuple containing the new sorted list and a human-readable description of the selected strategy.

import random
import bielsort

rng = random.Random(42)
values = [rng.randint(-(1 << 31), (1 << 31) - 1) for _ in range(100_000)]

ordered, strategy = bielsort.sort_with_strategy(values)
print(strategy)

`sort_in_place_with_strategy`¶

bielsort.sort_in_place_with_strategy(
    values,
    *,
    key=None,
    reverse=False,
)

Sort a list in place and return the human-readable strategy description.

import bielsort

values = [3, 1, 2] * 10_000
strategy = bielsort.sort_in_place_with_strategy(values)

assert values == sorted(values)
print(strategy)

Diagnostic strings are not a control-flow API

Strategy descriptions are intended for debugging, benchmarks, and issue reports. Their wording may evolve as heuristics improve before 1.0. Do not make application correctness depend on an exact diagnostic string.

`version`¶

import bielsort

print(bielsort.__version__)

For package-management code, importlib.metadata.version("bielsort") is also available.

Compatibility aliases¶

The original names remain aliases throughout the 0.1 series:

Compatibility name	Canonical name
`biel_sort`	`sort`
`biel_sort_in_place`	`sort_in_place`
`biel_sort_diagnostico`	`sort_with_strategy`
`biel_sort_with_strategy`	`sort_with_strategy`
`biel_sort_in_place_diagnostico`	`sort_in_place_with_strategy`
`biel_sort_in_place_with_strategy`	`sort_in_place_with_strategy`

The older bielsort_native import path is also retained for compatibility. New code should use import bielsort.

Behavior summary¶

natural ascending exact signed 64-bit integers may use a native fast path;
key= and reverse= use Python's Timsort;
non-integers, integer subclasses, and arbitrary-size integers use Timsort;
sorting is stable in every path;
sort() preserves the source iterable;
sort_in_place() preserves list identity and returns None.

API reference¶

At a glance¶

sort¶

sort_in_place¶

sort_with_strategy¶

sort_in_place_with_strategy¶

__version__¶