Enhance Library Sort: key/reverse, gap rebalancing, docs - #13392
Enhance Library Sort: key/reverse, gap rebalancing, docs#13392leo-soumyajit wants to merge 3 commits into
Conversation
Closing this pull request as invalid@leo-soumyajit, this pull request is being closed as none of the checkboxes have been marked. It is important that you go through the checklist and mark the ones relevant to this pull request. Please read the Contributing guidelines. If you're facing any problem on how to mark a checkbox, please read the following instructions:
NOTE: Only |
algorithms-keeper
Bot
added
require descriptive names
![algorithms-keeper[bot]](https://avatars.githubusercontent.com/in/235834?s=60&v=4){kind=small}
There was a problem hiding this comment.
Click here to look at the relevant links ⬇️
🔗 Relevant Links
Repository:
Python:
Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.
algorithms-keeper commands and options
algorithms-keeper actions can be triggered by commenting on this PR:
@algorithms-keeper reviewto trigger the checks for only added pull request files@algorithms-keeper review-allto trigger the checks for all the pull request files, including the modified files. As we cannot post review comments on lines not part of the diff, this command will post all the messages in one comment.NOTE: Commands are in beta and so this feature is restricted only to a member or owner of the organization.
| import bisect | ||
|
|
||
|
|
||
| def library_sort( |
There was a problem hiding this comment.
As there is no test file in this pull request nor any test function or class in the file sorts/library_sort.py, please provide doctest for the function library_sort
| A_vals[mid] = keyed[0][1] | ||
| pos.append(mid) | ||
|
|
||
| def rebalance(target_count: int) -> None: |
There was a problem hiding this comment.
As there is no test file in this pull request nor any test function or class in the file sorts/library_sort.py, please provide doctest for the function rebalance
|
|
||
| A_keys, A_vals, pos = new_keys, new_vals, new_pos | ||
|
|
||
| def desired_slot(rank: int) -> int: |
There was a problem hiding this comment.
As there is no test file in this pull request nor any test function or class in the file sorts/library_sort.py, please provide doctest for the function desired_slot
| cap = max(3, int((1.0 + epsilon) * n) + 1) | ||
|
|
||
| # Sparse physical storage for keys/values; None marks a gap (empty slot). | ||
| A_keys: List[Optional[Tuple]] = [None] * cap |
There was a problem hiding this comment.
Variable and function names should follow the snake_case naming convention. Please update the following name accordingly: A_keys
|
|
||
| # Sparse physical storage for keys/values; None marks a gap (empty slot). | ||
| A_keys: List[Optional[Tuple]] = [None] * cap | ||
| A_vals: List[Optional[object]] = [None] * cap |
There was a problem hiding this comment.
Variable and function names should follow the snake_case naming convention. Please update the following name accordingly: A_vals
| new_vals[new_index] = A_vals[old_idx] | ||
| new_pos.append(new_index) | ||
|
|
||
| A_keys, A_vals, pos = new_keys, new_vals, new_pos |
There was a problem hiding this comment.
Variable and function names should follow the snake_case naming convention. Please update the following name accordingly: A_keys
Variable and function names should follow the snake_case naming convention. Please update the following name accordingly: A_vals
| return items.copy() | ||
|
|
||
| # Normalize to a key/value representation so we can sort arbitrary objects. | ||
| key_fn = key if key is not None else (lambda x: x) |
There was a problem hiding this comment.
Please provide descriptive name for the parameter: x
There was a problem hiding this comment.
Click here to look at the relevant links ⬇️
🔗 Relevant Links
Repository:
Python:
Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.
algorithms-keeper commands and options
algorithms-keeper actions can be triggered by commenting on this PR:
@algorithms-keeper reviewto trigger the checks for only added pull request files@algorithms-keeper review-allto trigger the checks for all the pull request files, including the modified files. As we cannot post review comments on lines not part of the diff, this command will post all the messages in one comment.NOTE: Commands are in beta and so this feature is restricted only to a member or owner of the organization.
| import bisect | ||
|
|
||
|
|
||
| def library_sort( |
There was a problem hiding this comment.
As there is no test file in this pull request nor any test function or class in the file sorts/library_sort.py, please provide doctest for the function library_sort
| A_vals[mid] = keyed[0][1] | ||
| pos.append(mid) | ||
|
|
||
| def rebalance(target_count: int) -> None: |
There was a problem hiding this comment.
As there is no test file in this pull request nor any test function or class in the file sorts/library_sort.py, please provide doctest for the function rebalance
|
|
||
| A_keys, A_vals, pos = new_keys, new_vals, new_pos | ||
|
|
||
| def desired_slot(rank: int) -> int: |
There was a problem hiding this comment.
As there is no test file in this pull request nor any test function or class in the file sorts/library_sort.py, please provide doctest for the function desired_slot
| cap = max(3, int((1.0 + epsilon) * n) + 1) | ||
|
|
||
| # Sparse physical storage for keys/values; None marks a gap (empty slot). | ||
| A_keys: List[Optional[Tuple]] = [None] * cap |
There was a problem hiding this comment.
Variable and function names should follow the snake_case naming convention. Please update the following name accordingly: A_keys
|
|
||
| # Sparse physical storage for keys/values; None marks a gap (empty slot). | ||
| A_keys: List[Optional[Tuple]] = [None] * cap | ||
| A_vals: List[Optional[object]] = [None] * cap |
There was a problem hiding this comment.
Variable and function names should follow the snake_case naming convention. Please update the following name accordingly: A_vals
| new_vals[new_index] = A_vals[old_idx] | ||
| new_pos.append(new_index) | ||
|
|
||
| A_keys, A_vals, pos = new_keys, new_vals, new_pos |
There was a problem hiding this comment.
Variable and function names should follow the snake_case naming convention. Please update the following name accordingly: A_keys
Variable and function names should follow the snake_case naming convention. Please update the following name accordingly: A_vals
| return items.copy() | ||
|
|
||
| # Normalize to a key/value representation so we can sort arbitrary objects. | ||
| key_fn = key if key is not None else (lambda x: x) |
There was a problem hiding this comment.
Please provide descriptive name for the parameter: x
algorithms-keeper
Bot
removed
the
awaiting reviews
2 participants
Title
Enhance: Add Library Sort (gapped insertion) with docs and examples
Summary
Adds an educational, well-documented implementation of Library Sort (gapped insertion) to the sorts directory, including key/reverse parameters, gap rebalancing, and a minimal example script for quick verification. This provides learners with a practical, annotated reference for a distribution-aware insertion strategy.
What’s included
New: sorts/library_sort.py implementing Library Sort with:
key and reverse parameters aligned with Python’s sorting API.
epsilon parameter to control gap density and rebalance behavior.
detailed docstrings and inline comments explaining the data structures (gapped arrays, logical positions) and the rebalance heuristic.
Example: main block demonstrating usage with a small dataset.
Complexity notes in the header docstring: average O(n log n) with high probability, worst O(n^2), space O(n(1+epsilon)).
Motivation
Teaches a lesser-known, research-backed variant of insertion sort that achieves expected O(n log n) by maintaining evenly distributed gaps and rebalancing when clusters form. Ideal for learners comparing practical sort designs beyond classic algorithms.
Implementation notes
Uses a sparse backing array for keys/values plus a “pos” list for logical order; insertions do a binary search on logical order and choose a midpoint slot, rebalancing when local density prevents gap placement.
API mirrors built-in sorted where practical, enabling side-by-side comparison in exercises and tests.
How to test
Run the built-in example:
python sorts/library_sort.py should print a sorted “After:” list.
Sanity checks (suggested):
Compare against sorted on random arrays and edge cases (empty, single element, duplicates).
Verify key and reverse, e.g., key=lambda x: x % 10 and reverse=True.
Scope and trade-offs
Focuses on pedagogy and clarity; not a drop-in replacement for Timsort in production scenarios. For arbitrary real-world data, Python’s built-in sort remains recommended due to stability and adaptiveness.
Library Sort worst case remains O(n^2); documentation calls this out to set correct expectations.
Related
Closes #13203 (advanced sorting algorithms request).
References: Bender et al., “Insertion Sort is O(n log n)” (Library Sort analysis); Wikipedia overview for algorithm characteristics.