Django New Project Structure/Name

I’m curious how the community is naming new Django projects these days.

In the past, in my books I recommended something like books_project or blog_project as the name to keep it clear vs apps. A while back I switched to config as a default across my projects and books. Recently, however, several teachers have told me that config is confusing to their students. Especially for students using PyCharm.

My sense is that project naming and directory structure varies quite a lot in the wild. So I’m curious what’s being used these days. And any thoughts on what would be clearest to those new to Django.

Thanks!

3 Likes

I don’t think it matters what it’s called. I picked config years ago because it bubbles up to the top of a list of folders/files, it’s not clever, and it’s mentally easier to remember in big projects than {app_name}_project like everything else I had worked with leading up to it.

One could argue that project is a better name because you create it with python manage.py startproject. I think calling your web app “project” would be more confusing for new people because most people don’t even know what a project is. Most IDEs have a completely different set of opinions and features for projects as well, which doesn’t help.

In a perfect world, I would rename/merge startproject and startapp into one command, and I would call my default app+config just app, but going against ~16 years of Django material, so that’s out.

If you work on more than one project, I recommend standardizing one config folder name for all of your web applications/projects. Bonus points for being sort friendly so that it’s easier to locate.

In the medium to long term, I think standardizing to one config/project naming scheme is better because it makes copying and pasting configs between projects less problematic for people.

When in doubt, use config until you can come up with a better name.

4 Likes

I keep my projects inside a single Python package these days, and the apps as submodules within that. For example, for a project called books with two apps called core and loans:

books/
    core/
    loans/
    __init__.py
    settings.py

I normally have only one app called core. But when splitting things out into multiple apps, core is a good place for “base functionality” e.g. custom user model, custom model subclasses, etc.

It’s also possible to have the “project” module also be its one and only app:

books/
    __init__.py
    models.py
    settings.py

I think this is pretty beginner friendly, it’s what you’d when expanding up from one file in smaller frameworks like Flask. It’s just harder to split into multiple apps later, but is that really needed most of the time?:man_shrugging:

2 Likes

I am actually a big fan of config (or core) and would say keep it. Just maybe a brief explanation in the books(if not there already) on directory structure and why it matters - and Django defaults v. Common Patterns.

I don’t think there is anything consistent in the wild, and config is a pretty reasonable pattern.

1 Like

In my lat project I use:

my_project/
    app/
        app1
        app2
        ..
    config/ -> This is the Django Project directory
        base.py
        production.py
        development.py
    templates/
    tests/
    utils/ -> A directory for non-specific-app stuff
        helpers.py
        validators.py
        views.py
    activate -> a symbolic link to my venv activate file
    manage.py
    requirements.txt
   .gitignore
    ...

I am very happy with the layout.

Bumping: PR issued!

I’ve also settled on config over the years, and have issued a PR to make the startproject template follow this convention. I’ve taught Django to well over 100 newcomers, and it is alarmingly frequent how confusing have two directories with the same name can be:

  • my_project at the root
  • my_project/my_project for configuration.

I can’t tell you how many times I’ve said, “Okay switch into the ‘my_project’ directory - no, the other one! The one with manage.py / settings.py!”

I think config is the right choice. settings is already taken by settings.py in the default project, and conf isn’t as explicit an abbreviation as config (conf is often used for conference).

Ticket: #33650 (Update startproject template with config directory) – Django (djangoproject.com)
WIP PR: Refs #33650: Changes to the startproject template by FlipperPA · Pull Request #15609 · django/django (github.com)

If we are going to simplify, I think @adamchainz One Folder suggestion is the way to go. Ever increasingly enjoying this myself, plus thinking it fits the bill for most users better…

If I were to teach a beginner I would use startproject as-is but then add to INSTALLED_APPS and add the models.py, rather than startapp… — If we shipped the single-folder option, I could skip that.

It’s just harder to split into multiple apps later…

FWIW I don’t find that really: most of the project lives in the single-folder, with (if needed) extra apps along side… — but likely I’m not seeing exactly what Adam was referring to. :thinking:

I’m almost certainly in a minority but I think custom user models are a distraction (and swappable models in general TBH…) All folks ever wanted was a unique email field.

Realistically speaking, I think we could maybe/likely ship a single-file, and a single-folder template, in addition to the existing classic one, but getting consensus on a change to the classic template seems difficult. (I didn’t search the archives but this seems to come up frequently with no consensus…)

I thought the reason for having the configuration and settings in a separate folder was for security concerns. I’m not entirely sure what those security reasons are; maybe directory traversal?

Where do you place the projects urls.py, asgi.py and wsgi.py? Normally they are in the project dir next to settings.py.

How do you exactly do this?

You start with: django-admin startproject conf
and then rename the project folder simply to something else?
And then create an app with the name you want?
So it looks like this?
Is renaming the project folder all i have to do, or do i have to change the name also somewhere else?

renamed_project_name /
     config/
           settings.py
            urls.py
     app_you_created/
     manage.py