feat: publicly export Deferred

[NickCrews]

Is your feature request related to a problem?

I want to use this in type hints.

Before, I did from ibis.expr.deferred import Deferred but this recently broke, now I have to do from ibis.common.deferred import Deferred.

Describe the solution you'd like

It would be great to export this stably. just from ibis import Deferred should work?

What version of ibis are you running?

7.1.0

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

No response

Code of Conduct

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

[tswast]

I think this should be exposed in this API: ibis.expr.types as that's where I expect all the other expression-y types to be found.

[NickCrews]

That is fine with me as long as it is canonical and stable.

[kszucs]

Can you provide a couple of examples where you either use Deferred objects or check against its type? I have an assumption that you may rather need a function which transparently coerces various input objects - like Deferred - to expressions.

[tswast]

@kszucs FWIW, I encountered this here: googleapis/python-bigquery-dataframes#53 I needed to call get_name() on an object that might or might not be Deferred:

        self._column_names = {
            (
                column.resolve(table)
                # TODO(https://github.com/ibis-project/ibis/issues/7613): use
                # public API to refer to Deferred type.
                if isinstance(column, ibis.common.deferred.Deferred)
                else column
            ).get_name(): column
            for column in self._columns
        }

[NickCrews]

A polymorphic function that can either take python builtins int or float, or ibis types. Perhaps I'm not doing this the best way, if you have a way of avoiding the Deferred then I'm all ears.

@overload
def round_to(nums: NumericValue | Deferred, n: int) -> NumericValue:
    ...


@overload
def round_to(nums: int | float, n: int) -> int:
    ...


def round_to(nums: NumericValue | Deferred | int | float, n: int) -> IntegerValue:
    """Round to the nearest n, eg 5."""
    if isinstance(nums, (NumericValue, Deferred)):
        return (nums / n).round().cast(int) * n
    else:
        return round(nums / n) * n


def test_round_to_deferred():
    x = ibis.memtable({"inp": [1, 2, 4], "expected": [0, 0, 5]})
    x = x.mutate(result=round_to(_.inp, 5))
    df = x.to_pandas()
    assert df["result"].equals(df["expected"])

[cpcloud]

@kszucs Any thoughts here based on feedback from Tim and Nick?

[NickCrews]

I am also using it as a type annotation for a dataclass like condition: bool | Deferred | Callable[[Table], BooleanValue]

[NickCrews]

Another use case I have:

I have a Table -> Table function. I have some legacy pandas code that operates on DFs, but I want to use this new Table function. So I wrote
a decorator that makes it so a function takes either a Table or DF as input, converts it to a memtable if needed, calls the function, and reverts the result back to a DF if called with a DF. In those type checks i also need to worry about checking for Deferreds.

I have a similar decorator for Columns/pd.Series.

[jcrist]

This was fixed in #9008. Closing.