{"id":28066812,"url":"https://github.com/grantjenks/python-selectlib","last_synced_at":"2025-05-12T15:54:50.472Z","repository":{"id":275503825,"uuid":"926270543","full_name":"grantjenks/python-selectlib","owner":"grantjenks","description":"selectlib is a lightweight C extension module for Python that implements several in‑place selection algorithms for efficiently finding the kth smallest element in an unsorted list.","archived":false,"fork":false,"pushed_at":"2025-02-05T05:17:37.000Z","size":867,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-12T00:45:46.839Z","etag":null,"topics":["c","kth","python","sorting"],"latest_commit_sha":null,"homepage":"https://github.com/grantjenks/python-selectlib","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grantjenks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-02T23:41:43.000Z","updated_at":"2025-04-11T09:12:21.000Z","dependencies_parsed_at":"2025-02-03T00:36:18.745Z","dependency_job_id":null,"html_url":"https://github.com/grantjenks/python-selectlib","commit_stats":null,"previous_names":["grantjenks/python-selectlib"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantjenks%2Fpython-selectlib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantjenks%2Fpython-selectlib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantjenks%2Fpython-selectlib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantjenks%2Fpython-selectlib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grantjenks","download_url":"https://codeload.github.com/grantjenks/python-selectlib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253770422,"owners_count":21961769,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","kth","python","sorting"],"created_at":"2025-05-12T15:54:49.784Z","updated_at":"2025-05-12T15:54:50.460Z","avatar_url":"https://github.com/grantjenks.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# selectlib\n\nselectlib is a lightweight C extension module for Python that implements several in‑place selection algorithms for efficiently finding the kth smallest element in an unsorted list. The module provides three main functions—`nth_element`, `quickselect`, and `heapselect`—that allow you to partition a list so that the element at a given index is in its final sorted position, without performing a full sort.\n\nYou can install selectlib using pip:\n\n```bash\npython -m pip install selectlib\n```\n\n## Features\n\n- **In‑place partitioning using three different strategies:**\n  - **`nth_element`:** An adaptive selection function that chooses the optimal strategy based on the target index. For small indices, it uses the heapselect method; otherwise, it starts with quickselect and falls back to heapselect if necessary.\n  - **`quickselect`:** A classic partition‑based selection algorithm that uses random pivots to position the kth smallest element in its correct sorted order. If the operation exceeds an iteration limit, it automatically falls back to heapselect.\n  - **`heapselect`:** A heap‑based approach that builds a fixed‑size max‑heap to efficiently locate the kth smallest element.\n- **Performance as a feature!**\n  Selectlib comes with benchmark scripts that run multiple tests for varying list sizes and selection percentages, then produce visual output as grouped bar charts.\n- **Median Benchmarking:**\n  In addition to the benchmark for selecting the k‑smallest elements, selectlib provides a dedicated median benchmark script (`benchmark_median.py`) that compares Python’s built‑in `statistics.median_low` with selectlib’s `nth_element`, `quickselect`, and `heapselect` methods for computing the median of a list. This benchmark runs the tests for list sizes ranging from 1,000 to 1,000,000 elements and displays the median computation performance in a grouped bar chart.\n\n## Usage Example\n\nBelow is an example demonstrating how to use each of the three selection algorithms to find the kth smallest element in a list:\n\n```python\nimport selectlib\n\ndata = [9, 3, 7, 1, 5, 8, 2]\nk = 3  # We wish to position the element at index 3, as in a sorted list\n\n# Using nth_element:\nselectlib.nth_element(data, k)\nprint(\"After nth_element, kth smallest element is:\", data[k])\n\n# Reset the list for a fresh example:\ndata = [9, 3, 7, 1, 5, 8, 2]\n\n# Using quickselect:\nselectlib.quickselect(data, k)\nprint(\"After quickselect, kth smallest element is:\", data[k])\n\n# Reset the list:\ndata = [9, 3, 7, 1, 5, 8, 2]\n\n# Using heapselect:\nselectlib.heapselect(data, k)\nprint(\"After heapselect, kth smallest element is:\", data[k])\n```\n\nYou can also provide an optional key function to customize comparisons. For example, if you wish to determine the kth largest element rather than the kth smallest, simply negate the value in a lambda function:\n\n```python\ndata = [15, 8, 22, 5, 13]\nk = 2\nselectlib.quickselect(data, k, key=lambda x: -x)\nprint(\"The kth largest element is:\", data[k])\n```\n\n## Median Benchmarking\n\nIn addition to the k‑smallest elements benchmark, selectlib provides a median benchmark script named `benchmark_median.py`. This script compares the performance of the following methods for computing the median (using the low median for even‑length lists):\n\n1. **`median_low`** – Uses Python’s built‑in `statistics.median_low`.\n2. **`nth_element`** – Uses `selectlib.nth_element` to partition the list so that the median element is in place.\n3. **`quickselect`** – Uses `selectlib.quickselect` for median selection.\n4. **`heapselect`** – Uses `selectlib.heapselect` for median selection.\n\nFor each list size (from 1,000 to 1,000,000 elements), the script runs 5 iterations and records the median runtime. The performance results are then plotted as a grouped bar chart, with each group corresponding to a different list size.\n\n![Median Benchmark Results](https://github.com/grantjenks/python-selectlib/blob/main/plot_median.png?raw=true)\n\nTo run the median benchmark, execute:\n\n```bash\npython benchmark_median.py\n```\n\n## K-Smallest Benchmarking\n\nSelectlib comes with a benchmark script named `benchmark.py` that compares the following five methods to obtain the K smallest items from a list:\n\n1. **`sort`** – Creates a sorted copy of the list and slices the first k elements.\n2. **`heapq.nsmallest`** – Uses Python’s standard library heap algorithm.\n3. **`quickselect`** – Partitions using `selectlib.quickselect`, then slices and sorts the first k elements.\n4. **`heapselect`** – Partitions using `selectlib.heapselect`, then slices and sorts the first k elements.\n5. **`nth_element`** – Partitions using `selectlib.nth_element`, then slices and sorts the first k elements.\n\nFor each list size (ranging from 1,000 to 1,000,000 elements) and for several values of k (0.2%, 1%, 10%, and 25% of N), each method is executed five times, and the median runtime is recorded. The benchmark results are then visualized as grouped bar charts.\n\n![Benchmark Results](https://github.com/grantjenks/python-selectlib/blob/main/plot.png?raw=true)\n\nTo run the benchmark, execute:\n\n```bash\npython benchmark.py\n```\n\n## Development \u0026 Continuous Integration\n\nBefore installing locally, ensure you have a C compiler and the Python development headers installed for your platform.\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/grantjenks/python-selectlib.git\n   cd python-selectlib\n   ```\n\n2. **Build and install in editable mode:**\n\n   ```bash\n   python -m pip install -e .\n   ```\n\nThis project uses GitHub Actions for CI/CD. The available workflows cover:\n\n- **release.yml** – Builds wheels for multiple platforms and publishes packages to PyPI.\n- **test.yml** – Runs automated tests and linting on multiple Python versions.\n\n## License\n\nselectlib is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for full details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantjenks%2Fpython-selectlib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrantjenks%2Fpython-selectlib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantjenks%2Fpython-selectlib/lists"}