def test_args_to_enum_converts_unsigned_exp_float_to_ns_FU(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{'number_type': float, 'signed': False, 'exp': True}) == ns.F | ns.U # unsigned is default assert _args_to_enum(**{'number_type': float, 'signed': False, 'exp': True}) == ns.F
def test_args_to_enum_converts_unsigned_int_and_py3safe_to_ns_IUT(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{ 'number_type': int, 'signed': False, 'py3_safe': True }) == ns.I | ns.U | ns.T
def test_args_to_enum_converts_signed_noexp_float_to_ns_FN(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{ 'number_type': float, 'signed': True, 'exp': False }) == ns.F | ns.N | ns.S
def test_args_to_enum_converts_float_and_path_and_py3safe_to_ns_FPT(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{ 'number_type': float, 'as_path': True, 'py3_safe': True }) == ns.F | ns.P | ns.T
def index_versorted(seq, key=None, reverse=False, as_path=None, alg=0): """\ Return the list of the indexes used to sort the input sequence of version numbers. Sorts a sequence of version, but returns a list of sorted the indexes and not the sorted list. This list of indexes can be used to sort multiple lists by the sorted order of the given sequence. This is a wrapper around ``index_natsorted(seq, number_type=None)``. Parameters ---------- seq: iterable The sequence to sort. key: callable, optional A key used to determine how to sort each element of the sequence. It is **not** applied recursively. It should accept a single argument and return a single value. reverse : {{True, False}}, optional Return the list in reversed sorted order. The default is `False`. as_path : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.VERSION`. Returns ------- out : tuple The ordered indexes of the sequence. See Also -------- versorted order_by_index Examples -------- Use `index_versorted` just like the builtin `sorted`:: >>> a = ['num4.0.2', 'num3.4.1', 'num3.4.2'] >>> index_versorted(a) [1, 2, 0] """ alg = _args_to_enum(float, None, None, as_path, None) | alg return index_natsorted(seq, key, reverse=reverse, alg=alg | ns.VERSION)
def test_args_to_enum(): assert _args_to_enum(float, True, True, False, False) == ns.F assert _args_to_enum(float, True, False, False, False) == ns.F | ns.N assert _args_to_enum(float, False, True, False, False) == ns.F | ns.U assert _args_to_enum(float, False, False, False, False) == ns.F | ns.U | ns.N assert _args_to_enum(float, True, True, True, True) == ns.F | ns.P | ns.T assert _args_to_enum(int, True, True, True, False) == ns.I | ns.P assert _args_to_enum(int, False, True, False, True) == ns.I | ns.U | ns.T assert _args_to_enum(None, True, True, False, False) == ns.I | ns.U
def versorted(seq, key=None, reverse=False, as_path=None, alg=0): """\ Convenience function to sort version numbers. Convenience function to sort version numbers. This is a wrapper around ``natsorted(seq, alg=ns.VERSION)``. Parameters ---------- seq : iterable The sequence to sort. key : callable, optional A key used to determine how to sort each element of the sequence. It is **not** applied recursively. It should accept a single argument and return a single value. reverse : {{True, False}}, optional Return the list in reversed sorted order. The default is `False`. as_path : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.VERSION`. Returns ------- out : list The sorted sequence. See Also -------- index_versorted : Returns the sorted indexes from `versorted`. Examples -------- Use `versorted` just like the builtin `sorted`:: >>> a = ['num4.0.2', 'num3.4.1', 'num3.4.2'] >>> versorted(a) [{u}'num3.4.1', {u}'num3.4.2', {u}'num4.0.2'] """ alg = _args_to_enum(float, None, None, as_path, None) | alg return natsorted(seq, key, reverse=reverse, alg=alg | ns.VERSION)
def natsort_keygen(key=None, alg=0, **_kwargs): """\ Generate a key to sort strings and numbers naturally. Generate a key to sort strings and numbers naturally, not lexicographically. This key is designed for use as the `key` argument to functions such as the `sorted` builtin. The user may customize the generated function with the arguments to `natsort_keygen`, including an optional `key` function which will be called before the `natsort_key`. Parameters ---------- key : callable, optional A key used to manipulate the input value before parsing for numbers. It is **not** applied recursively. It should accept a single argument and return a single value. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.INT`. Returns ------- out : function A wrapped version of the `natsort_key` function that is suitable for passing as the `key` argument to functions such as `sorted`. See Also -------- natsorted Examples -------- `natsort_keygen` is a convenient way to create a custom key to sort lists in-place (for example). Calling with no objects will return a plain `natsort_key` instance:: >>> a = ['num5.10', 'num-3', 'num5.3', 'num2'] >>> a.sort(key=natsort_keygen(alg=ns.REAL)) >>> a [{u}'num-3', {u}'num2', {u}'num5.10', {u}'num5.3'] """ return partial(_natsort_key, key=key, alg=_args_to_enum(**_kwargs) | alg)
def __new__(cls, x, y, alg=0, *args, **kwargs): try: alg = _args_to_enum(**kwargs) | alg except TypeError: msg = ("natsort_keygen: 'alg' argument must be " "from the enum 'ns'") raise ValueError(msg + ', got {0}'.format(py23_str(alg))) # Add the _DUMB option if the locale library is broken. if alg & ns.LOCALEALPHA and natsort.compat.locale.dumb_sort(): alg |= ns._DUMB if alg not in cls.cached_keys: cls.cached_keys[alg] = natsort_keygen(alg=alg) return py23_cmp(cls.cached_keys[alg](x), cls.cached_keys[alg](y))
def test_args_to_enum_converts_int_and_path_to_ns_IP(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{'number_type': int, 'as_path': True}) == ns.I | ns.P
def test_args_to_enum_raises_TypeError_for_invalid_argument(): with raises(TypeError): _args_to_enum(**{'alf': 0})
def test_args_to_enum_converts_signed_exp_float_and_path_and_py3safe_to_ns_FPT(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(float, True, True, True, True) == ns.F | ns.P | ns.T
def test_args_to_enum_converts_singed_int_and_path_to_ns_IP(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(int, True, True, True, False) == ns.I | ns.P
def natsort_keygen(key=None, number_type=float, signed=None, exp=None, as_path=None, py3_safe=None, alg=0): """\ Generate a key to sort strings and numbers naturally. Generate a key to sort strings and numbers naturally, not lexicographically. This key is designed for use as the `key` argument to functions such as the `sorted` builtin. The user may customize the generated function with the arguments to `natsort_keygen`, including an optional `key` function which will be called before the `natsort_key`. Parameters ---------- key : callable, optional A key used to manipulate the input value before parsing for numbers. It is **not** applied recursively. It should accept a single argument and return a single value. number_type : {{None, float, int}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. signed : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. exp : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. as_path : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. py3_safe : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.FLOAT`. Returns ------- out : function A wrapped version of the `natsort_key` function that is suitable for passing as the `key` argument to functions such as `sorted`. Examples -------- `natsort_keygen` is a convenient way to create a custom key to sort lists in-place (for example). Calling with no objects will return a plain `natsort_key` instance:: >>> a = ['num5.10', 'num-3', 'num5.3', 'num2'] >>> b = a[:] >>> a.sort(key=natsort_key) >>> b.sort(key=natsort_keygen()) >>> a == b True The power of `natsort_keygen` is when you want to want to pass arguments to the `natsort_key`. Consider the following equivalent examples; which is more clear? :: >>> a = ['num5.10', 'num-3', 'num5.3', 'num2'] >>> b = a[:] >>> a.sort(key=lambda x: natsort_key(x, key=lambda y: y.upper(), ... signed=False)) >>> b.sort(key=natsort_keygen(key=lambda x: x.upper(), signed=False)) >>> a == b True """ alg = _args_to_enum(number_type, signed, exp, as_path, py3_safe) | alg return partial(_natsort_key, key=key, alg=alg)
def test_args_to_enum_converts_unsigned_int_and_py3safe_to_ns_IUT(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(int, False, True, False, True) == ns.I | ns.U | ns.T
def test_args_to_enum_converts_unsigned_unexp_float_to_ns_FNU(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(float, False, False, False, False) == ns.F | ns.U | ns.N
def natsort_key(val, key=None, alg=0, **_kwargs): """Undocumented, kept for backwards-compatibility.""" msg = "natsort_key is deprecated as of 3.4.0, please use natsort_keygen" warn(msg, DeprecationWarning) return _natsort_key(val, key, _args_to_enum(**_kwargs) | alg)
def test_args_to_enum_converts_None_to_ns_IU(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(None, True, True, False, False) == ns.I | ns.U
def test_args_to_enum_converts_signed_exp_float_and_path_and_py3safe_to_ns_FPT( ): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(float, True, True, True, True) == ns.F | ns.P | ns.T
def test_args_to_enum_converts_None_to_ns_IU(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{'number_type': None, 'exp': True}) == ns.I | ns.U
def test_args_to_enum_converts_signed_noexp_float_to_ns_FN(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{'number_type': float, 'signed': True, 'exp': False}) == ns.F | ns.N | ns.S
def natsorted(seq, key=None, reverse=False, alg=0, **_kwargs): """\ Sorts a sequence naturally. Sorts a sequence naturally (alphabetically and numerically), not lexicographically. Returns a new copy of the sorted sequence as a list. Parameters ---------- seq : iterable The sequence to sort. key : callable, optional A key used to determine how to sort each element of the sequence. It is **not** applied recursively. It should accept a single argument and return a single value. reverse : {{True, False}}, optional Return the list in reversed sorted order. The default is `False`. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.INT`. Returns ------- out: list The sorted sequence. See Also -------- natsort_keygen : Generates the key that makes natural sorting possible. realsorted : A wrapper for ``natsorted(seq, alg=ns.REAL)``. humansorted : A wrapper for ``natsorted(seq, alg=ns.LOCALE)``. index_natsorted : Returns the sorted indexes from `natsorted`. Examples -------- Use `natsorted` just like the builtin `sorted`:: >>> a = ['num3', 'num5', 'num2'] >>> natsorted(a) [{u}'num2', {u}'num3', {u}'num5'] """ alg = _args_to_enum(**_kwargs) | alg try: return sorted(seq, reverse=reverse, key=natsort_keygen(key, alg=alg)) except TypeError as e: # pragma: no cover # In the event of an unresolved "unorderable types" error # for string to number type comparisons (not str/bytes), # attempt to sort again, being careful to prevent this error. r = re.compile(r'(?:str|bytes)\(\) [<>] (?:str|bytes)\(\)') if 'unorderable types' in str(e) and not r.search(str(e)): return sorted(seq, reverse=reverse, key=natsort_keygen(key, alg=alg | ns.TYPESAFE)) else: # Re-raise if the problem was not "unorderable types" raise
def index_natsorted(seq, key=None, number_type=float, signed=None, exp=None, reverse=False, as_path=None, alg=0): """\ Return the list of the indexes used to sort the input sequence. Sorts a sequence naturally, but returns a list of sorted the indexes and not the sorted list. This list of indexes can be used to sort multiple lists by the sorted order of the given sequence. Parameters ---------- seq : iterable The sequence to sort. key : callable, optional A key used to determine how to sort each element of the sequence. It is **not** applied recursively. It should accept a single argument and return a single value. number_type : {{None, float, int}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. signed : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. exp : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. reverse : {{True, False}}, optional Return the list in reversed sorted order. The default is `False`. as_path : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.FLOAT`. Returns ------- out : tuple The ordered indexes of the sequence. See Also -------- natsorted order_by_index Examples -------- Use index_natsorted if you want to sort multiple lists by the sorted order of one list:: >>> a = ['num3', 'num5', 'num2'] >>> b = ['foo', 'bar', 'baz'] >>> index = index_natsorted(a) >>> index [2, 0, 1] >>> # Sort both lists by the sort order of a >>> order_by_index(a, index) [{u}'num2', {u}'num3', {u}'num5'] >>> order_by_index(b, index) [{u}'baz', {u}'foo', {u}'bar'] """ alg = _args_to_enum(number_type, signed, exp, as_path, None) | alg if key is None: newkey = itemgetter(1) else: def newkey(x): return key(itemgetter(1)(x)) # Pair the index and sequence together, then sort by element index_seq_pair = [[x, y] for x, y in enumerate(seq)] try: index_seq_pair.sort(reverse=reverse, key=natsort_keygen(newkey, alg=alg)) except TypeError as e: # pragma: no cover # In the event of an unresolved "unorderable types" error # attempt to sort again, being careful to prevent this error. if 'unorderable types' in str(e): index_seq_pair.sort(reverse=reverse, key=natsort_keygen(newkey, alg=alg | ns.TYPESAFE)) else: # Re-raise if the problem was not "unorderable types" raise return [x for x, _ in index_seq_pair]
def natsort_keygen(key=None, alg=0, **_kwargs): """\ Generate a key to sort strings and numbers naturally. Generate a key to sort strings and numbers naturally, not lexicographically. This key is designed for use as the `key` argument to functions such as the `sorted` builtin. The user may customize the generated function with the arguments to `natsort_keygen`, including an optional `key` function. Parameters ---------- key : callable, optional A key used to manipulate the input value before parsing for numbers. It is **not** applied recursively. It should accept a single argument and return a single value. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.INT`. Returns ------- out : function A function that parses input for natural sorting that is suitable for passing as the `key` argument to functions such as `sorted`. See Also -------- natsorted Examples -------- `natsort_keygen` is a convenient way to create a custom key to sort lists in-place (for example).:: >>> a = ['num5.10', 'num-3', 'num5.3', 'num2'] >>> a.sort(key=natsort_keygen(alg=ns.REAL)) >>> a [{u}'num-3', {u}'num2', {u}'num5.10', {u}'num5.3'] """ # Transform old arguments to the ns enum. try: alg = _args_to_enum(**_kwargs) | alg except TypeError: msg = "natsort_keygen: 'alg' argument must be from the enum 'ns'" raise ValueError(msg+', got {0}'.format(py23_str(alg))) # Add the _DUMB option if the locale library is broken. if alg & ns.LOCALEALPHA and natsort.compat.locale.dumb_sort(): alg |= ns._DUMB # Set some variables that will be passed to the factory functions sep = natsort.compat.locale.null_string if alg & ns.LOCALEALPHA else '' regex = _regex_chooser[alg & ns._NUMERIC_ONLY] # Create the functions that will be used to split strings. input_transform = _input_string_transform_factory(alg) component_transform = _string_component_transform_factory(alg) final_transform = _final_data_transform_factory(alg, sep) # Create the high-level parsing functions for strings, bytes, and numbers. string_func = _parse_string_factory( alg, sep, regex.split, input_transform, component_transform, final_transform ) if alg & ns.PATH: string_func = _parse_path_factory(string_func) bytes_func = _parse_bytes_factory(alg) num_func = _parse_number_factory(alg, sep) # Return the natsort key with the parsing path pre-chosen. return partial( _natsort_key, key=key, string_func=string_func, bytes_func=bytes_func, num_func=num_func )
def natsort_key(val, key=None, number_type=float, signed=None, exp=None, as_path=None, py3_safe=None, alg=0): """\ Key to sort strings and numbers naturally. Key to sort strings and numbers naturally, not lexicographically. It is designed for use in passing to the 'sorted' builtin or 'sort' attribute of lists. .. note:: Deprecated since version 3.4.0. This function remains in the publicly exposed API for backwards-compatibility reasons, but future development should use the newer `natsort_keygen` function. It is planned to remove this from the public API in natsort version 4.0.0. A DeprecationWarning will be raised via the warnings module; set warnings.simplefilter("always") to raise them to see if your code will work in version 4.0.0. Parameters ---------- val : {{str, unicode}} The value used by the sorting algorithm key : callable, optional A key used to manipulate the input value before parsing for numbers. It is **not** applied recursively. It should accept a single argument and return a single value. number_type : {{None, float, int}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. signed : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. exp : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. as_path : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. py3_safe : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.FLOAT`. Returns ------- out : tuple The modified value with numbers extracted. See Also -------- natsort_keygen : Generates a properly wrapped `natsort_key`. Examples -------- Using natsort_key is just like any other sorting key in python:: >>> a = ['num3', 'num5', 'num2'] >>> a.sort(key=natsort_key) >>> a [{u}'num2', {u}'num3', {u}'num5'] It works by separating out the numbers from the strings:: >>> natsort_key('num2') ({u}'num', 2.0) If you need to call natsort_key with the number_type argument, or get a special attribute or item of each element of the sequence, please use the `natsort_keygen` function. Actually, please just use the `natsort_keygen` function. Notes ----- Iterables are parsed recursively so you can sort lists of lists:: >>> natsort_key(('a1', 'a10')) (({u}'a', 1.0), ({u}'a', 10.0)) Strings that lead with a number get an empty string at the front of the tuple. This is designed to get around the "unorderable types" issue of Python3:: >>> natsort_key('15a') ({u}'', 15.0, {u}'a') You can give bare numbers, too:: >>> natsort_key(10) ({u}'', 10) If you have a case where one of your string has two numbers in a row, you can turn on the "py3_safe" option to try to add a "" between sets of two numbers:: >>> natsort_key('43h7+3', py3_safe=True) ({u}'', 43.0, {u}'h', 7.0, {u}'', 3.0) """ msg = "natsort_key is deprecated as of 3.4.0, please use natsort_keygen" warn(msg, DeprecationWarning) alg = _args_to_enum(number_type, signed, exp, as_path, py3_safe) | alg return _natsort_key(val, key, alg)
def natsort_keygen(key=None, alg=0, **_kwargs): """\ Generate a key to sort strings and numbers naturally. Generate a key to sort strings and numbers naturally, not lexicographically. This key is designed for use as the `key` argument to functions such as the `sorted` builtin. The user may customize the generated function with the arguments to `natsort_keygen`, including an optional `key` function which will be called before the `natsort_key`. Parameters ---------- key : callable, optional A key used to manipulate the input value before parsing for numbers. It is **not** applied recursively. It should accept a single argument and return a single value. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.INT`. Returns ------- out : function A wrapped version of the `natsort_key` function that is suitable for passing as the `key` argument to functions such as `sorted`. See Also -------- natsorted Examples -------- `natsort_keygen` is a convenient way to create a custom key to sort lists in-place (for example). Calling with no objects will return a plain `natsort_key` instance:: >>> a = ['num5.10', 'num-3', 'num5.3', 'num2'] >>> a.sort(key=natsort_keygen(alg=ns.REAL)) >>> a [{u}'num-3', {u}'num2', {u}'num5.10', {u}'num5.3'] """ # Transform old arguments to the ns enum. try: alg = _args_to_enum(**_kwargs) | alg except TypeError: msg = "natsort_keygen: 'alg' argument must be from the enum 'ns'" raise ValueError(msg+', got {0}'.format(py23_str(alg))) # Add the _DUMB option if the locale library is broken. if alg & ns.LOCALEALPHA and natsort.compat.locale.dumb_sort(): alg |= ns._DUMB # Set some variable that will be passed to the factory functions sep = natsort.compat.locale.null_string if alg & ns.LOCALEALPHA else '' regex = _regex_chooser[alg & ns._NUMERIC_ONLY] # Create the functions that will be used to split strings. pre = _pre_split_function(alg) post = _post_split_function(alg) after = _post_string_parse_function(alg, sep) # Create the high-level parsing functions for strings, bytes, and numbers. string_func = _parse_string_function( alg, sep, regex.split, pre, post, after ) if alg & ns.PATH: string_func = _parse_path_function(string_func) bytes_func = _parse_bytes_function(alg) num_func = _parse_number_function(alg, sep) # Return the natsort key with the parsing path pre-chosen. return partial( _natsort_key, key=key, string_func=string_func, bytes_func=bytes_func, num_func=num_func )
def natsorted(seq, key=None, number_type=float, signed=None, exp=None, reverse=False, as_path=None, alg=0): """\ Sorts a sequence naturally. Sorts a sequence naturally (alphabetically and numerically), not lexicographically. Returns a new copy of the sorted sequence as a list. Parameters ---------- seq : iterable The sequence to sort. key : callable, optional A key used to determine how to sort each element of the sequence. It is **not** applied recursively. It should accept a single argument and return a single value. number_type : {{None, float, int}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. signed : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. exp : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. reverse : {{True, False}}, optional Return the list in reversed sorted order. The default is `False`. as_path : {{True, False}}, optional Deprecated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the `alg` argument for all future development. See :class:`ns` class documentation for details. alg : ns enum, optional This option is used to control which algorithm `natsort` uses when sorting. For details into these options, please see the :class:`ns` class documentation. The default is `ns.FLOAT`. Returns ------- out: list The sorted sequence. See Also -------- natsort_keygen : Generates the key that makes natural sorting possible. versorted : A wrapper for ``natsorted(seq, alg=ns.VERSION)``. realsorted : Identical to ``natsorted(seq)``; for forwards-compatibility. humansorted : A wrapper for ``natsorted(seq, alg=ns.LOCALE)``. index_natsorted : Returns the sorted indexes from `natsorted`. Examples -------- Use `natsorted` just like the builtin `sorted`:: >>> a = ['num3', 'num5', 'num2'] >>> natsorted(a) [{u}'num2', {u}'num3', {u}'num5'] """ alg = _args_to_enum(number_type, signed, exp, as_path, None) | alg try: return sorted(seq, reverse=reverse, key=natsort_keygen(key, alg=alg)) except TypeError as e: # pragma: no cover # In the event of an unresolved "unorderable types" error # for string to number type comparisons (not str/bytes), # attempt to sort again, being careful to prevent this error. r = re.compile(r'(?:str|bytes)\(\) [<>] (?:str|bytes)\(\)') if 'unorderable types' in str(e) and not r.search(str(e)): return sorted(seq, reverse=reverse, key=natsort_keygen(key, alg=alg | ns.TYPESAFE)) else: # Re-raise if the problem was not "unorderable types" raise
def test_args_to_enum_converts_float_and_path_and_py3safe_to_ns_FPT(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{'number_type': float, 'as_path': True, 'py3_safe': True}) == ns.F | ns.P | ns.T
def test_args_to_enum_converts_unsigned_int_and_py3safe_to_ns_IUT(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(**{'number_type': int, 'signed': False, 'py3_safe': True}) == ns.I | ns.U | ns.T
def test_args_to_enum_converts_signed_exp_float_to_ns_F(): # number_type, signed, exp, as_path, py3_safe assert _args_to_enum(float, True, True, False, False) == ns.F