K Cartlidge

C#/DotNet. Go. Node. Python/Flask. Elixir.

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 ...

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.

mkdir my-app
cd my-app
python -m venv ./venv
source ./venv/bin/activate
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

venv/
__pycache__/
*.pyc
root = true

[*]
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
end_of_line = lf
charset = utf-8
# 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).