Skip to content

Latest commit

 

History

History
58 lines (43 loc) · 5.15 KB

django-tour.md

File metadata and controls

58 lines (43 loc) · 5.15 KB

A Tour Through a Django App

Django is powerful and useful. It is also huge and written by other people, which can make it feel daunting. This guide is meant to give you some things to think about and prioritize when getting started with Django.

This guide uses a django app called Uptact as example code.

Django Creates a lot of Infrastructure

When you run django-admin startproject <your_project> . or when you create a project using the Momentum Django Template, which runs that command, Django creates a number of files and directories. Let's have a look at them. Files marked with a 🙅‍♀️ are files that you leave as is and do not edit.

  • Inside the uptact directory
    • 🙅‍♀️ __init__.py - has no contents, but it has to be present so that python treats it like a module, which you can import and use elsewhere in the app.
    • .env - contains variables whose values you want to keep secret. django-environ helps read the values of these variables.
    • 🙅‍♀️ asgi.py - used in deployment
    • settings.py - a hodgepodge of variables and their values used by Django. Many of these settings are generated automatically by Django or by the project template. The settings that you might be adding to or changing include:
      • ALLOWED_HOSTS, where you list which lists hosts/domain names that this Django site can serve. This is for security reasons.
      • INSTALLED_APPS, where you put your own apps and external libraries you use.
      • MIDDLEWARE - you might add here if you use certain external packages or if you write your own middleware. Middleware pertains to Django's request/response cycle.
      • You may change LANGUAGE_CODE or TIMEZONE if you want them to be different from the default.
      • The AUTH_USER_MODEL must match your user model. It is currently set by the project template.
    • urls.py - you will add urls here that users will visit or that will be API endpoints.
    • 🙅‍♀️ wsgi.py - also used in deployment.

The django-admin startapp <appname> command creates individual "apps" inside your Django project, which each have a set structure and collection of files. The Momentum Django Template runs this command to create a users app and a main app for the project. Colloquially, we call the whole Django project an "app," but, in strict Django terminology, an "app" is a specific unit of structure and function within a project. The Django projects we build will likely have two "apps", users and <the main app>. Uptact has users and contacts, which each contain the same kinds of files.

  • migrations/ - when you run ./manage.py makemigrations Django checks for changes in your models and generates migration files that contain instructions for changing the database to match the models. ./manage.py migrate actually applies the migrations files to the database.
    • 🙅‍♀️ __init__.py
    • 0001_initial.py
    • ...
  • 🙅‍♀️__init__.py
  • admin.py - register your models one at a time here in order for them to appear in the admin.
  • apps.py - configuration file that you will usually leave as is.
  • forms.py - not required, but you will usually need it. This is where you will create the structure of your forms.
  • models.py - where your models will go, which will provide the structure for the database.
  • tests.py - any python tests you have for your app will go here.
  • views.py - this is where the action happens. Views recieve requests and generate responses. They can be class-based or function-based. Views can process forms, query the database, or simply render HTML responses. Views can also generate JSON responses for API endpoints. Views are called by a user or part of the Django app itself visiting the url connected to that view in urls.py.

There are two directories that most Django projects have that you have to create yourself. They are not automatically generated by Django.

  • static/ - where static files live. These can include:

    • css
    • js
    • images

    Django collects these static files when you run ./manage.py runserver

  • templates/ - where your HTML will live. There are different conventions for how to organize templates, but the one we will use in class is to have a templates/ directory at the root level of the project with a subdirectory with the name of the main app, containing the templates for the app. In this case, it's contacts/.

Any time you run a command that begins ./manage.py, Django uses the manage.py file at the root level of the directory.

  • 🙅‍♀️ manage.py - you should never have to modify this file. If you get an error that looks like there's a problem with the file, it's likely an indicator of a different problem. Make sure that django is installed and that you are in your virtual environment.

  • Pipfile - lists the dependencies used in your project.

  • 🙅‍♀️ Pipfile.lock - automatically generated and updated by pipenv. If there's a problem with it, you can delete it and pipenv will regenerate it.