0
# natsort
1
2
Simple yet flexible natural sorting in Python that enables you to sort strings containing numbers in a natural, human-expected order rather than lexicographical order. It provides multiple sorting functions including natsorted() for basic natural sorting, realsorted() for handling signed floats, humansorted() for locale-aware sorting, and os_sorted() for file system path sorting that matches operating system file browsers.
3
4
## Package Information
5
6
- **Package Name**: natsort
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install natsort`
10
11
## Core Imports
12
13
```python
14
from natsort import natsorted
15
```
16
17
Common imports for various functionality:
18
19
```python
20
from natsort import natsorted, humansorted, realsorted, os_sorted
21
from natsort import ns, natsort_keygen, index_natsorted
22
```
23
24
Full package import:
25
26
```python
27
import natsort
28
```
29
30
## Basic Usage
31
32
```python
33
from natsort import natsorted
34
35
# Basic natural sorting
36
a = ['num3', 'num5', 'num2', 'num10', 'num1']
37
sorted_list = natsorted(a)
38
print(sorted_list) # ['num1', 'num2', 'num3', 'num5', 'num10']
39
40
# Compare with built-in sorted (lexicographical)
41
regular_sorted = sorted(a)
42
print(regular_sorted) # ['num1', 'num10', 'num2', 'num3', 'num5']
43
44
# Sorting with mixed content
45
mixed = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
46
natural_order = natsorted(mixed)
47
print(natural_order) # ['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
48
49
# Real number sorting with signed floats
50
numbers = ['num5.10', 'num-3', 'num5.3', 'num2']
51
real_sorted = realsorted(numbers)
52
print(real_sorted) # ['num-3', 'num2', 'num5.10', 'num5.3']
53
```
54
55
## Architecture
56
57
natsort operates through a key-generation approach where:
58
59
- **Input Processing**: Strings are split into numeric and non-numeric components
60
- **Component Transformation**: Numbers are converted to their numeric values while preserving original string context
61
- **Algorithm Control**: The `ns` enum provides fine-grained control over sorting behavior (case sensitivity, locale handling, number interpretation)
62
- **Key Functions**: Generated keys enable both one-time sorting and reusable key generation for performance
63
- **Multiple Interfaces**: Core sorting functions, index-based sorting, and key generation functions provide flexibility
64
65
## Capabilities
66
67
### Core Sorting Functions
68
69
Primary sorting functions that provide natural ordering for different data types and use cases, including basic natural sorting, locale-aware sorting, real number handling, and OS-compatible file path sorting.
70
71
```python { .api }
72
def natsorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
73
def humansorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
74
def realsorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
75
def os_sorted(seq, key=None, reverse=False, presort=False): ...
76
```
77
78
[Core Sorting](./core-sorting.md)
79
80
### Index-Based Sorting
81
82
Functions that return sorted indexes rather than sorted sequences, enabling you to sort multiple related sequences by the sort order of one sequence.
83
84
```python { .api }
85
def index_natsorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
86
def index_humansorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
87
def index_realsorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
88
def order_by_index(seq, index, iter=False): ...
89
```
90
91
[Index Sorting](./index-sorting.md)
92
93
### Key Generation Functions
94
95
Functions for generating reusable sorting key functions that can be used with Python's built-in sorting functions for better performance when sorting multiple times.
96
97
```python { .api }
98
def natsort_keygen(key=None, alg=ns.DEFAULT): ...
99
def os_sort_keygen(key=None): ...
100
```
101
102
```python { .api }
103
# Pre-generated key functions
104
natsort_key: Callable
105
os_sort_key: Callable
106
```
107
108
[Key Generation](./key-generation.md)
109
110
### Algorithm Configuration
111
112
The `ns` enum system that provides fine-grained control over natural sorting behavior, including number interpretation, case sensitivity, locale handling, and path-specific options.
113
114
```python { .api }
115
class ns(enum.IntEnum):
116
# Number handling
117
DEFAULT = 0
118
INT = I = 0
119
UNSIGNED = U = 0
120
FLOAT = F = 1
121
SIGNED = S = 2
122
REAL = R = 3 # FLOAT | SIGNED
123
NOEXP = N = 4
124
125
# String handling
126
IGNORECASE = IC = 64
127
LOWERCASEFIRST = LF = 128
128
GROUPLETTERS = G = 256
129
UNGROUPLETTERS = CAPITALFIRST = C = UG = 512
130
131
# Locale and path handling
132
LOCALEALPHA = LA = 16
133
LOCALENUM = LN = 32
134
LOCALE = L = 48 # LOCALEALPHA | LOCALENUM
135
PATH = P = 8
136
137
# Special options
138
NANLAST = NL = 1024
139
COMPATIBILITYNORMALIZE = CN = 2048
140
NUMAFTER = NA = 4096
141
PRESORT = PS = 8192
142
```
143
144
[Algorithm Configuration](./algorithm-configuration.md)
145
146
### Utilities and Text Processing
147
148
Utility functions for text processing, decoding, and command-line interface functionality.
149
150
```python { .api }
151
def decoder(encoding): ...
152
def as_ascii(s): ...
153
def as_utf8(s): ...
154
def chain_functions(functions): ...
155
def numeric_regex_chooser(alg): ...
156
```
157
158
[Utilities](./utilities.md)
159
160
## Types
161
162
```python { .api }
163
from typing import Callable, List, Optional, Union, Any, Iterable, Tuple
164
165
# Core type aliases
166
NatsortInType = Optional[Any] # Input type for natsort functions
167
NatsortOutType = Tuple[Any, ...] # Output type from key functions
168
KeyType = Callable[[Any], NatsortInType] # Custom key function type
169
NatsortKeyType = Callable[[NatsortInType], NatsortOutType] # Natsort key function type
170
OSSortKeyType = Callable[[NatsortInType], NatsortOutType] # OS sort key function type
171
NSType = Union[ns, int] # Algorithm specification type
172
```