pandera[polars] 0.32.1 fails to import using `polars=0.20`

[fhoehle]

Describe the bug
The pandera extra polars does allow versions beginning with >= 0.20.0 see pyproject.toml of the latest release 0.32.1. Unfortunately, an import of pandera/engines/polars_engine.py raises a ModuleNotFoundError: No module named 'polars._typing' error for polars=0.20.*.

• I have checked that this issue has not already been reported.
• I have confirmed this bug exists on the latest version of pandera.
• (optional) I have confirmed this bug exists on the main branch of pandera.

Note: Please read this guide detailing how to provide the necessary information for us to reproduce your bug.

Code Sample, a copy-pastable example

# Environment: pandera[polars]==0.32.1, polars==0.20.31
import pandera.polars  # raises before we even define a schema

Traceback:

File ".../pandera/polars.py", line 10, in <module>
    from pandera.api.polars.components import Column
File ".../pandera/api/polars/components.py", line 15, in <module>
    from pandera.engines import polars_engine
File ".../pandera/engines/polars_engine.py", line 23, in <module>
    from polars._typing import ColumnNameOrSelector, PythonDataType
ModuleNotFoundError: No module named 'polars._typing'

Expected behavior

There should be no ModuleNotFoundError error.

Desktop (please complete the following information):

OS: macOS (Darwin 25.5.0, arm64)
Python: 3.12
pandera version: 0.32.1 (from PyPI)
polars version: 0.20.31

Comment

The polars._typing submodule was removed with polars>=1. If polars<1 should be still supported I'm open to submit a PR fixing this bug. My personal opinion would be to keep polars=0.20.* available for some time to ease migrations.

[deepyaman]

If polars<1 should be still supported I'm open to submit a PR fixing this bug.

Sounds good! Looks like there's a bug in CI (polars-version isn't a top-level key, so it's not included in the matrix), preventing it from actually getting tested.

[fhoehle]

Looks like there's a bug in CI (polars-version isn't a top-level key, so it's not included in the matrix), preventing it from actually getting tested.

According to the GHA workflow jobs the polars version gets picked up. The error seems to be that the matrix definition is overwriting the 0.20.0 version with the 1.33.1 version; see here.

[fhoehle]

@deepyaman @cosmicBboy I dug deeper and found that CI always installs the latest available polars version at unit-test time, regardless of which version the test matrix intends to use. See the CI logs of the latest main GHA runs — the extra-polars, polars=1.33.1 job actually installs polars==1.42.1.

Root cause: the requirements parsing in noxfile.py uses strict equality req == "polars" instead of prefix matching like the other dependencies pandas, which also tests req.startswith("pandas ")). Since the actual requirement string given by the pyproject.toml file is "polars >= 0.20.0" rather than a bare "polars", the pin is never applied; the latest release is used.

If you're interested in resolving these issues without dropping polars 0.20 support, I'm happy to open a PR. I'd also advocate for raising the lower polars boundary to 0.20.31, since supporting polars==0.20.0 itself (rather than >=0.20.31) requires working around several API differences between 0.20.0 and 0.20.31 — e.g. horizontal concat on pl.LazyFrame is not supported, pl.Array has no .shape attribute.

[deepyaman]

@fhoehle That all sounds good to me! It's clearly an oversight that it's not getting tested in CI, and using the latest of the pre-1.0 series also makes perfect sense.

[fhoehle]

@deepyaman thanks for your clarification. I opened a PR #2412 and am happy to receive any feedback.

[cosmicBboy]

@fhoehle are you actively using polars==0.20.*? If not I'd rather increase the min version of the extra instead of adding back support for an old pre-v1 version of polars.

[fhoehle]

Lucky not anymore but I did not want to exclude projects not yet migrated to newer versions since it was the first major release.
Personally I'm very happy to bump the lower version boundary to polars=1.20, released end of January 2025 or 1.3[12].0 released July/August 2025. What is your opinion @cosmicBboy ?

[cosmicBboy]

let's bump it to 1.20 !

[fhoehle]

@cosmicBboy I updated #2412 to bump it to 1.20.0. I am happy to receive feedback/comments. The PR also drops code paths handling polars <1.20.