Python Project Layout

Internal

• Python
• Calling Python from bash

Overview

A typical Python project layout, which allows for code written in other programming languages as well, is similar to:

.
├─ .gitignore
├─ requirements.txt
├─ run
├─ initialize
├─ src
│   └─ mypackage
│       ├─  __init__.py
│       ├─  __main__.py
│       ├─ mypackage-part-1.py
│       ├─ mypackage-part-2.py
│       ├─ ...
│       └─ VERSION
├─ tests
│   └─ mypackage
│       ├─  
│           
└─ venv # created automatically upon virtual environment initialization
      ├─ bin
      ...

Start with an empty requirements.txt file, it can be expanded incrementally.

Initialize the Virtual Environment

Initialize the virtual environment following the manual procedure described here:

Python Virtual Environment | Virtual Environment Creation

Update pip and, if requirements.txt has declared dependencies, install them:

Python Virtual Environment | Virtual Environments and pip

Add .gitignore

venv/
__pycache__/
idea/
.idea/

Add __main__.py

Add the initial __main__.py:

.
├─ src
│   └─ mypackage
│       └─ __main__.py 
...

def main():
    print('.')


main()

Also see:

Modularization | main_.py

Add the run script

#!/usr/bin/env bash
# shellcheck disable=SC2086

PYTHONPATH="$(dirname $0)/src"
export PYTHONPATH
"$(dirname $0)/venv/bin/python" -m mypackage "$@"

chmod a+x ./run

Expand requirements.txt

Add your dependency to requirements.txt:

# ...
PyGithub == 1.58.2

and run:

venv/bin/pip install -r requirements.txt

Also see:

pip | requirements.txt

initialize: Initialization and Dependency Maintenance Script

#!/usr/bin/env bash
# shellcheck disable=SC2086

python -m venv "$(dirname $0)/venv"
"$(dirname $0)/venv/bin/python" -m pip install --upgrade pip
"$(dirname $0)/venv/bin/pip" install -r requirements.txt

if ! trust_root.sh --help >/dev/null 2>&1; then
  cat 1>&2 <<EOF

trust_root.sh not found on your system.

Install it with:

 [...]
EOF
else
  trust_root.sh "$(dirname $0)/venv"
fi

Alternative (needs refactoring):

Set the PyCharm Project

A project set up this way will be compatible with PyCharm. To complete the PyCharm setup:

• Set the Python interpreter. Use the interpreter from venv/bin/python.
• Designate the src as the source root directory: Right Click → Mark Directory as → Sources Root
• Designate the tests as the test sources root directory: Right Click → Mark Directory as → Test Sources Root

Setup PyCharm Debugging

To setup main script debugging:

Edit Configurations → The + sign → Python

Name: "__main__.py arg1 arg2"

Script path: Click on the folder icon and navigate. The final result is similar to: /Users/ovidiu/projects/pygithub/src/pygithub_experiment/__main__.py.

Parameters: ...

Environment variables:

PYTHONUNBUFFERED=1;GITHUB_PAT=...;MY_ENV_VAR_1=val1

TO CONTINUE

TODO

Process this: PEP 517 – A build-system independent format for source trees https://peps.python.org/pep-0517/