mypyのコマンドラインオプションたち


# mypyのコマンドラインオプション

mypyのコマンドラインオプションの内、チェック項目に関するオプションの一覧をまとめる。
(2019/3/22現在)

mypyの概要などについてはここでは触れない。
それらに関しては既に素晴らしいブログ記事が存在するため、そちらを参照されたい。

@k-saka 『mypyやっていくぞ』
https://qiita.com/k-saka/items/8f05c89f675af219e081

@k-saka 『mypyやっていったぞ』
https://qiita.com/k-saka/items/9d7111e82cd06e5419db


## 一行解説

### 型チェック探索ルール系
| option                                        | 一行説明                                                                                                                     |     
| :-------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |
| `--ignore-missing-imports`                    | 解決できないモジュール(スクリプト)のインポートを無視する。ただし、解決できない関数のインポートエラーは例外搬出される。                                                             |     
| `--follow-imports`                            | mypyが再帰的に型チェックしていくルールの指定。(`normal`, `silent`, `skip`, `error`)                                                           |     |
| `--python-executable EXECUTABLE`              | python3.7で採択された PEP561に準拠する型情報の付与に関して、どのPythonで型情報のチェックを行うかを実行バイナリ指定する。                                                  |     
| `--no-site-packages`                          | PEP561対応に関するチェックをスキップする。                                                                                                 |     
| `--no-silence-site-packages`                  | mypyはデフォルトではPEP561基因の型チェックエラーを出力しないが、このオプション指定で出力させる様にする。                                                                |     

### 実行時環境制御系オプション

| option                                        | 一行説明                                                                                                                     |     
| :-------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |     
| `--python-version X.Y`                        | 型チェックするpythonバージョンを変更する                                                                                                  |     
| `--platform PLATFORM`                         | チェック環境のOS指定。('linux', 'win32', 'cygwin', 'darwin')                                                                       |     
| `--always-true NAME / --always-false NAME`    | 型チェック実行時に、引数に渡した `NAME` 変数を常に `True / False` として扱う。                                                                      |     

### 動的型付の禁止系オプション

| option                                        | 一行説明                                                                                                                     |     
| :-------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |
| `--disallow-any-unimported`                   | 型チェックされなかったモジュール・パッケージのメソッドからの返り値への型アノテーションを強要する。                                                                        |     
| `--disallow-any-expr`                         | `Any`アノテーションされた式の定義を禁止する。ただし`typing.cast()`への引数は例外的に認められる                                                                |     
| `--disallow-any-decorated`                    | デコレータのシグネチャ(引数等)に `Any` 型を含むことを禁止する。                                                                                     |     
| `--disallow-any-explicit`                     | 変数アノテーションやジェネリクス定義時の明示的な `Any` 型を禁止する                                                                                    |     
| `--disallow-any-generics`                     | ジェネリクス型定義時の暗黙的な `Any` 型を禁止する。<br> すなわち`list ->  typing.List[int]`, `dict -> Dict[str, int]`と明示。                               |     
| `--disallow-subclassing-any`                  | `Any` 型のクラスを継承したサブクラスの定義を禁止する。(稀な事例)                                                                                     |   
  
### 型チェックされていない変数定義や関数実行の禁止系オプション

| option                                        | 一行説明                                                                                                                     |     
| :-------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |
| `--disallow-untyped-calls`                    | アノテーションされていない関数呼出しを禁止する <br> (e.g. 誤： `var = func_return_int()` , 正： `var: int = func_return_int()`  )                        |     
| `--disallow-untyped-defs`                     | アノテーションされていない関数定義を禁する <br> (e.g. 誤： `def func(arg1, arg2):`, 正： `def func(arg1: int, arg2: int) -> int:` )                    |     
| `--disallow-incomplete-defs`                  | 部分的にアノテーションされている関数定義を禁止する(上記 `--disallow-untyped-defs` との違い不明。要調査。)                                                      |     
| `--check-untyped-defs`                        | アノテーションされていない関数定義の場合でも、関数内の型アノテーションをチェックする。(通常、型アノテーションされていない関数定義の内部は型チェックされない。)                                         |     
| `--disallow-untyped-decorators`               | 型アノテーションされていないデコレータを禁止する                                                                                                 |     
| `--no-implicit-optional`                      | デフォルト引数に `None` をセットする時、引数のアノテーションに `Optional` を使うことを強制する。                                                               |     
| `--no-strict-optional`                        | `None` に関する型チェックを緩和するオプション。 `Optional` 指定していない引数に `None` を渡すと通常エラーを挙げるが、このオプションでエラーを抑え、段階的に `Optional` を付与していくなどの使い方がある。 |     

