Metadata-Version: 2.1
Name: django-natural-sort
Version: 0.1.1
Summary: Natural sorting for Django and Django REST Framework
Home-page: https://github.com/akindele214/django-natural-sort
Author: Lekan Akindele
Author-email: lekan.akindele12@gmail.com
Project-URL: Bug Tracker, https://github.com/akindele214/django-natural-sort/issues
Project-URL: Documentation, https://github.com/akindele214/django-natural-sort
Project-URL: Source Code, https://github.com/akindele214/django-natural-sort
Keywords: django,drf,natural sort,sorting,ordering
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django >=3.2
Requires-Dist: djangorestframework >=3.9.0

# Django Natural Sort

![PyPI](https://img.shields.io/pypi/v/django-natural-sort)
![PyPI - License](https://img.shields.io/pypi/l/django-natural-sort)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-natural-sort)
![PyPI - Django Version](https://img.shields.io/pypi/djversions/django-natural-sort)

A  lightweight, efficient package for natural sorting in Django and Django REST Framework.

## The Problem

By default, when you order strings containing numbers in Django or DRF, they're sorted lexicographically:

```
['1', '10', '11', '12', '2', '3', '4', '5', '6', '7', '8', '9']
```

This is not the expected order for humans, who would expect:

```
['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12']
```

This package solves this issue by implementing natural sorting, where numbers within strings are treated as actual numbers rather than individual characters.

## Installation

```bash
pip install django-natural-sort
```

## Usage

### In Django REST Framework Views

```python
from django_natural_sort.filters import NaturalOrderingFilter

class MyModelViewSet(viewsets.ModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer
    filter_backends = [NaturalOrderingFilter]
    ordering_fields = ['id', 'name', 'version']
```

This automatically applies natural sorting to any `CharField`, `EmailField`, or `TextField` in your model when used in ordering. Just use the standard ordering parameter:

```
GET /api/mymodel/?ordering=version
```

## Features

- **Efficient**: Uses database ordering for non-string fields, only falls back to Python sorting when necessary
- **Compatible**: Works with Django 3.2+ and Django REST Framework 3.11.1+
- **Lightweight**: No external dependencies
- **Flexible**: Works with various string field types (CharField, TextField, EmailField)
- **Robust**: Handles edge cases like mixed types, None values, and more

## How It Works

The package detects which fields in your model are string fields. When ordering by these fields, it uses a natural sorting algorithm that correctly handles numbers embedded in strings.

For non-string fields, it uses the database's built-in ordering mechanism for optimal performance.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.
