Anatomy of a Django Project

Thanks. Uh sorry for the slight delay. Uh as I said, my name's Mark, uh, and I'm here to talk about the anatomy of a Django project. It's listed as a novice talk, but really this is for anyone who's ever started a new Django project and not quite understood what was going on or Come into an existing Django project and wondering what's going on. So and uh I'm the technical director at Cactus Consulting Group. Uh we do Django-based consulting. So I've started probably dozens of Django projects over my time there, and I've encountered code bases for a dozen more. So I've seen a lot about

what um How people like to set up their projects. I've seen things that work, I've seen things that don't work, and this is kind of like an idea a lot of those ideas come from that This is the central question that I want to answer today. What is a Django project? We talk about Django projects, we talk about Django apps, we talk about web apps, we talk about WISGI apps, use a lot of terms without really well defining them. And I I want to describe My thoughts on what a Django project is, and and uh let you guys decide that for yourself.

So Django applications our Django apps. It's kind of like Lego bricks. They're supposed to be these pieces that compose a larger application. Some apps are very reusable, some apps are not. Again, just like Legos. Apps don't usually run by themselves. Lego bricks aren't particularly interesting by themselves. They need to be assembled into something larger. And they're assembled into projects. So a project, a Django project, sort of as defined by the Django tutorial, is a

set of configurations for a set of apps. So apps can be used in multiple projects, projects can be comprised of multiple apps. This is the real high-level idea of what is a project and what is an app. When most people come to Django apps or Django projects, they begin with Start Project. And start project looks like this. I'm going to start a new virtual environment. I'm going to install Django, I'm going to run Start Project, and it's going to give me some stuff. This is the project, I guess. It's these files.

It's an outer directory named for the name that I gave StarProject. a manage py, and then an inner Python package. Now this directory is a Python package because it has an init. And somewhere in here is a Django project, or all of it is a Django project. Let's look at each one of these files and kind of understand what they do and see what they mean. So manage PY, if you've never looked at it, it's pretty simple. It doesn't really do much of anything. It sets a default for an environment variable.

And then it calls a function called execute from command line, which is built into Django. It looks much like of another file which we've already used, which is Django admin. Which just calls execute from the command line without setting the environment variable. Without setting the default to the environment variable. So, if I had already set this environment variable, then I wouldn't need manage. Manage really isn't part of my project. It doesn't have any real configuration for the collection of apps that I'm using.

It's just a shorthand for Django admin py. So it's pretty easy to get rid of manage. And if you haven't seen this, this is awesome. Manage is Not really that interesting. So we're gonna add the path of the project to our Python path, this is using virtual m wrapper, which again if you haven't used virtual m wrapper, you should be using virtual end wrapper. We use two little hooks. A virtual nwrapper post activate, post deactivate to set the environment variable and then unset the environment variable.

This is so I don't have to use the settings flag. And then just to make sure that it worked I deactivate, reactivate a virtual environment, delete manage, because I never wanted to use it, and I'm just run with Django admin. So, whatever a Django project is, even though StarProje gave it to me, I would say manage is not part of it. So let's continue on and dive into this this my project package that we got There's a settings PY. Well, one would guess that by the name of it, it is in fact a collection of settings for configuring a collection of Django apps.

An interesting little note is that this comment, and this is generated by 1-6 as you can tell. Is that there's a little comment says builds paths inside the project, and the path that it references is the parent parent. So it's that outer directory where manage py was. So settings, at least in this comment string, thinks that manage was part of this project. But I deleted it. Some other files that are in uh here are URLs PUI. Again, this is based on 1. 6. You don't need some of this in 1.

7 Admin goes away. In 1. 8 you don't need patterns or patterns is deprecated. This is 1. 6 and this is what your typical URLs PY looks like. It's pretty straightforward, but it's kind of a mixture of configuration and code. It's directing URLs to callables. That's what URLs PUI does. It delegates um potentially that responsibility to other files. In this case, we include the URLs from admin and route them to admin So this is sort of a configuration, and we'll error on the side of saying that

this is part of the project. Uh the last file, other than the init, which is empty, uh is a little whiskey py file. This builds the actual WSGI application that you need to deploy on your favorite WSGI server. Again, it sets the environment variable. We've already set that at least in our local environment. If you're just using the default WISGI application, you could say that this really isn't project specific. Uh if you are using additional WISGI middleware, which

would be an interesting thing to explore, I don't see very often. Then you could say this is really configuration. So this is sort of part of the project. It's sort of part of the deployment process So those are all the files that Start Project gave me. And I'm getting a little closer to understanding. What a Django project is, what Start Project gives me. If we look back at the settings, we realize that The settings point to these other files. The settings points to the root URL configuration and it points to the WSGI application. So the only file

that really stands by itself in a Django project is the settings. Uh this uh this namespace that we created, this my project package Bundles these files together, but here from these settings it's clear that they do not have to be. This is this is a choice that Django made for me. That I don't have to obey if I don't want. So the settings file is really the heart, or potentially the only thing that exists in a Django project. So, some questions that come up about settings, about

