When we talked about doing this before we rejected it because we wanted to be kind to static analysis so we would probably need to generate the pyi files still?

I don't think the pyi files necessarily need to follow pep8 (at least they may not need to be linewrapped)?

I thought we had an earlier discussion about this, but could not find it. I went through again and did a better search, and I believe the longterm goal was to get rid of boilerplate.py. Reading through the issues I've found that:

1. I left a comment that @jklymak had an implementation for this, but the branch was deleted. But I don't actually know where I found the reference to that branch any more.
2. Code generation improvements in Python 2.4 would enable dropping boilerplate.py, but 2.2 was still supported at the time: Pyplot update in setup.py #928 (comment)
3. The previous major holdup was the signature being *args, **kwargs

At this point, we are far and away from still supporting Python 2.2, and this implementation correctly creates the signature:

$ ipython
In [1]: import matplotlib.pyplot as plt

In [2]: plt.acorr  # Axes wrapper
Out[2]: <function matplotlib.pyplot.acorr(x, *, data=None, **kwargs)>
In [3]: plt.Axes.acorr
Out[3]: <function matplotlib.axes._axes.Axes.acorr(self, x, *, data=None, **kwargs)>

In [4]: plt.figimage  # Figure wrapper
Out[4]: <function matplotlib.pyplot.figimage(X, xo=0, yo=0, alpha=None, norm=None, cmap=None, vmin=None, vmax=None, origin=None, resize=False, **kwargs)>

In [5]: plt.Figure.figimage
Out[5]: <function matplotlib.figure.Figure.figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None, vmin=None, vmax=None, origin=None, resize=False, **kwargs)>

The only inconsistency is the error raised for incorrect arguments as noted above, but we could fix that with inspect.bind also?

I also could've sworn that yesterday I could get ipython/python to display the type annotations in signature, and thus confirmed that the wrapped versions were correct, but today I can't seem to get it to display anything, even for the original functions.

But yes, it looks like running mypy on an example that uses a pyplot wrapper does fail now, so we'll have to do something about that.

This will not have type hints for the generated functions. Type hints from pyi stub files are not available at runtime, and thus the signatures for any dynamic generation will not have them until and unless we have inline type hints.

This behavior may also explain the "ipython sometimes has annotations". It will have them, I think, for pyplot in #24976, but not any of the underlying functions. I believe Ipython uses the runtime annotations.

We could make boilerplate generate the pyi file instead of the py file, which is arguably easier (though not by much, honestly) and could be less strict about flake8...

I’m feeling very uneasy about this. Dynamically generated code can behave like static code, but it is different, which can show up in a number of ways:

• Only the executed code will reveal the added functions. But there are tools that statically analyze files.
• What happens when you step through this in a debugger?
• Is this correctly picked up in Sphinx? (Didn’t check because CI is broken). Maybe yes, but then likely without source links.
• Some types of structural errors in the generated functions would be caught by the parser (we at least know that we create syntactically valid functions). For dynamic functions, everything is deferred to call-time. (Which we might not cover systematically in our tests).
• Related: I assume it’s not possible to have a test coverage report on the dynamic functions.
• It’s harder to see that changes in our generating code will do the right thing: The static generator produces code that I can investigate. The dynamic generator produces runtime objects/ behavior that is much harder to reason about.
• For new contributors / readers of the code , it is much harder to understand what is going on.

Overall, I think this will work well in 99% of the cases, but I expect several edge cases where we’ll run into trouble. This is an essential part of the library. The static generator has proven to work well. Changing that is risky.

On the other hand, I do not fully understand the motivation. What are the benefits of this? Is this only because of flake8? If so, there have to be better ways to cope with it.

My understanding is that this is in response to my proposed change as part of the type hinting effort. See that discussion for my in depth reply.

The short version is that type hints made the auto generated code hit several edge cases on formatting that the existing naive textwrap implementation did not handle well and so rather than playing whack-a-mole with those edge cases, I used black, a tool designed to autoformat python code, to apply formatting to the autogenerated portions of pyplot.

I am not totally unwilling to rethink that, but the bar is pretty high, as outlined in my reply to the linked comment above.

I'm fine with running black on the autogenerated code.