PEP 791 – math.integer — 정수 전용 수학 함수를 위한 하위 모듈

Author:: Neil Girdhar <misterhsheik at gmail.com>, Sergey B Kirpichev <skirpichev at gmail.com>, Tim Peters <tim.peters at gmail.com>, Serhiy Storchaka <storchaka at gmail.com>
Sponsor:: Victor Stinner <vstinner at python.org>
Discussions-To:: Discourse thread
Status:: Final
Type:: Standards Track
Created:: 12-May-2025
Python-Version:: 3.15
Post-History:: 12-Jul-2018, 09-May-2025, 19-May-2025
Resolution:: 23-Oct-2025

Table of Contents

초록
동기
근거
명세
가능한 확장
하위 호환성
교육 방법
참조 구현
기각된 아이디어
- isqrt() 이름 변경
- 모듈 이름
감사의 글
Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

Important

This PEP is a historical document. The up-to-date, canonical documentation can now be found at math.integer — integer-specific mathematics functions.

See PEP 1 for how to propose changes.

초록

이 PEP는 math.gcd()나 math.isqrt()처럼 정수 인자에 대해 정의되는 정수론 함수, 조합론 함수 및 기타 함수를 위한 새 하위 모듈을 제안합니다.

동기

math 문서에는 “이 모듈은 C 표준에서 정의한 수학 함수에 대한 접근을 제공합니다.”라고 쓰여 있습니다. 하지만 시간이 지나면서 이 모듈에는 C 표준이나 부동 소수점 산술과 관련 없는 함수들이 채워졌습니다. 이제는 모듈의 범위, 내용 및 인터페이스(반환 값이나 허용되는 인자)를 설명하기가 훨씬 어려워졌습니다.

예를 들어, 문서에는 “달리 명시된 경우를 제외하고, 모든 반환값은 float입니다.”라는 문장이 있습니다. 이 문장은 더 이상 사실이 아닙니다. 문서의 Number-theoretic functions 하위 절에 나열된 함수 중 어느 것도 float를 반환하지 않지만, 문서에는 그렇게 적혀 있지 않습니다. 제안된 math.integer 하위 모듈의 문서에서는 “모든 반환값은 정수입니다”라는 문장이 정확할 것입니다. 마찬가지로 새 하위 모듈과 math 양쪽에서 함수가 받는 인자에 대한 설명을 단순화할 수 있습니다.

이제는 모듈 내용에 대한 사람들의 기대를 충족시키기가 훨씬 어려워졌습니다. 예를 들어, math.factorial(100)이 정확한 답을 반환하리라고 기대해야 합니까? 많은 언어, Python 패키지(scipy 등), 휴대용 계산기에는 이름이 같거나 비슷한 함수가 있는데, 이 함수들은 부동소수점 값을 반환하며, 이 예에서 그 값은 근삿값에 불과합니다.

cmath와 statistics 모듈도 있으므로, math 모듈이 모든 수학 함수를 담는 곳 역할을 할 수 없음은 분명합니다. 정수 관련 함수에 대해서도 같은 방식을 취합시다. 이는 공유된 맥락을 제공하여 문서의 장황함과 개념적 부담을 줄여 줍니다. 또한 관련 함수를 묶음으로써 함수를 찾기 쉽게 해 주고, IDE(예: CPython의 새 REPL)의 제안을 더 유용하게 만듭니다.

현재 CPython의 math 모듈 코드는 약 4200LOC이며, 그중 새 모듈에 해당하는 코드는 대략 1/3(1300LOC)입니다. 이는 math 모듈의 대부분의 함수와 달리 libm의 단순한 래퍼가 아닌 cmath (1340LOC)와 비슷한 규모입니다.

그리고 이 상황은 점점 악화되는 경향이 있습니다. 모듈 분리가 처음 제안되었을 당시에는 정수 관련 함수가 두 개뿐이었습니다: (모듈의 다른 함수들처럼 float도 받던) factorial()과 (fractions 모듈에서 옮겨 온) gcd()입니다. 그 후 isqrt(), comb(), perm()이 추가되었고, 새 함수가 모두 math 네임스페이스를 어지럽히지 않고 곧바로 새 모듈로 들어가도록 새 모듈 추가가 두 번째로 제안되었습니다. 이제 함수는 여섯 개가 되었고, factorial()은 더 이상 float를 받지 않습니다.

초기 논의 스레드와 이슈 python/cpython#81313에서 제안된 것 중 추가될 수 있는 것들은 다음과 같습니다:

c_div()와 n_div() — 양의 무한대 방향으로 올림하는 정수 나눗셈(ceiling divide)과 가장 가까운 정수로 반올림하는 정수 나눗셈을 위한 함수입니다. 관련 논의 스레드를 참조하십시오. 이는 표준 라이브러리에서 여러 번 재발명되었습니다. 예를 들어 datetime과 fractions에서 그렇습니다. 그리고 스레드에서 드러났듯이 이를 잘못 구현하기 쉽습니다.
gcdext() — 두 변수의 선형 디오판토스 방정식을 풀기 위한 함수입니다(int 구현에는 실제로 확장 유클리드 알고리즘이 포함되어 있습니다).
isqrt_rem() — 정수 제곱근과 나머지를 함께 반환하는 함수입니다(나머지는 정수가 완전제곱수가 아닐 때만 0이 아닙니다).
ilog() — 정수 로그입니다. math.log()는 정수 인자를 특별하게 처리합니다. 이 처리는 (모듈의 다른 함수들과 비교해) 독특하며 아직 문서화되지 않았습니다. 이슈 python/cpython#120950을 참조하십시오.
fibonacci() — 피보나치 수열.

