🎨📝 Fix in-tree PEP 517 backend wrapper example

[webknjaz]

Before this patch, the documentation suggested the package authors to declare a fixed set of hooks inherited from setuptools. But this approach turned out non-future proof. Over time, as setuptools added support for editable installs, it introduced new hooks per PEP 660. But if one were to follow the outlined example, they'd end up with an in-tree build backend that does not support editable installs, nor would it re-export any hooks that might be added in future versions of setuptools, implementing any new standards that may emerge over time.

This change demonstrates an approach that would allow the thin wrapper authors to get the new hooks that setuptools may add over time.

Ref: ansible/ansible#79606 (comment)

Pull Request Checklist

• Changes have tests
• News fragment added in changelog.d/.
  (See documentation for details)

[abravalheri]

Thank you very much @webknjaz. In #3897 I am trying to handle the CI problems identified here.

What do you think about keeping both:

from setuptools import build_meta as _orig
from setuptools.build_meta import *

This way we can use _orig.* directly in the wrapping hooks and don't have to do the renaming dance?
If you are OK with that, I can do the change myself while merging.

[abravalheri]

I was planning a new release today so I went ahead and merged with the changes mentioned above. I hope that is OK.

Thank you very much for the contribution.

[astrojuanlu]

TIL about backend-path! 💡

[webknjaz]

This way we can use _orig.* directly in the wrapping hooks and don't have to do the renaming dance?

I'm conflicted about this. I think some linters may complain about the double import. Hence my original suggestion.

Though, I personally prefer not shoving everything into a single module. Organizing things across many files as an importable package turned out to be more elegant, in my experience (I first used this approach like 3 years ago, and made use of it once or twice more over the years).
I didn't send this more complex suggestion because it seems that this document is not the right place, plus I wanted to keep the example small.

@abravalheri do you think there a place for a more comprehensive example in the setuptools' docs?

[abravalheri]

I'm conflicted about this. I think some linters may complain about the double import. Hence my original suggestion.

I believe that flake8 will require a # noqa in the import * even if there is no double import, and pylint in my opinion is too rigid, with a lot of false positives, to the point that is always tricky to use it... But conceptually the 2 lines have 2 different purposes, so I think it is kind of elegant.

do you think there a place for a more comprehensive example in the setuptools' docs?

Maybe, it is hard to tell before hand. More docs is usually a good thing (if the information they contain does not become outdated).

There is always the possibility of writing an "advanced tutorial" and keeping in a separated section to avoid confusing beginners.

[webknjaz]

There is always the possibility of writing an "advanced tutorial" and keeping in a separated section to avoid confusing beginners.

Do you think it's better to put it into the PyPUG?