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

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

[IndexSeek]

Thanks for flagging this! The issue is that cases was introduced in #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.

[NickCrews]

I agree this is a pain point that should be improved. See #10371 (comment) as a workaround that should make it easy to begin using the new API now, and then you can delete this compatibility code once you upgrade to 10.0.0.

My favorite as both a reader of the docs, and as a maintainer of the docs, is option 1, so I implemented that in #10551.

[deepyaman]

separate docs pages available for each version ( I believe pandas does this).

I think most docs do this. 😅

As somebody who has also been confused by the docs showing things that aren't available in the latest released version on many occasions, I wonder how hard it would be to have versioned docs?

But it seems the Quarto team doesn't plan to support it? quarto-dev/quarto-cli#474 (comment)

[NickCrews]

About 2 years ago, it appears we made the decision to explicitly move from versioned docs to unversioned docs: #5347. I personally think this was the right choice, and I personally would make the same choice again today. Not sure what other ibis maintainers think.

[gforsyth]

It's not worth the overhead, in my mind. I do push up historical docs when I remember to. (https://ibis-project.github.io/ibis/)

One thing we could do is have a /dev sub-directory in the docs tree, and only update the "main" docs when we push a new release. But this also causes confusion with scrapers, etc

[cpcloud]

We can probably link to the older versions somewhere on the main site too, if we don't already.

That would mostly solve the problem here IMO.