네임스페이스를 분리하면 기존 math 모듈 함수와 이름이 충돌할 가능성이 사라집니다. 예를 들어, 정수 올림 나눗셈에 쓸 만한 이름인 ceil_div()나 ceildiv()는 ceil()과 혼동을 일으킬 것입니다(이 함수는 float용이며, 정수 나눗셈에서 우연히 가끔 올바르게 동작하기도 하지만 — 대개는 그렇지 않습니다).

근거

이것은 결국 문서화의 문제이니, 문서를 고치면 되지 않습니까? 그렇지 않습니다. 물론 모듈 서문을 훨씬 더 모호하게 작성할 수도 있고(즉, “math 모듈에는 몇 가지 수학 함수가 들어 있습니다”라고 대략적으로 말하는 식으로), 각 함수의 입출력과 동작을 정확하게 기술할 수도 있습니다(예: factorial()의 출력이 기본 설정의 scipy.special.factorial처럼 정확하지 않은지, 아니면 정확한지).

그러나 핵심 문제는 현재 모듈이 서로 다르고 거의 겹치지 않는 응용 분야를 뒤섞고 있다는 점입니다. 문서를 더 추가하면 이 점이 더 부각될 뿐이며, 최종 사용자에게는 문제가 더 심해집니다(읽거나 건너뛰어야 할 텍스트가 늘어납니다). 또한 발견 가능성 문제(어떤 함수를 어느 모듈에서 찾을 수 있는지, 그리고 애초에 찾을 수 있기는 한지 알려면 모듈의 모든 함수를 살펴보아야 합니다)도, 탭 자동 완성 문제도 해결되지 않습니다.

명세

이 PEP는 다음의 정수 관련 함수들을 math.integer라는 새 하위 모듈로 옮길 것을 제안합니다:

math에 있는 이 함수들의 별칭은 soft deprecated 상태가 됩니다. 이 PEP는 하위 호환성을 깨는 변경을 도입하지 않습니다.

모듈 함수는 정수와, __index__() 메서드를 구현하는 객체를 받습니다. 이 메서드는 객체를 정수로 변환하는 데 사용됩니다. 적합한 함수는 충분한 시간과 메모리가 주어지면 정확하게 계산되어야 합니다.

PyPI에서 제공되는 intmath 패키지는 이전 Python 버전을 위해 새 하위 모듈의 내용을 제공할 것입니다.

가능한 확장

(동기 섹션에서 언급한 것과 같은) 새 함수는 이 제안에 포함되지 않습니다.

다만, GMP처럼 잘 지원되는 수학 라이브러리에 대한 바인딩을 제공하는 것으로 충분한 경우가 아니라면, 하위 모듈의 범위는 제한되어야 한다는 점을 언급해 두어야 합니다. 예를 들어, 소수 판정과 소인수분해는 포함하지 않습니다. 프로덕션 수준의 구현에는 기여자에게 상당한 수학적 배경지식이 필요하며, 이러한 기능은 오히려 전문 라이브러리에 속하기 때문입니다.

제안된 함수가 이미 gmpy2에 있다면, 표준 라이브러리에서도 호환되는 인터페이스를 택하는 편이 좋습니다.

하위 호환성

math에 있는 별칭은 무기한 유지되므로(사용은 권장되지 않습니다), 코드가 깨지는 일은 예상되지 않습니다.

교육 방법

새 하위 모듈은 1) int와 유사한 인자를 받고 정수를 반환하며, 2) 임의 정밀도 정수 산술 필드에 속하는, 즉 플랫폼의 부동소수점 형식이나 동작 및/또는 플랫폼 수학 라이브러리(libm)에 대한 의존성이 없는 함수를 위한 곳이 될 것입니다.

사용자에게는 표준 라이브러리의 별도 전용 위치보다, 대부분의 기본 사용 사례를 다루는 int의 메서드(예: int.bit_length() 메서드)를 먼저 살펴보는 것이 자연스러울 것입니다.

참조 구현

python/cpython#133909

기각된 아이디어

isqrt() 이름 변경

cmath.sqrt()가 math.sqrt()의 복소수 버전인 것과 같은 방식으로, 새 네임스페이스에서 math.isqrt()를 sqrt로 노출하자는 논의가 잠시 있었습니다. 하지만 isqrt는 결국 다른 함수입니다. 이 함수는 제곱근을 내림(floor)한 값을 반환합니다. (다른 하위 모듈 아래에 있더라도) 같은 이름을 붙이면 혼란스러울 것입니다.

모듈 이름

투표 결과 intmath가 가장 인기 있는 후보였고, imath가 그 뒤를 이었습니다.

그 밖에 제안된 이름으로는 ntheory(SymPy의 하위 모듈처럼), integermath, zmath, dmath, imaths가 있습니다.

하지만 SC는 새로운 최상위 모듈보다 하위 모듈을 선호합니다. math의 하위 모듈 이름으로 가장 많이 지지받은 안은 integer, discrete, ntheory입니다.

감사의 글

이 PEP를 후원해 주신 Victor Stinner 님께 감사드립니다. discuss.python.org에서 논의에 참여하여 피드백을 주신 모든 분께 감사드리며, 특히 Oscar Benjamin, Steve Dower, Paul Moore 님께 감사드립니다.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.