Some Python beginner’s tips

25 May '20

I love Python. And Python’s ecosystem is great. But starting Python can be rocky. So here’s some random miscellaneous tips I remember getting people set up.

In general, The Hitchhiker’s Guide to Python is a great resource.

TL;DR

Use a recent Python 3 version

Python 2 is dead. If you start off with Python 2 now, you are setting yourself up for a hard time in the future. Give yourself a fighting chance and use Python 3.

Many systems still come with Python 2, this is okay. You can run both Python 2 and Python 3. To check if you have Python 3 installed, you can usually just check if you have an executable called python3:

python3 --version

Although you may need to check specific versions like python3.8, python3.7, or python3.6. These binary names are codified in the Python Enhancement Proposal (PEP 394), although of course Windows doesn’t behave. In general, using Windows will be more painful.

Python 3.8 is very stable. Don’t run anything below 3.6, and newer is better. You’ll miss out on some neat, new features that can make life easier if you aren’t running 3.7 or 3.8.

A quick note on PyPI

The Python Package Index, or PyPI for short, is where you can easily download packages to use in your project. We’ll go over the tools that make this easy, but you should know what PyPI is.

Understanding virtual environments

I wish I didn’t have to explain this, but virtual environments are pretty much required in practice, so here we go. Stick with me.

Why do I need a virtual environment?

In theory, it should be as simple as pip install <cool-library>. But will this use Python 2 or Python 3? If you’re clever, you might try and use pip3 install <cool-library> (if your system provides this command). This is only slightly better.

Unfortunately, pip installs packages into your global, system-wide Python installation. But this can very easily break other installed stuff. Fixing this is a major headache; it isn’t worth it.

To be fair, Python does have a good solution - a virtual environment aka. virtualenv. There require a bit more setup, but are totally worth it.

Virtual environments set up a separate environment that keeps stuff away from your global Python installation, and is easy to wipe away. This means it’s no big deal if stuff gets messed up.

virtualenv and venv

TL;DR: Don’t install virtualenv, e.g. via pip install virtualenv. Use venv!

There is an old package that is called virtualenv, but in Python 3, it’s unnecessary to install. Python 3 comes with it’s own virtualenv utility, which works fine. Although on e.g. Ubuntu, for some dumb reason, you’ll have to install that via python3-venv first.

This is how you create a virtual environment:

python3 -m venv env

The env is actually what the directory containing the virtualenv will be called. Idiomatically, it’s usually called env or venv. Pick one of these, many tools will auto-detect them (like that default Python .gitignore, or IDEs). I’m going to assume you called it env, which I picked because it’s a bit less confusing than two venv.

Unfortunately, before you can use the virtualenv, you have to “activate” it. This basically sets things like python or pip to point to the virtualenv versions. For e.g. bash, you do this by typing:

env/bin/activate.bash

Once activated, your shell usually displays some kind of indication it’s active, e.g. by showing (env) in the prompt:

$ which python
/usr/bin/python
$ python3 -m venv env
$ source env/bin/activate
(env) $ which python
/home/me/env/bin/python

If you close your terminal, or open a new window or tab, you’ll have to re-activate the virtualenv. Also, if you use an IDE, you’ll have to set it to use the virtualenv, too. Here’s how to do that in PyCharm and VSCode. I believe PyCharm can also create a virtualenv for you.

Finally, consider setting PIP_REQUIRE_VIRTUALENV to true. With bash, you’d add this to your ~/.profile:

export PIP_REQUIRE_VIRTUALENV=true

The Hitchhiker’s Guide to Python has more options on how to set this up on e.g. Windows.

As the name suggests, this will save you from accidentally running pip install without a virtualenv activated, and so prevent you from messing up the system installation. It has saved me many times.

requirements.txt

To allow other people to create a virtualenv to match yours, the common way of doing this is using a file called requirements.txt. You put your requirements in that, and then someone else can install them all at once using:

pip install -r requirements.txt

In it’s simplest form, it’s just one line per package you’d install via pip install, so for example:

requests
flask

To install those two packages. It can be more complex, for example you can also specify which versions are needed, e.g. if you depend on a minimum version. Keeping a requirements.txt file from the start is a good idea, but also tedious (although maybe less tedious than figuring it out later).

Alternatives to venv (pipenv, poetry)

These alternatives make managing a virtualenv easier, but also bring more complexity. I believe understanding venv is important, and hiding it only hurts Python beginners in the long run. It’s an important part of Python, even if it is unfortunate. That said, managing virtualenvs and requirements is tedious.

pipenv

The author of “The Hitchhiker’s Guide to Python” also wrote pipenv, which explains why he pushes it so hard. This post isn’t the place to go into detail, but there’s controversy around pipenv. Apart from the controversy - which is also tedious - the reason I don’t like pipenv is mundane: you can’t specify Python 3.x or higher, you have to pick exactly one. For some scenarios, this is fine, but it can also turn into a hassle if you want to share your code.

TL;DR: I would avoid pipenv.

poetry

Poetry is a fairly new project, but does everything right - for me.

It’s easy to set up, this will create a new folder for you project:

poetry new <project>

Alternatively, you can use poetry init for existing projects.

It makes managing requirements easy. You just run this command, and it keeps track of them for you - no more manually updating requirements.txt:

poetry add <cool-library>

It also can keep track of development dependencies, like unit test libraries. Usually, this is a right pain requiring a second requirements file, often called requirements-dev.txt, but with poetry, it’s simply:

poetry add --dev pytest

Installing the virtualenv is also easy:

poetry install

This is also what other people can run when they download your project. Activating the virtualenv is also easy:

poetry shell

As I said, poetry is fairly new, and you’ll have to get used to some terminology being different. You no longer need to manually make a virtualenv, the pyproject.toml file replaces setup.py, setup.cfg, and requirements.txt. But poetry does simplify workflows, including building artefacts or publishing your project to PyPI. I’m 100% happy with it, and can easily recommend it, even for beginners.

Django

Django is a great - if not the greatest - web framework, with loads of features. But it crushes even advanced Python users with a lot of complexity and Django-specific knowledge. Unless you are using Django in a professional (i.e. paid), customer-facing project, or you know you absolutely need many of the features Django offers, other options are available.

Flask is also great, but very different. It’s a “micro”-framework, so the way you get more features is by using add-ons. This means it’s relatively simple, although you’ll have to slowly add things, and not all add-ons are as good. But it grows with you, and the templating engine is easily the best there is.

Flask makes projects fun, and so increases your change of success. I have written many an internal tool in Flask. It’s quick to get started, quick to get working, and quick to deploy. It’s a real joy. Flask is surprisingly capable.

And should you need to, it isn’t too horrible to port Flask projects to Django. They share a lot of DNA. I’m not going to pretend it’s easy. But getting a proof of concept running in Flask is a lot easier, and a trade-off I would make. If you ever find yourself in the situation of having to port to Django, that’s a success already in my books. Make no mistake, Flask is very capable and shouldn’t be seen as less professional. But there’s no denying Django offers more for e.g. big e-commerce projects, or when you need some CRM aspects for business reasons.

I hope this helps you get started with Python, or helps you tame some Python projects you had lying around!

Python

Newer Older