DOC: Example for natural sort using key argument (pandas-dev#36356)

Author: erfannariman

environment.yml

@@ -106,6 +106,7 @@ dependencies:
  - cftime # Needed for downstream xarray.CFTimeIndex test
  - pyreadstat # pandas.read_spss
  - tabulate>=0.8.3 # DataFrame.to_markdown
+ - natsort # DataFrame.sort_values
  - pip:
  - git+https://github.com/pandas-dev/pydata-sphinx-theme.git@master
  - git+https://github.com/numpy/numpydoc

pandas/core/generic.py

@@ -4409,6 +4409,32 @@ def sort_values(
  3 NaN 8 4 D
  4 D 7 2 e
  5 C 4 3 F
+
+ Natural sort with the key argument,
+ using the `natsort <https://github.com/SethMMorton/natsort>` package.
+
+ >>> df = pd.DataFrame({
+ ... "time": ['0hr', '128hr', '72hr', '48hr', '96hr'],
+ ... "value": [10, 20, 30, 40, 50]
+ ... })
+ >>> df
+ time value
+ 0 0hr 10
+ 1 128hr 20
+ 2 72hr 30
+ 3 48hr 40
+ 4 96hr 50
+ >>> from natsort import index_natsorted
+ >>> df.sort_values(
+ ... by="time",
+ ... key=lambda x: np.argsort(index_natsorted(df["time"]))
+ ... )
+ time value
+ 0 0hr 10
+ 3 48hr 40
+ 2 72hr 30
+ 4 96hr 50
+ 1 128hr 20
  """
  raise AbstractMethodError(self)
 

requirements-dev.txt

@@ -73,6 +73,7 @@ xarray
 cftime
 pyreadstat
 tabulate>=0.8.3
+natsort
 git+https://github.com/pandas-dev/pydata-sphinx-theme.git@master
 git+https://github.com/numpy/numpydoc
 pyflakes>=2.2.0