Quick and simple setup with pyenv and poetry

この記事のスコープ

Ubuntu 22.04.2 LTSにて分析用Python環境を以下の方針で構築

• pyenv: Python version管理
• poetry: 分析用仮想環境の作成

想定環境

Pyenv and Poetry Version

1
2
3
4
5
% pyenv --version
pyenv 2.3.23-2-gac5efed3

% poetry --version
Poetry (version 1.5.1)

Usage

パッケージ開発でPoetryは用いられますが, ここでは分析用Python環境の構築の際に用いる Poetry + pyenvの組み合わせを想定しています.

• 分析で用いたいPython Versionをpyenvでインストール
• 分析環境, パッケージ依存関係, プロジェクトのパッケージ化をPoetryで管理

---
title: Python Env Set-up Flow
---
classDiagram
  direction LR

%%--- Entityの定義

    class mkdir{
        mkdir <--local path-->
        git init & set-up .gitignore
        git remote add origin <--github path-->
        git commit & push
    }


    class pyenv{
        pyenv install --list
        pyenv install <--python version-->
        pyenv local <--python version-->
        \n
    }

    class poetry{
    poetry init
    poetry install --no-root
    poetry add <--packages-->
    poetry run python, poetry run pytest
    }

%%--- Entity Relationの定義

mkdir --> pyenv
pyenv --> poetry

Set-up

Preprocess for Ubuntu

Ubuntu環境でpyenvをインストール場合, Python関連パッケージのBuildに必要なツールを事前にインストールしておくことが推奨されます.

1
ModuleNotFoundError: No module named '_ctypes'

インストールは成功したが, いざ使用しようと思った際にpip関係で上記のエラーが発生する場合があります. 上記の場合は, Cで書かれたライブラリを Pythonから利用するための使用するctypes モジュールが存在しないエラーですが, libffiがインストールされていない状態でPythonをインストールしてしまったことが原因となります.

ですので, 以下のパッケージを事前にインストールしときましょう.

1
2
3
% sudo apt-get install -y make build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev

Install pyenv

今回は, $HOME直下に.pyenvというdirectoryを作り, そこにpyenvをgit経由でインストールしています.

1
2
3
4
5
6
7
% tree -L 1   
.
├── Desktop
├── Documents
├── Downloads
├── ...
└── .pyenv

インストール手順は簡単で

• pyenv repository をgit cloneする
• pyenvのpathを通す
• pyenv init --pathをシェル立ち上げ時に実行する設定をする

1
2
3
## pyenv install
% mkdir ~/.pyenv
% git clone https://github.com/pyenv/pyenv.git ~/.pyenv

次に, .zshenv(.zshrcでもok, bashを使っているならば.bashrcなど)の設定を行う:

1
2
3
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Install the plugins: pyenv-update/pyenv-virtualenv

pyenvにはpluginがあり今回は２つのpyenv-update, pyenv-virtualenvをインストールします.

• 後者は基本的にはPoetryを利用する予定なのであまり必要ないですが, 様々な環境で簡易的に使いまわしたいという場合を想定してインストールしておきます
• 前者は, python-listの更新など絶対に必要

1
% git clone https://github.com/pyenv/pyenv-update.git $(pyenv root)/plugins/pyenv-update

1
2
% git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
% echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshenv

Install Poetry

Installコマンドは公式ドキュメントに従い以下. なお, pip経由でインストールする方法がたまに紹介されていますがそれは非推奨です.

1
2
3
4
5
## pipxでのinstall
% pipx install poetry

## curlでのinstall
% curl -sSL https://install.python-poetry.org | python3 -

Poetryをupdateしたい場合は

1
% poetry self update

Tab completionの有効化

poetryコマンドの補完機能を利用したい場合は,

1. poetry completions zsh で出力されるスクリプトをシェルの仕様に従ったファイル保存し
2. シェルにPathを通す.

自分の場合は, zshを使用しているので

1
poetry completions zsh > ~/.zsh.d/.zfunc/_poetry

その後, .zshrcに以下のラインを追記しています

1
2
# zsh completion
fpath+=~/.zsh.d/.zfunc

Basic Poetry config setup

Poetryのconfig directoryはデフォルトでは以下で管理されてます

• Linux: ~/.config/pypoetry
• MacOS: ~/Library/Application Support/pypoetry
• Windows: %APPDATA%\pypoetry

config file自体は上記のディレクトリのconfig.tomlに記載されます. config setup内容は以下のコマンドで確認できます

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
% poetry config --list
cache-dir = "/home/hoshino_kirby/.cache/pypoetry"
experimental.system-git-client = true
installer.max-workers = null
installer.modern-installation = true
installer.no-binary = null
installer.parallel = true
keyring.enabled = true
solver.lazy-wheel = true
virtualenvs.create = true
virtualenvs.in-project = true
virtualenvs.options.always-copy = false
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # /home/hoshino_kirby/.cache/pypoetry/virtualenvs
virtualenvs.prefer-active-python = true
virtualenvs.prompt = "{project_name}-py{python_version}"
warnings.export = true

設定項目のうち明示的に今回指定しているのは以下です:

1
2
3
4
5
6
7
8
## setting
% poetry config experimental.system-git-client true 
% poetry config virtualenvs.in-project true
% poetry config virtualenvs.create true
% poetry config virtualenvs.prefer-active-python true

