Python Poetry Tutorial

In this article, we are going to learn all about the Python poetry library from scratch to advanced so that you don’t have any confusion regarding Python poetry.
Python Poetry is an external Python library that is used to manage the package dependencies. In this Python poetry tutorial, we will give you a complete guide to the use of the Python poetry library along with proper commands. At the end of this article, you will be completely able to work with the Python poetry module.

Firstly, we will start with an introduction.

What is Python Poetry Library ?

Poetry is a tool for dependency management and packaging in Python. Python poetry library allows you to declare the libraries your project depends on. It will automatically install and update the packages.

System Requirements

Python Poetry aims to run equally on multi-platform like windows, Linux, and even macOS.
Python 2.7 or 3.6+ should be installed in your system.

Installation

Poetry can be installed using pip and pipx.

pip install poetry

pipx install poetry

Update Poetry

To update poetry with a newer version, use self update command.

poetry self update

And, if you want to update poetry with a specific version, pass the version as an argument to self update command.

poetry self update version_number

Basic Usages

From here we will discuss all the poetry command with commands. I promise you after this article, you don’t have any confusion regarding the Python poetry library and its usages.

Setup

Firstly, to use Poetry you have to create a project using the new command.the new command takes the project name as a parameter.

poetry new poetry-demo

The above command will create a poetry-demo folder with the following content.

poetry-demo
├── pyproject.toml
├── README.rst
├── poetry_demo
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_poetry_demo.py

The pyproject.toml file is one of the most files here because it contains your project and its dependencies.
This file looks something like this.

Using Virtual Environment

By default, poetry creates a virtual environment in {cache-dir}/virtualenvs in windows and Linux. You can change it by editing your poetry config file. If you want to create a virtual environment in your project root directory, Then you have to set virtualenvs.in-project = true in config. Later we will see how you can
edit config.

Poetry Run

To run Python script file name with poetry, use the following command.

poetry run python python_script_file_name

Suppose we have a file name main.py and we want to execute it, Then we will use the following command.

poetry run python main.py

Activating the virtual environement

The easiest way to create the virtual environment is to create a new shell using the poetry shell command. To deactivate a virtual environment and exist from the shell, use the exit command.

Installing Dependecies

To install dependencies for your project, use the following command.

poetry install

Poetry Commands

Here we will see all the poetry command with the help of proper examples.

new:- This command helps you to kickstart a new Python project by creating a directory structure.

poetry new demo-project

The structure looks like this:

demo-project
├── pyproject.toml
├── README.rst
├── demo-project
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_demo-project.py

If you want to name your project differently from your folder use the --name option.

poetry new demo-project --name demo

The structure looks like this:

demo-project
├── demo
│   └── __init__.py
├── pyproject.toml
├── README.rst
└── tests
    ├── __init__.py
    └── test_demo.py

init:- This command is used to create pyproject.toml file interactively by promoting you to providing basic information about your package.

poetry init

This command has the following options

• --name:- Name of the project
• --description:- Description of the project
• --author:- Author of the package
• --python:- Compartible Python version
• --dependency: Package to require with a version constraint. Should be in format foo:1.0.0.
• --dev-dependency: Development requirements, see –require.

install:- Poetry install command read the pyproject.toml file from the current project resolves the dependencies and installs them.

poetry install

update:- To get the latest version of the dependencies, update the poetry.lock file by using the following command.

poetry update

Even you can update the specific version of the package by providing the package name.

poetry update requests

add:- The add command adds the required package to the pyproject.toml file and install them.

poetry add requests

remove:- The remove command is used to remove the installed packages from the list of installed packages.

poetry remove requests

show:- To list all the installed packages, use the show command.

poetry show 

Even you can see the details of specific packages.

poetry show requests

build:- The build command builds the source and wheels archives.

poetry build

publish:- The command is used to publish the packages to PyPI which build with the build command.

poetry publish

config:- This command is used to edit the poetry config settings.

poetry config --list

Syntax:

You can use the following syntax to change any existing config settings.

poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]

run:- The run command is used to execute the given command under project virtual env.

poetry run command

Even you can run your Python script file. Suppose we have a Python file named main.py, Then we will run the python file using the below command.

poetry run python main.py

shell:- Poetry shell command is used to activate the existing virtual environment, create if does not exists.

poetry shell

check:- The poetry check command is used to validate the pyproject.toml file and return “All set” if everything is ok.

poetry check

search:- This search command is used to search the packages on the remote index.

poetry search pendulum

export:- This command is used to export the lock file to another format. Only requirements.txt format supported.

poetry export requirements.txt --output requirements.txt

Configurations

List the current configurations:

To list the current configuration, use the --list option of the config command.

poetry config --list

Which will give something like this.

cache-dir = "/path/to/cache/directory"
experimental.new-installer = true
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = true
virtualenvs.path = "{cache-dir}/virtualenvs"  # /home/sazid/.cache/pypoetry/virtualenvs

Display single configuration settings

To display the single configuration settings, give the name of the settings to the config command.

poetry config virtualenvs.in-project

Adding or updating configuration settings:

To change or otherwise add new configuration settings, you can pass value after settings name.

poetry config virtualenvs.path /path/to/cache/directory/virtualenvs

Remove specific settings:

To remove specific settings, you have to use the --unset option.

poetry config virtualenvs.path --unset

Available Settings

cache-dir:- The path of cache-dir used by poetry.

macOS: ~/Library/Caches/pypoetry
Windows: C:\Users\<username>\AppData\Local\pypoetry\Cache
Unix: ~/.cache/pypoetry

installer.parallel:- Use parallel execution when using the new >=1.1.0 installer. Default is True.

virtualenvs.create:- Create a new virtual environment if does not exist. Default is True.

virtualenvs.in-project:- Create the virtual environment inside the project’s root directory. Default is None.

virtualenvs.path:- Directory where the virtual environment will be created.

Conclusion

So in this article, we have seen everything about the Python poetry library and its usages. Python poetry is one of the best python libraries for dependencies management and packaging. You should always use poetry in Python because it makes it easy to handle packages and their dependencies.

I hope this article will help you. If you like this article, please share, support, and keep visit for further Python tutorials.

Thanks for reading…

Python Poetry Reference:- Click Here