Metadata-Version: 2.4
Name: natsort-rs
Version: 0.1.17
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
License-File: LICENSE
Summary: A blazing fast natural sorting library for Python
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/valentinstn/natsort-rs
Project-URL: Repository, https://github.com/valentinstn/natsort-rs
Project-URL: Changelog, https://github.com/valentinstn/natsort-rs/blob/main/CHANGELOG.md

<h1 align="center">natsort-rs</h1>
<p align="center">
    <em>🚀 A blazing fast natural sorting library for Python written in Rust 🦀</em>
</p>

## Installation

```
pip install natsort-rs
```

## Usage

```py
from natsort_rs import natsort
```

### Sort a list of strings

```py
items = ['item 1', 'item 10', 'item 3']
print(natsort(items))  
# ['item 1', 'item 3', 'item 10']
```

### Sort case insensitively

```py
items = ['Item 1', 'Item 3', 'item 2']
print(natsort(items, ignore_case=True))
# ['Item 1', 'item 2', 'Item 3']
```

### Sort complex objects based on property

```py
items = [
    {'name': 'item 1', 'id': 1},
    {'name': 'item 3', 'id': 3},
    {'name': 'item 2', 'id': 2}
]
print(natsort(items, key=lambda d: d['name']))
# [{'name': 'item 1', 'id': 1}, {'name': 'item 2', 'id': 2}, {'name': 'item 3', 'id': 3}]
```

### Return the sorting indices

This can be helpful if you only want to get the sorted indices returned, that makes the performance-critical part
useful for custom sorting use cases:

```py
items = ['item 1', 'item 10', 'item 3']
print(natsort(items, return_indices=True))  
# [0, 2, 1]
```

## Benchmark

| No. of items | Duration natsort [s] | Duration natsort-rs [s] | Relative speedup |
|-----|-----|-----|-----|
| 10 | 0.00006 | 0.00000 | 16.8 |
| 100 | 0.00094 | 0.00002 | 44.3 |
| 1000 | 0.00281 | 0.00022 | 12.7 |
| 10000 | 0.02835 | 0.00262 | 10.8 |
| 100000 | 0.29712 | 0.03334 | 8.9 |
| 1000000 | 3.31207 | 0.45333 | 7.3 |

Execute `benchmark.py` to reproduce the results.

## Development

### Local build

To build and test the package locally using `uv`:

```bash
uv run maturin develop --release
```

### Running benchmarks

To run benchmarks:

```bash
uv run benchmark.py
```

This will compare the performance of `natsort-rs` against the pure Python `natsort` library and display results in a table format.

## Credits

This Python module is build on top of the [`natord`](https://docs.rs/natord/latest/natord/) crate and inspired by [`natsort`](https://pypi.org/project/natsort/).


## License

MIT License
