Rethink of project structure, or how I stopped worrying and learned to love startproject and startapp

[joshuadavidthomas]

Our current project layout looks a bit like this, not including hidden directories:

app_name/
	app_name/
		core/
			__init__.py
			apps.py
			views.py
		users/
			migrations/
			__init__.py
			admin.py
			apps.py
			forms.py
			models.py
		__init__.py
		asgi.py
		gunicorn.py
		settings.py
		urls.py
		wsgi.py
	docs/
	static/
	templates/
	tests/

This is a structure I settled on a few years ago. I like it alright, but I mostly landed on it after writing a few projects that had a bunch of internal, loosely-related apps (probably too many TBH!). Rather than all of those apps semi-cluttering up the base of the repo, they are all self-contained within the project's main directory. When adding a new app, you just create a new folder with all the requisite Django files, and bing bang boom you're all set.

However, there are a couple of issues with this. If your main app is named the same, you end up with something like this:

app_name/
	app_name/
		app_name/
			__init__.py
			...

And so imports end up looking a bit odd - from app_name.app_name.models import AppModel. If you have a bunch of imports, this ends up creating a lot of visual noise in the imports. On top of the fact it's just a bit clunky! And it's starting to drive me a bit crazy to type all of that out in the projects like that. 😵‍💫

You can get around this by naming the main app something different than the project name, but this can sometimes have the consequence of the name of the app not really fitting with what app itself does.

As well, this is not really an idiomatic way to organize a Django project and its apps. Generally, when using the startproject and startapp management commands provided by Django you end up with app directories at the base of the repo. (This used to bug me, not really anymore though. 🤷) There's also the single folder layout popularized by Carlton Gibson, plus a few other examples from Andrew Miller's blog.

As we've moved all of the common functionality needed by our projects in to installable libraries, the need for organizing the app directories has gone down. Now most of the projects only have ~3 folders in there. And we could probably trim down that even more since the core app isn't really needed anymore (it's all been moved to those libraries).

I've been using the following structure on a side-project and it's been nice not to have to worry about the app names clashing with the project's name, plus I can just use startapp in the base of the repo as-is when I need to expand by adding a new app.

app_name/
	app_name/
		migrations/
		__init__.py
		admin.py
		apps.py
		forms.py
		models.py
		views.py
	config/
		__init__.py
		asgi.py
		gunicorn.py
		settings.py
		urls.py
		wsgi.py
	docs/
	static/
	templates/
	tests/
	users/
		migrations/
		__init__.py
		admin.py
		apps.py
		forms.py
		models.py

Now, instead of from app_name.app_name.models import AppModel, it becomes the much shorter and readable from app_name.models import AppModel. And it's a much more common, idiomatic layout. And our projects generally won't need to go beyond this single app directory as we tend to write smaller, focused applications these days.

This is probably splitting hairs, and we should just stick with the way it is now. I mean, it works, right? Yeah, probably true. But this has been in the back of my mind for a few weeks/months now and I had to at least get it out of my system.