Enable tests.extra with 4-tier test organization and consistent naming conventions

.github/copilot-instructions.md

@@ -163,6 +163,14 @@
 - [ ] API endpoints must use proper HTTP return codes.
 - [ ] Follow web best practices as recommended by OpenAPI, IETF, W3C, etc.
 
+## Git
+
+- [ ] Follow these guidelines for writing a good commit message:
+  - How to Write a Git Commit Message
+    <https://chris.beams.io/posts/git-commit/>
+  - Commit Verbs 101: why I like to use this and why you should also like it.
+    <https://chris.beams.io/posts/git-commit/>
+
 ## Python
 
 - [ ] Defensive coding: always check for None/empty and handle exceptions

.github/workflows/deploy-docs.yml

@@ -35,11 +35,6 @@ jobs:
       # pip<24.1 because https://github.com/omry/omegaconf/pull/1195
       # setuptools>=65.0.2 because https://github.com/pypa/setuptools/commit/d03da04e024ad4289342077eef6de40013630a44#diff-9ea6e1e3dde6d4a7e08c7c88eceed69ca745d0d2c779f8f85219b22266efff7fR1
       # setuptools<=73.0.1 because https://github.com/pypa/setuptools/issues/4620
-    #- name: Install dependencies
-    #  env:
-    #    SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL: True
-    #  run: |
-    #    if [ -f docker_requirements.txt ]; then pip install -r docker_requirements.txt; fi
     - name: Install PyThaiNLP
       run: pip install ".[docs]"
     - name: Build sphinx documentation

.github/workflows/pypi-test.yml

@@ -15,28 +15,36 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        # Ideally, this is the minimum supported version, as in requires-python in pyproject.toml
-        python-version: ["3.9"]
+        # Ideally, this should be the minimum supported version,
+        # as in `requires-python` in pyproject.toml
+        # But for now, we just test on the second-latest supported version
+        # because some dependencies may not support the older versions.
+        python-version: ["3.12"]
 
     steps:
     - uses: actions/checkout@v6
+
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
+        cache: "pip"
+
     - name: Install dependencies
       env:
         SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL: True
       run: |
         python -m pip install --upgrade "pip<24.1" setuptools
-        python -m pip install pythainlp[testing,full]
+        python -m pip install ".[compact]"
         python -m nltk.downloader omw-1.4
+
+    # Download the sdist from PyPI, extract it, and run the tests inside it
+    # (the binary distribution does not contain tests).
     - name: Test
       run: |
         set -euo pipefail
         mkdir -p pythainlp_test
         cd pythainlp_test
-        # Download sdist from PyPI (the binary distribution does not contain tests)
         pip download --no-binary=:all: --no-dependencies pythainlp
         archive=$(ls -1 *.tar.gz | head -n1)
         echo "Found archive: $archive"
@@ -49,4 +57,4 @@ jobs:
         if [ -d data ] && [ -d tests ]; then
           mv data tests/
         fi
-        python -m unittest discover -v
+        python -m unittest tests.core tests.compact -v

.github/workflows/unittest.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2016-2026 PyThaiNLP Project
-# SPDX-License-Identifier: CC0-1.0
+# SPDX-License-Identifier: Apache-2.0
 
 name: Unit test
 
@@ -32,11 +32,34 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Test latest and earliest versions of Python on every OSes
+        # To save time and resources, and manage dependency compatibility,
+        # we divide test cases into 3 groups
+        # and run them in different configurations:
+        # - Core    (O): All supported Python versions on Ubuntu,
+        #                plus latest and earliest Python versions
+        #                on all supported OSes
+        # - Compact (C): Second-latest and earliest supported Python versions
+        #                on all supported OSes, plus latest on Ubuntu
+        # - Extra   (X): Second-latest supported Python version on Ubuntu only
+        #
+        # | Python | Ubuntu  | Windows | macOS |
+        # |--------|---------|---------|-------|
+        # | 3.14   | O+C     | O       | O     |
+        # | 3.13   | O+C+X   | O+C     | O+C   |
+        # | 3.12   | O       |         |       |
+        # | 3.11   | O       |         |       |
+        # | 3.10   | O       |         |       |
+        # | 3.9    | O+C     | O+C     | O+C   |
+        #
+        # We should also consider to reduce the number of dependencies
+        # to avoid conflicts between them.
+        # See: https://github.com/PyThaiNLP/pythainlp/issues/935
         os: ["ubuntu-latest", "windows-latest", "macos-latest"]
