API: deprecate show_in_notebook - #15905

Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

• Do the proposed changes actually accomplish desired goals?
• Do the proposed changes follow the Astropy coding guidelines?
• Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
• Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
• Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
• Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
• Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
• Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
• Is a milestone set? Milestone must be set but we cannot check for it on Actions; do not let the green checkmark fool you.
• At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.

I'll defer to subpackage maintainers and Jupyter experts here. The test fails because you need to handle this new warning. Also would need a change log.

Thanks!

As a developer, I agree to deprecating both (but I also support @mwcraig 's suggestion of discussing that in two separate PRs, since one case is more clear than the other).

As a user, I always forget that show_in_browser exists. I re-discover it about every other year, find that I love the feature, use if for a while and then forget about it again.

We already have a .to_pandas methods for tables and pandas has extensive styling support. Maybe we can just recommend to to use that for display in a notebook in one of our examples? Sure, it requires pandas to be installed, but that's not hard for most users and it actually offers functionality that the current show_in_notebook does not have, in particular the pandas build-in styles look pretty good. Maybe that extra styling functionality can compensate for the slightly less convenient use (pandas needs to be installed, need to click to the pandas docs to see how to use it)?

If we can make the same work for show_in_browser, then again that "extra functionality" makes up for the loss of convenience for me.

panel is less commonly used than pandas, but their Tabulator widgets displays a table sortable per column, which is often useful.

Edit: Add link to Tabulator widget.

Similarly, one might also use a bokeh DataTable.

My point is that instead of offloading the task of displaying the html table to a js library that we bundle, we could do that indirectly and offload to some other python package from the scientific ecosystem where js support is closer to their core mission and have them worry about which version to bundle and howto handle notebook updates etc.

I think of this a mostly a documentation task: "If you want to display your astropy.table.Table nicely, here are a few packages that can do that for you and here is a simple example how your astropy table can be passed to them and displayed ... "

Thanks all for your reviews!

Yes I think it probably makes sense to link to other well maintained libraries for working with Tables interactively inside a jupyter environment. I have removed the deprecation of JSViewer in this PR, I'll open a new one so we can discuss this it there.

👍 in general on deprecating these methods. I never found them all that useful in practice and the interactive browser is a bit clunky.

pandas has extensive styling support. Maybe we can just recommend to to use that for display in a notebook in one of our examples?

I just had a look at the pandas styling and I don't think that would be useful for the most-common use case of someone that was previously using show_in_notebook or show_in_browser using default styling (i.e. not supplying some custom CSS to make a fancy looking table).

The pandas machinery does not (AFAIK) provide a way to interactively browse a table. It just clips the table in the same way that astropy does. (Maybe I'm missing something?). So I would be against recommending a workflow that uses pandas styling. For the 98% use case here (setting precision of floats), astropy table formatting does the job and is way more convenient (IMHO).

There are good reasons to deprecate the functions in question, but I would like there to be documentation about available alternatives, and if we do write such documentation then the deprecation message should point to it.

There are good reasons to deprecate the functions in question, but I would like there to be documentation about available alternatives, and if we do write such documentation then the deprecation message should point to it.

I'm not aware of any easy alternatives to show_in_notebook(). The pandas styling stuff is basically equivalent to the table repr in a notebook but AFAIK it does not have any javascript bling like showing only 50 rows or sorting by columns.

tl;dr -- I see one approval, so is the diff okay as-is or more discussion needed? If so, what?

ipydatagrid is what I would have recommended -- I think that with the alternatives listed now this is good to go. May want to wait for @taldcroft though?

@taldcroft just wanted to bump this up.

One more thing that we have failed to notice so far is that show_in_notebook() is mentioned in the table documentation:

Just in case, you could do a recursive grep on the whole repo checkout too, to smoke out the rest.

And thanks to other reviewers for the inputs.

@MridulS - I've approved this, but can you track down the "show-in-notebook" issues that this fixes and put them in the description before we merge so they all get auto-closed?

@taldcroft thanks! updated #15905 (comment) with the relevant issues.

So, is this good to merge now? 😸

So, is this good to merge now? 😸

YES!

So happy to see one PR closes multiple issues. Thanks, all!

Looks like not everyone is happy with this, please see #16702 and advise. Thanks!

I run into this today as prepping notebooks for an upcoming AAS workshop. I see why it is removed, but otoh none of the offered alternatives are as nice our of the box experience, I mean I don't want to pull in all of bokeh just to have nicely formatted tables in a notebook.

(we didn't use the show_in_notebook for anything fancy and interactive just to have a sensibly formatted, and not ellipsed table with nicely defaulted scroller and such. Part of the workshop was to showcase astropy, too and why Table is "better" than pandas (the question comes up regularly), but if any of these third-party table tools need to be pulled in we may just pull the plug and switch to pandas?).

why Table is "better" than pandas (the question comes up regularly)

We should have a FAQ, but for the record (and for your tutorial), Table provides these capabilities that are not in pandas DataFrame:

• Robust support for table and column metadata. This is needed for representing data in file formats like FITS and VOTable.
• Support for N-dimensional column data, for example a table of thumbnail images in a source catalog.
• Support for columns of astropy Time, Quantity, and SkyCoord / Frame objects.
• General support for external "mixin" columns, for instance dask arrays.

As far as I can tell (from quick googling), pandas does not provide an interactive scrollable notebook interface for exploring notebooks. Google just shows 3rd party solutions. This choice by pandas would seem to support the astropy decision to delegate this kind of functionality to 3rd party packages.

I mean I don't want to pull in all of bokeh just to have nicely formatted tables in a notebook.

This sort of comment comes up regularly, and I respect your perspective but honestly do not understand it. I just installed bokeh and it required 6.9 Mb and completed in under a second, so I would just do it without a second thought and then use it.

There is this interesting news: https://blog.jupyter.org/ipydatagrid-is-now-part-of-project-jupyter-3b3dfb877664

I haven't looked into it carefully, but maybe we can leverage ipydatagrid and provide interactive Table display using this as the optional (?) dependency. BTW standalone ipydatagrid install is a little lighter at 3.1 Mb.

Thanks, all! Let's continue discussions of follow-up topics here:

• Support showing interactive tables in Jupyter Notebooks (again!) #16702
• DOC: Why use astropy Table/QTable over pandas DataFrame #17146

If you forget interactivity (I don't necessarily need that, for more complex interactivity tasks we use firefly anyway), but if there was an easy opt in config list that would make Table printing look pretty in a notebook by default, I would be super happy with it.
I know it shouldn't really be astropy's task to come up with this and keep maintaining it, but in practice, we already do something similar for visualization etc.

(I am thinking for my users who work in notebooks, and I really can't see it being a nice workflow to have them work with tables and any time they need to print more than a handful or rows I suggest them to pop into a third-party library instead. )

And my issue with adding bokeh just for this is not about size, but past experience of their changing API (it may very well be more stable now), and the technical debt I would introduce to this material just by introducing a new dependency with the sole purpose of pretty printing tables.