Skip to content

Project Structure

  • module - a file containing Python code
  • package - a collection of python modules and an__init__.py file

Split the code into meaningful modules and packages, and store them in the main directory mypackage. If the code consists of a single file, store the mymodule.py in root instead. Below is a sample project structure.

├── mypackage
│   ├── subpackage1
│   │   ├── *.py
│   ├── subpackage2
│   ├── subpackage3
│   ├── module1.py
├── tests
│   ├── fixtures.py
│   ├── data
│   ├── test_*.py
├── docs/
│   ├── index.md
│   ├── *.md
├── setup.sh
├── pyproject.toml
├── poetry.lock 
├── README.md 
└── .gitignore

Store directories like docs/, tests/, benchmark/ under the root directory

Other things to store under the root directory (* indicates required for all projects):

  • *README.md
  • *pyproject.toml/setup.py+requirements.txt
  • Dockerfile, .dockerignore
  • setup.sh or other script to set up dependencies like dvc remote
  • mkdocs.yml to host the documentation

Group logically connected stuff in separate modules. For example, an api can have separate modules for

  • endpoints(routers)
  • schemas
  • handlers
  • globals

Place miscellaneous functions in utils.py. Avoid having dependencies from the current or sibling subpackages in this file. For example, package/subpackage/utils.py is allowed to have internal dependencies only from the package/utils.py and not from package/subpackage/other_file.py nor package/other_subpackage/some_file.py.

README.md

README should include a basic description of the project, as well as instructions for:

  • Installation and setup
  • Basic usage

Modules/packages naming

  • Subpackages can have subpackages too and follow the same rules as the main package
  • Write module & package names in lowercase
  • Never use space (), dot (.), dash (—), hyphen (-) or other special symbols in module/package names. You can use underscore(my_module), but avoiding it is preferred (mymodule).
  • Don’t use underscore for namespacing (app/mysql_client.py, mymodule/mongo_client.py), use submodules instead ( mymodule/clients/sql.py, mymodule/clients/mongo.py)
  • Make sure to not override builtin or external module/package names, i.e. don’t name your package flask if you plan to use flask package inside it.