-        python-version: ["3.13", "3.9"]  # Latest and earliest      
+        python-version: ["3.14", "3.9"] # Latest and earliest
         include:
           # Test the rest of Python versions only on Ubuntu
+          - os: "ubuntu-latest"
+            python-version: "3.13"
           - os: "ubuntu-latest"
             python-version: "3.12"
           - os: "ubuntu-latest"
@@ -46,87 +69,89 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     env:
-      PYICU_WIN_VER: 2.14
-      INSTALL_TORCH: false
+      PYICU_WIN_VER: 2.15 # 2.15 is the last version that supports Python 3.9
       INSTALL_FULL_DEPS: false
-      PYTHON_VERSION_LATEST: "3.13"
-      PYTHON_VERSION_LATEST_2: "3.12"
+      PYTHON_VERSION_LATEST: "3.14"
+      PYTHON_VERSION_LATEST_2: "3.13" # Second-latest supported version
+      PYTHON_VERSION_EARLIEST: "3.9"
 
     steps:
-    - name: Checkout
-      uses: actions/checkout@v6
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v6
-      with:
-        python-version: ${{ matrix.python-version }}
-        cache: "pip"
-    - name: Install build tools
-      run: |
-        pip install --upgrade "pip<24.1" "setuptools>=69.0.0,<=73.0.1"
-        pip install coverage coveralls
-      # pip<24.1 because https://github.com/omry/omegaconf/pull/1195
-      # setuptools>=65.0.2 because https://github.com/pypa/setuptools/commit/d03da04e024ad4289342077eef6de40013630a44#diff-9ea6e1e3dde6d4a7e08c7c88eceed69ca745d0d2c779f8f85219b22266efff7fR1
-      # setuptools<=73.0.1 because https://github.com/pypa/setuptools/issues/4620
-    - name: Install ICU (macOS)
-      if: startsWith(matrix.os, 'macos-')
-      run: |
-        brew install icu4c
-        PKG_CONFIG_PATH=$(brew --prefix)/opt/icu4c/lib/pkgconfig
-        echo "PKG_CONFIG_PATH=${PKG_CONFIG_PATH}" >> "${GITHUB_ENV}"
-        ICU_VER=$(pkg-config --modversion icu-i18n)
-        echo "ICU_VER=${ICU_VER}"
-        echo "ICU_VER=${ICU_VER}" >> "${GITHUB_ENV}"
-    - name: Install PyICU (Windows)
-      if: startsWith(matrix.os, 'windows-') && (matrix.python-version == '3.12' || matrix.python-version == '3.13')
-      shell: powershell
-      run: |
-        $PYTHON_WIN_VER = "${{ matrix.python-version }}"
-        $CP_VER = "cp" + $PYTHON_WIN_VER.Replace(".", "")
-        $WHEEL_URL = "https://github.com/cgohlke/pyicu-build/releases/download/v${{ env.PYICU_WIN_VER }}/PyICU-${{ env.PYICU_WIN_VER }}-${CP_VER}-${CP_VER}-win_amd64.whl"
-        pip install "$WHEEL_URL"
-      # Get wheel URL from https://github.com/cgohlke/pyicu-build/releases
-    - name: Install PyTorch
-      if: env.INSTALL_TORCH == 'true'
-      run: pip install torch
-      # If torch for the platform is not available in PyPI, use this command:
-      # pip install "<torch_wheel_url>"
-      # Get wheel URL from http://download.pytorch.org/whl/torch/
-    - name: Install testing dependencies
-      if: env.INSTALL_FULL_DEPS == 'true'
-      env:
-        SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL: True
-      run: pip install ".[testing]"
-    - name: Install PyThaiNLP + dependencies (minimum)
-      if: matrix.python-version != env.PYTHON_VERSION_LATEST && matrix.python-version != env.PYTHON_VERSION_LATEST_2
-      run: pip install .
-    - name: Install PyThaiNLP + dependencies (compact)
-      if: matrix.python-version == env.PYTHON_VERSION_LATEST || matrix.python-version == env.PYTHON_VERSION_LATEST_2
-      run: pip install ".[compact]"
-      # If you want to install a safe small set of optional dependencies, use:
-      # pip install ".[compact]"
-      # We can gradually run more test cases by installing more optional
-      # dependencies. But we should also consider to reduce the number
-      # of dependencies to avoid the conflict between dependencies.
-      # See: https://github.com/PyThaiNLP/pythainlp/issues/935
-    - name: Unit test (core)
-      if: matrix.python-version != env.PYTHON_VERSION_LATEST && matrix.python-version != env.PYTHON_VERSION_LATEST_2
-      env:
-        PYTHONIOENCODING: utf-8
-      run: coverage run -m unittest tests.core
-    - name: Unit test (core + compact)
-      if: matrix.python-version == env.PYTHON_VERSION_LATEST || matrix.python-version == env.PYTHON_VERSION_LATEST_2
-      env:
-        PYTHONIOENCODING: utf-8
-      run: coverage run -m unittest tests.core tests.compact
-      # Only test "compact" set with the latest two stable Python versions.
-      # Use 'unittest <test_module>' instead of 'unittest discover' to avoid
-      # loading tests with dependencies more than expected.
-      # Test cases loaded is defined in __init__.py in the tests directory.
-      # See also tests/README.md
-    - name: Coverage report
-      if: matrix.os == 'ubuntu-latest' && matrix.python-version == env.PYTHON_VERSION_LATEST
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        COVERALLS_SERVICE_NAME: github
-      run: coveralls
-      # Only submit a report from the latest Python version on ubuntu-latest.
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install build tools
+        run: |
+          pip install --upgrade "pip<24.1" "setuptools>=69.0.0,<=73.0.1"
+          pip install coverage coveralls
+        # pip<24.1 because https://github.com/omry/omegaconf/pull/1195
+        # setuptools>=65.0.2 because https://github.com/pypa/setuptools/commit/d03da04e024ad4289342077eef6de40013630a44#diff-9ea6e1e3dde6d4a7e08c7c88eceed69ca745d0d2c779f8f85219b22266efff7fR1
+        # setuptools<=73.0.1 because https://github.com/pypa/setuptools/issues/4620
+
+      - name: Install ICU (macOS)
+        if: startsWith(matrix.os, 'macos-')
+        run: |
+          brew install icu4c
+          PKG_CONFIG_PATH=$(brew --prefix)/opt/icu4c/lib/pkgconfig
+          echo "PKG_CONFIG_PATH=${PKG_CONFIG_PATH}" >> "${GITHUB_ENV}"
+          ICU_VER=$(pkg-config --modversion icu-i18n)
+          echo "ICU_VER=${ICU_VER}"
+          echo "ICU_VER=${ICU_VER}" >> "${GITHUB_ENV}"
+
+      - name: Install PyICU (Windows)
+        if: startsWith(matrix.os, 'windows-') && (matrix.python-version == env.PYTHON_VERSION_LATEST_2 || matrix.python-version == env.PYTHON_VERSION_EARLIEST)
+        shell: powershell
+        # Get the wheel URL from https://github.com/cgohlke/pyicu-build/releases
+        run: |
+          $PYTHON_WIN_VER = "${{ matrix.python-version }}"
+          $CP_VER = "cp" + $PYTHON_WIN_VER.Replace(".", "")
+          $WHEEL_URL = "https://github.com/cgohlke/pyicu-build/releases/download/v${{ env.PYICU_WIN_VER }}/PyICU-${{ env.PYICU_WIN_VER }}-${CP_VER}-${CP_VER}-win_amd64.whl"
+          pip install "$WHEEL_URL"
+
+      - name: Install PyThaiNLP + full testing dependencies
+        if: env.INSTALL_FULL_DEPS == 'true'
+        env:
+          SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL: True
+        run: pip install ".[full]"
+
+      - name: Test (core)
+        if: ${{ (matrix.os == 'ubuntu-latest' && matrix.python-version != env.PYTHON_VERSION_LATEST_2 && matrix.python-version != env.PYTHON_VERSION_EARLIEST) || (matrix.os != 'ubuntu-latest' && matrix.python-version == env.PYTHON_VERSION_LATEST) }}
+        env:
+          PYTHONIOENCODING: utf-8
+        run: |
+          pip install .
+          python -m unittest tests.core
+        # Use 'unittest <test_module>' instead of 'unittest discover' to avoid
+        # loading tests with dependencies more than expected.
+        # Test cases loaded is defined in __init__.py in the tests directory.
+        # See also tests/README.md
+
+      - name: Test (compact + core)
+        if: ${{ ((matrix.python-version == env.PYTHON_VERSION_LATEST_2) || (matrix.python-version == env.PYTHON_VERSION_EARLIEST)) && !(matrix.os == 'ubuntu-latest' && matrix.python-version == env.PYTHON_VERSION_LATEST_2) }}
+        env:
+          PYTHONIOENCODING: utf-8
+        run: |
+          pip install ".[compact]"
+          python -m unittest tests.core tests.compact
+
+      - name: Test (extra + compact + core)
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == env.PYTHON_VERSION_LATEST_2
+        env:
+          PYTHONIOENCODING: utf-8
+        run: |
+          pip install ".[compact,extra]"
+          coverage run -m unittest tests.core tests.compact tests.extra
+
+      # Only submit a report from the "extra" run, to get maximum coverage
+      - name: Coverage report
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == env.PYTHON_VERSION_LATEST_2
+        env:
+          COVERALLS_SERVICE_NAME: github
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PYTHONIOENCODING: utf-8
+        run: coveralls

