CLI オプション名

デフォルトでは、Typer は関数パラメータから CLI オプション 名を作成します。

そのため、次のような関数がある場合

def main(user_name: Optional[str] = None):
    pass

または

def main(user_name: Annotated[Optional[str], typer.Option()] = None):
    pass

Typer は CLI オプション を作成します

--user-name

ただし、必要に応じてカスタマイズできます。

上記の例のように、関数パラメータ名が user_name だとします。しかし、CLI オプション を単に --name にしたいとします。

typer.Option() に渡される次の位置引数で、必要な CLI オプション 名を渡すことができます

Python 3.7+Python 3.7+ アノテーションなし

import typer
from typing_extensions import Annotated


def main(user_name: Annotated[str, typer.Option("--name")]):
    print(f"Hello {user_name}")


if __name__ == "__main__":
    typer.run(main)

ここでは、文字列 "--name" を typer.Option() の最初の位置引数として渡しています。

ヒント

可能な場合は、Annotated バージョンを使用することをお勧めします。

import typer


def main(user_name: str = typer.Option(..., "--name")):
    print(f"Hello {user_name}")


if __name__ == "__main__":
    typer.run(main)

ここでは、文字列 "--name" を typer.Option() の2番目の位置引数として渡しています。最初の引数は、必須としてマークするための ... です。

情報

"位置引数" とは、キーワード名を持たない関数引数のことです。

たとえば、show_default=True はキーワード引数です。"show_default" がキーワードです。

しかし、"--name" には option_name="--name" のようなものはありません。typer.Option() に入る文字列値 "--name" だけです。

それが関数の「位置引数」です。

確認してください

$ python main.py --help

// Notice the --name instead of --user-name
Usage: main.py [OPTIONS]

Options:
  --name TEXT           [required]
  --help                Show this message and exit.

// Try it
$ python --name Camila

Hello Camila

CLI オプションの短縮名¶

短縮名とは、2つ（--）ではなく1つ（-）のダッシュと1文字で構成される CLI オプション 名です。たとえば、--name の代わりに -n となります。

たとえば、ls プログラムには --size という名前の CLI オプション があり、同じ CLI オプション には -s という短縮名もあります。

// With the long name --size
$ ls ./myproject --size

12 first-steps.md   4 intro.md

// With the short name -s
$ ls ./myproject -s

12 first-steps.md   4 intro.md

// Both CLI option names do the same

CLI オプションの短縮名をまとめて使う¶

短縮名にはもう1つの機能があります。-s のように1文字の場合、これらの CLI オプション を1つのダッシュでまとめて使用できます。

たとえば、ls プログラムには、次の2つの CLI オプション があります（他にもあります）。

--size：リストされたファイルのサイズを表示します。
--human：1024 ではなく 1MB のように、人間が読める形式で表示します。

また、これら2つの CLI オプション には短縮バージョンもあります。

--size：短縮バージョン -s。
--human：短縮バージョン -h。

そのため、-sh または -hs とまとめて使用できます。

// Call ls with long CLI options
$ ls --size --human

12K first-steps.md   4.0K intro.md

// Now with short versions
$ ls -s -h

12K first-steps.md   4.0K intro.md

// And with short versions together
$ ls -sh

12K first-steps.md   4.0K intro.md

// Order in short versions doesn't matter
$ ls -hs

12K first-steps.md   4.0K intro.md

// They all work the same 🎉

CLI オプションの短縮名と値¶

短縮名を持つ CLI オプション を使用する場合、--size や --human のようなブール値フラグであれば、まとめて使用できます。

ただし、値を受け取る短縮名 -f を持つ CLI オプション --file がある場合、他の CLI オプション の短縮名と一緒に使用する場合は、最後の文字として配置する必要があります。これにより、直後に来る値を受け取ることができます。

たとえば、tar プログラムを使用してファイル myproject.tar.gz を解凍/展開しているとします。

tar に次の CLI オプション の短縮名を渡すことができます。

-x：「eXtract」を意味し、コンテンツを解凍して展開します。
-v：「Verbose」を意味し、何をしているかを画面に出力します。そのため、各ファイルを解凍していることがわかり、待っている間に楽しむことができます。
-f：「File」を意味し、これは値、つまり展開する圧縮ファイルを必要とします（この例では、myproject.tar.gz です）。
- そのため、すべての短縮名をまとめて使用する場合は、この -f は最後に来て、次に来る値を受け取る必要があります。

例えば

$ tar -xvf myproject.tar.gz

myproject/
myproject/first-steps.md
myproject/intro.md

// But if you put the -f before
$ tar -fxv myproject.tar.gz

// You get an ugly error
tar: You must specify one of the blah, blah, error, error

CLI オプションの短縮名の定義¶

Typer では、長い名前をカスタマイズできるのと同じ方法で、CLI オプション の短縮名も定義できます。

位置引数を typer.Option() に渡して、CLI オプション 名を定義できます。

ヒント

位置関数引数はキーワードを持たない引数であることを覚えておいてください。

prompt=True や help="このオプションは..." のように typer.Option() に渡す他のすべての関数引数/パラメータには、キーワードが必要です。

前の例のように CLI オプション 名を上書きできますが、短縮名を含む追加の代替案を宣言することもできます。

