Rehashing the src layout

25 September 2017 (updated 20 September 2018)

Looking back at my Python packaging post, now it got more popular. Even Twisted is using it now but there's still confusion about it.

I mean, places that you'd expect would use a src-layout don't. Take flit for instance, I wrote a rant on packaging almost 1 year later, and that prompted Thomas Kluyver to make flit but strangely enough it uses the ad-hoc layout [1].

And there are plenty of guides on the Internet with the ol' ad-hoc layout.

So people are wondering: "I don't understand this packaging mumbo-jumbo, what should I use?"

It's not that complicated, just have these thoughts in mind when choosing:

  • If you use a project template (e.g.: cookiecutter) the choice of layout is not so important. The template should solve all the annoying packaging problems.

    You should use a template anyway.

  • If you already have a project using the ad-hoc layout, and you don't have problems with testing or packaging then there's little value in switching over to a src-layout.

  • The ad-hoc layout is more convenient and that's why there's high resistance to src-layouts.

    You need tooling to use the src-layout effectively. If you don't use a tool to manage virtualenvs and install your project like Tox then it's going to be painful.

  • Any layout will work. Mistakes can be corrected.

    If this don't make sense (I agree it's a bit heavy on jargon and technicalities) and you don't want to use a template then perhaps you're looking to learn packaging the hard way. Just flip a coin and start with something.


Now people have already asked for flit to support the src-layout. I have even added my thoughts on the issue.

Don't go over there and spam the issue with comments, I don't think there's anything new to add.

This entry was tagged as packaging python src