hasenpfote/python-poetry-example

A simple example of how to use pyenv + poetry + tox + pytest.

python-poetry-example's Issues

Considerations for Dynamic Versioning

目的

バージョン変数を動的に書き換える.
具体的には git tag を利用する.

対象

書き換える対象は少なくとも

• pyproject.toml の version
• __init_.py または __version__.py の __version__

方法 - poetry-dynamic-versioning

準備

Installation

pyproject.toml

[tool.poetry]
...
version = "0.0.0"
...
[build-system]
requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning"]
build-backend = "poetry_dynamic_versioning.backend"

[tool.poetry-dynamic-versioning]
enable = true # If manual, false.
vcs = "git"
style = "pep440"

[tool.poetry-dynamic-versioning.substitution]
folders = [
  { path = "src" }
]
...

__version__.py

__version__ = '0.0.0'

__init__.py

from .__version__ import __version__

概要

• 自動で書き換える場合
  vcs で管理されるファイルのバージョンは変更されない.
  厳密には一時的に変更されるが元に戻される.

  $ git tag v0.1.0
  $ poetry build

  dist 内の pyproject.toml と指定ファイルのバージョンが 0.1.0 に置き換えられる.
  元は変化しないので初期値が 0.0.0 ならそのままを維持する.
  ドキュメント生成を考慮しなければ最も楽な方法.

• 手動で書き換える場合 - tool.poetry-dynamic-versioning.enable = false
  vcs で管理されるファイルのバージョンは変更される.

  $ git tag v0.1.0
  $ poetry dynamic-versioning

  pyproject.toml と指定ファイルのバージョンが 0.1.0 に置き換えられる.
  置き換えられたファイルをコミットした後に git tag を振り直さなけば 1 つずれるので注意.

  ドキュメント生成を poetry build 以前に済ませる場合の選択肢の 1 つ.
  sphinx なら conf.py から __version__ を参照できる.

  • dist 内にドキュメントを含める場合など

  flowchart LR
  
    id0(start)
    id1(end)
  
    subgraph versioning
      id_v1(git tag v0.1.0)
      --> id_v2(poetry dynamic-versioning)
      --> id_v3(git add ...)
      --> id_v4(git commit ...)
      subgraph re-tagging
      id_v5(git tag -d v0.1.0)
      --> id_v6(git tag v0.1.0)
      end
      id_v4 --> re-tagging
    end
  
    subgraph documentation
      id_d1(poetry run sphinx-build ...)
    end
  
    subgraph build
      id_b1(poetry build)
    end
  
    subgraph publish
      id_p1(poetry publish ...)
    end
  
    subgraph targets
      id_t1(pyproject.toml)
      id_t2(__init__.py)
      id_t3(__version__.py)
      id_t3 .-o id_t2
    end
  
    id0 ==> id_v1
    versioning ==> documentation ==> build ==> publish ==> id1
  
    id_v2 .-> |v0.0.0 to v0.1.0| targets
  

  Loading
  • dist 内にドキュメントを含めない場合など

  flowchart LR
  
    id0(start)
    id1(end)
  
    subgraph versioning
      id_v1(git tag v0.1.0)
      --> id_v2(poetry dynamic-versioning)
      --> id_v3(git add ...)
      --> id_v4(git commit ...)
      subgraph re-tagging
      id_v5(git tag -d v0.1.0)
      --> id_v6(git tag v0.1.0)
      end
      id_v4 --> re-tagging
    end
  
    subgraph documentation
      id_d1(poetry run sphinx-build ...)
    end
  
    subgraph build
      id_b1(poetry build)
    end
  
    subgraph publish
      id_p1(poetry publish ...)
    end
  
    subgraph targets
      id_t1(pyproject.toml)
      id_t2(__init__.py)
      id_t3(__version__.py)
      id_t3 .-o id_t2
    end
  
    id0 ==> id_v1
    versioning ==> build ==> publish ==> id1
    versioning ==> documentation ==> id1
  
    id_v2 .-> |v0.0.0 to v0.1.0| targets
  

  Loading

課題

1. ドキュメント生成を考慮する場合の作法が煩わしい

2. poetry-dynamic-versioning がファイルを書き換える際に, ファイルの改行コードではなく OS を尊重する.
   [2022/12/16] バグだったようなので修正して頂き v0.21.2 で解消.
   Windows 環境下では変換の度に LF が CRLF に置き換わるが, v0.21.1 時点では簡便な回避方法がない.
   - 自動の場合
   poetry build 時なので dist 内のファイルに CRLF が混じる
   本例なら pyproject.toml と __version__.py
   - 手動の場合
   ファイル毎に手動で修正するか, pre-commit で自動化してもコミットが1度は失敗するので手間が発生する.

   本体の poetry version コマンドならば pyproject.toml の tool.poetry.version を改行コードを維持したまま変更する.

Considerations for caching Poetry in GHA

GitHub Actions で Poetry 自身のキャッシュを行うための考察.

動機

1. 時間
   GHA で Lint や Test の度に Poetry を用意する必要がある.
   準備をするのにそれなりの時間を要するため, Poetry 自身をキャッシュできるか考察をする.
   snok/install-poetry@v1 で実現できなかったことにも起因する.
2. 制限
   根本的には Included storage and minutes

対象

• OS は Linux / Windows / macOS
• 特に指定がなければ Poetry (1.3.1)
• actions/cache@v3

話題

• POETRY_HOME を指定することで起きる不具合
• Poetry のローカルキャッシュ
• Windows 上でシンボリックリンク復元に問題がある
• Windows 上で poetry run tox - e py が意図しないバージョンを参照する

外部の問題

• Poetry (1.3.1) でWindows に POETRY_HOME を指定すると動作が怪しい
• actions/cache@v3 の Windows におけるシンボリックリンク復元動作が怪しい

成果物

• Draft - 1
• Draft - 2
• Draft - 3
• Draft - 4
• Draft - 5