[PYTHON] Poetry begins

Poetry begins

We will summarize the basic usage of the Python project management tool Poetry through a series of simple CLI application creation steps. The execution environment is assumed to be MacOS / Ubuntu. Poetry version is 1.0.5

goal

Create a greet command that works as follows. Poetry is used to manage the Python packages required for commands and to install and use commands in a local virtual environment.

$ greet hello John
Hello John!

$ greet goodnight John
Goodnight John...

$ greet goodnight --sleeping John
zzz

Supplement

Installing packages directly in your local environment using Poetry is a bit tricky. I used the CLI tool as the subject because it was easy, but I didn't know how to install it with Poetry for everyday use. For details, refer to the item "Poetry settings" at the end of this article.

Poetry

A tool for managing dependencies and versions of packages used in Python projects (Here, the directory structure and files required to create a package are collectively called a project).

Since the package information is managed based on the pyproject.toml file, the environment required for the project can be easily reproduced by sharing the pyproject.toml file. Poetry also automatically creates a template for the pyproject.toml file.

Officially

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

Poetry installation

If Pyenv can be used in advance, there will be less trouble during installation.

In the following explanation, Python execution is assumed to be by the python command.

For MacOS / Linux, install Poetry as follows.

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

Execute source ~ / .bashrc for MacOS and source ~ / .profile for Ubuntu to pass the path of the poetry command. If you execute poetry -h and get clean help, it's OK.

For installing Poetry with the python3 command, refer to the item" Installing Poetry with the python3 command "at the end of this article.

Create a new Python project

Create a new Python project with Poetry's new command.

Execute poetry new greet at any location to create a new Python project greet. The set of files required to create the greet package is automatically created.

greet
├── greet
│   └── __init__.py
├── pyproject.toml
├── README.rst
└── tests
    ├── __init__.py
    └── test_greet.py

pyproject.toml It is used when creating a package from a project with poetry install described later. If you look closely when executing the command, you can see that Poetry temporarily creates setup.py.

[tool.poetry.dependencies] and [tool.poetry.dev-dependencies] list the packages used in the project and their versions.

It is automatically updated when the dependent packages are installed.

Python package installation

You can install the Python packages used in your project with the ʻaddcommand, By default,virtualenv` automatically creates a virtual environment for your project and installs it in it.

The greet tool uses the following Python packages.

--Required packages for operation - cleo --Packages used only during development (for dev) - flake8 - autopep8

Execute the following in the greet directory where pyproject.toml is located.

poetry add cleo
poetry add --dev flake8 autopep8

For dev, install with the --dev / -D option to the ʻaddcommand. This allows you to specify the--no-dev option when installing a project package (here, the greetpackage) withpoetry install` and skip the installation of packages that are not needed for execution.

Supplement 1

If you run poetry add ... on Ubuntu and get the following error, run ʻapt-get install python3-venv` as per the error message and it will work fine.

Creating virtualenv greet-b6grBBry-py3.6 in /root/.cache/pypoetry/virtualenvs
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt-get install python3-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Failing command: ['/root/.cache/pypoetry/virtualenvs/greet-b6grBBry-py3.6/bin/python', '-Im', 'ensurepip', '--upgrade', '--default-pip']

Supplement 2

If you are using VSCode, select the Python interpreter used by VSCode in the virtual environment created by Poetry. The path of the virtual environment can be confirmed by the Path of poetry env info, so specify it. For example, in the following case, specify /root/.cache/pypoetry/virtualenvs/greet-b6grBBry-py3.6.

$ poetry env info

Virtualenv
Python:         3.6.9
Implementation: CPython
Path:           /root/.cache/pypoetry/virtualenvs/greet-b6grBBry-py3.6
Valid:          True

System
Platform: linux
OS:       posix
Python:   /usr

Implementation of greet tool

Execute poetry shell in the greet directory containing pyproject.toml to enter the virtual environment for this project.

Create the following application.py in the greet / greet directory. Cleo is a Python CLI package that allows you to easily add commands and options, and the output can be nicely colored. I also use Poetry.

greet/greet/application.py

from cleo import Command, argument, option, Application


class HelloCommand(Command):

    name = 'hello'
    description = 'Say hello to someone'

    arguments = [argument('name', 'Name of a person to hello')]

    def handle(self):
        self.line(f'Hello {self.argument("name")}!')


class GoodnightCommand(Command):

    name = 'goodnight'
    description = 'Say goodnight to someone'

    arguments = [argument('name', 'Name of a person to goodnight')]
    options = [option('sleeping', 's', 'Sleeping...')]

    def handle(self):
        if self.option('s'):
            self.line('zzz')
        else:
            self.line(f'Goodnight {self.argument("name")}...')


application = Application()
application.add_commands(HelloCommand(), GoodnightCommand())


def main():
    application.run()

Editing the pyproject.toml file

Add the following to the pyproject.toml file.

greet/pyproject.toml

[tool.poetry.scripts]
greet = 'application:main'

[tool.poetry.scripts] corresponds to entry_points of setuptools, and is specified as <command_name> ='<module_name>: <function_name>'. As a result, the main function of application.py is executed when the greet command is executed.

Create and install greet package

Execute poetry install in the greet directory where pyproject.toml is located.

If you do poetry install --no-dev, the dev package will not be installed. Use poetry install for development purposes, and use poetry install --no-dev if you just want to use the package.

Checking the operation of the greet command

As shown in the goal at the beginning, the greet command can be executed in the virtual environment as follows.

$ greet hello John
Hello John!

$ greet goodnight John
Goodnight John...

$ greet goodnight --sleeping John
zzz

Run greet -h and you should see some pretty help colored by Cleo.

The above is the purpose of this paper.

Appendix

Installing Poetry with python3 command

It is assumed that there is no python command (there is no python in / usr / bin and only python3).

If you are using the python3 command, you can install it with:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python3

If necessary, run ʻecho'alias python =" python3 "'>> ~ / .bashrc && source ~ / .bashrc to make Python3 executable with the pythoncommand, thencurl ... python You can install Poetry with `.

However, in either case, Poetry cannot be executed with the following error even after passing the path after installation.

/usr/bin/env: ‘python’: No such file or directory

The cause is that Poetry uses the interpreter used for installation when it runs, but #! / Usr / bin / env python is hardcoded on the first line of ~ / .poetry / bin / poetry. It is because it tries to use / usr / bin / python even if it is installed with python3, and it can be used normally by rewriting this to #! / usr / bin / env python3. (issue: https://github.com/python-poetry/poetry/issues/1543)

As a solution to the state without the python command (the state where there is no python in / usr / bin and only python3), ln -s / usr / bin / python3 / usr / bin / python Even if you create a symbolic link with and then install Poetry with curl ... python, it works fine.

In addition, be careful when executing Python2 with the python command and Python3 with the python3 command.

Using Pyenv, switching to 3 series and installing Poetry seems to have the least trouble.

Multi-person development using Poetry

By sharing the pyproject.toml file in the repository, you can prepare the development environment. If you are new to development, just clone the repository and then run poetry install in the directory containing the pyproject.toml file to cut off the virtual environment for this Python project and install the required packages in it. Is done.

Poetry settings

The Poetry settings are listed in poetry config --list.

To install the package directly in the local environment, you can set virtualenvs.create to false, but if you install the package with poetry install --no-dev, the dev package will be uninstalled from the local environment. .. On the other hand, if you install a package with poetry install, unnecessary packages for dev will be installed, so it is difficult to install a package to be used throughout the local environment with Poetry. Please let me know if there is a good way.