pythondevpractice

Practice of Python development environment.

Setup

0. Install VSCode, Python, Rust, and Rye in that order. If Rye becomes corrupted, you should delete the Users/.rye folders and reinstall.
1. Clone this projects >>> git clone [this url].
2. Install recommended extensions of VSCode (written in extensions.json).
3. Synchronize the Python environment >>> rye sync.
4. If you use pre-commit, install it at the first time >>> rye run pre-commit install.

Structure

Methods

Version control system: Git / GitHub
Source-code editor: VSCode
Language: Python
Package manager: Rye (uv) by Rust
Spell check: Code Spell Checker in VSCode
Logging: logging package in Python
Linter: Ruff (CUI/VSCode)
Formatter: Ruff (CUI/VSCode)
Type Checking: Pylance in VSCode, mypy in CUI
Python docstring style: Numpy style
Test process: pytest
Container virtualization: Docker & DevContainer in VSCode
Continuous integration & deployment (CI/CD): pre-commit or GitHub Actions

VSCode extensions

• ms-python.python
• ms-toolsai.jupyter
• njpwerner.autodocstring
• charliermarsh.ruff
• ms-python.vscode-pylance
• ms-azuretools.vscode-docker
• ms-vscode-remote.remote-containers
• streetsidesoftware.code-spell-checker
• github.vscode-github-actions

Folder hierarchy

Package programs: /package_name
Test programs: /tests
Scripts for analysis: /experiments
VSCode extensions and settings: .vscode

Additional tools you might consider

• bandit
• rope

Guide

• Activate a .venv: >>> .\.venv\Scripts\activate for Windows, and >>> source .venv/bin/activate for Unix-like OS
• Add a library for development: >>> rye add --dev library_name
• >>> pytest search functions titled as test_* and classes titled as Test* in test_*.py or *_test.py.
• Add a local dependency by Rye: >>> rye add packagename --path path/to/packagename
• Test a docstring by Pytest: >>> rye run pytest --doctest-modules
• Store functions and test data used in tests as fixtures in tests/conftest.py. Fixtures defined in a conftest.py file can be used without import in files within the same or deeper directory levels.
• Rye scripts is prepared in [tool.rye.scripts] in pyproject.html. >>> rye fmt, >>> rye lint, and >>> rye test can be used.
• Level in logging: DEBUG < INFO < WARNING < ERROR < CRITICAL

Troubleshooting

• To ensure the correct syntax analysis in VSCode for import packagename from the tests folder, I added ${workspaceFolder} to the python.analysis.extraPaths in the VSCode's settings.json.
• If you encounter a ModuleNotFoundError: No module named 'pythondevpractice', execute them like python -m tests.test_base to force Python to run the scripts with the project's root directory in its path. Additionally, using rye add packagename --path . may add the project's root to the path persistently.
• Mypy does not check .ipynb files. It is neither to check them during pre-commit.
• Initially, I thought using a /src/packagename structure would allow for mimicking the production package environment by using pip install -e or rye add packagename --path ./src/packagename. However, VSCode unexpectedly adds src/ to the PYTHONPATH, which results in direct references to src/packagename. Consequently, I decided to place the package directly under the project root at /packagename.
• Be aware that README.md uses trailing whitespace for line breaks. Depending on the editor settings, these trailing spaces might be automatically removed.
• When using Docker containers on a Windows system, be aware that the contents of the .venv directory may change. So use >>> rye sync first in each environment.
• While most files will use LF for line endings, Windows-specific files such as .cmd and .bat scripts will retain CRLF. See .gitattributes.

Reference (mostly in Japanese)

Git

• Setting up Git & Authenticating with GitHub from Git
• Git まとめ
• もう迷わない .gitattributes で改行コードを統一 #Git - Qiita

VSCode

• json 設定ファイルの優先度について
• Workspace recommended extensions
• VSCode に Code Spell Checker を導入して typo と戦う #VSCode - Qiita
• VSCode で Python 書くのにおすすめな拡張機能

Python

• Python
• Status of Python versions
• Pythonの相対パスimportを理解する #Python - Qiita

Rust

• Installing Rust for Windows

Rye/uv in Rust

• Rye
• Installing Rye for Windows
• 【Pythonのパッケージ管理に悩む方へ】パッケージ管理ツールRyeを使ってみた
• pythonパッケージ管理ツールryeを使う - 肉球でキーボード

Ruff in Rust

• Ruff
• Configuring Ruff（default はかなり black に近い）

pre-commit

• pre-commit で Python コードをキレイに管理してみた
• pre-commit + Ruff
• pre-commitでコミット時にコードの整形やチェックを行う

Github Actions

• GitHub Actions を理解する - GitHub Docs
• 【初心者向け】【入門】GitHub Actionsの書き方についてデバッグ設定、runs-onやcheckoutなどの仕組みや構造も含めて徹底解説 #Linux - Qiita
• `pre-commit`を`Github Actions`で実行する

project

• Python プロジェクトテンプレート
• [2023年最新版:rye対応]Python案件で汎用的に使えるモダンなプロジェクトテンプレート
• 僕の考えた最強の Python 開発環境 (2024)

Docker

• Docker 概要
• Docker Desktop: The #1 Containerization Tool for Developers | Docker
• Add local file mount to a container
• Windows環境でdevcontainerにほぼ引き篭れる構成を作った #Docker - Qiita
• VSCode と devcontainer で始める開発環境構築 #Docker - Qiita
• 【Rye + uv + Ruff】Docker で VS Code の Dev Container 上に快適な Python 環境を構築する
• Dev Containers入門～Dev Containersってなんだ編～ #VSCode - Qiita

Pytest

• pytest: helps you write better programs — pytest documentation
• pytest ヘビー🐍ユーザーへの第一歩 - エムスリーテックブログ

mypy

• The mypy configuration file - mypy 1.9.0 documentation

Logging

• Logging HOWTO — Python 3.12.3 documentation
• logging入門 #Python - Qiita