When it comes to driving, we don’t make the student assemble the car before learning how to drive. Yet when it comes to learning Python, users first need to learn how to:
- Install Python, preferably in a virtual environment
- Use pip to install all requirements
- Resolve any dependency conflicts, as needed
Before they can even begin to start their Python course. This approach assumes the user has some familiarity with Python before they’ve even installed it, which can be both a false assumption by the course creator, and intimidating for the student. For example:
- Which Python version should I use? The Readme for the course doesn’t look like it’s been updated in a while and is recommending an older version, but shouldn’t I use the latest version?
- Which distribution should I use? The older one that’s pre-installed on my OS? Or should I download a newer version from python.org, or just get Anaconda? Will these conflict with my OS-installed one?
- I heard I should be using a virtual environment – how do I do that?
All good arguments why new users should get a good Python book or else a teacher/adviser before you start. But there’s another way to lower the barrier to entry for new users of Python: ActiveState’s State Tool.
Simple Python Installations
The State Tool can install a Python runtime into a virtual environment on Linux or Windows with a single command, simplifying the deployment of Python:
- On a developer’s workstation
- On any/all instances across your CI/CD chain
- In production
It’s also ideal for first time users since it automates the creation of their Python environment without requiring any previous knowledge. For example, take the popular “Learn Python” repository created by Oleksii Trekhleb on Github (trekhleb/learn-python). The Readme has this to say about environment setup:
- “Make sure that you have Python3 installed on your machine” with a link to RealPython’s website to explain the process in detail.
- “You might want to use venv standard Python library to create virtual environments…”
- “Install all dependencies that are required for the project by running:”
pip install -r requirements.txt
Alternatively, you could install the State Tool and run the “state activate” command to get started in just a few seconds without requiring any prior knowledge of Python.
In fact, you can do just that right here: https://github.com/shnewto/learn-python. That link goes to a fork of Trekhleb’s repo that we’ve created to show off the simple yet powerful capabilities of the State Tool. In this case, you just need to:
From the point of view of an end user, the State Tool dramatically reduces the amount of language-specific knowledge you require in order to set up your environment before you can get to what you really want to do: coding.
But for Github repository owners, it also means your users and contributors get started working with your project much faster, which may result in a lot more code contributions.
Reducing the Readme
To simplify the environment setup for your project, you can do exactly what we did for the Learn Python project: create a Python runtime on the ActiveState Platform, and include a YAML file in your repo that points to it. Let’s take it one step at a time:
- Create a free ActiveState Platform account
- Create a new project for Python on Linux or Windows
- Add the packages required for your project, and let the Platform automatically pull in all the dependencies, resolve them, and create an installer for you in just a few minutes
- Create an activestate.yaml file and add it to your repository. The file contains four lines:
name:<the name of your project from step 2>
owner:<the username you entered during step 1>
languages: <this line is left blank>
- name: python
- Don’t forget to add a link in your Readme to download the State Tool, as well as the instructions to clone your repo, cd into it and issue the “state activate” command.
While there may be other steps you require in your Readme, such as setting up a database, the State Tool lets you dramatically reduce the number of hoops your users have to jump through before they can start working on your project. Or if you’re an educator, it can make setting up a classroom full of Python environments every semester as simple as writing a script to delete the old virtual environment and “state activate” a new one on each system.