projects. Um Where should my apps live? Should they live in this namespace? Uh where should additional templates live? What about static files? Should they live in here? Can my project have views? Can my project have models? I would say that they all have one kind of real answer, and that is there is no such thing as a Django project. There's only settings files. And a single deployment may have multiple settings files. It probably has multiple settings files for different environments.

Local development is not running the same settings as the production environment. So to answer a lot of these questions kind of falls from this idea. Django projects don't exist. Because Django projects don't exist, if you want templates which aren't part of an app, you have to tell Django where they are. And you tell Django where templates live if they aren't in an app in template there 's. It's a setting. The same thing for static resources. If you want to reference static resources that don't live in an app, you have to tell Django where they are. And you tell them through the static files

tours. Whether or not apps should live inside this project namespace or not is entirely up to you as a Python or Django developer You would use the same rules for however you would organize your application code. You can put them in the namespace. You cannot put them in the namespace. Some apps are reusable, some apps are not. A better question is probably not whether they should live inside the app name or inside the project namespace. But whether they should live in the same repository at all.

So, I want to show some alternate project layout configurations that I kind of made for fun. uh to really think about this idea or or explore this concept that projects don't exist or that the project that you get from start project isn't the project that you have to use. This namespacing is totally optional. And you should use the facilities that Django gives you to organize your project in a way not at what makes sense to Django, but what makes sense to you. So we're gonna we're gonna play. We're gonna explore.

If you didn't know, uh Start Project takes a little option called template, and you can point it to a path That can be a file system path. That can be a zip file. It can be a remote URL. At Cactus we have one. You can see it. It's open source. for our project layout and how we like to how we like to lay out projects, our default SALT deployment with fabric pieces and the apps that we like to use by default. And and these projects that we're gonna look at All follow this template

and so when you when you call start project you give it a name and that project name is replaced throughout. So here's the first one. So I like to call the app project layout. This replaces that inner project name space. Not with the project, but with an app. And by app I mean something that's going to contain real business functionality. Maybe models, maybe views. But more importantly, when I say app, I mean a Python package which must be added to the installed app setting. Because uh That definitely by 17

uh models are no longer required. The only thing that defines an app Is that it's in the installed app setting. An app is really not a thing. That's a different talk. I'll leave it for America to tell you why an app isn't a thing. So, I like this idea of a layout because I see people do this a lot. They say, I want an app that Sort of holds this logic for my sight. But I already used the cool name that I thought of. Naming things is hard. So I name the project, my fancy project, and I think, oh, now I need an app.

To be part of my fancy project, but I don't know what to call it, so I'll call it something really stupid, like core or common And that's what they do. So this layout says, let's take that cool namespace and we're going to use it for this core app instead. So settings PY is just settings and URLs is just URLs. They don't exist inside this namespace and we reserve the project name for this project app And because this project app is our core app, it potentially has templates which override other templates, it needs to be first in the installed apps. So we make that change.

The base der, we've moved settings outside that inner directory, so we changed the base dir settings. We changed the root URL configuration in the WISGI application configuration to remove the namespace. So now I have this project app. When I want to define project level templates, I put them in the project app. When I want to define project level static files, I put them in the project app. This is another layout. Uh it's called a micro project. It's a single file Django project. This isn't that new. I've

seen people as early as I think 2011 that have demonstrated this idea of a single file Django project. Uh Julie and I blogged about it. We write about it in the book. This is a working Django project. Please don't do this. It's interesting to know that it can be done, but please don't do this. Uh there's better ways to make this so that you don't run into a circular import nightmare. Which is why these constructs of moving things into separate files already exist. So uh If you want to run this hello world with all your views as lambdas, you can do this.

Please don't do this. If you want to see a better example, read the book. And this is something that's uh somewhere in between. I like to call the turnkey app layout. It's similar to the project app, but I envision this more for reusable apps. Imagine reusable apps that you could actually deploy. Because you can't deploy an app. And there's a lot of apps, a lot of reusable apps in the Django world that sort of straddled this line already. E-commerce apps, CMS apps, blog apps. That you may

want to use as a part of a larger project, or maybe that's your entire project. Maybe all my site is is a blog. And I just want to install a blog and run it. So I write a reusable app. So it has an app. With the models and views, it has a setup PY so I can pip install it, and it has a WSGI file so that I can deploy it. My WSGI file looks something like this. It kind of takes inspiration from the micro project. It configures the settings if the settings aren't configured.

So people can override the entirety of the configurations or you can give them same defaults. You can also envision things like pulling settings from the OS environment, from a configuration file, and it becomes deployable. You pip install it, you tell GUnicorn to run it. So the real summary here is uh projects don't exist. You've all been living a lie. Stop worrying about where files should go and just build cool stuff. These are some of the photos I used.

And thank you. There's time for questions. And you have questions, I'd love to hear them. Again, check out Lightweight Django. It's in pre-release by O'Reilly. I have some discount cards if you are interested. Thank you.