1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
.. default-domain:: py
.. currentmodule:: natsort
.. _api:
natsort API
===========
.. contents::
:local:
Standard API
------------
:func:`~natsort.natsorted`
++++++++++++++++++++++++++
.. autofunction:: natsorted
The :class:`~natsort.ns` enum
+++++++++++++++++++++++++++++
.. autodata:: ns
:annotation:
:func:`~natsort.natsort_key`
++++++++++++++++++++++++++++
.. autofunction:: natsort_key
:func:`~natsort.natsort_keygen`
+++++++++++++++++++++++++++++++
.. autofunction:: natsort_keygen
:func:`~natsort.os_sort_key`
++++++++++++++++++++++++++++
.. autofunction:: os_sort_key
:func:`~natsort.os_sort_keygen`
+++++++++++++++++++++++++++++++
.. autofunction:: os_sort_keygen
Convenience Functions
---------------------
:func:`~natsort.os_sorted`
+++++++++++++++++++++++++++
.. autofunction:: os_sorted
:func:`~natsort.realsorted`
+++++++++++++++++++++++++++
.. autofunction:: realsorted
:func:`~natsort.humansorted`
++++++++++++++++++++++++++++
.. autofunction:: humansorted
:func:`~natsort.index_natsorted`
++++++++++++++++++++++++++++++++
.. autofunction:: index_natsorted
:func:`~natsort.index_realsorted`
+++++++++++++++++++++++++++++++++
.. autofunction:: index_realsorted
:func:`~natsort.index_humansorted`
++++++++++++++++++++++++++++++++++
.. autofunction:: index_humansorted
:func:`~natsort.order_by_index`
+++++++++++++++++++++++++++++++
.. autofunction:: order_by_index
.. _bytes_help:
Help With Bytes
+++++++++++++++
The official stance of :mod:`natsort` is to not support `bytes` for
sorting; there is just too much that can go wrong when trying to automate
conversion between `bytes` and `str`. But rather than completely give up
on `bytes`, :mod:`natsort` provides three functions that make it easy to
quickly decode `bytes` to `str` so that sorting is possible.
.. autofunction:: decoder
.. autofunction:: as_ascii
.. autofunction:: as_utf8
.. _function_help:
Help With Creating Function Keys
++++++++++++++++++++++++++++++++
If you need to create a complicated *key* argument to (for example)
:func:`natsorted` that is actually multiple functions called one after the
other, the following function can help you easily perform this action. It is
used internally to :mod:`natsort`, and has been exposed publicly for
the convenience of the user.
.. autofunction:: chain_functions
If you need to be able to search your input for numbers using the same
definition as :mod:`natsort`, you can do so using the following function.
Given your chosen algorithm (selected using the :class:`~natsort.ns` enum),
the corresponding regular expression to locate numbers will be returned.
.. autofunction:: numeric_regex_chooser
Help With Type Hinting
++++++++++++++++++++++
If you need to explicitly specify the types that natsort accepts or returns
in your code, the following types have been exposed for your convenience.
+--------------------------------+----------------------------------------------------------------------------------------+
| Type | Purpose |
+================================+========================================================================================+
|:attr:`natsort.NatsortKeyType` | Returned by :func:`natsort.natsort_keygen`, and type of :attr:`natsort.natsort_key` |
+--------------------------------+----------------------------------------------------------------------------------------+
|:attr:`natsort.OSSortKeyType` | Returned by :func:`natsort.os_sort_keygen`, and type of :attr:`natsort.os_sort_key` |
+--------------------------------+----------------------------------------------------------------------------------------+
|:attr:`natsort.KeyType` | Type of `key` argument to :func:`natsort.natsorted` and :func:`natsort.natsort_keygen` |
+--------------------------------+----------------------------------------------------------------------------------------+
|:attr:`natsort.NatsortInType` | The input type of :attr:`natsort.NatsortKeyType` |
+--------------------------------+----------------------------------------------------------------------------------------+
|:attr:`natsort.NatsortOutType` | The output type of :attr:`natsort.NatsortKeyType` |
+--------------------------------+----------------------------------------------------------------------------------------+
|:attr:`natsort.NSType` | The type of the :class:`ns` enum |
+--------------------------------+----------------------------------------------------------------------------------------+
|
