I am 👎 on this due to the type instability (for the same reason plot always returns a list) unless I am misunderstanding things.

What is the motivation for this other than the improved repr?

The point is mainly to improve the repr, but also so that in the most common case (histtype="bar" + single dataset), the returned artist is actually what got added to ax.containers rather than it being unpacked and repacked

To be clear: previously, the return types were
1 dataset:

• bar/barstacked -> "silent_list of Patch" (actually, a list of Polygons)
• step/stepfilled -> "silent_list of Patch" (actually, a list of one Patch)
  >1 datasets:
• bar/barstacked -> "silent_list of List of Patches" (actually, a list of lists of Polygons)
• step/stepfilled -> "silent_list of List of Patches" (actually, a list of lists of 1 Patch)

With this PR:

• in the bar/barstacked case, the list of Polygons was constructed by unpacking the BarCollection returned by bar(), and rewrapping it in a list. Instead, just return that BarCollection (which inherits from tuple, so most of the API one may want is there).
• in the step/stepfilled case, when using a single dataset, there is no benefit of wrapping in a silent_list (the repr of the normal list is more informative and barely longer). In the multiple-dataset case, just use a more accurate type info (which, again, just goes to the repr -- silent_list otherwise inherits from list).

So there is no additional type instability (well, except for the fact that hist's return type is already a total mess). The relevant type changes are, once again:

• in the bar/barstacked case, we don't convert BarContainers to silent_lists (again, note that the BarContainer is what's in ax.containers.
• in the step/stepfilled single-dataset case, we return a bare list of one element, not a silent_list of one element; the only difference is in the repr.

I'm 50/50 on type stability.

There are prominent examples that return different types depending on the input, e.g.

• numpy functions: np.sqrt(4) -> numpy.float64; np.sqrt([4, 9]) ->numpy.array
• pandas.read_excel: DataFrame or dict of DataFrames

IMHO it makes sense to have both Y and list of Y as return types, when you can pass X or list of X in and the common use case would be just to work with a single item.

plot() is a good (or bad) example for this. People are regularly confused that plot(x, y) returns a 1-element list. Only in the advanced use case of plottling multiple y-values at once (either by passing an array as y or by using the matlab-style parameter chain, there is actually a need for multiple return values. If I had to design plot() from scratch, it would return Line2D or list of Line2D.

With an existing API there's the additional problem of introducing an API change. I haven't made up my mind if it's worth it. However, we should try to have a consistent way of handling this topic and not just change one isolated function.

I was misunderstanding things, this is switching a silent list for a tuple sub-class. Still an API change, but a much smaller one than I thought.

Anyone can merge on green.

should be good to go post-ci.

Sphinx warnings:

/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:245: WARNING: py:obj reference target not found: Axes.hist
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:245: WARNING: py:obj reference target not found: silent_list
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:248: WARNING: py:obj reference target not found: Axes.hist()
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:248: WARNING: py:obj reference target not found: BarContainer
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:248: WARNING: py:obj reference target not found: Polygon
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:248: WARNING: py:obj reference target not found: silent_list
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:248: WARNING: py:obj reference target not found: BarContainer
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:248: WARNING: py:obj reference target not found: BarContainer
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:248: WARNING: py:obj reference target not found: Polygon
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:267: WARNING: py:obj reference target not found: Axes.hist()
/home/circleci/project/doc/api/api_changes_3.3/behaviour.rst:267: WARNING: py:obj reference target not found: silent_list