Python functools.Placeholder 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Python functools.Placeholder 사용법

functools.Placeholder는 partial()과 partialmethod()에서 positional argument의 빈자리를 미리 예약할 때 쓰는 sentinel이다. 2026년 7월 10일 확인 기준 Python 3.14.6 공식 문서는 이 객체가 3.14에서 추가됐고, 앞쪽 인자만 고정할 수 있던 기존 partial()의 제약을 줄여 준다고 설명한다.

실무에서는 문자열 치환 함수, 포맷터, 콜백 어댑터처럼 "첫 번째 인자만 미리 고정하는 게 아니라 중간 인자도 나중에 넣고 싶다"는 상황에서 검토할 수 있다. 이 글은 Placeholder의 동작 방식, partial()에서의 채움 규칙, partialmethod()와의 관계, 안전한 사용 기준만 정리한다.

functools.Placeholder는 왜 추가됐을까?

기존 functools.partial()는 앞에서부터 positional argument를 고정하는 데는 편하지만, 중간 위치를 비워 두는 기능은 없었다. Python 3.14부터는 Placeholder를 인자 목록에 넣어 두고, 실제 호출 시 그 자리를 먼저 채우는 방식이 가능해졌다.

즉, partial()를 단순한 "앞부분 고정" 도구가 아니라 "호출 시그니처 일부를 예약하는" 도구로 확장한 셈이다. 그래서 여러 인자 중 가운데 값만 호출 시점에 받도록 구성해야 할 때 코드가 덜 우회적으로 바뀐다.

언제 쓰는 편이 맞을까?

상황	무난한 선택	이유
중간 positional argument를 나중에 채우고 싶다	Placeholder 사용	앞쪽 인자만 고정하는 제약을 피할 수 있음
앞에서부터 연속된 인자만 고정하면 된다	기존 partial()	굳이 placeholder를 넣지 않아도 충분함
의미가 keyword로 더 분명하다	keyword argument 우선	가독성이 더 낫고 호출 실수도 줄일 수 있음
메서드 정의에서 일부 인자를 미리 고정하고 싶다	partialmethod()와 함께 사용	인스턴스 메서드에도 같은 패턴을 적용할 수 있음

partial()에서는 어떻게 동작할까?

공식 문서 기준 Placeholder가 args 안에 있으면, partial()로 만든 객체를 호출할 때 새 positional argument가 placeholder 자리를 먼저 채운다. 그다음에 남는 인자가 뒤로 이어 붙는다.

from functools import partial, Placeholder as _

say_to_world = partial(print, _, _, "world!")
say_to_world("Hello", "dear")
# Hello dear world!

핵심은 "비어 있는 자리부터 먼저 채운다"는 규칙이다. 그래서 인자 순서를 억지로 뒤집는 래퍼 함수를 따로 만들지 않아도 되는 경우가 생긴다.

placeholder를 일부만 채워도 될까?

아니다. 공식 문서는 placeholder가 하나라도 남아 있으면 호출이 완성되지 않은 것으로 보고, 필요한 개수만큼 positional argument가 들어오지 않으면 TypeError가 난다고 설명한다.

즉, placeholder를 두 개 넣었으면 호출 시 그 두 자리를 모두 채워야 한다. 이 특성 때문에 placeholder 개수가 많아질수록 호출 규칙이 복잡해질 수 있으므로, 보통은 1개나 2개 수준에서 쓰는 편이 읽기 쉽다.

 

 

여러 번 partial()를 겹치면 어떻게 될까?

이 부분이 Placeholder의 핵심이다. Python 3.14.6 공식 문서는 기존 partial() 객체에 다시 partial()를 적용하면, 먼저 있던 placeholder가 새 positional argument로 채워진다고 설명한다. 필요하면 같은 자리에 새 Placeholder를 다시 넣어 예약 상태를 유지할 수도 있다.

from functools import partial, Placeholder as _

remove = partial(str.replace, _, _, "")
remove_dear = partial(remove, _, " dear")

이 패턴은 문자열 처리나 변환 파이프라인처럼 "기본 동작은 고정하되 실제 입력은 나중에 받는" 함수 조합에서 유용하다. 반대로 중첩이 깊어지면 호출 규칙을 머릿속으로 추적해야 하므로, 두세 단계 이상 겹치기 시작하면 별도 함수를 두는 편이 더 낫다.

keyword argument 자리에도 쓸 수 있을까?

불가능하다. 공식 문서는 Placeholder를 partial()의 keyword argument로 넘길 수 없다고 명시한다. 따라서 이름이 있는 인자 자리를 나중에 비워 두고 싶다면, 보통은 기본값을 둔 래퍼 함수나 명시적 keyword 인자를 받는 새 함수를 만드는 쪽이 안전하다.

partialmethod()와는 어떤 관계가 있을까?

Placeholder는 partialmethod()에도 같은 목적로 쓸 수 있다. 즉, 메서드 정의 단계에서 일부 positional argument는 고정하고, 일부는 실제 호출 시점에 채우는 방식이 가능하다.

다만 메서드에서는 인스턴스의 self가 먼저 바인딩된다는 점을 같이 봐야 한다. 그래서 가독성을 위해서는 "어떤 인자가 이미 메서드 바인딩으로 들어가고, 어떤 인자가 placeholder로 남는지"를 코드 리뷰에서 바로 읽을 수 있게 짧은 패턴으로 유지하는 편이 좋다.

실무에서 무난한 사용 기준

기준	설명
placeholder 수를 적게 유지	개수가 많아질수록 호출 규칙이 직관적이지 않다
keyword로 풀 수 있으면 keyword 우선	이름이 드러나는 호출이 유지보수에 유리하다
중첩 partial()은 얕게 유지	재예약 규칙을 과도하게 쓰면 별도 함수보다 읽기 어려워질 수 있다
Python 버전 확인	Placeholder는 3.14부터 추가됐다

FAQ

Q. Placeholder 없이도 같은 일을 할 수 있지 않을까?

가능한 경우가 많다. 다만 기존 partial()만으로는 앞에서부터 연속된 positional argument만 쉽게 고정할 수 있었다. 중간 자리를 비워 두고 싶다면 Placeholder가 더 직접적인 선택지다.

Q. placeholder를 남긴 상태로 호출하면 자동으로 나중에 채워질까?

아니다. 공식 문서 기준 placeholder는 호출 시 모두 채워져야 한다. 필요한 positional argument 수가 부족하면 TypeError가 발생한다.

Q. 모든 partial() 코드에 Placeholder를 쓰는 편이 좋을까?

그렇지는 않다. 앞부분 인자만 고정하면 충분한 코드에서는 기존 partial()가 더 단순하다. Placeholder는 중간 자리 예약이 실제로 필요한 경우에만 쓰는 편이 무난하다.

정리

functools.Placeholder는 Python 3.14에서 추가된 작은 기능이지만, partial()와 partialmethod()를 더 유연하게 만든다. 핵심 기준은 세 가지다. 중간 positional argument를 예약할 수 있다는 점, 호출 시 placeholder를 모두 채워야 한다는 점, 그리고 keyword 자리에는 쓸 수 없다는 점이다.

대부분의 코드에서는 keyword 인자로 해결할 수 있으면 그쪽이 더 읽기 쉽다. 다만 positional argument 순서를 유지한 채 일부 자리만 뒤로 미루고 싶다면 Placeholder가 가장 직접적인 표준 도구다.

참고 자료

• Python 3.14.6 공식 문서: functools