[파이썬 기초] argparse로 커맨드라인 도구 만들기

분석 스크립트를 작성할 때 파일 경로나 파라미터를 코드 안에 직접 하드코딩하면, 값을 바꿀 때마다 코드를 수정해야 합니다.

argparse는 커맨드라인 인자를 파싱하는 파이썬 표준 라이브러리로, 스크립트를 유연하고 재사용 가능한 도구로 만들어줍니다.

자동화 파이프라인에서도 필수적으로 사용됩니다.

---

기본 사용법

import argparse

parser = argparse.ArgumentParser(description="샘플 분석 도구")

# 인자 추가
parser.add_argument("input", help="입력 파일 경로")
parser.add_argument("output", help="출력 파일 경로")

args = parser.parse_args()

print(f"입력: {args.input}")
print(f"출력: {args.output}")

python script.py data.csv result.csv
# 입력: data.csv
# 출력: result.csv

 

--help 또는 -h는 자동으로 생성됩니다.

python script.py --help
# usage: script.py [-h] input output
#
# 샘플 분석 도구
#
# positional arguments:
#   input       입력 파일 경로
#   output      출력 파일 경로

---

위치 인자와 선택 인자

위치 인자 (positional argument)

반드시 입력해야 하는 인자입니다.

순서대로 전달합니다.

parser.add_argument("input", help="입력 파일 경로")
parser.add_argument("output", help="출력 파일 경로")

선택 인자 (optional argument)

--로 시작하며 생략할 수 있습니다.

짧은 형태(-)도 함께 지정할 수 있습니다.

parser.add_argument("--threshold", "-t",
                    help="임계값 (기본값: 0.05)")
parser.add_argument("--threads", "-n",
                    help="사용할 스레드 수 (기본값: 1)")

python script.py data.csv result.csv --threshold 0.01 --threads 4
python script.py data.csv result.csv -t 0.01 -n 4

---

인자 옵션 설정

type: 타입 지정

argparse는 기본적으로 모든 인자를 문자열로 받습니다. type 옵션으로 자동 변환할 수 있습니다.

parser.add_argument("--threshold", type=float, default=0.05,
                    help="p-value 임계값 (기본값: 0.05)")
parser.add_argument("--threads", type=int, default=1,
                    help="사용할 스레드 수 (기본값: 1)")
parser.add_argument("--min-length", type=int, default=50,
                    help="최소 리드 길이 (기본값: 50)")

default: 기본값

선택 인자를 생략했을 때 사용할 기본값입니다.

parser.add_argument("--output", default="output.tsv",
                    help="출력 파일 경로 (기본값: output.tsv)")

required: 필수 선택 인자

선택 인자이지만 반드시 입력해야 할 때 사용합니다.

parser.add_argument("--input", required=True,
                    help="입력 파일 경로 (필수)")

choices: 허용 값 제한

특정 값만 허용할 때 사용합니다.

parser.add_argument("--format", choices=["fasta", "fastq", "tsv"],
                    default="fasta", help="출력 형식")
parser.add_argument("--strand", choices=["+", "-", "both"],
                    default="both", help="분석할 가닥 방향")

 

허용되지 않은 값을 입력하면 자동으로 오류 메시지를 출력하고 종료합니다.

action: 플래그 인자

값 없이 존재 여부만 확인하는 인자입니다.

주로 특정 기능을 켜고 끄는 데 사용합니다.

parser.add_argument("--verbose", "-v", action="store_true",
                    help="상세 로그 출력")
parser.add_argument("--no-header", action="store_true",
                    help="헤더 없이 출력")

python script.py data.csv result.csv --verbose
# args.verbose → True

python script.py data.csv result.csv
# args.verbose → False

nargs: 여러 값 받기

인자 하나로 여러 값을 받을 때 사용합니다.

# 정해진 수의 값
parser.add_argument("--range", nargs=2, type=float,
                    metavar=("MIN", "MAX"),
                    help="값 범위 (예: --range 0.1 0.9)")

# 1개 이상
parser.add_argument("--samples", nargs="+",
                    help="샘플 이름 목록")

# 0개 이상
parser.add_argument("--exclude", nargs="*",
                    help="제외할 샘플 목록")

python script.py --samples sample_01 sample_02 sample_03
# args.samples → ['sample_01', 'sample_02', 'sample_03']

---

인자 그룹화

관련 인자를 그룹으로 묶으면 도움말이 더 읽기 쉬워집니다.

parser = argparse.ArgumentParser(description="RNA-seq 분석 도구")

# 입력/출력 그룹
io_group = parser.add_argument_group("입력/출력")
io_group.add_argument("--input", required=True, help="입력 파일")
io_group.add_argument("--output", default="result.tsv", help="출력 파일")

# 분석 파라미터 그룹
param_group = parser.add_argument_group("분석 파라미터")
param_group.add_argument("--threshold", type=float, default=0.05,
                         help="p-value 임계값")
param_group.add_argument("--fold-change", type=float, default=2.0,
                         help="최소 fold change")
