前提条件を減らし、コードを爆発させる
Reducing Assumptions, Exploding Your Code (ryelang.org)
要約
この記事では、エレガントなスクリプトがしばしば「ハッピーパス」を前提としているが、現実世界は不完全であり、コードはその不完全性に対処する必要があると論じています。PythonとRye言語で、引数処理、設定ファイルの読み込み、HTTPリクエスト、ファイル保存といった処理を行うスクリプトを例に、段階的にエラーハンドリングとバリデーションを追加していく過程を示し、Rye言語が構造を維持しながら堅牢なコードを記述できることを強調しています。
全文翻訳
前提条件を減らすと、コードが爆発する
エレガントなスクリプト
誰もが書いたことがあるでしょう。完璧にまとまり、読みやすく、しかし「ハッピーパス」のみを前提としたスクリプトです。世界は幸せな場所になり得ますが、同時に深く欠陥があり、不完全でもあります。そのような世界でコードが機能し、さらには価値を提供するためには、その不完全さを処理しなければなりません。
実際の、世の中の例
私たちのスクリプトは、引数としてIDを受け取ります。setup.jsonからAPIトークンを見つけ、リモートサーバーからPDFをダウンロードするリクエストを行います。ダウンロードされるファイル名はサーバーによって決定されます。
シンプルですが、少し現実的に厄介です。しかし、私たちはプログラマーであり、これこそが私たちの仕事であり、私たちが得意とするところですよね :) …ですよね :I (すべてのバイブレーションを思い浮かべながら…)
Python版
Pythonはプログラミングの共通言語です。さあ、行きましょう!
import sys, json, requests, re
from requests.auth import HTTPBasicAuth
id = int(sys.argv[1])
with open('setup.json') as f:
setup = json.load(f)
url = f"https://www.example.com/pdf-api?id={id}"
resp = requests.get(url, auth=HTTPBasicAuth(setup['token'], 'x'))
pattern = re.compile(r"filename\*?=[f']?(.*?)[']?(?:;?$")
content_disp = resp.headers['Content-Disposition']
filename = pattern.search(content_disp).group(1)
with open(filename, 'wb') as f:
f.write(resp.content)
これは完璧な小さなスクリプトです。コードの各ブロックは1つのことを行い、それぞれが数行で、不要な構造やボイラープレートは本当にありません。私はこれが好きです。
Rye版
ここはRye言語のブログなので、Ryeでも書いてみましょう :)
rye .Args? .load .first :id
Load %setup.rye |context :setup
re: regexp "filename\*?=[f']?(.*?)[']?(?:;?$)"
format id https://www.example.com/pdf-api?id=%d
|Request 'GET ""
|Basic-auth! setup/token "x"
|Call :resp
|Header? "Content-Disposition" |Submatch?* re
|file .Create
|Copy* Reader resp
少し違いますが、似ています。
何を前提としているか?
- スクリプトは常に1つの整数引数を受け取る
setupファイルが存在し、正しい内容を持っている- HTTPリクエストは決して失敗しない
Content-Dispositionヘッダーが常にファイル名とともに存在している- 新しいファイルを作成できる
Eugene Lewis Fordswortheなら言うでしょう――それはたくさんの…前提条件だ :(
基本的な検証の追加(ステップ2)
私はEugeneの薄められたバージョンになれます。
「ユーザー入力は多くの問題の源である」。
ユーザー入力がなければ問題はない――しかし、私たちにはユーザーが必要です。だから、それらの入力を検証しましょう。
Python版
今度は以下を行います。
- 引数の数をチェックする
- IDが整数かチェックする
setupにトークン値が定義されているかチェックする
import sys, json, requests, re
from requests.auth import HTTPBasicAuth
if len(sys.argv) != 2:
raise ValueError("script argument id - expected exactly one integer")
try:
id = int(sys.argv[1])
except ValueError:
raise ValueError("script argument id - must be an integer")
with open('setup.json') as f:
setup = json.load(f)
if 'token' not in setup or not isinstance(setup['token'], str):
raise ValueError("loading setup - token field required as string")
url = f"https://www.example.com/pdf-api?id={id}"
resp = requests.get(url, auth=HTTPBasicAuth(setup['token'], 'x'))
pattern = re.compile(r"filename\*?=[f']?(.*?)[']?(?:;?$")
content_disp = resp.headers['Content-Disposition']
filename = pattern.search(content_disp).group(1)
with open(filename, 'wb') as f:
f.write(resp.content)
これらの数行のチェックを追加しましたが、私に言わせれば(私はこれに偏っていますが)、エレガントで読みやすいスクリプトはすでに消えてしまいました。これが私がtry/catchアプローチを嫌う理由の1つです。それはコードの流れを妨げる構造を追加します。
Rye版
引数と設定ファイルのために検証ダイアレクトを使用しました。そして、リソース(ファイルライターとHTTPストリームリーダー――メモリへのコピーはなし)がクリーンアップされることを保証するために.defer\ 'Closeを使用しました。
rye .Args? .validate { <one> integer }
|check "script argument id" |first :id
Load %setup.rye |context |validate { token: required string }
|check "setup file" :setup
re: regexp "filename\*?=[f']?(.*?)[']?(?:;?$)"
format id https://www.example.com/pdf-api?id=%d
|Request 'GET ""
|Basic-auth! setup/token "x"
|Call :resp
|Header? "Content-Disposition" |Submatch?* re
|file .Create .defer\ 'Close
|Copy* resp .Reader .defer\ 'Close
スクリプトは少し複雑になりましたが、構造とフローは変わりませんでした。
完全なエラーハンドリング(ステップ3)
すべての失敗を処理し、失敗した場合にユーザーに役立つフィードバックを提供しましょう。当初のエレガントなスクリプトは、これに爆発しました… :o
Python版
今度は以下についてもチェックします。
setup.jsonが存在するかsetup.jsonのJSONを解析できるか- HTTPリクエストが成功したか
Content-Dispositionがない場合、デフォルトのファイル名を提供する- 新しいファイルを作成できるか
- PDFをそれに書き込めるか
import sys, json, requests, re
from requests.auth import HTTPBasicAuth
# Validate arguments
if len(sys.argv) != 2:
print("Error: script argument id - expected exactly one integer")
sys.exit(1)
try:
id = int(sys.argv[1])
except ValueError:
print("Error: script argument id - must be an integer")
sys.exit(1)
# Load and validate config
try:
with open('setup.json') as f:
setup = json.load(f)
except (FileNotFoundError, json.JSONDecodeError) as e:
print(f"Error: couldn't open config - {e}")
sys.exit(1)
if 'token' not in setup or not isinstance(setup['token'], str):
print("Error: loading setup - token field required as string")
sys.exit(1)
pattern = re.compile(r"filename\*?=[f']?(.*?)[']?(?:;?$")
url = f"https://www.example.com/pdf-api?id={id}"
try:
resp = requests.get(url, auth=HTTPBasicAuth(setup['token'], 'x'))
resp.raise_for_status()
except requests.RequestException as e:
print(f"Error: Http request failed - {e}")
sys.exit(1)
# Extract filename with default fallback
content_disp = resp.headers.get('Content-Disposition', '')
match = pattern.search(content_disp) if content_disp else None
filename = match.group(1) if match else "default.pdf"
try:
with open(filename, 'wb') as f:
f.write(resp.content)
except IOError as e:
print(f"Error: couldn't create local pdf - {e}")
sys.exit(1)
except Exception as e:
print(f"Error: couldn't save contents - {e}")
sys.exit(1)
当初15行だったスクリプトは、多くの構造を持つ45行のコードになりました。動作するコードはすべての安全コードの中に隠れてしまい、ほとんど見当たりません。
Pythonプログラマーは、当然、これをヘルパー関数でリファクタリングし、argparseや検証ライブラリのような追加ライブラリを使用するでしょうが、それでも以前のクリーンなハッピーパスに「構造」を追加します。より隠蔽されますが、依存関係も追加されます。
Rye版
同じチェックをすべてRye版にも追加しました。
rye .Args? .validate { <one> integer }
|^check "script argument id" |first :id
Load %setup.rye |check "couldn't open setup file" |context
|validate { token: required string } |^check "loading setup" :setup
re: regexp "filename\*?=[f']?(.*?)[']?(?:;?$)"
format id https://www.example.com/pdf-api?id=%d
|Request 'GET ""
|Basic-auth! setup/token "x"
|Call |^check "Http request failed" :resp
|Header? "Content-Disposition"
|Submatch?* re |fix { "default.pdf" }
|file .Create |^check "couldn't create local pdf" |defer\ 'Close
|Copy* resp .Reader .defer\ 'Close |^check "couldn't save contents"
コードは少し凝縮されましたが、行数はほとんど変わらず、最も重要なことに、プログラムの構造は同じままです! :O
しかし…魔法
上記のコードに魔法はありません。見えるすべての単語は通常のRye関数です。上記のコードは、Ryeの前任者、私たち、そしていくつかの幸運による多くの慎重な設計上の決定の結果にすぎません。
実際、Ryeの失敗と検証処理機能のほんの一部しか使用しませんでした。最初にRyeについてもっと読む without first reading more about Ryeなしで直接飛び込むのは難しいですが、上記の重要な関数は次のことを行います。
check- 値を返します。失敗でなければ値を返し、失敗の場合は失敗を上位レベルの失敗にラップして返します。fix- 値を返します。失敗でなければ値を返し、失敗の場合はブロックを評価してその結果を返します。
上記で使用したのは関連する関数です。Ryeには返り値関数(Ryeではreturnも返り値関数です――アクティブな単語はすべてRyeでは関数です)の概念があります。返り値関数の命名規則は、それらの前に^を付けることです。
^check-checkに似ていますが、失敗の場合に呼び出し元(上位レベルの失敗)に返り値/終了します。
ポイント
上記は、Pythonだけでなく多くの言語で主要な失敗処理モデルであるtry/catchモデルを私が嫌う理由の1つです。
より良い選択肢があります。上記で1つ実証しましたが、これはGoが行うことの洗練されたバージョンにすぎません。型システムとOption型を使用することも別の方法です。これらのアプローチに共通することは何ですか?失敗はあなたの言語における通常の値であり、あなたの言語の機能と調和し、その一部であるべきです。私はこれについてもっと書きたいと思っています。
これについて議論したい場合は、(かなり新しい)Homoiconic discordを訪れてください。