Metadata-Version: 2.4
Name: gsort
Version: 1.0.4
Summary: Adaptive Python sorting library with native C++ algorithms.
Author: Gayathri Chilukuri
License: MIT
Project-URL: Homepage, https://github.com/GayathriChilukuri/gsort
Project-URL: Repository, https://github.com/GayathriChilukuri/gsort
Project-URL: Issues, https://github.com/GayathriChilukuri/gsort/issues
Keywords: sorting,algorithms,python,radix-sort,counting-sort,bucket-sort,adaptive
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gsort

A Python sorting library that automatically chooses the best available sorting algorithm for your data.

For most datasets, `gsort` works just like Python's built-in `sorted()`. When it detects data that can benefit from specialized algorithms, it automatically uses optimized native implementations instead.

---

## Installation

```bash
pip install gsort
```

---

# When should I use gsort?

`gsort` is recommended for:

* Large datasets of integers with a small value range (marks, ages, ratings, RGB values)
* Large collections of 32-bit unsigned integers
* Floating-point values uniformly distributed between `0` and `1`
* When you want automatic algorithm selection
* Learning and experimenting with different sorting techniques

---

# When is it **not** recommended?

For small datasets, already sorted lists, strings, or general-purpose data, Python's built-in `sorted()` is usually the better choice.

---

# Usage

Import the library:

```python
from gsort import gsort
```

### Automatic selection (recommended)

```python
sorted_data = gsort(data)
```

or

```python
sorted_data = gsort(data, "decide")
```

### Choose an algorithm yourself

```python
gsort(data, "counting")
gsort(data, "radix")
gsort(data, "bucket")
gsort(data, "timsort")
```

### Explain why an algorithm was chosen

```python
sorted_data, info = gsort(data, explain=True)

print(info["chosen_algorithm"])
print(info["reasons"])
```

Example output:

```text
counting
Small integer range detected; native Counting Sort selected.
```

---

# Example

```python
from random import randint
from time import perf_counter

from gsort import gsort

# Large dataset with a small integer range
data = [randint(0, 100) for _ in range(200000)]

# Python's built-in sorted()
start = perf_counter()
python_sorted = sorted(data)
python_time = (perf_counter() - start) * 1000

# gsort
start = perf_counter()
gsort_sorted, info = gsort(data, explain=True)
gsort_time = (perf_counter() - start) * 1000

print(f"Python sorted(): {python_time:.3f} ms")
print(f"gsort          : {gsort_time:.3f} ms")
print(f"Algorithm      : {info['chosen_algorithm']}")
print(f"Reason         : {info['reasons'][0]}")
```

---

# Supported Algorithms

* Counting Sort (Native C++)
* Radix Sort (Native C++)
* Bucket Sort (Native C++)
* TimSort

---

# License

MIT License.
