Poetry

poetry.md

POETRY | PYTHON PACKAGING AND DEPENDENCY MANAGEMENT

Poetry serves as a versatile tool for dependency management and packaging within Python projects. With Poetry, you can effortlessly specify the libraries your project relies on, and it takes care of managing their installation and updates. Moreover, Poetry provides a lockfile mechanism to ensure consistent installs and facilitates project distribution through its build capabilities.

Requirements

Poetry mandates Python 3.8 or higher for its operation. It boasts multi-platform compatibility, aiming to deliver seamless performance across Linux, macOS, and Windows environments.

Installing Poetry

If you haven't installed Poetry yet, you can do so by running the following command in your terminal:

curl -sSL https://install.python-poetry.org | python3 -

Or if you prefer using pip:

pip install poetry

Make sure Poetry has been installed correctly by checking its version:

poetry --version

Creating a New Project

To create a new project using Poetry, you run the poetry new command followed by the name of the project.

poetry new my_project

This will create a new directory named my_project with the following structure:

my_project
├── pyproject.toml
├── README.md
├── my_project
│   └── __init__.py
├── tests
│   └── __init__.py

The pyproject.toml file is the project configuration file, and the my_project directory will contains the source code for the project. The tests directory will contains the tests for the project.

Initializing Poetry on a existing project

Inside your project directory

cd my_project

initialize Poetry by running:

poetry init

Follow the prompts to fill in the project information (name, description, author, etc.). At the end, Poetry will create a pyproject.toml file with your project's information.

The pyproject.toml file

The pyproject.toml file is what will orchestrate your project and its dependencies. It looks like this:

[tool.poetry]
name = "my_project"
version = "0.1.0"
description = "My project description"
authors = ["Your Name <your@email.com>"]
readme = "README.md"
packages = [{include = "my_project"}]

[tool.poetry.dependencies]
python = "^3.8"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

You can edit this file to add or remove dependencies, scripts, and other project information. Refer to the official Poetry documentation for more information on the pyproject.toml file.

Using virtual environment

Poetry automatically creates a virtual environment for your project when you run the poetry install command. This ensures that the dependencies are installed in an isolated environment, separate from your system Python installation. This is a best practice for Python development, as it avoids conflicts between different projects and allows you to manage dependencies more effectively.

To activate the virtual environment, you can run:

poetry shell

This will activate the virtual environment and allow you to run commands and scripts within it. You can deactivate the virtual environment by running:

exit

This will return you to your system's Python environment.

But if you don't want to use the virtual environment created by Poetry and want to use your own virtual environment, you can run the following command to install the dependencies in your own virtual environment:

poetry install --no-root

This will install the dependencies in a virtual environment created by you, and you can activate it using the source command.

source /path/to/your/virtual/environment/bin/activate

Replace /path/to/your/virtual/environment with the path to your virtual environment.

Adding Dependencies

You can add dependencies to your project using Poetry's add command. For example, to add the requests package, you can run:

poetry add requests

Replace requests with the name of the package you want to add. This will also create a corresponding entry in the pyproject.toml file, under the [tool.poetry.dependencies] section.

You can also specify the version of the package you want to install. For example, to install version 1.0.0 of the requests package, you can run:

poetry add requests@1.0.0

Installing Dependencies

After adding your dependencies, you need to install them. Simply run:

poetry install

This will install the dependencies listed in the pyproject.toml file and create a poetry.lock file to lock the versions of the installed packages. This ensures that the same versions of the packages are installed across different environments. You should commit the poetry.lock file to version control to ensure consistent installs.

Running Scripts and Commands

You can run scripts and commands from your project using Poetry's run command. For example, if you have a Python script named my_script.py, you can execute it with:

poetry run python my_script.py

This is for running Python scripts. If you have other scripts or commands, you can run them using the same syntax, replacing python my_script.py with the appropriate command.

Publishing Your Project (Optional)

If you want to publish your project to PyPI, you can do so using Poetry's publish command. However, you'll need to set up your PyPI account first. Refer to the Poetry documentation for more information on how to do this.

With these steps, you have successfully set up your project using Poetry and are ready to start developing! Make sure to refer to the official Poetry documentation for more information and advanced features.

Official Site >> https://python-poetry.org/docs/