Creating new Python projects

I've recently seen some small Python projects which have followed the ancient path of simply installing Python, adding dependencies, and starting to code.

At first glance, this may appear fine. However ...

• You may have a different system version of Python installed than the one you want
• Installing a new version may break existing system tooling
• Global Python means global dependencies, which may conflict when you have multiple codebases
• You may find things run fine for you, but not for someone else, due to their dependencies
• And so on.

Choosing a version of Python

Use Python 3. The older Python 2 is deprecated and about to lose support. Different operating systems have different ways of switching to Python 3 if Python 2 is your default one; there are many tutorials online.

Avoiding global/shared dependencies

In Python the simplest way is to use venv, a command-line tool which allows multiple segregated Python environments and dependencies to coexist. You could always use containers (eg Docker) but this way is easier. Here's the venv documentation.

• Create your new project folder and navigate into it

mkdir my-app
cd my-app

• Create a virtual environment and activate it

python -m venv ./venv
source ./venv/bin/activate

• Do all your development, run your app, whatever
• When done, deactivate this segregated virtual environment

deactivate

Starting and ending subsequent sessions

After the initial setup, working in one of your virtual environments is simple.

cd my-app
source ./venv/bin/activate
# do all your stuffs
deactivate

Install dependencies

You can install as many dependencies of whichever versions you like, safe in the knowledge that you are only doing so for your current virtual environment.

pip install Whatever-Dependency
pip freeze > requirements.txt

The second command (pip freeze) generates a list of all installed dependencies and their versions. That list is used to create an up to date requirements.txt file so other machines/users can see a definitive list of expected dependencies.

An existing project with a requirements.txt file can have all the required dependencies installed with a single command.

pip install -r requirements.txt

Other helpful files to add

• .gitignore is used by Git to know which files/folders don't belong in source control:

venv/
__pycache__/
*.pyc

• .editorconfig is used by many editors/IDEs to specify various formatting styles:

root = true

[*]
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
end_of_line = lf
charset = utf-8

• README.md should always exist to describe the project and how to use it
• LICENSE is a file containing details of the license the code is released under, for example one from OpenSource.org
• CHANGELOG.md details changes per date/version, for example:

# CHANGELOG

## v2.0.0 - 29th May 2020

- Adds a new way of doing stuff
- Includes auditing to a Postgres database

## v1.3.42 - 20th May 2020

- Final tests added to complete v1 development

It can be helpful to link from your README.md file to your CHANGELOG.md one:

# my app

This does a thing to a thing and it's great.
You can see the current status in [the CHANGELOG](./CHANGELOG.md).