incremental

増分

Incremental は、将来をサポートする CalVer バージョン マネージャーです。

API ドキュメントはここにあります。物語のドキュメントが続きます。

コンテンツ

• 動作理論

• クイックスタート

• セットアップツールの使用

• 孵化したばかりの子の使用

• setup.pyの使用

• プロジェクトを初期化する

• ランタイム統合

• 増分バージョン

• 更新中

• 不確定なバージョン

動作理論

• バージョン番号の形式は YY.MM.PATCH です。

• プロジェクトの名前が「Shrubbery」の場合、そのコードはshrubbery/またはsrc/shrubbery/にあります。

• Incremental は、プロジェクトのバージョン番号を{src/}shrubbery/_version.pyに保存します。

• バージョンを更新するには、必要に応じて--rcおよび/または--patch渡して、 incremental update Shrubberyを実行します (下記の「更新」を参照)。

• バージョンを変更すると、コードベース内の「Shrubbery NEXT」などの不定バージョンも更新されるため、ドキュメントで次のリリースを参照できます。それがインクリメンタルが未来をサポートする方法です。

クイックスタート

セットアップツールの使用

Incremental をpyproject.tomlに追加します。

 [build-system]requires = ["setuptools","incremental>=24.7.2", # ← ビルドの依存関係としてインクリメンタルを追加]build-backend = "setuptools.build_meta"[project]name = "<プロジェクト名>"dynamic = ["version"] # ← バージョンをマークする Dynamicdependency = ["incremental>=24.7.2", # ← 依存実行時のインクリメンタル]# ...[tool.incremental] # ← Incremental の setuptools プラグインをアクティブ化する

[tool.incremental]テーブルが空でも問題ありませんが、存在する必要があります。

[project] version =エントリと[tool.setuptools.dynamic] version =エントリを削除します。

次にプロジェクトを初期化します。

孵化したばかりの子の使用

Hatchling を使用してプロジェクトをパッケージ化している場合は、 pyproject.toml変更して Incremental の Hatchling プラグインをアクティブにします。

 [build-system]requires = ["hatchling","incremental>=24.7.2", # ← ビルドの依存関係としてインクリメンタルを追加]build-backend = "hatchling.build"[project]name = "<プロジェクト名>"dynamic = ["version"] # ← バージョンをマークします。 runtime]# ...[tool.hatch.version]source = "incremental" # ← Incremental の Hatchling プラグインをアクティブにする

インクリメンタルは、オプションの[tool.incremental]テーブルで通常どおり構成できます。

hatch versionコマンドは、増分管理バージョンを報告します。バージョンを変更するには、 incremental updateコマンドを使用します ( hatch versionでの設定はサポートされていません)。

次にプロジェクトを初期化します。

setup.pyの使用

Incremental はpyproject.tomlの代わりにsetup.pyから使用できます。これをsetup()呼び出しに追加し、他のバージョン管理引数を削除します。

 setup(use_incremental=True,setup_requires=['incremental'],install_requires=['incremental'], # 他のインストール依存関係も含めて...
}

次に、プロジェクトを初期化します。

プロジェクトを初期化する

pipx install incrementalを使用して、Incremental をローカル環境にインストールします。次に、 incremental update <projectname> --create実行します。次のような_version.pyという名前のファイルがパッケージ内に作成されます。

増分インポートから Version__version__ = Version("<プロジェクト名>", 24, 1, 0)__all__ = ["__version__"]

プロジェクトの後続のインストールでは、バージョン管理に増分が使用されます。

ランタイム統合

パッケージの API で_version.pyからincremental.Version公開できます。これを行うには、ルート パッケージの__init__.pyに次の内容を追加します。

 ._version インポート __version__ から

注記

インストールされているパッケージのバージョンを取得できる Python 3.6 の importlib.metadata.version() の導入以降、 __version__属性を指定することは時代遅れになりつつあります。

このオブジェクトを公開しない場合、またはパッケージ内で使用しない場合は、実行時に Incremental に依存する必要はありません。これは、プロジェクトのdependencies配列から (または、 setup.pyのinstall_requiresから) 削除できます。

増分バージョン

incremental.Versionは、特定のプロジェクトのバージョンを表すクラスです。これは、次の要素で構成されます (インスタンス化中に指定されます)。

• package (必須)、このVersionが表すパッケージの名前。

• major 、 minor 、 micro (すべて必須)、プロジェクトのVersionの XYZ 。

• release_candidate (オプション)。0 以上に設定すると、このVersionリリース候補 (「プレリリース」とも呼ばれる) であることをマークします。

• post (オプション)。このVersionポストリリースとしてマークするには、0 以上に設定します。

• dev (オプション)。このVersion開発リリースとしてマークするには、0 以上に設定します。

PEP-440 と互換性のあるバージョン文字列を抽出するには、 .public()メソッドを使用します。このメソッドは、完全なバージョンを含むstr返します。これは、ユーザーに提供するか、公的に使用する必要があるバージョンです。出力例は、 "13.2.0" 、 "17.1.2dev1" 、または"18.8.0rc2"になります。

Versionを指定してrepr()呼び出すと、その Python ソース コード表現が得られ、 Versionでstr()を呼び出すと、 '[Incremental, version 16.10.1]'のような文字列が生成されます。

更新中

Incremental には、 incrementalと呼ばれる、Incremental を使用するプロジェクトのバージョンの更新を自動化するツールが含まれています。 _version.pyファイルを更新し、増分バージョンの一部の使用を不定バージョンから現在のバージョンに自動的に更新します。 PyPI からclick必要があります。

incremental update <projectname>そのパッケージの更新を実行します。その後に実行できるコマンドによって、次のバージョンが決まります。

• --newversion=<version> 、プロジェクト バージョンを完全に指定されたバージョン (1.2.3 や 17.1.0dev1 など) に設定します。

• --rc 、現在のバージョンがリリース候補でない場合はプロジェクト バージョンを<year-2000>.<month>.0rc1に設定し、リリース候補の場合はリリース候補番号を 1 つ増やします。

• --dev 、プロジェクトが開発リリースでない場合は開発リリース番号を 0 に設定し、開発リリースである場合は開発リリース番号を 1 つ上げます。

• --patch 、リリースのパッチ番号を増やします。これにより、リリース候補番号もリセットされ、同時に--rc渡してパッチ番号をインクリメントし、リリース候補にします。

• --post 、ポストリリースでない場合はプロジェクトのポストリリース番号を 0 に設定し、ポストリリースである場合はポストリリース番号を 1 つ増やします。これにより、リリース候補および開発リリース番号もリセットされます。

引数を指定しない場合は、リリース候補番号が削除され、「完全リリース」になります。

不確定なバージョン

インクリメンタルは、次の「完全」バージョンの代わりとして、「不確定」バージョンをサポートします。これは、エンドユーザーに表示されるバージョンが不明な場合に使用できます (たとえば、「で導入された」または「非推奨」)。インクリメンタルは、次の不定バージョンをサポートします。

• Version("<projectname>", "NEXT", 0, 0)

• <projectname> NEXT

incremental update <projectname> --rc実行すると、これらは実際のバージョンに更新されます (ターゲットの最終バージョンが 17.1.0 であると仮定します)。

• Version("<projectname>", 17, 1, 0, release_candidate=1)

• <projectname> 17.1.0rc1

最終バージョンが作成されると、次のようになります。

• Version("<projectname>", 17, 1, 0)

• <projectname> 17.1.0