{{tag>[cli python click argument-parser decorator]}}

====== Click ======
decorator 조합으로 command, option, argument, group을 구성하는 Python CLI framework다.

===== Summary =====
  * ''@click.command()'', ''@click.option()'', ''@click.argument()''로 함수를 CLI로 변환한다.
  * ''@click.group()''으로 중첩 가능한 subcommand tree를 만든다.
  * help, type conversion, prompt, environment variable, terminal 출력, testing 도구를 제공한다.

===== Installation =====
공식 문서는 virtual environment에서 PyPI package를 설치하도록 안내한다.

<code bash>
# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install click
python3 -c "import importlib.metadata; print(importlib.metadata.version('click'))"
</code>

<code powershell>
# Windows PowerShell
py -m venv .venv
.venv\Scripts\Activate.ps1
py -m pip install click
py -c "import importlib.metadata; print(importlib.metadata.version('click'))"
</code>

Click가 공식적으로 별도 안내하는 APT, DNF/YUM, Homebrew, ''winget'' package는 없다. Python project dependency로 설치한다.

===== Usage =====
<code python>
import click

@click.command()
@click.argument("name")
@click.option("--count", default=1, type=int, show_default=True)
@click.option("--verbose", is_flag=True, help="상세 출력")
def hello(name: str, count: int, verbose: bool):
    """NAME에게 인사합니다."""
    if verbose:
        click.echo(f"count={count}", err=True)
    for _ in range(count):
        click.echo(f"Hello, {name}!")

if __name__ == "__main__":
    hello()
</code>

<code bash>
python3 hello.py --help
python3 hello.py World --count 2 --verbose
</code>

  * ''<color #c3c3c3>**python3**</color> <color #7092be>HELLO.py NAME</color> <color #22b14c>[--count COUNT] [--verbose]</color>''
  * ''<color #22b14c>**--count**</color> <color #7092be>COUNT</color>'': integer option
  * ''<color #22b14c>**--verbose**</color>'': 값 없는 boolean flag
  * ''<color #22b14c>**--help**</color>'': 자동 생성된 help 표시

===== Commands and Groups =====
<code python>
import click

@click.group()
def cli():
    """프로젝트 관리 CLI."""

@cli.command()
@click.argument("name")
def init(name: str):
    """새 프로젝트를 생성합니다."""
    click.echo(f"Initialized {name}")

@cli.command(deprecated=True)
def cleanup():
    """이전 cache를 정리합니다."""
    click.echo("Cleaned")

if __name__ == "__main__":
    cli()
</code>

  * ''<color #c3c3c3>**python3**</color> <color #7092be>PROJECT.py</color> <color #ff7f27>init</color> <color #7092be>NAME</color>''
  * <del>''<color #c3c3c3>**python3**</color> <color #7092be>PROJECT.py</color> <color #ff7f27>cleanup</color>''</del>: deprecated warning을 출력하는 예제 command

===== Common API =====
  * ''@click.command()'' : callback 함수를 ''Command''로 변환
  * ''@click.group()'' : child command를 가질 수 있는 ''Group'' 생성
  * ''@click.option()'' / ''@click.argument()'' : option과 positional argument 선언
  * ''@click.pass_context'' / ''@click.pass_obj'' : context 또는 공유 object 전달
  * ''click.echo()'' / ''click.secho()'' : Unicode와 color 처리를 고려한 출력
  * ''click.prompt()'' / ''click.confirm()'' : 대화형 입력
  * ''click.Path'' / ''click.File'' / ''click.Choice'' : 자주 쓰는 parameter type
  * ''click.ClickException'' / ''click.UsageError'' : 사용자에게 보여 줄 CLI 오류

===== Environment Variables =====
<code python>
@click.command()
@click.option("--username", envvar="APP_USERNAME", required=True)
def greet(username):
    click.echo(f"Hello {username}")
</code>

<code bash>
APP_USERNAME=alice python3 app.py
</code>

group 전체에는 ''auto_envvar_prefix''를 적용할 수 있다. 명시적 command-line 값과 환경 변수의 우선순위를 함께 문서화한다.

===== Packaging =====
설치 가능한 CLI는 ''pyproject.toml''의 entry point로 연결한다.

<code toml>
[project]
name = "hello-cli"
version = "0.1.0"
dependencies = ["click>=8.1"]

[project.scripts]
hello = "hello_cli.main:hello"
</code>

<code bash>
python3 -m pip install -e .
hello --help
</code>

===== Troubleshooting =====
  * group option은 subcommand option과 별개다. ''tool --debug run''과 ''tool run --debug''는 같은 위치로 처리되지 않는다.
  * callback parameter 이름과 option의 destination 이름이 일치하는지 확인한다.
  * test에서는 subprocess 대신 ''click.testing.CliRunner''로 exit code, output, exception을 검사할 수 있다.
  * library 내부에서 임의로 ''sys.exit()''을 호출하기보다 Click exception 또는 callback return 구조를 사용하면 테스트가 쉽다.

===== Compatibility =====
  * 이 환경에는 Click library가 설치되어 있지만 독립 ''click'' executable은 제공되지 않는다. 작성한 Python application 또는 package entry point를 실행한다.
  * application에서 요구하는 Python 및 Click 최소 version을 dependency metadata에 고정한다.

===== Help =====
Click 자체의 공통 ''click --help'' 명령은 없다. 작성한 command마다 자동 생성되는 help를 확인한다.

<code bash>
python3 hello.py --help
python3 project.py --help
python3 project.py init --help
</code>

===== See Also =====
  * [[python|Python]]
  * [[python:typer:ko|Typer]]
  * [[python:argparse:ko|argparse]]
  * [[https://click.palletsprojects.com/en/stable/|Click 공식 문서]]
  * [[https://click.palletsprojects.com/en/stable/quickstart/|Click 공식 문서: Quickstart]]
  * [[https://click.palletsprojects.com/en/stable/commands-and-groups/|Click 공식 문서: Commands and Groups]]
  * [[https://click.palletsprojects.com/en/stable/entry-points/|Click 공식 문서: Packaging Entry Points]]

===== History =====
  * codex:: 2026-08-03 Click 설치, decorator, command group, environment variable과 packaging 사용법을 정리.

{{indexmenu>.#1|js}}