Avoid incentivizing multi-package distributions

[abravalheri]

Hi @codeandfire, thank you very much for the PR.
I would like to avoid incentivising a distribution with multiple top-level packages. What do you think about this alternative examples?

[codeandfire]

@abravalheri Sure, makes sense! I must admit I found the multi-package layout a little strange too, but I assumed there was some reason for keeping it that way. However, if we are advocating a single-package structure - I think that the src-layout becomes unnecessary, because the src directory is just a wrapper around the mypkg package directory; we might as well just stick to the flat-layout instead. What are your thoughts on this?

[abravalheri]

Well, there is some division in the community about the src-layout... some people like it, other people don't.

Personally, I think the src layout is less error prone and more explicit. It avoids problems with unintentional implicit namespaces (PEP 420) and make it easier to do better testing (which is independent of distributing one or multiple packages per wheel). I use the src layout in all my projects.

You can find some pointers in and discussion in pypa/packaging.python.org#320 (which motivated the example in the packaging tutorial to move towards the src-layout).

Also the classic explanation can be found in https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure (there is a newer post revisiting the topic which argues that a good project template will already take care of the things for you, but I still think the arguments in the original article are valid, and that the src-layout just facilitate doing the right thing).

[codeandfire]

Sure, no problem! Have merged your commit.