docs: cases() documentation doesn't work for me at all.

[lexual]

Please describe the issue

Can't get the conditional cases() examples to work (as opposed matching on a value), am I missing something?:

$ python -c 'import ibis; print(ibis.__version__); ibis.cases'
9.5.0
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/var/home/lexfed/code/lex_budget/_venv/lib64/python3.12/site-packages/ibis/__init__.py", line 142, in __getattr__
    return load_backend(name)
           ^^^^^^^^^^^^^^^^^^
  File "/var/home/lexfed/code/lex_budget/_venv/lib64/python3.12/site-packages/ibis/__init__.py", line 66, in load_backend
    raise AttributeError(msg)
AttributeError: module 'ibis' has no attribute 'cases'. . Did you mean: 'case'?

I tried other examples that specify I should be using else_ kwarg, and it complains about it not existing, and it looks like it should be default ?

This is another verbatim from the docs:

$ python
Python 3.12.6 (main, Sep  9 2024, 00:00:00) [GCC 14.2.1 20240801 (Red Hat 14.2.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import ibis
>>> ibis.options.interactive = True
>>> v = ibis.memtable({"values": [1, 2, 1, 2, 3, 2, 4]}).values
>>> v.to_polars()
shape: (7,)
Series: 'values' [i64]
[
        1
        2
        1
        2
        3
        2
        4
]
>>> ibis.cases((v == 1, "a"), (v > 2, "b"), else_="unk").name("cases")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/var/home/lexfed/code/lex_budget/_venv/lib64/python3.12/site-packages/ibis/__init__.py", line 142, in __getattr__
    return load_backend(name)
           ^^^^^^^^^^^^^^^^^^
  File "/var/home/lexfed/code/lex_budget/_venv/lib64/python3.12/site-packages/ibis/__init__.py", line 66, in load_backend
    raise AttributeError(msg)
AttributeError: module 'ibis' has no attribute 'cases'. . Did you mean: 'case'?

Code of Conduct

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

[IndexSeek]

Thanks for flagging this! The issue is that cases was introduced in https://github.com/ibis-project/ibis/pull/9096 about a month after the 9.5 release.

If you do not want to install from source, you can still use case with only the column like this particular example: v.case().when(1, "a").when(2, "b").else_("unk").end() or with the table expression like:

In [1]: import ibis
    ...: ibis.options.interactive = True
    ...: t = ibis.memtable({"values": [1, 2, 1, 2, 3, 2, 4]})

In [2]: t.mutate(
   ...:     case_expr=ibis.case()
   ...:     .when(t.values == 1, "a")
   ...:     .when(t.values == 2, "b")
   ...:     .else_("unk")
   ...:     .end()
   ...: )
Out[2]: 
┏━━━━━━━━┳━━━━━━━━━━━┓
┃ values ┃ case_expr ┃
┡━━━━━━━━╇━━━━━━━━━━━┩
│ int64  │ string    │
├────────┼───────────┤
│      1 │ a         │
│      2 │ b         │
│      1 │ a         │
│      2 │ b         │
│      3 │ unk       │
│      2 │ b         │
│      4 │ unk       │
└────────┴───────────┘

I apologize for the inconvenience; I can understand how frustrating this is. We should get another release out before too long.

[lexual]

Thanks @IndexSeek

Appreciate the apology, but not a big deal for me. Is the next release likely to be any time soon?

This is bad UX for an end user. It could be worth considering any of the following, which might help with this issue:

• add some text for features of which version they are introduced in (python docs do this I believe). That way people on older versions who were reading the docs would be aware that they need a newer version (probably easiest to implement)
• have the docs site point to a release branch/tag not main or development branch?
• separate docs pages available for each version ( I believe pandas does this).

Thanks.