CONTRIBUTING.md

@@ -6,9 +6,11 @@ SPDX-License-Identifier: CC0-1.0
 
 # Contributing to PyThaiNLP
 
-Hi! Thanks for your interest in contributing to [PyThaiNLP](https://github.com/PyThaiNLP/pythainlp).
+Hi! Thanks for your interest in contributing to
+[PyThaiNLP](https://github.com/PyThaiNLP/pythainlp).
 
-Please refer to our [Contributor Covenant Code of Conduct](https://github.com/PyThaiNLP/pythainlp/blob/dev/CODE_OF_CONDUCT.md).
+Please refer to our
+[Contributor Covenant Code of Conduct](https://github.com/PyThaiNLP/pythainlp/blob/dev/CODE_OF_CONDUCT.md).
 
 ## Issue Report and Discussion
 
@@ -52,8 +54,9 @@ Please refer to our [Contributor Covenant Code of Conduct](https://github.com/Py
 
 ### Version Control System
 
-- We use [Git](http://git-scm.com/) as our [version control system](http://en.wikipedia.org/wiki/Revision_control),
-so it may be a good idea to familiarize yourself with it.
+- We use [Git](http://git-scm.com/) as our
+  [version control system](http://en.wikipedia.org/wiki/Revision_control),
+  so it may be a good idea to familiarize yourself with it.
 - You can start with the [Pro Git book](http://git-scm.com/book/) (free!).
 
 ### Commit Message
@@ -65,19 +68,24 @@ so it may be a good idea to familiarize yourself with it.
 
 - We use the famous [gitflow][] to manage our branches.
 - When you create pull requests on GitHub, GitHub Actions will run tests
-and several checks automatically. Click the "Details" link at the end of
-each check to see what needs to be fixed.
+  and several checks automatically. Click the "Details" link
+  at the end of each check to see what needs to be fixed.
 
 [gitflow]: http://nvie.com/posts/a-successful-git-branching-model/
 
 ## Documentation
 
-- We use [Sphinx](https://www.sphinx-doc.org/en/master/) to generate API document
-automatically from "docstring" comments in source codes. This means the comment
-section in the source codes is important for the quality of documentation.
-- A docstring should start with one summary line, end with one line with a full stop (period),
-then be followed by a blank line before starting a new paragraph.
-- A commit to release branches (e.g. `2.2`, `2.1`) with a title **"(build and deploy docs)"** (without quotes) will trigger the system to rebuild the documentation files and upload them to the website <https://pythainlp.org/docs>.
+- We use [Sphinx](https://www.sphinx-doc.org/en/master/) to generate
+  API document automatically from "docstring" comments in source codes.
+  This means the comment section in the source codes is important for the
+  quality of documentation.
+- A docstring should start with one summary line, end with one line with
+  a full stop (period), then be followed by a blank line before starting
+  a new paragraph.
+- A commit to release branches (e.g. `2.2`, `2.1`) with a title
+  **"(build and deploy docs)"** (without quotes) will trigger the system
+  to rebuild the documentation files and upload them to the website
+  <https://pythainlp.org/docs>.
 
 ## Testing
 
@@ -124,14 +132,12 @@ Install with optional dependency groups:
 # Install with compact set of dependencies (recommended for development)
 pip install -e ".[compact]"
 
-# Install with full dependencies
-pip install -e ".[full]"
-
-# Install with testing dependencies (pinned versions for reproducibility)
-pip install -e ".[testing]"
+# Install with extra set of dependencies (can be huge)
+pip install -e ".[compact,extra]"
 ```
 
-See all available optional dependency groups in `pyproject.toml` under `[project.optional-dependencies]`.
+See all available optional dependency groups in `pyproject.toml`
+under `[project.optional-dependencies]`.
 
 ### Building Distribution Packages
 
@@ -145,8 +151,11 @@ This will create distribution packages in the `dist/` directory.
 
 ## Releasing
 
-- We use [semantic versioning](https://semver.org/): MAJOR.MINOR.PATCH, with development build suffix: MAJOR.MINOR.PATCH-devBUILD
-- We use [`bump-my-version`](https://github.com/callowayproject/bump-my-version) to manage versioning. The configuration is in `pyproject.toml` under `[tool.bumpversion]`.
+- We use [semantic versioning](https://semver.org/): MAJOR.MINOR.PATCH,
+  with development build suffix: MAJOR.MINOR.PATCH-devBUILD
+- We use [`bump-my-version`](https://github.com/callowayproject/bump-my-version)
+  to manage versioning. The configuration is in `pyproject.toml`
+  under `[tool.bumpversion]`.
   - `bump-my-version bump [major|minor|patch|release|build]`
   - Example:
 
@@ -190,7 +199,8 @@ This will create distribution packages in the `dist/` directory.
 
 [![Contributors](https://contributors-img.firebaseapp.com/image?repo=PyThaiNLP/pythainlp)](https://github.com/PyThaiNLP/pythainlp/graphs/contributors)
 
-Thanks to all [contributors](https://github.com/PyThaiNLP/pythainlp/graphs/contributors). (Image made with [contributors-img](https://contributors-img.firebaseapp.com))
+Thanks to all [contributors](https://github.com/PyThaiNLP/pythainlp/graphs/contributors).
+(Image made with [contributors-img](https://contributors-img.firebaseapp.com))
 
 ### Development Leads
 

Dockerfile

@@ -12,5 +12,4 @@ RUN apt-get update && apt-get install -y --no-install-recommends build-essential
 ENV VIRTUAL_ENV=/opt/venv
 RUN python3 -m venv $VIRTUAL_ENV
 ENV PATH="$VIRTUAL_ENV/bin:$PATH"
-# Install PyThaiNLP with testing dependencies (replaces docker_requirements.txt)
-RUN pip install -e ".[testing]" && pip cache purge
+RUN pip install -e ".[full]" && pip cache purge