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 itLICENSE
is a file containing details of the license the code is released under, for example one from OpenSource.orgCHANGELOG.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).