### Install natsort with Optional Dependencies

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Instructions for installing natsort with its optional dependencies, fastnumbers and PyICU, using pip's 'extras' notation. This allows users to include performance enhancements or advanced Unicode support during installation.

```console
# Install both optional dependencies.
$ pip install natsort[fast,icu]
# Install just fastnumbers
$ pip install natsort[fast]
```

--------------------------------

### Installing Natsort Library via Pip

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

This snippet provides the command-line instruction to install the `natsort` library using the pip package manager. It is the standard method for installing Python packages.

```Shell
$ pip install natsort
```

--------------------------------

### Verify natsort Package Installation

Source: https://github.com/sethmmorton/natsort/blob/main/RELEASING.md

This command sequence uninstalls the existing 'natsort' package and then reinstalls it from PyPI. It's used to verify that the newly deployed package can be installed correctly by users.

```bash
python -m pip uninstall -y natsort && python -m pip install -U natsort
```

--------------------------------

### Run natsort Tests using Tox

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Explains the recommended method for running natsort's tests using the tox automation tool. Tox automatically sets up virtual environments and installs testing requirements, supporting specific Python versions with the '-e' flag and static analysis with 'tox -e flake8'.

```console
$ tox
```

--------------------------------

### Sort Files Like a File Browser with natsort's os_sorted

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Demonstrates how to use `os_sorted()` from the `natsort` library to sort file names in a way that matches common file browsers across different operating systems. It highlights the recommendation to install `PyICU` for better results on non-Windows systems, which helps `natsort` give results that match most file browsers.

```python
import os
from natsort import os_sorted
print(os_sorted(os.listdir()))
# The directory sorted like your file browser might show
```

--------------------------------

### Sort version numbers naturally with natsorted()

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

This example demonstrates how `natsorted()` can naturally sort common versioning schemes like MAJOR.MINOR or MAJOR.MINOR.PATCH, which often behave correctly with standard natural sorting techniques.

```pycon
>>> a = ['version-1.9', 'version-2.0', 'version-1.11', 'version-1.10']
>>> natsorted(a)
['version-1.9', 'version-1.10', 'version-1.11', 'version-2.0']
```

--------------------------------

### Understanding Natsort's Core Sorting Mechanism in Python

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

This example illustrates how `natsorted()` internally uses `natsort_keygen()` to provide natural sorting behavior. It shows a simple case of sorting a list of strings that represent numbers, demonstrating how `natsort` correctly orders '1', '10', and '2' as '1', '2', '10'.

```Python
>>> from natsort import natsort_keygen
>>> natsort_key = natsort_keygen()
>>> sorted(['1', '10', '2'], key=natsort_key)
['1', '2', '10']
```

--------------------------------

### Perform natural sorting with natsorted()

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

This example demonstrates how to use the `natsorted()` function from the `natsort` library to sort a list of strings containing numbers naturally, producing the expected numerical order.

```pycon
>>> from natsort import natsorted
>>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> natsorted(a)
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
```

--------------------------------

### Build natsort Documentation with Tox

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Provides the command to build natsort's project documentation using tox. This command generates the documentation and places the output HTML files in the 'build/sphinx/html' directory.

```console
$ tox -e docs
```

--------------------------------

### Push Git Tags

Source: https://github.com/sethmmorton/natsort/blob/main/RELEASING.md

This command pushes any newly created Git tags (typically associated with the version bump) to the remote repository, making the release tag available.

```bash
git push --tags
```

--------------------------------

### Bump Project Version with tox

Source: https://github.com/sethmmorton/natsort/blob/main/RELEASING.md

This command uses 'tox' to automatically bump the project's version number. Users must specify whether to apply a 'major', 'minor', or 'patch' update. It also handles updating the CHANGELOG.md file with the correct release information.

```bash
tox -e bump patch
```

--------------------------------

### API Reference: natsort Function Key Creation Helpers

Source: https://github.com/sethmmorton/natsort/blob/main/docs/api.rst

This section introduces utility functions designed to assist in creating complex 'key' arguments for sorting functions. These tools are useful for advanced scenarios where multiple transformations or specific number-matching logic is required before sorting.

```APIDOC
natsort.chain_functions: function
```

```APIDOC
natsort.numeric_regex_chooser: function
```

--------------------------------

### Push Bumped Commit to Git

Source: https://github.com/sethmmorton/natsort/blob/main/RELEASING.md

After bumping the version, this command pushes the newly created commit, which includes the version update and changelog changes, to the remote Git repository.

```bash
git push
```

--------------------------------

### API Reference: natsort Convenience Functions

Source: https://github.com/sethmmorton/natsort/blob/main/docs/api.rst

This section outlines convenience functions built upon the core `natsort` logic. These functions simplify common sorting tasks, providing quick access to specific natural sorting behaviors like OS-style or human-friendly sorting, and index-based reordering.

```APIDOC
natsort.os_sorted: function
```

```APIDOC
natsort.realsorted: function
```

```APIDOC
natsort.humansorted: function
```

