Python projects with Poetry and VSCode Part 1
A Virtual Environment is an isolated Python installation designed to avoid filling our base one with libraries we might use for only one project. It also allows us to manage multiple versions of the same package in different projects. We could, for example, need Django 4.1 for one and 1.9 for the other.
Poetry is a tool to handle dependency installation as well as building and packaging of Python packages. It only needs one file to do all of that: the new, standardized
pyproject.toml`. In other words, poetry uses
pyproject.toml to replace
MANIFEST.in and the newly added
In this first part, we will:
- Start a new project.
- Create a Virtual Environment.
- Manage dependencies.
In the second article, we’ll:
- Add our virtual Environment to VSCode.
- Integrate our dev dependencies:
And finally, in a third article we’ll:
- Write a sample library.
- Build our project with Poetry.
- Publish it on PyPI.
The easiest way is to use pip:
$ pip install poetry
But we will use Poetry own installer to isolate it from the rest of the system by vendorizing its dependencies. This is the recommended way of installing poetry:
$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
This way, we will later be able to update poetry to the latest stable version with the
poetry self update command.
Starting a new project
We can now start a new Python project by using the
poetry new [project_name] command. I will call it how-long and will be a simple library to measure the execution time of a function:
$ poetry new how-long
Note: For existing projects, you can use the
poetry initcommand and interactively create a pyproject.toml.
The directory how-long is created and inside is a basic project structure:
how-long ├── README.rst ├── how_long │ └── __init__.py ├── pyproject.toml └── tests ├── __init__.py └── test_how_long.py
Note: To be able to publish your project, you need an available name. Use the PyPI search for this.
The pyproject.toml file
The pyproject.toml file will manage the details and dependencies of the project:
[tool.poetry] name = "how-long" version = "0.1.0" description = "A simple decorator to measure a function execution time." authors = ["wilfredinni <email@example.com>"] [tool.poetry.dependencies] python = "^3.7" [tool.poetry.dev-dependencies] pytest = "^3.0" [build-system] requires = ["poetry>=0.12"] build-backend = "poetry.masonry.api"
[tool.poetry] ... license = "MIT" readme = "README.rst"
First is the Python version. Basically, this project will be compatible with Python 3.7 and up. Furthermore, from now on, every package we install that is meant to be used in production will be listed here.
These packages are only for development and will not be included when we publish our project. By default, Poetry includes Pytest, so we will use it to test our project later on.
Creating a Virtual Environment
To create a Virtual Environment and install Pytest, we will use the
poetry install command:
$ poetry install
After is done, a new file,
poetry.lock will be created.
When Poetry has finished installing, it writes all the packages and the exact versions of them that it downloaded to the poetry.lock file, locking the project to those specific versions. You should commit the poetry.lock file to your project repo so that all people working on the project are locked to the same versions of dependencies.
One way to add or remove dependencies is to directly edit pyproject.toml and then run
poetry install to apply the changes. We will instead use the
remove commands to avoid manual modifications.
Let’s add two packages to the project, pendulum, and coo:
$ poetry add pendulum coo
Open pyproject.toml and poetry.lock and see how they have updated.
Adding Dev dependencies
These dependencies will be available only during development, Poetry will not include them when building and publishing the project.
$ poetry add -D flake8 mypy
Now that I think about it, I forgot to add a formatter. We’ll go with black:
$ poetry add -D black [ValueError] Could not find a matching version of package black add [-D|--dev] [--git GIT] [--path PATH] [-E|--extras EXTRAS] [--optional] [--python PYTHON] [--platform PLATFORM] [--allow-prereleases] [--dry-run] [--] <name> (<name>)...
This error happens because black is in a pre-release state, so Poetry cannot find any stable version for us. But I really want it, so let’s install it anyway with the
$ poetry add -D black --allow-prereleases
You know what, I changed my mind, this project will use nor coo nor mypy. Start by removing coo, a normal dependency of our project:
$ poetry remove coo
Now mypy which is a dev dependency:
$ poetry remove -D mypy
In this first part, we have started a new project, created a Virtual Environment and added and removed dependencies by using the following commands:
|Start a new Python Project.|
|Create a pyproject.toml file interactively.|
|Install the packages inside the pyproject.toml file.|
|Add a package to a Virtual Environment.|
|Add a dev package to a Virtual Environment.|
|Remove a package from a Virtual Environment.|
|Remove a dev package from a Virtual Environment.|
|Update poetry to the latest stable version.|
In a second article, we will see more Poetry commands, add our Virtual Environment to VSCode and use the dev packages we installed to lint (Flake8), format (Black) and test (Pytest) our code inside the editor. Finally, in a third one, we will write and publish a sample library to PyPI.
Any doubt or suggestion? Please leave a comment.