discuss: top-level APIs future

[NickCrews]

What happened?

Thought of these things as I'm going through moving top-level stuff in #7141

• [ibis.greatest](https://ibis-project.org/reference/top_level#ibis.expr.api.greatest) has no docstring. [ibis.ifelse](https://ibis-project.org/reference/top_level#ibis.expr.api.ifelse) has an incorrect docstring. Should we make some more refined mechanism that updates/fixes the docstrings to be correct (ie replace use of "self", add an additional param in front)? Or just keep it simple and copy paste, with a few manual edits?
• Do we even need top-level ibis.ifelse? when is that needed/preferable to BooleanValue.ifelse()? Just trying to reduce our API. Similar with .isin, name, and a few others.
• Can we deprecate ibis.where? ifelse does the same thing (IMO with a better name), and I'd prefer there to be exactly one way. Maybe just a soft deprecation where we remove it from the docs but don't add a DeprecationWarning?

What version of ibis are you using?

main

What backend(s) are you using, if any?

Na

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[contang0]

I can only agree that gravitation towards a smaller API is a virtue! I like it that with Ibis I usually can think of only one correct way to do a task, and this has to do with absence of redundant / overly similar methods.

[cpcloud]

Should we make some more refined mechanism that updates/fixes the docstrings to be correct (ie replace use of "self", add an additional param in front)? Or just keep it simple and copy paste, with a few manual edits?

Probably a copy-paste is fine for these cases.

Do we even need top-level ibis.ifelse? when is that needed/preferable to BooleanValue.ifelse()? Just trying to reduce our API. Similar with .isin, name, and a few others.

I think the top-level is around for folks coming from tools and systems that are function-based (SQL, R/dplyr) instead of class/method-based tools like those in the PyData ecosystem.

I'm in favor of reducing our API surface by removing redundancies, though in this particular case the API is literally a copy of the other.

Any chance you'd be will to do an audit for redundancies and post it here for discussion 😅?

Can we deprecate ibis.where?

Yeah, I think that makes sense. The soft deprecation sounds like a fine approach to me.

[NickCrews]

Any chance you'd be will to do an audit for redundancies and post it here for discussion 😅?

I think the .where/.ifelse is the only redundancy I can think of at this point. Will bring them up here if I find them as I refactor.

The soft deprecation sounds like a fine approach to me.

One question is should we rename ops.Where to ops.IfElse? The name of computed columns is "Where", which is a little confusing to users. But that has always been an inconsistency you saw if you used .ifelse, so this isn't a new problem we are creating.

[cpcloud]

ibis.expr.operations is not guaranteed to be stable across non-major versions, so renaming ops.Where → ops.IfElse seems fine to me.

[NickCrews]

Ah, one other instance of aliasing the same thing is ibis.NA and ibis.null(). Sort weird one is a function the other an attribute. I would love to move to just one of these, but IDK which. I like how NA is shorter, but null seems to be the more general/accepted term. I would like to be able to specify a type for the null, ie ibis.null("string") (that isn't currently supported, I have to do ibis.literal(None, "string"), but in the future I would want to add this), so keeping the API as a function seems good.

[cpcloud]

Yeah, there's sort of a question whether NullLiteral is worth keeping around internally too.

It's not clear that literal(None, T) wouldn't be strictly better than NullLiteral.

[cpcloud]

Let's deal with these on a case by case basis for now and avoid any general decisions until we see a pattern emerge.

[NickCrews]

related (in the sense of trying to reduce the API surface): Can we remove (or merely remove from docs as a start)

• NumericValue.zeroifnull(): easily replaced with .fillna(0)
• NumericValue.nullifzero(): easily replaced with Value.nullif(0)

[NickCrews]

exhaustive list of null/NA inconsistencies/reduncancies (✅ means it exists, ❌ means it doesn't)

• ✅ isnull
• ❌ isna
• ✅ notnull
• ❌ notna
• ✅ nullif
• ❌ naif (how am I supposed to pronounce that, "nafe"??? 🤣 )
• ✅ fillna
• ❌ fillnull
• ✅ ibis.NA
• ✅ ibis.null

It seems like we slightly already prefer null over NA. I agree with this, I think NULL is more generally accepted.

What do we think about soft-deprecating fillna and ibis.NA (no warning, but removing from docs/examples), and moving to just NULL?

[jcrist]

What do we think about soft-deprecating fillna and ibis.NA (no warning, but removing from docs/examples), and moving to just NULL?

We've talked about this in the past with respect to fillna/dropna, I don't think that's a bad idea. Some users may assume those operations work with nan too, which is incorrect.

I personally never use ibis.NA and don't fully understand when it's needed so maybe that could be deprecated too?

[NickCrews]

I personally never use ibis.NA

I also don't understand the distinction. I use it interchangeably/inconsistently with ibis.null().

Once #7262 is done I think I'm going to submit a PR moving to null from na, as I outline above.

[jcrist]

With #7263 and #7236 in, I think we can close this. The remaining na-related APIs are covered in #7276.