[ENH] nth function

ci/Jenkinsfile.groovy

@@ -1,6 +1,6 @@
 #!/usr/bin/groovy
 //------------------------------------------------------------------------------
-// Copyright 2018-2020 H2O.ai
+// Copyright 2018-2022 H2O.ai
 //
 // Permission is hereby granted, free of charge, to any person obtaining a
 // copy of this software and associated documentation files (the "Software"),
@@ -256,12 +256,14 @@ ansiColor('xterm') {
                                             /opt/python/cp38-cp38/bin/python3.8 ci/ext.py wheel --audit && \
                                             /opt/python/cp39-cp39/bin/python3.9 ci/ext.py wheel --audit && \
                                             /opt/python/cp310-cp310/bin/python3.10 ci/ext.py wheel --audit && \
+                                            /opt/python/cp311-cp311/bin/python3.11 ci/ext.py wheel --audit && \
                                             echo '===== Py3.8 Debug =====' && unzip -p dist/*debug*.whl datatable/_build_info.py && \
                                             mv dist/*debug*.whl . && \
                                             echo '===== Py3.7 =====' && unzip -p dist/*cp37*.whl datatable/_build_info.py && \
                                             echo '===== Py3.8 =====' && unzip -p dist/*cp38*.whl datatable/_build_info.py && \
                                             echo '===== Py3.9 =====' && unzip -p dist/*cp39*.whl datatable/_build_info.py && \
                                             echo '===== Py3.10 =====' && unzip -p dist/*cp310*.whl datatable/_build_info.py && \
+                                            echo '===== Py3.11 =====' && unzip -p dist/*cp311*.whl datatable/_build_info.py && \
                                             mv *debug*.whl dist/ && \
                                             ls -la dist"
                                 """
@@ -296,10 +298,14 @@ ansiColor('xterm') {
                                         source /Users/jenkins/datatable_envs/py310/bin/activate
                                         python ci/ext.py wheel
                                         deactivate
+                                        source /Users/jenkins/datatable_envs/py311/bin/activate
+                                        python ci/ext.py wheel
+                                        deactivate
                                         echo '===== Py3.7 =====' && unzip -p dist/*cp37*.whl datatable/_build_info.py
                                         echo '===== Py3.8 =====' && unzip -p dist/*cp38*.whl datatable/_build_info.py
                                         echo '===== Py3.9 =====' && unzip -p dist/*cp39*.whl datatable/_build_info.py
                                         echo '===== Py3.10 =====' && unzip -p dist/*cp310*.whl datatable/_build_info.py
+                                        echo '===== Py3.11 =====' && unzip -p dist/*cp311*.whl datatable/_build_info.py
                                         ls dist
                                     """
                                     stash name: 'x86_64-macos-wheels', includes: "dist/*.whl"
@@ -340,12 +346,14 @@ ansiColor('xterm') {
                                                 /opt/python/cp38-cp38/bin/python3.8 ci/ext.py wheel --audit && \
                                                 /opt/python/cp39-cp39/bin/python3.9 ci/ext.py wheel --audit && \
                                                 /opt/python/cp310-cp310/bin/python3.10 ci/ext.py wheel --audit && \
+                                                /opt/python/cp311-cp311/bin/python3.11 ci/ext.py wheel --audit && \
                                                 echo '===== Py3.8 Debug =====' && unzip -p dist/*debug*.whl datatable/_build_info.py && \
                                                 mv dist/*debug*.whl . && \
                                                 echo '===== Py3.7 =====' && unzip -p dist/*cp37*.whl datatable/_build_info.py && \
                                                 echo '===== Py3.8 =====' && unzip -p dist/*cp38*.whl datatable/_build_info.py && \
                                                 echo '===== Py3.9 =====' && unzip -p dist/*cp39*.whl datatable/_build_info.py && \
                                                 echo '===== Py3.10 =====' && unzip -p dist/*cp310*.whl datatable/_build_info.py && \
+                                                echo '===== Py3.11 =====' && unzip -p dist/*cp311*.whl datatable/_build_info.py && \
                                                 mv *debug*.whl dist/ && \
                                                 ls -la dist"
                                     """
@@ -435,6 +443,20 @@ ansiColor('xterm') {
                             }
                         }
                     }) <<
+                    namedStage('Test x86_64-manylinux-py311', { stageName, stageDir ->
+                        node(NODE_LINUX) {
+                            buildSummary.stageWithSummary(stageName, stageDir) {
+                                cleanWs()
+                                dumpInfo()
+                                dir(stageDir) {
+                                    unstash 'datatable-sources'
+                                    unstash 'x86_64-manylinux-wheels'
+                                    test_in_docker("x86_64-manylinux-py311", "311",
+                                                   DOCKER_IMAGE_X86_64_MANYLINUX)
+                                }
+                            }
+                        }
+                    }) <<
                     namedStage('Test ppc64le-manylinux-py37', doPpcTests, { stageName, stageDir ->
                         node(NODE_PPC) {
                             buildSummary.stageWithSummary(stageName, stageDir) {
@@ -505,6 +527,20 @@ ansiColor('xterm') {
                             }
                         }
                     }) <<
+                    namedStage('Test ppc64le-manylinux-py311', doPpcTests && doPy38Tests, { stageName, stageDir ->
+                        node(NODE_PPC) {
+                            buildSummary.stageWithSummary(stageName, stageDir) {
+                                cleanWs()
+                                dumpInfo()
+                                dir(stageDir) {
+                                    unstash 'datatable-sources'
+                                    unstash 'ppc64le-manylinux-wheels'
+                                    test_in_docker("ppc64le-manylinux-py311", "311",
+                                                   DOCKER_IMAGE_PPC64LE_MANYLINUX)
+                                }
+                            }
+                        }
+                    }) <<
                     namedStage('Test x86_64-macos-py37', { stageName, stageDir ->
                         node(NODE_MACOS) {
                             buildSummary.stageWithSummary(stageName, stageDir) {
@@ -792,6 +828,7 @@ def get_python_for_docker(String pyver, String image) {
         if (pyver == "38") return "/opt/python/cp38-cp38/bin/python3.8"
         if (pyver == "39") return "/opt/python/cp39-cp39/bin/python3.9"
         if (pyver == "310") return "/opt/python/cp310-cp310/bin/python3.10"
+        if (pyver == "311") return "/opt/python/cp311-cp311/bin/python3.11"
     }
     throw new Exception("Unknown python ${pyver} for docker ${image}")
 }

ci/appveyor.yml

@@ -1,7 +1,7 @@
 image:
   - Visual Studio 2019
-  - macos-monterey
   - Ubuntu
+  - macos-monterey
 
 init:
   # Uncomment the line below to enable RDP access on AppVeyor
@@ -82,18 +82,18 @@ build_script:
 
 
     # =======================================================================
-    #   Build and test wheel for Python 3.10
+    #   Build and test wheel for Python 3.11
     # =======================================================================
 
-    source $HOME/venv3.10/bin/activate
+    source $HOME/venv3.11/bin/activate
 
     python -V
 
     python ci/ext.py wheel
 
-    DT_WHEEL=`ls dist/*-cp310-*.whl`
+    DT_WHEEL=`ls dist/*-cp311-*.whl`
 
-    echo "----- _build_info.py for Python 3.10 ------------------------------"
+    echo "----- _build_info.py for Python 3.11 ------------------------------"
 
     cat src/datatable/_build_info.py
 
@@ -183,42 +183,37 @@ build_script:
 
 
 
-    if ($env:DT_RELEASE -eq "True") {
-
-
-      # =======================================================================
-      #   Build and test wheel for Python 3.7
-      # =======================================================================
-
-      $env:PATH = "C:/Python37-x64;C:/Python37-x64/Scripts;$DEFAULT_PATH"
+    # =======================================================================
+    #   Build and test wheel for Python 3.7
+    # =======================================================================
 
-      python -V
+    $env:PATH = "C:/Python37-x64;C:/Python37-x64/Scripts;$DEFAULT_PATH"
 
-      python ci/ext.py wheel
+    python -V
 
-      $DT_WHEEL = ls dist/*-cp37-*.whl
+    python ci/ext.py wheel
 
-      echo "DT_WHEEL = $DT_WHEEL"
+    $DT_WHEEL = ls dist/*-cp37-*.whl
 
-      echo "----- _build_info.py for Python 3.7 ------------------------------"
+    echo "DT_WHEEL = $DT_WHEEL"
 
-      cat src/datatable/_build_info.py
+    echo "----- _build_info.py for Python 3.7 ------------------------------"
 
-      echo "------------------------------------------------------------------"
+    cat src/datatable/_build_info.py
 
-      python -m pip install --upgrade pip
+    echo "------------------------------------------------------------------"
 
-      python -m pip install $DT_WHEEL
+    python -m pip install --upgrade pip
 
-      python -m pip install pytest docutils pandas pyarrow
+    python -m pip install $DT_WHEEL
 
-      python -m pytest -ra --maxfail=10 -Werror -vv --showlocals ./tests/
+    python -m pip install pytest docutils pandas pyarrow
 
-      if(!$?) { Exit $LASTEXITCODE }
+    python -m pytest -ra --maxfail=10 -Werror -vv --showlocals ./tests/
 
-      python -m pip uninstall -y $DT_WHEEL
+    if(!$?) { Exit $LASTEXITCODE }
 
-    }
+    python -m pip uninstall -y $DT_WHEEL
 
 
 
@@ -257,20 +252,20 @@ build_script:
 
 
     # =======================================================================
-    #   Build and test wheel for Python 3.9
+    #   Build and test debug wheel for Python 3.8
     # =======================================================================
 
-    $env:PATH = "C:/Python39-x64;C:/Python39-x64/Scripts;$DEFAULT_PATH"
+    $env:PATH = "C:/Python38-x64;C:/Python38-x64/Scripts;$DEFAULT_PATH"
 
     python -V
 
-    python ci/ext.py wheel
+    python ci/ext.py debugwheel
 
-    $DT_WHEEL = ls dist/*-cp39-*.whl
+    $DT_WHEEL = ls dist/*debug-cp38-*.whl
 
     echo "DT_WHEEL = $DT_WHEEL"
 
-    echo "----- _build_info.py for Python 3.9 ------------------------------"
+    echo "----- _build_info.py for Python 3.8 debug wheel ------------------"
 
     cat src/datatable/_build_info.py
 
@@ -291,20 +286,20 @@ build_script:
 
 
     # =======================================================================
-    #   Build and test debug wheel for Python 3.9
+    #   Build and test wheel for Python 3.9
     # =======================================================================
 
     $env:PATH = "C:/Python39-x64;C:/Python39-x64/Scripts;$DEFAULT_PATH"
 
     python -V
 
-    python ci/ext.py debugwheel
+    python ci/ext.py wheel
 
-    $DT_WHEEL = ls dist/*debug-cp39-*.whl
+    $DT_WHEEL = ls dist/*-cp39-*.whl
 
     echo "DT_WHEEL = $DT_WHEEL"
 
-    echo "----- _build_info.py for Python 3.9 debug wheel ------------------"
+    echo "----- _build_info.py for Python 3.9 ------------------------------"
 
     cat src/datatable/_build_info.py
 
@@ -356,3 +351,37 @@ build_script:
 
     python -m pip uninstall -y $DT_WHEEL
 
+
+
+    # =======================================================================
+    #   Build and test wheel for Python 3.11
+    # =======================================================================
+
+    $env:PATH = "C:/Python311-x64;C:/Python311-x64/Scripts;$DEFAULT_PATH"
+
+    python -V
+
+    python ci/ext.py wheel
+
+    $DT_WHEEL = ls dist/*-cp311-*.whl
+
+    echo "DT_WHEEL = $DT_WHEEL"
+
+    echo "----- _build_info.py for Python 3.11 ------------------------------"
+
+    cat src/datatable/_build_info.py
+
+    echo "------------------------------------------------------------------"
+
+    python -m pip install --upgrade pip
+
+    python -m pip install $DT_WHEEL
+
+    python -m pip install pytest docutils pandas pyarrow
+
+    python -m pytest -ra --maxfail=10 -Werror -vv --showlocals ./tests/
+
+    if(!$?) { Exit $LASTEXITCODE }
+
+    python -m pip uninstall -y $DT_WHEEL
+

ci/ext.py

@@ -337,6 +337,7 @@ def build_extension(cmd, verbosity=3):
                 "-Weverything",
                 "-Wno-c++98-compat-pedantic",
                 "-Wno-c99-extensions",
+                "-Wno-disabled-macro-expansion",
                 "-Wno-exit-time-destructors",
                 "-Wno-float-equal",
                 "-Wno-global-constructors",

docs/api/dt/by.rst

@@ -26,11 +26,12 @@
       will select those rows where column A reaches its peak value within
       each group (there could be multiple such rows within each group).
 
-    - Before ``j`` is evaluated, the ``by()`` clause adds all its columns
-      at the start of ``j`` (unless ``add_columns`` argument is ``False``). If
-      ``j`` is a "select-all" slice (i.e. ``:``), then those columns will
-      also be excluded from the list of all columns so that they will be
-      present in the output only once.
+    - Before ``j`` is evaluated, the ``by()`` clause adds all the groupby
+      columns at the start of ``j`` (unless ``add_columns`` argument is
+      ``False``). If ``j`` is a "select-all" slice (i.e. ``:`` or
+      ``f[:]``), then the groupby columns will be excluded
+      from the list of all columns, so that they will be present in the output
+      only once.
 
     - During evaluation of ``j``, the reducer functions, such as
       :func:`min`, :func:`sum`, etc, will be evaluated by-group, that is

docs/api/dt/categories.rst

@@ -0,0 +1,23 @@
+
+.. xfunction:: datatable.categories
+    :src: src/core/expr/fexpr_categories.cc pyfn_categories
+    :tests: tests/types/test-categorical.py
+    :cvar: doc_dt_categories
+    :signature: categories(cols)
+
+    .. x-version-added:: 1.1.0
+
+    Get categories for categorical data.
+
+    Parameters
+    ----------
+    cols: FExpr
+        Input categorical data.
+
+    return: FExpr
+        f-expression that returns categories for each column
+        from `cols`.
+
+    except: TypeError
+        The exception is raised when one of the columns from `cols`
+        has a non-categorical type.

docs/api/dt/cbind.rst

@@ -13,16 +13,26 @@
     Parameters
     ----------
     frames: Frame | List[Frame] | None
+        The list/tuple/sequence/generator expression of Frames to append.
+        It may also contain `None` values, which will be simply
+        skipped.
 
     force: bool
+        If `True`, allows Frames to be appended even if they have unequal
+        number of rows. The resulting Frame will have number of rows equal
+        to the largest among all Frames. Those Frames which have less
+        than the largest number of rows, will be padded with NAs (with the
+        exception of Frames having just 1 row, which will be replicated
+        instead of filling with NAs).
 
     return: Frame
+        A new frame that is created by appending columns from `frames`.
 
 
     See also
     --------
     - :func:`rbind()` -- function for row-binding several frames.
-    - :meth:`dt.Frame.cbind()` -- Frame method for cbinding some frames to
+    - :meth:`dt.Frame.cbind()` -- Frame method for cbinding several frames to
       another.
 
 

docs/api/dt/codes.rst

@@ -0,0 +1,23 @@
+
+.. xfunction:: datatable.codes
+    :src: src/core/expr/fexpr_codes.cc pyfn_codes
+    :tests: tests/types/test-categorical.py
+    :cvar: doc_dt_codes
+    :signature: codes(cols)
+
+    .. x-version-added:: 1.1.0
+
+    Get integer codes for categorical data.
+
+    Parameters
+    ----------
+    cols: FExpr
+        Input categorical data.
+
+    return: FExpr
+        f-expression that returns integer codes for each column
+        from `cols`.
+
+    except: TypeError
+        The exception is raised when one of the columns from `cols`
+        has a non-categorical type.