After writing about our experience with moving a mature Django app to Pants, I began wondering how difficult it would be to start a brand new Django project on Pants. While it overall wasn’t too great an undertaking to move our project over, it sure would have saved time if we had been using Pants from the beginning.

Of course, if you want to get up and running with Django as fast as possible, adding in the complexity of a build tool like Pants is going to slow you down. My hypothesis is that the early benefits of Pants outweigh the initial complexity bump. In particular, I believe the following features of Pants can pay large dividends early in a project’s lifecycle.

- out-of-the-box linting and syntax formatting
- eliminating the need for a virtualenvs
- fast test runs with out-of-the-box caching and parallelization
- painless deployments with .pex files

To test this hypothesis, I decided to follow the official django beginner tutorial and see what was involved to get it running on Pants.

If you are trying to follow this tutorial, checkout the repo for this tutorial. I have created each step as its own commit so you can refer to the diffs to see exactly how it works. If you encounter any trouble, the Pants Slack group is an amazing community with some of the most helpful people I have met in OSS.

Step 1: Initial Repo Setup

To begin, we want to create a new directory, initialize a git repo, and add a gitignore for python. We are going to be following the django tutorial so we will page_seo_title our project “django-tutorial”.

Now add the following Pants specific lines to end of your gitignore

Step 2: Setup Pants

Now we are going to setup Pants. To do this, I am going to loosely follow the Getting Started section of their docs.

First, create a file page_seo_titled pants.toml. At the root of your new repo. This will be the central place for all of your Pants configuration.

This sets up Pants for a python project and also enables the string import feature which is necessary for Pants to play nicely with Django settings files.

Now you are ready to download the pants script. This will be committed to your repo. Will be the entrypoint for Pants going forward.

Step 3: Setup 3rdparty dependencies.

One of the features of Pants is that it can manage all of your third party dependencies. This allows you to enforce consistent third party dependency versions across all of your applications. The biggest advantage, though is it can build all third party dependencies into standalone pex files (python executable) which can be used to easily deploy your code in a consistent way to production.

Pants is incredibly flexible with how you configure your repo but in our case we are going to create a subdirectory called 3rdparty where we will keep a list of all our requirements. We will then create another directory called src where we will keep our application code. In each of these folders we will create BUILD files which provide targets for Pants to use when building your project.

Create the following files with the contents indicated.

The combination of these files ends up making an executable target called django-admin which will run the django-admin script in the Django pypi module. That means that by running ./pants run src:django-admin, Pants will download Django from pypi, install it into an ephemeral virtual environment and run the django-admin script.

Step 4: Setup the Django Project

Part 1 of the Django tutorial instructs you how to setup a django project. We can roughly follow along, however, because we are using Pants there are a few differences.

When the tutorial says to run django-admin startproject mysite, you will need to run the following:

This causes Pants to invoke the django-admin binary target you created in the previous step. The arguments after -- are passed as arguments to django-admin.

In our case, we want to keep all our source code nested under the src/ prefix, so we will want to move the results of the startproject call.

Start project creates a manage.py script which becomes the entry point for many django tasks. To run this with Pants we will need to create a target for it. Add the following to src/BUILD

This creates another binary target that can be invoked using ./pants run. You’ll notice that we are specifying src/mysite:mysite as a dependency. This is telling Pants that when it builds this script to run, it needs to include src/mysite in order for it to work correctly.

The only issue is, currently, Pants will not find any targets in src/mysite, because we haven’t created any. To fix this, create src/mysite/BUILD as follows.

We should now be able to call manage.py like this:

This should output the available commands from manage.py.

Step 5: Create the Polls App

We can now use this manage binary target to create the polls app as directed in the tutorial. Just as before, we will need to move it into the src directory after we create it.

We also need to create a BUILD file like we did with the mysite directory. While we can do this manually, this is a common task so Pants has a helper for this. This simple command will introspect your project. Create BUILD files in all directories that it thinks need them with the correct targets. Don’t worry, it won’t modify any of the BUILD files you have already.

You can now follow the “Write your first view” step verbatim by creating/modifying the following files:

At this point in the tutorial, we are instructed to run the development server. We can do this with the following command.

If you are following along, at this point you are probably looking at ModuleNotFoundError: No module page_seo_titled ‘polls’. This is because, when we originally made the manage target, we did not specify polls as a dependency. This means that when Pants builds this target, it completely excludes that directory. This might seem annoying in a small project like this, but when you have a massive project with hundreds of thousands of lines of code, including every file in every build becomes a big issue.

To fix this, we need to amend the manage target in src/BUILD.

Now we can run the server. We are going to turn off autoreloading for now - in the next part of this tutorial we will cover how to get this working with Pants. Visit http://localhost:8000/polls in our browser. You should be able to see the view we wrote.

Step 6: Models and Migrations