### 追加警告系

| option                                        | 一行説明                                                                                                                     |     
| :-------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |     
| `--warn-redundant-casts`                      | 冗長なキャストを行っている箇所に警告を挙げる。                                                                                                  |     
| `--warn-unused-ignores`                       | `mypy` のエラーが発生する箇所の文末に `# type: ignore` を付与するとエラーを隠蔽できるが、本来エラーが上がらない箇所に付与されている場合に警告を挙げる。                                 |     
| `--no-warn-no-return`                         | `abstractmethod` などで `return` 文が無い場合のエラーを抑制する。                                                                           |     
| `--warn-return-any`                           | 戻り値が `Any` 型ではない関数で `Any` 型が返される場合に警告を挙げる。                                                                               |     
| `--allow-untyped-globals`                     | 型推論できないグローバル変数やクラス変数を許容する。                                                                                               |     
| `--allow-redefinition`                        | 同じ変数名で異なる型の変数の再定義を許容する。                                                                                                              |     
| `--strict`                                    | すべてのエラーチェック系オプションを有効にする。                                                                                                 |     

### 出力エラー文に関するオプション

| option                                        | 一行説明                                                                                                                     |     
| :-------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |     
| `--show-error-context`                        | エラーメッセージを詳細にする。                                                                                                          |     
| `--show-column-numbers`                       | エラー発生箇所を行列数で明示する。                                                                                                        |     

### キャッシュ操作系

| option                                        | 一行説明                                                                                                                     |     
| :-------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |    
| `--no-incremental`                            | `mypy` のキャッシュ機能を無効にする。                                                                                                   |     
| `--cache-dir DIR`                             | キャッシュを保存するディレクトリを指定する。保存しない場合は `--cache-dir=/dev/null`                                                                   |     
| `--skip-version-check`                        | `mypy` がキャッシュを参照する時に行う `mypy` 自体のバージョンチェックを無効にする。                                                                        |     
| `--pdb`                                       | 例外に遭遇した時に、デバッガ`pdb`を起動するオプション                                                                                            |     
| `--show-traceback`, `--tb`                    | 例外に遭遇した時に、トレースバックを出力するオプション                                                                                              |     
| `--custom-typing MODULE`                      | `typing` ではない型アノテーションモジュールを指定して使うためのオプション                                                                                |   
| `--custom-typeshed-dir DIR`                   | `typeshed`から取得してきた外部モジュールの型情報を使うためのオプション                                                                                 |     
| `--warn-incomplete-stub`                      | 型アノテーションされていない `typeshed` のスタブが処理内に存在する時に警告を挙げる。主にContribute目的                                                           |     
| `--shadow-file SOURCE_FILE SHADOW_FILE`       | `SOURCE_FILE` に関する型アノテーションチェック処理を `SHADOW_FILE` で代替する。                                                                   |     

### レポート出力系

| option                                        | 一行説明                                                                                                                     |     
| :-------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |     
| `--any-exprs-report DIR`                      | `Any` 型の式がいくつ存在するか計測し `DIR` に出力する。                                                                                       |     
| `--linecount-report DIR`                      | 型アノテーションされている行数とされていない行数を計測し `DIR` に出力する。                                                                                |     
| `--linecoverage-report DIR`                   | ファイル名がキー、そのファイル内の型アノテーションされている行番号のリストがバリューのJsonを `DIR` に出力する。                                                            |     
| `--cobertura-xml-report DIR`                  | 型チェックも同時に行う `Cobertura` ベースのXLM形式カバレッジレポートを `DIR` に出力する。                                                                 |     
| `--html-report DIR`, `--xslt-html-report DIR` | HTML形式のカバレッジレポートを `DIR` に出力する。                                                                                           |     
| `--txt-report DIR`, `--xslt-txt-report DIR`   | TXT形式のカバレッジレポートを `DIR` に出力する。                                                                                            |     
| `--junit-xml JUNIT_XML`                       | 型チェックも同時に行う `JUnit` ベースのXLM形式カバレッジレポートを `DIR` に出力する。                                                                     |


## 型チェックオプション例

関数定義のアノテーションはきっちり行いたいが、呼び出しの自由度は保ちたい時のチェック

```
mypy 
    --allow-redefinition         # 変数再定義を許容
    --ignore-missing-imports     # サードパーティ製モジュールの型アノテーションチェックを無視
    --disallow-untyped-defs      # 関数定義時の型アノテーション強制
    --warn-redundant-casts       # 無駄なキャストへの警告
    --no-implicit-optional       # None へのOptionalアノテーション強制
    --html-report ./mypyreport   # HTML形式レポート出力
    ./src      
```