search

der-gabe / django-colorinput

Model and form fields to store RGB colors as hex strings and widget to render the native HTML5 color input element
GNU General Public License v3.0
0 stars 0 forks source link

Move source code into `src` subdirectory #2

Open der-gabe opened 5 years ago

der-gabe commented 5 years ago

This might not be necessary, after all.

It certainly wasn't necessary for packaging and publishing this project on PyPI, which already happened! :smile:

That leaves this to be decided as to whether it makes sense at all. I need to find out something about why people do this, what problems it solves and what the benefits are...

jugmac00 commented 4 years ago

Hi @der-gabe,

there seems to be more than one reason.

A minor reason: When more and more projects adept a src directory, it is easier to navigate the code base when you have a look at a new project.

It seems to be an emerging standard - just a few projects which follow this new, unwritten convention:

The important reason: When you develop a package, which is also installed, when you do a from your_project import something - is your_project then the installed package or your project's folder?

This can be problematic both when you start testing, but also already for your application.

There are several well written articles out there which explain the issues in detail - and what to do about it: https://hynek.me/articles/testing-packaging/ https://web.archive.org/web/20170615032800/https://enotuniq.org/ https://blog.ganssle.io/articles/2019/08/test-as-installed.html

der-gabe commented 4 years ago

Hi @jugmac00 ,

thanks for your comment and the list of projects that already follow this convention. You're quite right, it does seem to be the new normal.

Thanks for the articles, as well, which I've now read.

I was aware of Hynek's article, as that's the one everyone always references when it comes to this, but I had never actually read it. Now I have and he makes some very good points.

Interestingly, the second article actually argues that you don't need to do the whole src thing just to let your tests run against the code as installed, since tox provides a mechanism to run in another directory. Nice, but Hynek's other points about nicer repo structure and packaging still stand (and indeed, forgetting to include a resource when packaging has happened to me with this very project).

The third article is interesting, as it recommends the src subdir approach, but then goes on to show the way to avoid it - the same changedir trick for tox as presented in article 2. Towards the end, the author does say that they were inspired by the older article and merely wrote theirs to spread the word and preserve the knowledge.

Either way, at this point the src subdirectory is so common that it's even got its own subsection in the official setuptools docs and it does make for a rather cleaner code layout.

Not to mention that fact that it makes packaging easier.

I'll probably bite the bullet and make the switch at some point after merging my testing branch and certainly before the next release (i.e. the next time I need to package this thing).