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
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
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
.gitignoreis used by Git to know which files/folders don’t belong in source control:
venv/ __pycache__/ *.pyc
.editorconfigis 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.mdshould always exist to describe the project and how to use it
LICENSEis a file containing details of the license the code is released under, for example one from OpenSource.org
CHANGELOG.mddetails 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
# my app This does a thing to a thing and it's great. You can see the current status in [the CHANGELOG](./CHANGELOG.md).