조만간 def handler(*args, **kwargs)과 같은 함수를 읽고 그것이 무엇을 받아들이는지 궁금할 것입니다. Python *args 및 **kwargs를 사용하면 함수가 유연한 수의 인수를 사용할 수 있습니다. 데코레이터, 래퍼 및 많은 라이브러리 API를 지원합니다.

이 가이드에서는 Python이 함수 호출 방법을 제어할 수 있는 새로운 방법과 함께 양방향으로 작동하는 방법을 다룹니다. Python 3.13에서 각 예제를 실행했으며 표시된 출력은 해당 실행에서 나온 것입니다.

*args가 하는 일

별표 하나로 작성된 매개변수는 추가 위치 인수를 튜플로 수집합니다.

def total(*args):
    print(type(args).__name__, args)
    return sum(args)

print(total(1, 2, 3))
# tuple (1, 2, 3)
# 6

print(total())
# tuple ()
# 0

인수가 없으면 단순히 빈 튜플을 얻게 되므로 함수는 계속 작동합니다. 이름 args은 관례입니다. *numbers는 동일하게 작동하며 더 설명적인 이름이 더 나은 경우가 많습니다.

**kwargs가 하는 일

별 두 개는 추가 키워드 인수를 사전에 수집합니다.

def describe(**kwargs):
    print(type(kwargs).__name__, kwargs)

describe(name="Asha", city="Pune")
# dict {'name': 'Asha', 'city': 'Pune'}

이는 일반적인 사전이므로 반복할 수 있고 get()를 사용하여 키를 찾아 전달할 수 있습니다. 키는 전달된 순서를 유지합니다.

매개변수 순서

다양한 매개변수를 혼합할 때 Python에는 특정 순서가 필요합니다.

1. 일반 위치 매개변수
2. *인수
3. 키워드 전용 매개변수
4. **크와르그

def order(item, qty=1, *extras, priority=False, **notes):
    print(item, qty, extras, priority, notes)

order("pen")
# pen 1 () False {}

order("pen", 2, "gift wrap", "card", priority=True, note="leave at door")
# pen 2 ('gift wrap', 'card') True {'note': 'leave at door'}

공지사항 priority. *extras 뒤에 오기 때문에 이름으로만 설정할 수 있으므로 길을 잃은 위치 인수로 인해 실수로 설정할 수 없습니다. **kwargs을 더 일찍 넣는 것은 허용되지 않으며 테스트에서는 “인수는 var-keyword 인수 뒤에 올 수 없습니다.”라는 SyntaxError를 발생시켰습니다.

전화할 때 포장 풀기

동일한 별이 호출 사이트에서 반대로 작동합니다. 별 하나는 목록이나 튜플을 위치 인수로 퍼뜨리고, 별 두 개는 사전을 키워드 인수로 퍼뜨립니다.

nums = [4, 5, 6]
total(*nums)            # same as total(4, 5, 6) -> 15

settings = {"name": "Ben", "city": "Delhi"}
describe(**settings)    # same as describe(name="Ben", city="Delhi")

압축 풀기는 *args 및 **kwargs를 사용하는 기능뿐만 아니라 모든 기능에서 작동합니다. 이는 구성이 사전으로 도착할 때 편리합니다.

def connect(host, port, timeout=5):
    return f"{host}:{port} (timeout {timeout})"

connect(**{"host": "db.local", "port": 5432})
# 'db.local:5432 (timeout 5)'

connect(**{"host": "db.local", "port": 5432, "ssl": True})
# TypeError: connect() got an unexpected keyword argument 'ssl'

그 오류는 유용합니다. **kwargs이 없는 함수는 알 수 없는 옵션을 거부하므로 설정 이름의 오타는 조용히 무시되는 대신 큰 소리로 실패합니다.

키워드 전용 인수

서명에 이름이 없는 *은 “이후의 모든 내용은 키워드로 전달되어야 함”을 의미합니다.

def make_user(name, *, admin=False):
    return name, admin

make_user("Asha", admin=True)
# ('Asha', True)

make_user("Asha", True)
# TypeError: make_user() takes 1 positional argument but 2 were given

이는 부울 플래그를 보호하는 좋은 방법입니다. make_user("Asha", True)과 같은 호출은 독자가 True의 의미를 추측하게 만듭니다. admin=True을 요구하면 모든 호출이 자명해집니다.

위치 전용 인수

Python 3.8부터 /은 위치로만 전달될 수 있는 매개변수를 표시합니다.

def area(width, height, /):
    return width * height

area(3, 4)                 # 12
area(width=3, height=4)
# TypeError: area() got some positional-only arguments
#   passed as keyword arguments: 'width, height'

누구도 이름에 의존할 수 없기 때문에 이를 통해 라이브러리는 나중에 다른 사람의 코드를 손상시키지 않고 해당 매개변수의 이름을 바꿀 수 있습니다. 여러 내장 기능이 이런 방식으로 작동합니다. 예를 들어, len(obj=[1])은 작동하지 않습니다.

데코레이터 및 래퍼

이것이 두 가지를 함께 사용하는 주요 실제 이유입니다. 래퍼는 원래 함수가 취하는 인수가 무엇이든 받아들이고 이를 변경하지 않고 전달해야 하는 경우가 많습니다.

import functools, time

def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        print(f"{func.__name__} took {time.perf_counter() - start:.4f}s")
        return result
    return wrapper

@timed
def slow_add(a, b, delay=0.01):
    time.sleep(delay)
    return a + b

