feat(python)!: Update function signature of nth to allow positional input of indices, remove columns parameter

[stinodego]

Closes #16511

Changes

• Update nth to remove the overloaded capability to select values from given columns at the specified indices.
• Now positional parameters are parsed as additional column indices to select.

Example

Before:

>>> df = pl.DataFrame({"a": [1, 2], "b": [3, 4], "c": [5, 6]})
>>> df.select(pl.nth(1, "a"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
└─────┘

After:

>>> df.select(pl.nth(1, "a"))
...
TypeError: argument 'indices': 'str' object cannot be interpreted as an integer

Use instead:

>>> df.select(pl.col("a").get(1))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
└─────┘

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.51%. Comparing base (d856b49) to head (81fed6e).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #16510      +/-   ##
==========================================
- Coverage   81.53%   81.51%   -0.02%     
==========================================
  Files        1410     1410              
  Lines      185061   185059       -2     
  Branches     2982     2982              
==========================================
- Hits       150885   150848      -37     
- Misses      33660    33695      +35     
  Partials      516      516              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[alexander-beedie]

The addition of multi-index support for nth made the existing function signature awkward. This fixes the issue.

Completely agree with this one 💯

EDIT: Looking at this more, the columns parameter on this function makes no sense at all. first/last do have a similar signature, but there it makes sense because first/last are Expr methods. I removed it.

This one I'm less sure about; the reason I matched it to first/last is because the functionality is equivalent and we have a naming mismatch with the Expr method (which is get instead of nth). Seems arbitrary that we say "you can have this param for first and last, but not nth, even though we can trivially support it". Your call though, I don't feel that strongly about it if you think aligning by name is more important😉

[stinodego]

We allow pl.first("a") as a syntactic sugar for pl.col("a").first(). This is used a lot in groupby-type contexts.

pl.nth(1, columns=["a"]) isn't really any 'sweeter' than pl.col("a").get(1). In fact, I would say it's a lot worse because I am reading left-to-right and thinking "Okay, selecting columns by index, taking the first index, ... oh nevermind, I am doing something completely different". So including it makes no sense (to me).

[alexander-beedie]

Fine by me; to be honest I don't really like the "columns" param in the other two that much either, so feel free to ditch it for nth ;)

[stinodego]

Fine by me; to be honest I don't really like the "columns" param in the other two that much either, so feel free to ditch it for nth ;)

Agree - it makes sense for pl.sum("a") because it's shorter than pl.col("a").sum() and pl.sum() isn't already a thing. But pl.first() is already a thing so now it's overloaded. Not very clean.

Maybe we can make progress on this once we solve #13757 - when selectors are better integrated, we can probably get rid of pl.first() and pl.last(), as those are really just a type of selector. I'm leaving that for 2.0.0 though I think.