CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-natsort

Simple yet flexible natural sorting in Python that enables developers to sort strings containing numbers in a natural, human-expected order rather than lexicographical order.

—

Pending
Overview
Eval results
Files

natsort

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.

Package Information

  • Package Name: natsort
  • Package Type: pypi
  • Language: Python
  • Installation: pip install natsort

Core Imports

from natsort import natsorted

Common imports for various functionality:

from natsort import natsorted, humansorted, realsorted, os_sorted
from natsort import ns, natsort_keygen, index_natsorted

Full package import:

import natsort

Basic Usage

from natsort import natsorted

# Basic natural sorting
a = ['num3', 'num5', 'num2', 'num10', 'num1']
sorted_list = natsorted(a)
print(sorted_list)  # ['num1', 'num2', 'num3', 'num5', 'num10']

# Compare with built-in sorted (lexicographical)
regular_sorted = sorted(a)
print(regular_sorted)  # ['num1', 'num10', 'num2', 'num3', 'num5']

# Sorting with mixed content
mixed = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
natural_order = natsorted(mixed)
print(natural_order)  # ['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']

# Real number sorting with signed floats
numbers = ['num5.10', 'num-3', 'num5.3', 'num2']
real_sorted = realsorted(numbers)
print(real_sorted)  # ['num-3', 'num2', 'num5.10', 'num5.3']

Architecture

natsort operates through a key-generation approach where:

  • Input Processing: Strings are split into numeric and non-numeric components
  • Component Transformation: Numbers are converted to their numeric values while preserving original string context
  • Algorithm Control: The ns enum provides fine-grained control over sorting behavior (case sensitivity, locale handling, number interpretation)
  • Key Functions: Generated keys enable both one-time sorting and reusable key generation for performance
  • Multiple Interfaces: Core sorting functions, index-based sorting, and key generation functions provide flexibility

Capabilities

Core Sorting Functions

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.

def natsorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
def humansorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
def realsorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
def os_sorted(seq, key=None, reverse=False, presort=False): ...

Core Sorting

Index-Based Sorting

Functions that return sorted indexes rather than sorted sequences, enabling you to sort multiple related sequences by the sort order of one sequence.

def index_natsorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
def index_humansorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
def index_realsorted(seq, key=None, reverse=False, alg=ns.DEFAULT): ...
def order_by_index(seq, index, iter=False): ...

Index Sorting

Key Generation Functions

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.

def natsort_keygen(key=None, alg=ns.DEFAULT): ...
def os_sort_keygen(key=None): ...
# Pre-generated key functions
natsort_key: Callable
os_sort_key: Callable

Key Generation

Algorithm Configuration

The ns enum system that provides fine-grained control over natural sorting behavior, including number interpretation, case sensitivity, locale handling, and path-specific options.

class ns(enum.IntEnum):
    # Number handling
    DEFAULT = 0
    INT = I = 0
    UNSIGNED = U = 0
    FLOAT = F = 1
    SIGNED = S = 2
    REAL = R = 3  # FLOAT | SIGNED
    NOEXP = N = 4
    
    # String handling  
    IGNORECASE = IC = 64
    LOWERCASEFIRST = LF = 128
    GROUPLETTERS = G = 256
    UNGROUPLETTERS = CAPITALFIRST = C = UG = 512
    
    # Locale and path handling
    LOCALEALPHA = LA = 16
    LOCALENUM = LN = 32
    LOCALE = L = 48  # LOCALEALPHA | LOCALENUM
    PATH = P = 8
    
    # Special options
    NANLAST = NL = 1024
    COMPATIBILITYNORMALIZE = CN = 2048
    NUMAFTER = NA = 4096
    PRESORT = PS = 8192

Algorithm Configuration

Utilities and Text Processing

Utility functions for text processing, decoding, and command-line interface functionality.

def decoder(encoding): ...
def as_ascii(s): ...
def as_utf8(s): ...
def chain_functions(functions): ...
def numeric_regex_chooser(alg): ...

Utilities

Types

from typing import Callable, List, Optional, Union, Any, Iterable, Tuple

# Core type aliases
NatsortInType = Optional[Any]  # Input type for natsort functions
NatsortOutType = Tuple[Any, ...]  # Output type from key functions
KeyType = Callable[[Any], NatsortInType]  # Custom key function type
NatsortKeyType = Callable[[NatsortInType], NatsortOutType]  # Natsort key function type
OSSortKeyType = Callable[[NatsortInType], NatsortOutType]  # OS sort key function type
NSType = Union[ns, int]  # Algorithm specification type

Install with Tessl CLI

npx tessl i tessl/pypi-natsort
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/natsort@8.4.x
Publish Source
CLI
Badge
tessl/pypi-natsort badge