print(slow_add(2, 3, delay=0.02))
# slow_add took 0.0205s
# 5

래퍼는 slow_add의 매개변수를 전혀 알 필요가 없으므로 모든 기능에서 작동합니다. 타이밍 수치는 약간 다를 수 있습니다. Python 데코레이터 가이드에서는 functools.wraps 및 기타 세부 사항을 설명합니다.

병합 옵션

**은 사전 리터럴 내에서도 작동하며, 기본값 위에 재정의를 적용하는 깔끔한 방법을 제공합니다.

defaults = {"theme": "light", "lang": "en"}

def build(**overrides):
    return {**defaults, **overrides}

build(theme="dark")
# {'theme': 'dark', 'lang': 'en'}

나중에 키가 우선하므로 재정의가 기본값을 대체합니다. 하위 클래스도 super().__init__(*args, **kwargs)에서처럼 이 패턴을 사용하여 상위 클래스에 추가 인수를 전달합니다. super()에 대한 자세한 내용은 Python 클래스 및 개체를 참조하세요.

치트 시트

피해야 할 때

유연성에는 대가가 따릅니다. def create(**kwargs)로 정의된 함수는 독자에게 어떤 옵션이 있는지 알려주지 않으며 편집자는 해당 옵션을 자동 완성할 수 없습니다. 오타는 오류가 발생하기 전에 여러 레이어를 조용히 통과할 수 있습니다.

따라서 함수에 필요한 것이 무엇인지 알면 명시적인 매개변수를 선호하세요. 래퍼, 데코레이터, 인수를 다른 함수로 전달 또는 total(*numbers)과 같은 실제 가변 길이 입력 등 유연성이 정말로 필요한 경우 *args과 **kwargs를 사용하세요. 함수에 명명된 옵션이 많이 필요한 경우 dataclass가 더 명확할 수도 있습니다.

일반적인 실수

변경 가능한 기본값 사용

이것은 별에 관한 것이 아니라 별 근처에 자주 나타납니다. 기본값은 함수가 정의될 때 한 번 생성된 후 호출 간에 공유됩니다.

def bad(items=[]):
    items.append(1)
    return items

print(bad(), bad())
# [1, 1] [1, 1]

두 호출 모두 매우 동일한 목록을 반환했으며 그 목록에는 두 개의 항목이 포함되었습니다. items=None을 사용하고 함수 내부에 새 목록을 만듭니다.

기타 오류

• 포장 풀기를 잊어버렸습니다. total(nums)를 호출하면 세 개의 숫자가 아닌 하나의 목록이 전달됩니다. total(*nums)을 쓰세요.
• 오타를 삼키는 중입니다. **kwargs를 허용하지만 알 수 없는 키를 무시하는 함수는 철자가 틀린 옵션을 숨깁니다. 검증하거나 피하세요 **kwargs.
• 동일한 인수를 두 번 전달합니다. f(1, **{"a": 2}), 여기서 a이 첫 번째 매개변수인 경우 “다중 값” 오류가 발생합니다.
• 래퍼로 전달하지 않습니다. func(args, kwargs)를 호출하면 튜플과 사전이 전달됩니다. 올바른 형식은 func(*args, **kwargs)입니다.

*args 및 **kwargs에 대한 힌트를 입력하세요.

*args과 **kwargs의 힌트를 입력하면 전체 컬렉션이 아닌 각 개별 값을 설명합니다. 이는 많은 사람들을 놀라게 합니다.

def total(*prices: float) -> float:
    return sum(prices)      # prices is tuple[float, ...]

def tag(**attrs: str) -> str:
    return " ".join(f'{k}="{v}"' for k, v in attrs.items())   # dict[str, str]

total(1.5, 2.5)                  # 4.0
tag(id="x", role="button")       # id="x" role="button"

여기서 prices은 부동 소수점의 튜플로 처리되고 attrs는 문자열 사전으로 처리됩니다. 키워드 인수의 유형이 다른 경우 Python 3.12에서는 Unpack와 결합된 TypedDict이라는 정확한 옵션을 추가했습니다.

from typing import TypedDict, Unpack

class Options(TypedDict, total=False):
    timeout: float
    retries: int

def fetch(url: str, **opts: Unpack[Options]) -> None: ...

그런 다음 mypy 또는 Pyright와 같은 유형 검사기는 fetch(url, retries="3") 또는 철자가 틀린 옵션 이름을 거부할 수 있습니다. 이는 일반 **kwargs에서는 절대 수행할 수 없는 일입니다. 그러나 런타임 동작은 변경되지 않습니다. Python 3.13에서 fetch("u", retries="3")을 실행했을 때 Python 자체는 유형 힌트를 적용하지 않기 때문에 아무런 문제 없이 실행되었습니다.

**kwargs에 대해 허용되는 키의 긴 목록을 문서화하고 있는 경우 이를 명시적인 키워드 전용 매개변수로 바꾸는 것을 고려해 보십시오. 그런 다음 편집자는 자동 완성 기능을 사용할 수 있으며 실수는 즉시 발견됩니다.

마무리

두 가지 방향을 기억하세요. 정의에 따르면 스타는 수집됩니다. 통화 중에 그들은 짐을 푼다. 호출을 더 명확하게 하려면 키워드 전용 인수를 추가하고 인수를 실제로 전달하는 코드용으로 **kwargs을 예약하세요. 연습하려면 모든 호출의 인수를 기록하는 작은 데코레이터를 작성하고 이를 몇 가지 다른 함수에 사용하세요.

자주 묻는 질문

계속 학습하세요