I'm not too familiar with the scaling mechanism. @anntzer @jklymak could the labels be included in the auto-scaling calculation, so that we don't have to explicitly scale here?

Texts normally don't participate (at all) in autoscaling -- they have the same problem as the one recently fixed by @jklymak for scatter(), which is that their extents is in physical units, not in data units.
To be honest I'm not really a fan of the solution here -- it'll likely break if e.g. someone adds more plot elements causing a rescaling, because then the "data limits" computed for the text won't be correct anymore.
I think a simpler solution for now is to just make sure that for "default" settings (a 640x480 figure, default axes size, default 5% margins, default font size), the default padding used by bar_label() ensures that the text indeed fits into the 5% margins, and leave more complex scaling to the user.

I'm not familiar with the scaling either (and mpl codebase 😂), do you mean I just drop the autoscale stuff and use a smaller default padding and fontsize?

No worries, it's a rather tricky part of the codebase, and your original approach is far from silly.
I would suggest indeed that (if possible) you make the default padding small enough that the things fit (normally) without re-autoscaling (if possible keeping the normal fontsize).

oops, I tried and found immediately that it seems not feasible for horizontal bar labels.. 😱

Ah, fair point re: horizontal labels. Even then I would be tempted to just document this as a limitation of the method and suggest that the user picks whatever limits works for them.

No problem, if so, I believe I can manage to achieve the goal! 😜

This variable name feels not quite right. But I don't have a better either right now.

displacement? 🤔

padding => longitudinal_offset
shifting => lateral_offset ? 🤔

This will ignore user input of an empty string, probably better to check for None-ness?

Instead of "longitudinal" and "lateral" how about "{parallel, perpendicular} to the direction of the bar" ?

I'd suggest:

`padding` : float, default: 0
      Distance of label from end of bar
`offset` : float default: 0
     Distance label is moved relative to the centre line of the bar (positive up/right)

currently the padding is still effective when position is 'center' and its direction will be the same as the bar points to, how could we describe this behavior? (or we disable it for 'center'?)

Do we need the shift perpendicular to the bar?

1. I can't imagine a plot that wants this shift. Anybody has a good example?
2. As it is implemented no, it's difficult to use because the label is centered in that direction. And offsets relative to center are somewhat messy (neither the centers nor the boundaries of the labels are very distinct reference points).

Admittedly, perpendicular shifting is a bit over-design, I would vote for remove it because I can't think of a justified / common use case either.

My opinion is to leave it off for now. Folks can still manually place the text if they don't like the helper. We can always add it later if its requested.

OTOH, don't be confused. Different folks have different opinions. @timhoffm is now API lead so if we don't get a consensus in a day or so, we can ask him for an explicit ruling 😉

got it & thanks for the reply!

I agree with @jklymak. Leave perpendicular shifts out for now.

@immaxchen is this taken care of now? (being lazy and not totally refreshing myself on this). If so, I think you are just waiting for @QuLogic to unblock. If you have addressed all his concerns this should be very close...

I think just @QuLogic need some time to think about if adding datavalues into BarContainer is a good idea, other suggestions should all be already addressed

It took me a while to understand what this meant, would it be clearer to say "If edge the value is the position of the edge (cumulative for stacked bars)" and "if center the value shown will be the length of the bar"?

I don't understand this description.

In the code this looks like it affects both the position and the value printed? I really don't understand this at all, and the docstring should make it clear what "position" and "value" have to do with one another.

Sorry didn't explain well, yes it affects both the label position and the value printed, please refer to the second example for better illustration, as below:

ax.bar_label(p1, position='center')
ax.bar_label(p2, position='center') # print 25 32 34 20 -25
ax.bar_label(p2) # default 'edge', print 45 67 64 55 -52

how could we describe it better?

I see what you are trying to do, but this is pretty confusing. I'm probably not the right person to help you because I'm not sure that I have ever plotted a stacked bar in my life.
But this is not really what we usually call a "position" in matplotlib, this is really two distinct ways to label a bar, so suggest perhaps:

label_type: string, default: 'edge'
  'edge' :  Label the end of the bar with the bar's absolute value 
                at the end.  
  'center':  Label the center of the bar, with the length of this segment 
                 (useful for stacked bars, i.e. `link_to_your_example`.)

👍 for (label_)type or kind because this does not only affect the label position but also it's semantics.

Description-wise, I think this would be even a bit clearer:

  'edge' :  Place the label beyond the top/right edge and display the
            value of that edge.  
  'center':  Place the label at the center of the bar and display the bar size.
             (useful for stacked bars, i.e. `link_to_your_example`.)

I didn’t suggest “bar size” because that’s a bit ambiguous. Does it include the whole bar down to the baseline or just the segment?

Well, it's a bit of terminology. Since we need multiple calls to bar I see every block of unique color (what you call segment) as a separate bar. And these bars are stacked on top of each other. Also if you say "place the label at the center of the bar" you implicitly adopt that perspective.

I'm open to discussion. We should try to find a consistent and understandable description. IMHO it helps if multiple people contribute their impression/expectation here.

Combining suggestions into a slightly more verbose one:

label_type : {'edge', 'center'}, default: 'edge'

'edge' :   label placed at the end-point of the bar segment, 
           and the value displayed will be the position of that end-point.

'center' : label placed in the center of the bar segment, 
           and the value displayed will be the length of that segment.
           (useful for stacked bars, i.e. `link_to_your_example`.)

does it make sense?

👍 For a standard way of formatting see e.g. the paramter align of bar().

I'd suggest:

`padding` : float, default: 0
      Distance of label from end of bar
`offset` : float default: 0
     Distance label is moved relative to the centre line of the bar (positive up/right)

do we want to take new style format strings instead? See arguments both ways.

do we? both ok for me, currently using old style just for consistency with clabel.

One could also support both using

try:
    label = fmt % value
except TypeError:
    label = fmt.format(value)

But I'm not sure if that's worth it or if we even want that redundancy.

I'm fine with sticking to %-formatting, but don't have a strong opinion on that.

Hi @tacaswell, could you make a final decision? new, old or both?

I think we should stick to old-style formatting for consistency throughout the lib.

Why not update the existing example?

applicable for lines_bars_and_markers/barchart and horizontal_barchart_distribution
but sadly, this PR does not provide fine-grained controls needed in statistics/barchart_demo
this PR acts on BarContainer as a whole instead of fine-tuning color/position for every single bar
and for misc/demo_ribbon_box it will not work because they are not bars, they are images

Shift by (size of bar)/2 to place the label centered, but over the bar?

I don't think these extrema calculations are quite correct, as you could set the bottom=-1, height=0.5, then the center is at -0.75, and this code would pick below, but it should pick above. I don't know if BarContainer has all information you need to catch this case.

in order to perceive the contextual position of labels (i.e. to distinguish between bottom=-1, height=0.5 vs. bottom=-0.5, height=-0.5), I have added an additional datavalues attribute into BarContainer in this new commit, i think this might be the only way to do it but not sure if it is desired.

This is not the type.

I agree with @jklymak. Leave perpendicular shifts out for now.