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
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
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.
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 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.
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) with
poetry install` and skip the installation of packages that are not needed for execution.
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']
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
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()
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.
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.
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
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, then
curl ... 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.
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.
The Poetry settings are listed in poetry config --list
.
Setting items | Default value | Description |
---|---|---|
virtualenvs.create | true | poetry add Orpoetry install Whether to use a virtual environment when executing. Note that if set to false, it will affect the direct environment. For example, in the false statepoetry install --no-dev When you execute pyproject.The dev packages listed in toml are uninstalled from the direct environment. |
virtualenvs.in-project | false | poetry virtualenvs.in-project true Can be set to true with. Files for the virtual environment will be created in the project. As a result, when the project directory is deleted, the virtual environment can be deleted at the same time. |
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.