In 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:
helloworld/
│
├── bin/
│
├── docs/
│ ├── hello.md
│ └── world.md
│
├── helloworld/
│ ├── __init__.py
│ ├── runner.py
│ ├── hello/
│ │ ├── __init__.py
│ │ ├── hello.py
│ │ └── helpers.py
│ │
│ └── world/
│ ├── __init__.py
│ ├── helpers.py
│ └── world.py
│
├── data/
│ ├── input.csv
│ └── output.xlsx
│
├── tests/
│ ├── hello
│ │ ├── helpers_tests.py
│ │ └── hello_tests.py
│ │
│ └── world/
│ ├── helpers_tests.py
│ └── world_tests.py
│
├── .gitignore
├── LICENSE
└── README.md
The tests/ directory can also look like the following one.
│
└── tests/
│ |
│ └── unit/
│ | ├── __init__.py
│ | └── test_sum.py
│ |
│ └── integration/
│ |
│ ├── fixtures/
│ | ├── test_basic.json
│ | └── test_complex.json
│ |
│ ├── __init__.py
│ └── test_integration.py
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.
bin/: This directory holds any executable files. I’ve adapted this from Jean-Paul Calderone’s classic structure post, and his prescriptions for the use of a bin/ directory are still important. The most important point to remember is that your executable shouldn’t have a lot of code, just an import and a call to a main function in your runner script. If you are using pure Python or don’t have any executable files, you can leave out this directory.
/docs: With a more advanced application, you’ll want to maintain good documentation of all its parts. I like to put any documentation for internal modules here, which is why you see separate documents for the hello and world packages. If you use docstrings in your internal modules (and you should!), your whole-module documentation should at the very least give a holistic view of the purpose and function of the module.
helloworld/: This is similar to helloworld/ in the previous structure, but now there are subdirectories. As you add more complexity, you’ll want to use a “divide and conquer” tactic and split out parts of your application logic into more manageable chunks. Remember that the directory name refers to the overall package name, and so the subdirectory names (hello/ and world/) should reflect their package names.
data/: Having this directory is helpful for testing. It’s a central location for any files that your application will ingest or produce. Depending on how you deploy your application, you can keep “production-level” inputs and outputs pointed to this directory, or only use it for internal testing.
tests/: Here, you can put all your tests—unit tests, execution tests, integration tests, and so on. Feel free to structure this directory in the most convenient way for your testing strategies, import strategies, and more. For a refresher on testing command-line applications with Python, check out my article 4 Techniques for Testing Python Command-Line (CLI) Apps.
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.
Note: Keep in mind that these are just layouts. If a directory or file doesn’t make sense for your specific use case (like tests/ if you aren’t distributing tests with your code), feel free to leave it out. But try not to leave out docs/. It’s always a good idea to document your work.