## use --unset option if you want to unset
% poetry config virtualenvs.path --unset

1
% poetry config virtualenvs.create false --local

Maintenance

poetryとpyenvのupdateは定期的に実行したいので, shell scriptに僕の場合はまとめました.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
#!/bin/bash
## name: python_update
## Update the python env
## Author: RyoNak
## Revised: 2023-07-28
## REQUIREMENT: pyenv, virtualenv, poetry

set -e

# Functions
function usage {
  cat <<EOM
NAME
    $(basename "$0") - update pyenv and its plugins, and poetry. 

        pyenv update;
        poetry self update;

DESCRIPTION
    <pyenv and its plugins>
    pyenv
        https://github.com/pyenv/pyenv

    pyenv-update
        https://github.com/pyenv/pyenv-update

    pyenv-virtualenv
        https://github.com/pyenv/pyenv-virtualenv

    <poetry>
    poetry
        https://python-poetry.org/docs/
    
OPTIONS
  -h, --help
    Display help

EOM

  exit 0
}


# Main
if [[ $1 == '-h' || $1 == '--help' ]]; then
    usage
else
    pyenv update;
    poetry self update;
fi

How to use poetry in your project

Package install: poetry add

パッケージをインストールするときは, poetry add commandを用います. 以下のようにバージョン制約を指定いない場合, poetryは利用可能なパッケージバージョンに基づいて適したものを選びます.

1
% poetry add requests pendulum

poetry add with version constraints

Version成約をつける場合は以下のように指定します:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Allow >=2.0.5, <3.0.0 versions
poetry add pendulum@^2.0.5

# Allow >=2.0.5, <2.1.0 versions
poetry add pendulum@~2.0.5

# Allow >=2.0.5 versions, without upper bound
poetry add "pendulum>=2.0.5"

# Allow only 2.0.5 version
poetry add pendulum==2.0.5

# get the latest version
poetry add pendulum@latest

poetry add directly from GitHub Repository

GitHubのレポジトリからpackageをインストールしたい場合は以下のようなコマンドを用います

1
2
3
4
5
6
7
8
## via https protocol
% poetry add git+https://github.com/sdispater/pendulum.git

# install a package from the develop branch
% poetry add git+https://github.com/sdispater/pendulum.git#develop

# install a package based on a specific tag(2.0.5)
poetry add git+ssh://github.com/sdispater/pendulum.git#2.0.5

editable modeでのインストール

1
% poetry add --editable <package>

でeditable modeでのインストールがpoetryではできます. ローカルにファイルのあるパッケージをpluginとして利用するが, バグの可能性も考えて編集モードでインストールしたい場合に便利です.

Pythonコマンドの実行

Poetryで作成した仮想環境のPythonでfileを実行したい場合,

• poetry shellで仮想環境をコール, 呼びたした仮想環境内部でPythonコマンドを実行
• poetry runコマンドを頭につけて, Pythonコマンドを実行

の２つがあります

1
2
3
4
5
6
## 仮想環境を呼び出して実行
% poetry shell
(.venv) $ python main.py

## poetry runで実行
% poetry run python main.py

Tips

zsh promptに仮想環境状態を表示する

留意点として, 事前にvirtualenvのpluginを加えておく必要があります. まず, custom fucntionを.zshrcに以下のように定義します.

1
2
3
4
# Python virtual env
function virtualenv_info { 
    [ $VIRTUAL_ENV ] && echo '('`basename $VIRTUAL_ENV`') '
}

つぎにinteractive shellのpromptに表示するため, pro,pt_setup()に$(virtualenv_info)を加えます.

1
2
3
4
5
6
7
8
9
10
prompt_setup() {
    prompt_color1=${1:-'cyan'}
    prompt_color2=${2:-'cyan'}

    base_prompt="%F{$prompt_color1}%n@%m%f %F{$prompt_color2}%B%~%b%f "
    git_prompt='$(__posh_git_echo)'
    post_prompt=$'\n'"$(virtualenv_info)%# "

    PROMPT=$base_prompt$git_prompt$post_prompt
}

List up pyenv-based python version

1
% pyenv install --list | grep -P "^\s{1,}\d{1,}\.\d{1,}\.\d{1,}"

• grep -P: Pearl regular expressionを用いて検索
• pyenv-listなどシェルスクリプト定義しておくと便利

poetry install when there is no project module

1
2
3
% poetry install
...
<path-to-working-directory>/ <project-name> does not contain any element

poetry new, or poetry init コマンドで生成されるpyproject.tomlには以下のラインがデフォルトで記載されます:

1
2
[tool.poetry]
packages = [{include = "<project-name>"}]

package開発用のderectoryの場合ならば<project-name>の名前を持つdirectoryが存在するケースが多いと思いますが, 単に分析用に仮想環境を作成した場合はない場合があります.

このような状況のときに, poetry installコマンドを実行すると, 存在しない<project-name>directoryをpoetryが探してしまい以下のようなwarning messageがでてきます:

1
2
3
% poetry install
...
<path-to-working-directory>/ <project-name> does not contain any element

1
% poetry install --no-root

References

• GitHub > pyenv: pyenv source code respository
• GitHub > pyenv-virtualenv: pyenv-virtualenv plugin source code respository
• Poetry
• stackoverflow > Poetry install on an existing project Error “does not contain any element”
• stckoverflow > virtualenv name not show in zsh prompt