uvによるpythonプロジェクト作成RTA

これはなに？

アーキテクチャの検討や技術選定、ライブラリの試用のためにpythonプロジェクトを頻繁に立てるので、その手順の覚え書きと、開発の中で醸成したおすすめの初期設定の共有です。

前提

uv がインストール済み
参考: https://docs.astral.sh/uv/getting-started/installation/#standalone-installer

手順

プロジェクト作成

uv init で基本的な面倒は見てくれます。
pythonのバージョンは後からでも指定できますが、このタイミングに-pでpythonバージョンを明示するのがおすすめです。後からuv pinコマンドでも対応できますが、pyproject.tomlの設定と衝突して面倒な場合があります。
インタプリタのバージョンは、新規プロジェクトの場合特に理由がなければStatusがbugfixのうち、最も新しいインタプリタを選んでおくと良いでしょう。

# my-project というディレクトリの作成から、プロジェクト雛形の作成までやってくれる
uv init my-project -p 3.13
cd my-project
# VSCodeで開く
code .

環境作成

uv initで作成されたファイルを元に、仮想環境を作ってくれます。
.python-versionに記載のインタプリタがインストールされていない場合、自動でインストールまでやってくれます。すごい！ ありがとう！

uv sync

最低限の依存追加

どんなに小さなプロジェクトでも、以下は入れておくと得です。シンプルに作業効率が上がります。
--group による依存関係のグルーピングは積極的に使っていきましょう！

uv add --group lint ruff
uv add --group lint mypy

pyproject.tomlへの追記

追加したlinterやformatterの設定を追記していきます。できる限りpyproject.tomlに集約できるとうれしいですね。最近のメジャーなツールであれば、殆どがpyproject.tomlをサポートしていますよ。

linterやformatterのルール、特にドキュメント系は後から増やすのが難しいので、初めはキツめに縛っておくのが良いかもしれません。緩和するのは簡単ですから。

[dependency-groups]
lint = [
    "mypy>=1.19.1",
    "ruff>=0.14.10",
]
# よく使うので以下も雑に追加
test = [
    "pytest>=9.0.2",
    "pytest-asyncio>=1.3.0",
    "pytest-mock>=3.15.1",
]

[tool.ruff]
line-length = 120 # なんだかんだで120くらいないとつらいことが多い
target-version = "py313"

[tool.ruff.format]
# https://docs.astral.sh/ruff/settings/#format

[tool.ruff.lint]
# ruffのデフォルトは flake8 の subset と pyflakes
# select = ["E4", "E7", "E9", "F"]
select = [
    "E",    # flake8
    "F",    # pyflakes
    "B",    # flake8-bugbear        # バグになりそうなコードを警告
    "A",    # flake8-builtins       # 組み込み関数と同名の変数名を警告
    "N",    # pepe8-naming          # 変数名の命名規則を警告
    "C4",   # flake8-comprehensions # リスト内包表記の警告
    "I",    # isort
    "D",    # pydocstyle            # docstring の形式を警告（Google形式を強制） プロジェクトの最初の方で決めておくと、あとから辛くない
    "UP",   # pyupgrade             # Python の新しい書き方を使うように促す
]

ignore = [
    # == formatterの動作とlinterが競合する場合がある。これを避けるため、ruff公式の推奨設定を踏襲する ==
    # # https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
    "E111",  # indentation is not a multiple of four
    "E114",  # indentation is not a multiple of four (comment)
    "E117",  # over-indented
    "E501",  # line too long
    # == Docstring関連のignore設定 ==
    "D1",    # pydocstyleのうち、docstyleの記載を必須化するグループ。 docstring 自体はチェックするが、必須化はしない方針。
    "D203",  # one-blank-line-before-class, blank-line-before-class (D211)と競合するため無効化
    "D213",  # multi-line-summary-second-line, multi-line-summary-first-line (D212)と競合するため無効化
    "D415",  # First line should end with a period
]
[tool.ruff.lint.pydocstyle]
# docstringのスタイルは最初に決めておくと吉です。
convention = "google"

[tool.ruff.lint.per-file-ignores]
# def test_対象名_コンテキスト_期待する結果()の命名をするため、N802を無視する。
"**/tests/**/test_*.py" = ["N802"]
"**/tests/**/*_test.py" = ["N802"]

[tool.ruff.lint.isort]
combine-as-imports = true
known-first-party = []

[tool.mypy]
python_version = "3.13"
ignore_missing_imports = true
plugins = ["pydantic.mypy"] # pydanticを使う場合は入れておくと吉

[tool.pytest.ini_options]
testpaths = ["tests"]

VSCode設定の追加

以下のlinter、formatter、言語サポート系の拡張機能は入れるとコードが書きやすくなるので必須級です。

{
  "recommendations": [
    "charliermarsh.ruff",
    "ms-python.mypy-type-checker",
    "ms-python.python",
    "tamasfe.even-better-toml"
  ]
}

上記の拡張機能と合わせて、以下の設定をします。
.vscode/settings.jsonに入れても良いですが、どこでも使いたい機能だと思うので、pythonプロジェクト用のプロファイルを作って設定してあげるといろんな場所で使えて嬉しいと思います。

 // settings.json
{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "[python]": {
    // ruff の save 時フォーマットを有効化
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    // import 整理を save 時に実行
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  },
  // キャッシュ系ファイルを非表示にする
  "files.exclude": {
    "**/__pycache__": true,
    "**/.mypy_cache": true,
    "**/.pytest_cache": true,
    "**/.ruff_cache": true
  }
}

簡単！以上！