```APIDOC
natsort.index_natsorted: function
```

```APIDOC
natsort.index_realsorted: function
```

```APIDOC
natsort.index_humansorted: function
```

```APIDOC
natsort.order_by_index: function
```

--------------------------------

### Apply Custom Transformation Functions with Natsort's Key Argument

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Demonstrates how to use the `key` argument in `natsorted()` to apply a custom transformation function to elements before sorting. This allows for highly specific sorting logic, which can be combined with existing `alg` modifiers for even more tailored sorting behavior.

```pycon
>>> a = ['apple2.50', '2.3apple']
>>> natsorted(a, key=lambda x: x.replace('apple', ''), alg=ns.REAL)
['2.3apple', 'apple2.50']
```

--------------------------------

### API Reference: natsort Type Hinting Definitions

Source: https://github.com/sethmmorton/natsort/blob/main/docs/api.rst

This section provides explicit type definitions exposed by the `natsort` library for improved code clarity and static analysis. These types allow developers to precisely specify the expected inputs, outputs, and internal types used within `natsort` operations.

```APIDOC
natsort.NatsortKeyType: Type
Purpose: Returned by natsort.natsort_keygen, and type of natsort.natsort_key
```

```APIDOC
natsort.OSSortKeyType: Type
Purpose: Returned by natsort.os_sort_keygen, and type of natsort.os_sort_key
```

```APIDOC
natsort.KeyType: Type
Purpose: Type of key argument to natsort.natsorted and natsort.natsort_keygen
```

```APIDOC
natsort.NatsortInType: Type
Purpose: The input type of natsort.NatsortKeyType
```

```APIDOC
natsort.NatsortOutType: Type
Purpose: The output type of natsort.NatsortKeyType
```

```APIDOC
natsort.NSType: Type
Purpose: The type of the ns enum
```

--------------------------------

### API Reference: Standard natsort Functions

Source: https://github.com/sethmmorton/natsort/blob/main/docs/api.rst

This section details the core functions provided by the `natsort` library for natural sorting. These functions are fundamental for implementing natural order in various data structures.

```APIDOC
natsort.natsorted: function
```

```APIDOC
natsort.ns: enum
```

```APIDOC
natsort.natsort_key: function
```

```APIDOC
natsort.natsort_keygen: function
```

```APIDOC
natsort.os_sort_key: function
```

```APIDOC
natsort.os_sort_keygen: function
```

--------------------------------

### Perform Locale-Aware Human Sorting with natsort's humansorted

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Shows how to achieve locale-aware sorting, where non-numeric characters are ordered based on their meaning and locale-dependent thousands/decimal separators are accounted for. This is done using `humansorted()` or `natsorted()` with `ns.LOCALE`, often requiring explicit locale setting for accurate results.

```pycon
>>> a = ['Apple', 'apple15', 'Banana', 'apple14,689', 'banana']
>>> natsorted(a)
['Apple', 'Banana', 'apple14,689', 'apple15', 'banana']
>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'en_US.UTF-8')
'en_US.UTF-8'
>>> natsorted(a, alg=ns.LOCALE)
['apple15', 'apple14,689', 'Apple', 'banana', 'Banana']
>>> from natsort import humansorted
>>> humansorted(a)  # shortcut for natsorted with alg=ns.LOCALE
['apple15', 'apple14,689', 'Apple', 'banana', 'Banana']
```

--------------------------------

### Using natsort_keygen for Custom Sorting Keys in Python

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

This snippet demonstrates how `natsort_keygen()` generates a custom sorting key that can be used with Python's built-in `sorted()` function or `list.sort()` method for natural sorting of mixed string and number data. It shows how to achieve the same natural sort order as `natsorted()` using a custom key.

```Python
>>> from natsort import natsort_keygen
>>> natsort_key = natsort_keygen()
>>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> natsorted(a) == sorted(a, key=natsort_key)
True
>>> a.sort(key=natsort_key)
>>> a
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
```

--------------------------------

### List of Deprecated natsort APIs (v6.0.0)

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Lists the APIs and functions that were removed in natsort version 6.0.0. These include various keyword arguments and specific constants/functions, with their respective deprecation histories.

```APIDOC
Removed APIs in natsort v6.0.0:
- number_type keyword argument (deprecated since 3.4.0)
- signed keyword argument (deprecated since 3.4.0)
- exp keyword argument (deprecated since 3.4.0)
- as_path keyword argument (deprecated since 3.4.0)
- py3_safe keyword argument (deprecated since 3.4.0)
- ns.TYPESAFE (deprecated since version 5.0.0)
- ns.DIGIT (deprecated since version 5.0.0)
- ns.VERSION (deprecated since version 5.0.0)
- versorted() (discouraged since version 4.0.0, officially deprecated since version 5.5.0)
- index_versorted() (discouraged since version 4.0.0, officially deprecated since version 5.5.0)
```

--------------------------------

### Sort Byte Strings by Decoding with natsort's as_utf8

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Explains how `natsort` can handle `bytes` types by using the `as_utf8` convenience function as a `key` argument. This decodes byte strings to `str` before sorting, preventing `TypeError` and ensuring natural sorting behavior for byte data.