At this point, we are ready to start Part 2 of the Django tutorial. One of the features of Pants is that it builds. Executes targets in isolation. This means when your files are running, they will actually be running out of short lived temporary directories. This creates some slight wrinkles with commands that are trying to modify your source tree, such as the django migration commands.

The first step to mitigate this is to hardcode the path to the SQLite database in settings.py (currently it relies on __file__ which will result in a SQLite DB being made in the temporary directory for the Pants run and then immediately being torn down.

When prompted to run migrate, use the following Pants equivalent

You should see db.sqlite3 created at the root of your project.

Now, follow the instructions to create a new model and add the polls app to settings.py.

At this point we need to run makemigrations. Unfortunately there isn’t a great path for this on Pants as of writing. What I found worked best was the following.

This command prints the proposed migration files to stdout. You then need to write this output to src/polls/migrations/0001_initial.py.

We also need to run tailor again to create a BUILD file in the src/polls/migrations directory so Pants can find it.

And, because these migrations are not referenced anywhere in our code, we need to create an explicit dependency for the poll library on polls/migrations.

You should now be able to apply your new migrations.

Step 7: Complete Django Tutorial Parts 2, 3 and 4

We can now complete the rest of Part 2 as well as Parts 3 and 4 with pretty much no adjustment. Any time you are asked to run manage.py xyz you will instead run ./pants run src:manage -- xyz.

When the tutorial prompts you to create templates, create polls/templates/polls/index.html. If you run the server at this point and try to access http://127.0.0.1:8000/polls/ you will get an error: TemplateDoesNotExist at /polls/. Once again, Pants is not bundling our new templates directory when running the manage target. To prove this, we can run the ./pants dependencies command to see what is being included.

In the output, you will not see the templates directory. To solve this, we need to create a target for the templates directory and then include it as a dependency of the polls target.

Normally in Pants, each directory represents a single target. This establishes a nice balance between the boilerplate of BUILD files and keeping targets narrowly scoped (you could theoretically have one target that includes all the files in your app but it would kind of defeat the whole purpose of Pants). With templates, the benefits of narrow modules are reduced (they are just static files that don’t get evaluated unless explicitly used). As a result, we are just going to make a single target at the top of the templates directory to include all html files.

Now we can add this as a dependency of the polls target.

At this point, you should be able to run the server and visit http://127.0.0.1:8000/polls/ successfully.

You can now complete the rest of Parts 3 and 4 of the tutorial without any adjustment.

Step 8: A few quick wins from Pants

If you’ve been following along with these steps you may now be wondering why it’s worth all this effort. So, before we stop for the day, let’s take a moment and take advantage of some of the best practices that Pants makes trivial to implement: syntax formatting, dependency ordering and linting.

To do this, we just need to add some more backend packages to our pants config.

By default, black and isort do not play nicely together so we need to define a pyproject.toml file to configure them (more details here).

Now we can run the lint goal to see whether we are failing any of these new checks.

If you want to enforce these rules in CI, you simply need to add a step to run this goal. In a large project, you can get great performance on this by using the --changed-since flag to only lint files that have changed since the provided gitref.

In my case, flake8 was very mad that all my lines were too long. I like longer lines so I added the following to my pants.toml.

To actually fix the problems being found by lint, we can use the fmt goal. This will format all your syntax with black. Order your dependencies with isort. Unfortunately you have to solve your own flake8 errors!

That’s it for this time.

At this point, we have completed the first four parts of the seven part Django tutorial. The next part deals with testing. This is another area where Pants can really take things up a notch, giving us parallelized test runs, test result caching and smart target selection for free. I’ll also make sure to cover how to get autoreload working on the development server. Follow me on Twitter for notifications about the next post (I keep it pretty quiet otherwise).

And, as always, we are hiring at iManage Closing Folders. If you want to help us figure out how to build high performing software development teams check out the job postings for our Toronto office (remote friendly!).

Costway US $314.00 Modern Loveseat Sofa Upholstered Dutch Velvet Sofa Couch-Green Costway US $144.00 Loveseat Cushioned Patio Steel Frame Swing Glider -Black Costway US $153.00 Swing Glider Chair 48 Inch Loveseat Rocker Lounge Backyard-Beige Costway US $431.00 4 Pieces Patio Rattan Conversation Set with Loveseat Sofas and Coffee Table Costway US $458.00 4 Pieces Patio Rattan Furniture Set with Glass Table and Loveseat-Navy Costway US $323.00 Modern Loveseat Sofa with 2 Bolsters and Side Storage Pocket-Pink Costway US $152.00 Swing Glider Chair 48 Inch Loveseat Rocker Lounge Backyard-Brown Costway US $212.00 Living Room Wooden Leg Armless Loveseat Sofa-Multicolor Costway US $139.00 50 Inch Patio Garden Bench Loveseats for Outdoor Costway US $448.00 Patio Aluminum Loveseat Sofa Outdoor Furniture Set with Thick Back and Seat Cushions-Gray