0
# Core Sorting Functions
1
2
Primary sorting functions that provide natural ordering for different data types and use cases. These functions serve as drop-in replacements for Python's built-in `sorted()` function but with natural number ordering.
3
4
## Capabilities
5
6
### Natural Sorting
7
8
Sorts an iterable naturally, treating numbers within strings as their numeric values rather than lexicographically.
9
10
```python { .api }
11
def natsorted(seq, key=None, reverse=False, alg=ns.DEFAULT):
12
"""
13
Sorts an iterable naturally.
14
15
Parameters:
16
- seq: iterable - The input to sort
17
- key: callable, optional - A key function to determine sorting
18
- reverse: bool, optional - Return in reversed order (default: False)
19
- alg: ns enum, optional - Algorithm control flags (default: ns.DEFAULT)
20
21
Returns:
22
List - The sorted input
23
24
Examples:
25
>>> natsorted(['num3', 'num5', 'num2'])
26
['num2', 'num3', 'num5']
27
28
>>> natsorted(['version1.10', 'version1.2', 'version1.9'])
29
['version1.2', 'version1.9', 'version1.10']
30
"""
31
```
32
33
### Human-Friendly Sorting
34
35
Convenience function for locale-aware sorting that properly handles non-ASCII characters and follows human sorting expectations.
36
37
```python { .api }
38
def humansorted(seq, key=None, reverse=False, alg=ns.DEFAULT):
39
"""
40
Convenience function to properly sort non-numeric characters.
41
42
This is a wrapper around natsorted(seq, alg=ns.LOCALE).
43
44
Parameters:
45
- seq: iterable - The input to sort
46
- key: callable, optional - A key function to determine sorting
47
- reverse: bool, optional - Return in reversed order (default: False)
48
- alg: ns enum, optional - Additional algorithm flags (default: ns.DEFAULT)
49
50
Returns:
51
List - The sorted input with locale-aware character ordering
52
53
Examples:
54
>>> humansorted(['Apple', 'Banana', 'apple', 'banana'])
55
['apple', 'Apple', 'banana', 'Banana']
56
57
Notes:
58
Locale support varies by system. Install PyICU for best results.
59
"""
60
```
61
62
### Real Number Sorting
63
64
Convenience function for properly sorting strings containing signed floating point numbers.
65
66
```python { .api }
67
def realsorted(seq, key=None, reverse=False, alg=ns.DEFAULT):
68
"""
69
Convenience function to properly sort signed floats.
70
71
A signed float in a string could be "a-5.7". This is a wrapper around
72
natsorted(seq, alg=ns.REAL).
73
74
Parameters:
75
- seq: iterable - The input to sort
76
- key: callable, optional - A key function to determine sorting
77
- reverse: bool, optional - Return in reversed order (default: False)
78
- alg: ns enum, optional - Additional algorithm flags (default: ns.DEFAULT)
79
80
Returns:
81
List - The sorted input with proper signed float handling
82
83
Examples:
84
>>> realsorted(['num5.10', 'num-3', 'num5.3', 'num2'])
85
['num-3', 'num2', 'num5.10', 'num5.3']
86
"""
87
```
88
89
### Operating System File Sorting
90
91
Sort elements in the same order as your operating system's file browser, providing OS-native file ordering.
92
93
```python { .api }
94
def os_sorted(seq, key=None, reverse=False, presort=False):
95
"""
96
Sort elements in the same order as your operating system's file browser.
97
98
Platform-specific sorting that matches file explorer behavior on Windows,
99
macOS, and Linux systems.
100
101
Parameters:
102
- seq: iterable - The input to sort (each element must be str-like)
103
- key: callable, optional - A key function to determine sorting
104
- reverse: bool, optional - Return in reversed order (default: False)
105
- presort: bool, optional - Pre-sort as strings first (default: False)
106
107
Returns:
108
List - The sorted input in OS-native file browser order
109
110
Examples:
111
>>> os_sorted(['file10.txt', 'file2.txt', 'File1.txt'])
112
# Result varies by operating system
113
114
Notes:
115
- On Windows: Uses Windows Explorer sorting via StrCmpLogicalW
116
- On macOS/Linux: Uses ICU collation if available, falls back to locale-aware sorting
117
- Results intentionally differ between platforms to match OS behavior
118
- Install PyICU on macOS/Linux for best results
119
"""
120
```
121
122
## Usage Examples
123
124
### Basic Natural Sorting
125
126
```python
127
from natsort import natsorted
128
129
# File names with numbers
130
files = ['file1.txt', 'file10.txt', 'file2.txt', 'file20.txt']
131
print(natsorted(files))
132
# Output: ['file1.txt', 'file2.txt', 'file10.txt', 'file20.txt']
133
134
# Version strings
135
versions = ['v1.0.10', 'v1.0.2', 'v1.0.1', 'v1.1.0']
136
print(natsorted(versions))
137
# Output: ['v1.0.1', 'v1.0.2', 'v1.0.10', 'v1.1.0']
138
```
139
140
### Advanced Algorithm Control
141
142
```python
143
from natsort import natsorted, ns
144
145
# Case-insensitive sorting
146
mixed_case = ['Item1', 'item10', 'Item2', 'item20']
147
print(natsorted(mixed_case, alg=ns.IGNORECASE))
148
# Output: ['Item1', 'Item2', 'item10', 'item20']
149
150
# Float number handling
151
floats = ['value1.5', 'value1.10', 'value1.05']
152
print(natsorted(floats, alg=ns.FLOAT))
153
# Output: ['value1.05', 'value1.5', 'value1.10']
154
155
# Path sorting
156
paths = ['folder/file10.txt', 'folder/file2.txt', 'folder/file1.txt']
157
print(natsorted(paths, alg=ns.PATH))
158
# Output: ['folder/file1.txt', 'folder/file2.txt', 'folder/file10.txt']
159
```
160
161
### Custom Key Functions
162
163
```python
164
from natsort import natsorted
165
from pathlib import Path
166
167
# Sort by filename only (ignore path)
168
file_paths = ['/path/to/file10.txt', '/other/file2.txt', '/path/file1.txt']
169
sorted_by_name = natsorted(file_paths, key=lambda x: Path(x).name)
170
print(sorted_by_name)
171
# Output: ['/path/file1.txt', '/other/file2.txt', '/path/to/file10.txt']
172
173
# Sort custom objects
174
class Version:
175
def __init__(self, version_str):
176
self.version = version_str
177
178
def __repr__(self):
179
return f"Version('{self.version}')"
180
181
versions = [Version('1.10.0'), Version('1.2.0'), Version('1.9.0')]
182
sorted_versions = natsorted(versions, key=lambda v: v.version)
183
print(sorted_versions)
184
# Output: [Version('1.2.0'), Version('1.9.0'), Version('1.10.0')]
185
```