python-package.yml

# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions

name: Test the Python package

on:
  workflow_dispatch:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

permissions:
  contents: read

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
    # 3.15 is pre-release until 2026-10-01 (#259): surface breakage
    # without blocking the branch; flip to blocking when it goes final.
    continue-on-error: ${{ matrix.python-version == '3.15' }}
    env:
      # Without this, uv sync honors .python-version (3.11) over the
      # matrix interpreter and every job silently tests 3.11.
      UV_PYTHON: ${{ matrix.python-version }}
      # Coverage is collected in ONE job, the one that uploads it; the
      # others would pay for a report nobody reads. 3.14 because
      # coverage.py runs its sys.monitoring core there by default, which
      # stops reporting a line once it is recorded: a line tracer
      # (sys.settrace, its core below 3.14) is called on every line
      # every time, and cost CI's 3.12 job most of its ~12 minutes on
      # the property grids in tests/v2/test_properties.py. The package
      # has no version-conditional code, so one interpreter's report
      # stands for all of them.
      COVERAGE_ON: ${{ matrix.python-version == '3.14' }}

    steps:
    - uses: actions/checkout@v7
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v7
      with:
        python-version: ${{ matrix.python-version }}
        allow-prereleases: true
    - name: Install uv
      uses: astral-sh/setup-uv@v7
      with:
        enable-cache: true
    - name: Install dependencies
      run: uv sync --group dev
    - name: Run linter
      run: uv run ruff check
    - name: Check types
      run: uv run mypy
    - name: Run Tests
      run: |
        if [ "$COVERAGE_ON" = "true" ]; then
          uv run pytest --cov=nameparser --cov-report=xml
        else
          uv run pytest
        fi
        uv run --with build python -m build --sdist
        uv run --with twine twine check dist/*
        uv run sphinx-build -b html docs dist/docs
        uv run sphinx-build -b doctest docs dist/doctest
        uv run python -m doctest README.rst
    - name: Upload coverage to Codecov
      if: env.COVERAGE_ON == 'true'
      uses: codecov/codecov-action@v7
      with:
        token: ${{ secrets.CODECOV_TOKEN }}
        files: ./coverage.xml
        fail_ci_if_error: false

  # The optional nameparser[ja] segmenter (#272). Its own job, not a
  # matrix entry: the matrix above must keep proving that the package
  # installs and passes with NO third-party dependency at all, which is
  # the promise the extra is carved out of. Everything the extra adds
  # is under tests/v2/ (the ja pack's integration tests, which skip
  # without it).
  ja-extra:
    runs-on: ubuntu-latest
    # 3.14, not the matrix's newest: namedivider-python pulls lightgbm,
    # which pulls scipy/numpy, and those have no 3.15 wheels yet (the
    # sdist build fails). 3.15 is pre-release and this matrix is ahead
    # of the ecosystem; revisit when it goes final.
    env:
      UV_PYTHON: "3.14"
    steps:
    - uses: actions/checkout@v7
    - name: Set up Python 3.14
      uses: actions/setup-python@v7
      with:
        python-version: "3.14"
    - name: Install uv
      uses: astral-sh/setup-uv@v7
      with:
        enable-cache: true
    - name: Install dependencies
      run: uv sync --group dev --extra ja
    - name: Run Tests
      # The import check first: every test the extra adds is guarded by
      # a find_spec("namedivider") skipif, so a job where the extra
      # silently failed to install is a job where all of them SKIP and
      # the step still passes green. This line is what makes that
      # failure loud -- without it the job proves nothing on the day it
      # matters.
      #
      # The _PREFIXED_SHAPES clock guard in tests/v2/test_benchmark.py
      # skips under a LINE tracer (sys.settrace -- coverage's core below
      # py3.14), which dilutes the C-level cost it measures below its
      # bound (#553). No CI job installs one today -- coverage runs on
      # 3.14 alone, under its sys.monitoring core, which does not dilute
      # the cost -- but this job is the one that must measure it
      # whatever the build matrix's coverage setup becomes, so the env
      # var below makes a line tracer here fail those rows rather than
      # skip them: a Python downgrade under coverage,
      # COVERAGE_CORE=ctrace, or a debugger.
      env:
        NAMEPARSER_REQUIRE_CLOCK_GUARDS: "1"
      run: |
        uv run python -c "import namedivider"
        uv run pytest tests/v2/ -q