fix(str): reject a negative width or length in zfill, pad_start and pad_end

[mkzung]

Description

A negative width or length reached the backends and each one did something
different with it. pandas returned the string unchanged, Polars raised
InvalidOperationError: conversion from 'i128' to 'u64' failed ... [-1], and
PyArrow raised ArrowInvalid: Negative buffer resize: -21. pad_start and
pad_end do the same, since the argument reaches the same backend calls.

This started as a PyArrow-only fix for zfill. @camriddell raised the question of
whether the check belonged further up in expr_str.py instead, so it raises early
and every backend reports the same thing. That is what it now does. The PyArrow
backend keeps only its width == 0 short-circuit, which is an evaluation-order
problem rather than an argument one.

The check is in both expr_str.py and series_str.py because Series.str.zfill
calls the compliant series directly rather than going through an expression, so
expr_str.py alone would not cover it. Removing either set turns tests red.

pc.case_when is why PyArrow crashed rather than returned: it evaluates every
branch eagerly, so pc.utf8_lpad(remaining_chars, width - 1) ran with a negative
pad length before any row was selected.

The tests pin the message and not just the exception type, which matters here more
than it usually would. Polars already raised InvalidOperationError for this, just
with its internal cast message, so without the message pinned the Polars case
passes against unfixed code. InvalidOperationError is also what the library
raises elsewhere for an argument rejected before anything is computed.

Tests run on every backend through the existing fixtures. The expression cases use
constructor rather than constructor_eager, so the lazy backends are covered as
well, where the check raises at select() rather than at collect().

Reproduction, before this change:

import narwhals as nw, pyarrow as pa
s = nw.from_native(pa.table({"a": ["1", "-5", "abc"]}), eager_only=True)["a"]
s.str.zfill(0)   # ArrowInvalid: Negative buffer resize: -9
s.str.zfill(-1)  # ArrowInvalid: Negative buffer resize: -21

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

Related issues

• No existing issue; found while exercising the string namespace on the PyArrow backend.

AI assistance

• No AI tools were used for this PR.
• AI tools were used.

I used an AI coding assistant to help locate the root cause and draft the regression
test. I have read, run, and verified every line, and I take full responsibility for
the change.

Checklist

• Code follows style guide (ruff)
• Tests added
• Documented the changes (no doc change needed; behaviour matches the documented str.zfill)

[MarcoGorelli]

thanks @mkzung !

If you would rather the Arrow backend raise on a negative width to match Polars
instead of returning unchanged, I am happy to switch.

i think i'd prefer that, could we do that instead please? thanks 🙏

[mkzung]

Done. The Arrow backend now raises InvalidOperationError on a negative width, matching Polars, instead of returning unchanged, and width 0 stays a no-op. I also moved the regression tests to pyarrow only, since Polars' own zfill(0) raises on the older CI versions.

[camriddell]

@MarcoGorelli should we push this check up to narwhals/expr_str.py. If we do that then

1. The error can be raised as early as possible for all backends
2. All implementations will have a uniform error message

If not, then I'm happy with the implementation here.

[mkzung]

Worth adding that the inconsistency is wider than zfill. With a negative width today, pandas returns the string unchanged, Polars raises conversion from 'i128' to 'u64' failed, and pyarrow crashes inside utf8_lpad. pad_start and pad_end do the same thing - on pyarrow they leak ArrowInvalid: Negative buffer resize.

So moving the check up to expr_str/series_str fixes three methods at once and gives every backend the same error. I have it on a branch: validation in Expr.str and Series.str, the Arrow negative-width raise removed (the width == 0 no-op stays, that one is a genuine pyarrow quirk), tests parametrised across backends, full suite green.

mkzung/narwhals@main...mkzung:narwhals:fix/zfill-validate-in-public-layer

Happy to fold it into this PR, or to leave it until you and @MarcoGorelli have settled where the check belongs.

[mkzung]

Moved it up to expr_str.py, so every backend now raises the same message before
anything reaches a compliant object.

I kept the guards in series_str.py as well. Series.str.zfill calls the compliant
series directly rather than building an expression, so the expression layer alone
does not cover that path. With the series-side checks removed, 8 tests in
tests/expr_and_series/str fail.

The _arrow change is still in there for the case Marco raised earlier: a negative
width returned the string unchanged on that backend instead of raising.

[MarcoGorelli]

shall we parametrise over all constructors, to make sure none of the others crash?

[mkzung]

The zero-width test runs over every constructor now (plus a series version) - nothing crashes, only the pandas+pyarrow xfail.

[MarcoGorelli]

this is repeated a few times, could/should it be a util function? like validate_width

[mkzung]

Pulled the check into a validate_width helper in _utils.py, used by zfill and both pad methods.

[camriddell]

@mkzung looks like the above failures are from a behavior alignment correction we implement for older Polars versions.

narwhals/src/narwhals/_polars/expr.py

Line 464 in 34edd7e

.str.zfill(width - 1)

I think if we replace the linked line .str.zfill(width - 1) with .str.zfill(max(width - 1, 0)) we should be looking good on the tests and wrap this one up.

[mkzung]

Done, pushed.

The reason it fires with the predicate false is that Polars builds the then arm before choosing, so width 0 reaches zfill(-1) either way. Checked against a real 1.30.0 rather than my local 1.42, where the branch never runs: all three failures reproduce there and clear with the change.

One thing I ran into while checking, separate from this PR and already on main: that branch disagrees with newer Polars when the remainder is multibyte or holds a second plus. "+é" at width 4 comes out "++0é" against "+0é", and "++7" comes out "++07" against "+0+7". It mixes units, since zfill pads to bytes and pad_start to characters. Happy to open a follow-up if you want it.

[camriddell]

One thing I ran into while checking, separate from this PR and already on main: that branch disagrees with newer Polars when the remainder is multibyte or holds a second plus. "+é" at width 4 comes out "++0é" against "+0é", and "++7" comes out "++07" against "+0+7". It mixes units, since zfill pads to bytes and pad_start to characters. Happy to open a follow-up if you want it.

I cannot replicate this. Can you re-confirm and if this issue persists then create an issue following the issue template (with an MRE).

[mkzung]

You are right not to be able to replicate it, and one half of what I wrote was wrong.

It only happens on Polars <= 1.30.0, which is the only case that enters that branch at all. I should have said so. I have now checked it on a real 1.30.0 rather than by pinning the reported backend version, and the "++7" half does not hold: it comes out "+0+7" on both, matching newer Polars. Sorry for the noise on that one.

What does hold is multibyte content after a leading +. Same narwhals commit, same input, two Polars:

polars 1.42.1   "+é".zfill(4) -> "+0é"
polars 1.30.0   "+é".zfill(4) -> "++0é"

Filed as #3838 with the MRE and the version matrix. The cause is that the branch mixes units, zfill padding to bytes and pad_start to characters, so on ASCII they agree and on multibyte one + too many is prepended.

The two red checks here are Install uv failing to fetch on the lightgbm job and the downstream scikit-lego job, which has been red on main since April.