```pycon
>>> from natsort import as_utf8
>>> a = [b'a', 14.0, 'b']
>>> # natsorted(a) would raise a TypeError (bytes() < str())
>>> natsorted(a, key=as_utf8) == [14.0, b'a', 'b']
True
>>> a = [b'a56', b'a5', b'a6', b'a40']
>>> # natsorted(a) would return the same results as sorted(a)
>>> natsorted(a, key=as_utf8) == [b'a5', b'a6', b'a40', b'a56']
True
```

--------------------------------

### Demonstrate Python's default lexicographical sort

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

This snippet shows how Python's built-in `sorted()` function sorts a list of strings containing numbers lexicographically, leading to an order that may not be numerically intuitive (e.g., '10' comes before '2').

```pycon
>>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> sorted(a)
['1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '2 ft 7 in', '7 ft 6 in']
```

--------------------------------

### Display Python Deprecation Warnings

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Provides a console command to explicitly show Python DeprecationWarnings, which are hidden by default. This helps users identify if their code is using deprecated natsort APIs or other deprecated Python features.

```console
$ python -Wdefault::DeprecationWarning my-code.py
```

--------------------------------

### API Reference: natsort Byte Handling Functions

Source: https://github.com/sethmmorton/natsort/blob/main/docs/api.rst

While `natsort` does not directly support sorting bytes, this section provides helper functions to facilitate decoding byte strings to standard strings. This enables users to sort byte data by first converting it to a compatible string format.

```APIDOC
natsort.decoder: function
```

```APIDOC
natsort.as_ascii: function
```

```APIDOC
natsort.as_utf8: function
```

--------------------------------

### Combine Multiple Natsort Algorithm Modifiers for Custom Sorting

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Explains how to combine various algorithm modifiers like `ns.REAL`, `ns.LOCALE`, and `ns.IGNORECASE` using the bitwise OR operator (`|`) with `natsorted()`. It also demonstrates the equivalence of long and short forms of `ns` enum options and how convenience functions can be customized by passing additional algorithm flags.

```pycon
>>> a = ['Apple', 'apple15', 'Banana', 'apple14,689', 'banana']
>>> natsorted(a, alg=ns.REAL | ns.LOCALE | ns.IGNORECASE)
['Apple', 'apple15', 'apple14,689', 'Banana', 'banana']
>>> # The ns enum provides long and short forms for each option.
>>> ns.LOCALE == ns.L
True
>>> # You can also customize the convenience functions, too.
>>> natsorted(a, alg=ns.REAL | ns.LOCALE | ns.IGNORECASE) == realsorted(a, alg=ns.L | ns.IC)
True
>>> natsorted(a, alg=ns.REAL | ns.LOCALE | ns.IGNORECASE) == humansorted(a, alg=ns.R | ns.IC)
True
```

--------------------------------

### Sort Data by Real Numbers Using natsort's realsorted

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Illustrates how to sort lists containing numbers interpreted as signed floats using `realsorted()` or `natsorted()` with the `ns.REAL` algorithm. This is particularly useful in scientific data analysis where numeric values might be embedded within strings, ensuring correct numerical order.

```pycon
>>> from natsort import realsorted, ns
>>> # Note that when interpreting as signed floats, the below numbers are
>>> #            +5.10,                -3.00,            +5.30,              +2.00
>>> a = ['position5.10.data', 'position-3.data', 'position5.3.data', 'position2.data']
>>> natsorted(a)
['position2.data', 'position5.3.data', 'position5.10.data', 'position-3.data']
>>> natsorted(a, alg=ns.REAL)
['position-3.data', 'position2.data', 'position5.10.data', 'position5.3.data']
>>> realsorted(a)  # shortcut for natsorted with alg=ns.REAL
['position-3.data', 'position2.data', 'position5.10.data', 'position5.3.data']
```

--------------------------------

### Sort Mixed Data Types with Natsort

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

Illustrates `natsort`'s ability to sort lists containing a mix of `int`, `float`, and `str` types without raising `TypeError` errors, unlike Python's built-in `sorted()` function. This provides robust and flexible sorting for heterogeneous data collections.

```pycon
>>> a = ['4.5', 6, 2.0, '5', 'a']
>>> natsorted(a)
[2.0, '4.5', '5', 6, 'a']
>>> # sorted(a) would raise an "unorderable types" TypeError
```

--------------------------------

### Illustrate natsorted() not sorting in-place

Source: https://github.com/sethmmorton/natsort/blob/main/README.rst

This snippet clarifies that `natsorted()` returns a new sorted list and does not modify the original list in-place, similar to Python's built-in `sorted()`. To update the original list, the returned value must be assigned back.

```pycon
>>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> natsorted(a)
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
>>> print(a)  # 'a' was not sorted; "natsorted" simply returned a sorted list
['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> a = natsorted(a)  # Now 'a' will be sorted because the sorted list was assigned to 'a'
>>> print(a)
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.