たとえば、前の例を拡張して、CLI オプション の短縮名 -n を追加してみましょう。

Python 3.7+Python 3.7+ アノテーションなし

import typer
from typing_extensions import Annotated


def main(user_name: Annotated[str, typer.Option("--name", "-n")]):
    print(f"Hello {user_name}")


if __name__ == "__main__":
    typer.run(main)

ヒント

可能な場合は、Annotated バージョンを使用することをお勧めします。

import typer


def main(user_name: str = typer.Option(..., "--name", "-n")):
    print(f"Hello {user_name}")


if __name__ == "__main__":
    typer.run(main)

ここでは、デフォルトでは --user-name になる CLI オプション 名を上書きし、--name に定義しています。また、CLI オプション の短縮名 -n も宣言しています。

確認してください

// Check the help
$ python main.py --help

// Notice the two CLI option names -n and --name
Usage: main.py [OPTIONS]

Options:
  -n, --name TEXT       [required]
  --help                Show this message and exit.

// Try the short version
$ python main.py -n Camila

Hello Camila

CLI オプションの短縮名のみ¶

-n のような短縮名のみを宣言した場合、それが唯一の CLI オプション 名になります。--name も --user-name も使用できません。

Python 3.7+Python 3.7+ アノテーションなし

import typer
from typing_extensions import Annotated


def main(user_name: Annotated[str, typer.Option("-n")]):
    print(f"Hello {user_name}")


if __name__ == "__main__":
    typer.run(main)

ヒント

可能な場合は、Annotated バージョンを使用することをお勧めします。

import typer


def main(user_name: str = typer.Option(..., "-n")):
    print(f"Hello {user_name}")


if __name__ == "__main__":
    typer.run(main)

確認してください

$ python main.py --help

// Notice there's no --name nor --user-name, only -n
Usage: main.py [OPTIONS]

Options:
  -n TEXT               [required]
  --help                Show this message and exit.

// Try it
$ python main.py -n Camila

Hello Camila

CLI オプションの短縮名とデフォルト値¶

上記の例を続けると、Typer では短縮名のみを持つ CLI オプション を宣言できるため、デフォルトの長い名前と短縮名の両方を使用する場合は、両方を明示的に宣言する必要があります。

Python 3.7+Python 3.7+ アノテーションなし

import typer
from typing_extensions import Annotated


def main(user_name: Annotated[str, typer.Option("--user-name", "-n")]):
    print(f"Hello {user_name}")


if __name__ == "__main__":
    typer.run(main)

ヒント

可能な場合は、Annotated バージョンを使用することをお勧めします。

import typer


def main(user_name: str = typer.Option(..., "--user-name", "-n")):
    print(f"Hello {user_name}")


if __name__ == "__main__":
    typer.run(main)

確認してください

$ python main.py --help

// Notice that we have the long version --user-name back
// and we also have the short version -n
Usage: main.py [OPTIONS]

Options:
  -n, --user-name TEXT  [required]
  --help                Show this message and exit.

// Try it
$ python main.py --user-name Camila

Hello Camila

// And try the short version
$ python main.py -n Camila

CLI オプションの短縮名をまとめて使う¶

複数の短縮名を作成してまとめて使用できます。

動作させるために特別なことはする必要はありません（これらの短縮バージョンを宣言する以外）。

Python 3.7+Python 3.7+ アノテーションなし

import typer
from typing_extensions import Annotated


def main(
    name: Annotated[str, typer.Option("--name", "-n")],
    formal: Annotated[bool, typer.Option("--formal", "-f")] = False,
):
    if formal:
        print(f"Good day Ms. {name}.")
    else:
        print(f"Hello {name}")


if __name__ == "__main__":
    typer.run(main)

ヒント

可能な場合は、Annotated バージョンを使用することをお勧めします。

import typer


def main(
    name: str = typer.Option(..., "--name", "-n"),
    formal: bool = typer.Option(False, "--formal", "-f"),
):
    if formal:
        print(f"Good day Ms. {name}.")
    else:
        print(f"Hello {name}")


if __name__ == "__main__":
    typer.run(main)

ヒント

繰り返しますが、CLI オプション 名の長いバージョンと短いバージョンの両方を宣言していることに注意してください。

確認してください

$ python main.py --help

// We now have short versions -n and -f
// And also long versions --name and --formal
Usage: main.py [OPTIONS]

Options:
  -n, --name TEXT       [required]
  -f, --formal
  --help                Show this message and exit.

// Try the short versions
$ python main.py -n Camila -f

Good day Ms. Camila.

// And try the 2 short versions together
// See how -n has to go last, to be able to get the value
$ python main.py -fn Camila

Good day Ms. Camila.

CLI オプション名

CLI オプション の短縮名¶

CLI オプション の短縮名をまとめて使う¶

CLI オプション の短縮名と値¶

CLI オプション の短縮名の定義¶

CLI オプション の短縮名のみ¶

CLI オプション の短縮名とデフォルト値¶

CLI オプション の短縮名をまとめて使う¶

CLI オプションの短縮名¶

CLI オプションの短縮名をまとめて使う¶

CLI オプションの短縮名と値¶

CLI オプションの短縮名の定義¶

CLI オプションの短縮名のみ¶

CLI オプションの短縮名とデフォルト値¶

CLI オプションの短縮名をまとめて使う¶