param_group.add_argument("--threads", type=int, default=4,
                         help="스레드 수")

---

서브커맨드

git commit, git push처럼 하나의 스크립트에서 여러 기능을 서브커맨드로 나눌 수 있습니다.

parser = argparse.ArgumentParser(description="생물정보학 분석 도구")
subparsers = parser.add_subparsers(dest="command", help="서브커맨드")

# qc 서브커맨드
qc_parser = subparsers.add_parser("qc", help="품질 검사")
qc_parser.add_argument("--input", required=True, help="FASTQ 파일")
qc_parser.add_argument("--min-quality", type=int, default=20,
                       help="최소 품질 점수")

# align 서브커맨드
align_parser = subparsers.add_parser("align", help="시퀀스 정렬")
align_parser.add_argument("--input", required=True, help="FASTQ 파일")
align_parser.add_argument("--reference", required=True, help="참조 게놈")
align_parser.add_argument("--threads", type=int, default=4)

args = parser.parse_args()

if args.command == "qc":
    print(f"QC 실행: {args.input}, 최소 품질: {args.min_quality}")
elif args.command == "align":
    print(f"정렬 실행: {args.input} → {args.reference}")
elif args.command is None:
    parser.print_help()

python script.py qc --input reads.fastq --min-quality 30
python script.py align --input reads.fastq --reference hg38.fa

---

예시: FASTA 필터링 도구

실제로 사용할 수 있는 수준의 스크립트 예시입니다.

#!/usr/bin/env python3
"""
FASTA 파일에서 특정 조건을 만족하는 시퀀스를 필터링하는 도구
"""

import argparse
import sys
from Bio import SeqIO
from Bio.SeqUtils import gc_fraction


def parse_args():
    parser = argparse.ArgumentParser(
        description="FASTA 시퀀스 필터링 도구",
        formatter_class=argparse.ArgumentDefaultsHelpFormatter
    )

    parser.add_argument("input", help="입력 FASTA 파일 경로")
    parser.add_argument("output", help="출력 FASTA 파일 경로")

    filter_group = parser.add_argument_group("필터 조건")
    filter_group.add_argument("--min-length", type=int, default=100,
                              help="최소 시퀀스 길이")
    filter_group.add_argument("--max-length", type=int, default=None,
                              help="최대 시퀀스 길이")
    filter_group.add_argument("--min-gc", type=float, default=0.0,
                              help="최소 GC 함량 (0~1)")
    filter_group.add_argument("--max-gc", type=float, default=1.0,
                              help="최대 GC 함량 (0~1)")
    filter_group.add_argument("--ids", nargs="*",
                              help="포함할 시퀀스 ID 목록")

    parser.add_argument("--verbose", "-v", action="store_true",
                        help="상세 로그 출력")

    return parser.parse_args()


def filter_sequence(record, args):
    seq_len = len(record.seq)
    gc = gc_fraction(record.seq)

    if seq_len < args.min_length:
        return False
    if args.max_length and seq_len > args.max_length:
        return False
    if not (args.min_gc <= gc <= args.max_gc):
        return False
    if args.ids and record.id not in args.ids:
        return False
    return True


def main():
    args = parse_args()

    total = 0
    passed = 0
    filtered_records = []

    for record in SeqIO.parse(args.input, "fasta"):
        total += 1
        if filter_sequence(record, args):
            filtered_records.append(record)
            passed += 1
        elif args.verbose:
            print(f"제외: {record.id} (길이: {len(record.seq)})",
                  file=sys.stderr)

    SeqIO.write(filtered_records, args.output, "fasta")

    print(f"전체: {total}개, 통과: {passed}개, 제외: {total - passed}개",
          file=sys.stderr)


if __name__ == "__main__":
    main()

# 기본 실행
python filter_fasta.py input.fasta output.fasta

# 조건 지정
python filter_fasta.py input.fasta output.fasta \
    --min-length 200 \
    --min-gc 0.4 \
    --max-gc 0.6 \
    --verbose

# 도움말
python filter_fasta.py --help

---

자주 사용하는 패턴 정리

# 파일 존재 여부를 type으로 검증
import argparse
import os

def existing_file(path):
    if not os.path.exists(path):
        raise argparse.ArgumentTypeError(f"파일을 찾을 수 없습니다: {path}")
    return path

parser.add_argument("--input", type=existing_file, required=True)

# 범위 검증
def positive_float(value):
    v = float(value)
    if v <= 0:
        raise argparse.ArgumentTypeError(f"양수여야 합니다: {value}")
    return v

parser.add_argument("--threshold", type=positive_float, default=0.05)

---

주요 옵션 정리표

옵션	설명	예시
type	인자 타입 지정	type=int
default	기본값	default=0.05
required	필수 여부	required=True
choices	허용 값 목록	choices=["a", "b"]
action="store_true"	플래그 인자	--verbose
nargs	인자 수	nargs="+", nargs=2
help	도움말 설명	help="설명"
metavar	도움말에 표시할 이름	metavar="FILE"