What is the best project structure for a python application?
Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Structuring a Python Application Show
Python, though opinionated on syntax and style, is surprisingly flexible when it comes to structuring your applications. On the one hand, this flexibility is great: it allows different use cases to use structures that are necessary for those use cases. On the other hand, though, it can be very confusing to the new developer. The Internet isn’t a lot of help either—there are as many opinions as there are Python blogs. In this article, I want to give you a dependable Python application layout reference guide that you can refer to for the vast majority of your use cases. You’ll see examples of common Python application structures, including command-line applications (CLI apps), one-off scripts, installable packages, and web application layouts with popular frameworks like Flask and Django. Command-Line Application LayoutsA lot of us work primarily with Python applications that are run via command-line interfaces (CLIs). This is where you often start with a blank canvas, and the flexibility of Python application layouts can be a real headache. Starting with an empty project folder can be intimidating and lead to no shortage of coder’s block. In this section, I want to share some proven layouts that I personally use as a starting point for all of my Python CLI applications. We’ll start with a very basic layout for a very basic use case: a simple script that runs on its own. You’ll then see how to build up the layout as the use cases advance. One-Off ScriptYou just make a Well, that’s fine if you’re just making a script for your own use, or one that doesn’t have any external dependencies, but what if you have to distribute it? Especially to a less tech-savvy user? The following layout will work for all of these cases and can easily be modified to reflect whatever installation or other tools you use in your workflow. This layout will cover you whether you’re creating a pure Python script (that is, one with no dependencies) or using a tool like pip or Pipenv. While you read this
reference guide, keep in mind that the exact location of the files in the layout matters less than the reason they are placed where they are. All of these files should be in a project directory named after your project. For this example, we will use (what else?) Here’s the Python project structure I typically use for a CLI app:
This is pretty straightforward: everything is in the same directory. The files shown here are not necessarily exhaustive, but I recommend keeping the number of files to a minimum if you plan on using a basic layout like this. Some of these files will be new to you, so let’s take a quick look at what each of them does.
But now that your application is growing, and you’ve broken it out into multiple pieces within the same package, should you keep all pieces in the top-level directory? Now that your application is more complex, it’s time to organize things more cleanly. Installable Single PackageLet’s imagine that We are going to package the Let’s take a look at the updated structure:
The only difference here is that your application code is now all held in the
This layout is a stripped down version of Kenneth Reitz’s samplemod application structure. It is another great starting point for your CLI applications, especially for more expansive projects. Application with Internal PackagesIn larger applications, you may have one or more internal packages that are either tied together with a main runner script or that provide specific functionality to a larger library you are packaging. We will extend the conventions laid out above to accommodate for this:
There’s a bit more to digest here, but as long as you remember that it follows from the previous layout, you will have an easier time following along. I’ll go through the additions and modifications in order, their uses, and the reasons you might want them.
The top-level files remain largely the same as in the previous layout. These three layouts should cover most use cases for command-line applications, and even GUI applications with the caveat that you may have to tinker with some things depending on the GUI framework you use. Web Application LayoutsAnother major use case of Python is web applications. Django and Flask are arguably the most popular web frameworks for Python and thankfully are a little more opinionated when it comes to application layout. In order to make sure this article is a complete, full-fledged layout reference, I wanted to highlight the structure common to these frameworks. DjangoLet’s go in alphabetical order and start with Django. One of the nice things about Django is that it will create a project skeleton for you after
running
This seems a little empty, doesn’t it? Where does all the logic go? The views? There aren’t even any tests! In Django, this is a project, which ties together the other Django concept, apps. Apps are where logic, models, views, and so on all live, and in doing so they do some task, such as maintaining a blog. Django apps can be imported into projects and used across projects, and are structured like specialized Python packages. Like projects, Django makes generating Django app layouts really easy. After you set up your project, all you have to do is navigate to the location of This will result in a directory called
This can then be imported directly into your project. Details on what these files do, how to harness them for your project, and so forth are outside the scope of this reference, but you can get all that information and more in our Django tutorial and also in the official Django docs. This file and folder structure is very barebones and the basic
requirements for Django. For any open-source Django project, you can (and should) adapt the structures from the command-line application layouts. I typically end up with something like this in the outer
For a deeper discussion on more advanced Django application layouts, this Stack Overflow thread has you covered. The django-project-skeleton project documentation explains some of the directories you will find in the Stack Overflow thread. A comprehensive dive into Django can be found in the pages of Two Scoops of Django, which will teach you all of the latest best practices for Django development. For more Django tutorials, visit our Django section at Real Python. FlaskFlask is a Python web “microframework.” One of the main selling points is that it is very quick to set up with minimal overhead. The Flask documentation has a web application example that’s under 10 lines of code and in a single script. Of course, in practice, it’s highly unlikely you’ll be writing a web application this small. Luckily, the Flask documentation swoops in to save us with a suggested layout for their tutorial project (a blogging web application called Flaskr), and we will examine that here from within the main project directory:
From these contents, we can see that a Flask application, like most Python applications, is built around Python packages. In this layout, everything lives in the Be sure to also visit our Flask Boilerplate Github page for a view of a more fully fleshed-out Flask application and see the boilerplate in action here. For more on Flask, check out all of our Flask tutorials here. Conclusions and RemindersNow you’ve seen example layouts for a number of different application types: one-off Python scripts, installable single packages, larger applications with internal packages, Django web applications, and Flask web applications. Coming away from this guide, you will have the tools to successfully prevent coder’s block by building out your application structure so that you’re not staring at a blank canvas trying to figure out where to start. Because Python is largely non-opinionated when it comes to application layouts, you can customize these example layouts to your heart’s content to better fit your use case. I want you to not only have an application layout reference but also come away with the understanding that these examples are neither hard-and-fast rules nor the only way to structure your application. Over time and with practice, you’ll develop the ability to build and customize your own useful Python application layouts. Did I miss a use case? Do you have another application structure philosophy? Did this article help prevent coder’s block? Let me know in the comments! Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Structuring a Python Application What is the best structure for a Python project?The Good way to structure a Python Project. Tip #1: Create a virtual environment.. Tip #2: Create a separate directory for tests.. Tip #3: Create different content directories.. How do you structure a program in Python?Programming Structure of python. Attributes and Imports: The structure Python Program consists of three files such as : a.py,b.py and c.py. ... . Functions: For example b.py defines a function called spam. ... . Statements: Python import statement gives file a.py access to file b.py. ... . Modules : ... . Standard library files:. How are Python projects organized?Organize your modules into packages. Each package must contain a special __init__.py file. Your project should generally consist of one top-level package, usually containing sub-packages. That top-level package usually shares the name of your project, and exists as a directory in the root of your project's repository.
How do I set up a Python project?Step 1: Make a Plan. We're eventually planning to make a very simple library for use in a Python program. ... . Step 2: Name it. ... . Step 3: Configure Environment. ... . Step 4: Create Organization on GitHub. ... . Step 5: Set up GitHub Repo. ... . Step 6: Clone and Add Directories. ... . Step 7: Create and Install requirements_dev. ... . Step 8: Code and Commit.. |