Should we discuss ./src/mypackage vs ./mypackage for project layout?

[stxlvt]

I think there is an issue in the Local Development Project Skeleton section:

mypackage/init.py preferred to src/mypackage/init.py

I have yet to see a rebuttal to ionel's arguments for using a src folder, and I was suprised to see this guide recommend the opposite. Why, specifically, do you recommend not using src?

[amontalenti]

@stxlvt That is quite the set of arguments you've linked to. I see some validity in his points -- but, I'm not sure I found them entirely convincing. I'll think on this one some more after looking at how a few prominent open source projects do it.

[stxlvt]

Thanks for answering, @amontalenti.

looking at how a few prominent open source projects do it.

Feel free to look, but I don't think it's relevant, except if they have good arguments for why they do what they do. And if they have, then those arguments are relevant not because they come from a prominent project or because many projects do likewise, but because they are good arguments.

Look at what he says himself in the webpage I linked:

Most projects use them incorrectly

He's challenging the status quo here. If you try to determine whether he's right or not by checking the status quo, then I can tell you ahead of time what conclusions you'll reach. ;-)

It is nontheless an interesting question, so I have googled for setup.py files on github, and 6 of the first 20 results used a src folder or something equivalent. Of those, the most well-known are perhaps matplotlib and Apache thrift.

I'm not sure I found them entirely convincing

If you could be a little more specific I will attempt to address each of your concerns. :-)

[cfperez]

Feel free to look, but I don't think it's relevant, except if they have good arguments for why they do what they do.

I don't have a dog in this "fight", so to speak, but definitely agree that following the popular convention is not necessarily the same as doing the right thing. One has to examine the arguments for the convention and compare them to the alternative arguments to find out, as @stxlvt says.

[amontalenti]

@stxlvt @cfperez I'm with you. This style guide is certainly not just a collection of popular techniques. It is seeking to distill down The Right Thing.

In the case of "To ./src, or not to ./src", I am not 100% sure what The Right Thing is. My initial sense is that creating a ./src directory is sorta un-Pythonic, because of "flat is better than nested" and also because having the package/module in the root leads to ease of development, such as simply running python and import mypackage right from the root of a project (or running python -m mypackage), without fiddling with PYTHONPATH.

I suspect that if GvR or Hettinger were working on a fresh project, that would be what they'd naturally start with. On the other hand, I can see the arguments of ./src, especially when the package is meant to be consumed as a standalone/open source project. So, that's why I need to do a little more research and thinking before I revise my opinion on this one. I still believe no ./src is simpler, and in this guide I've been trying to have simplicity win by default when the gains are not so great for the alternative.

[dirn]

Here's some more support for src.