Rust로 만든 앱의 진입점을 Python으로 바꾸고 싶다면, 어디까지를 Rust 확장 모듈로 남길지가 첫 결정이다. 나는 이 결정을 취향이 아니라 줄 수로 계산했다. 계산 결과는 Rust 약 4.09만 줄을 남기고 약 1.1만 줄을 Python으로 옮기는 것이었다. 이 글은 그 계산과, 계산만으로는 정해지지 않았던 부분, 옮기는 도중 실제로 막힌 문제, 마지막에 잰 패키지 크기를 적은 기록이다.

대상은 로컬 API 게이트웨이와 데스크톱 GUI를 가진 개인 앱이다. 2026-11-04부터 2026-11-05까지 에이전트 여러 개가 슬라이스로 나눠 작업했고, 나는 계획과 병합 판단을 맡았다. 아래 수치와 결함은 그 실행의 종료 기록과 계획 문서에서 옮겼으며 이번에 다시 재현하지 않았다. 코드 조각은 설명하려고 새로 쓴 합성 예시다.

무엇을 정해야 했나

요구는 두 가지였다. 앱의 메인을 Python 명령줄 도구와 PySide6 GUI로 하고, 기존 Rust 함수는 PyO3 확장으로 import해서 쓴다. 두 번째 요구는 대화 중에 GUI까지 Python으로 옮기되 Rust와의 트레이드 오프를 계산해서 진행하라는 지시로 이어졌다. 그래서 정해야 할 것은 “Rust를 얼마나 남기나”가 아니라 “어느 단위를 어느 쪽에 두고, 그 사이를 무엇으로 건너나”였다.

이런 전환에서 흔한 실패는 두 방향이다. 전부 Python으로 다시 쓰면 이미 테스트가 있는 코드를 다시 검증해야 한다. 전부 Rust에 남기면 Python 메인은 껍데기가 되어 전환한 이유가 사라진다. 나는 단위별로 크기와 성격을 적어 두고 결정하기로 했다.

줄 수부터 셌다

계획 문서의 첫 절에서 크레이트별 Rust 소스 줄 수를 셌다. 세는 방법은 문서에 그대로 적혀 있다. 소스 디렉터리의 .rs 파일을 이어 붙여 줄을 센 값이고, 테스트 수는 테스트 속성이 붙은 줄을 따로 셌다.

# 계획 문서에 적힌 집계 방식(크레이트 이름은 일반화)
find crates/<c>/src -name '*.rs' | xargs cat | wc -l
grep -c '#\[test\]\|#\[tokio::test\]' ...   # 전체 1,323개, 이 중 GUI 크레이트 295개

결과를 단위별로 정리하면 아래 표와 같다. 마지막 열은 그 단위를 어디에 둘지 정한 결정 요인이다.

단위별 Rust 줄 수와 배치 결정(계획 문서 집계)
단위Rust 줄 수배치결정 요인
코어(SQLite 저장소, 키체인 비밀값, 장애 전환·우선순위 정책, 사용량, 가림 처리)8,099Rust 유지키체인과 SQLite와 정책이 테스트된 순수 코어이고, 다시 쓴다고 얻는 것이 없다
프로바이더(CLI·HTTP 실행, 사용량 조회, 프로세스 그룹)9,940Rust 유지프로세스 그룹 처리와 스트리밍 실행이 OS 수준 작업이다
API 라이브러리(허브, 게이트웨이, SSE, 제어 API, MCP 서버)약 22,830Rust 유지, PyO3로 노출SSE·HTTP 핫패스가 GIL을 쥐면 안 되고, 게이트웨이 로직에 테스트가 있다
API 크레이트의 CLI(인자 파싱, 출력 서식, 헬스체크)1,160Python인자 파싱과 출력 서식은 셸 접착 코드이고 이것이 “메인”이다
데스크톱 GUI(iced, 트레이, 자동 시작, 로컬 API 점검)9,838 (테스트 줄 2,678, 테스트 295개)Python(PySide6)사용자 결정이며, 5초 사용량 갱신과 250ms 트레이 폴링 주기는 JSON 경계를 견딘다

API 라이브러리 줄 수는 크레이트 전체 23,993줄에서 CLI 1,160줄을 뺀 값이다. 남는 Rust는 8,099 + 9,940 + 약 22,830으로 약 40,869줄, 옮기는 쪽은 1,160 + 9,838로 10,998줄이다. 계획 문서는 이를 “Rust 약 4.09만 줄 유지, 약 1.1만 줄 이동”으로 요약했다. 이동하는 줄이 Python으로 다시 쓰이면 테스트를 포함해 5,000~7,000줄쯤 된다는 추정도 문서에 있다. 이 마지막 값은 측정이 아니라 추정이고, 실제 Python 줄 수는 종료 기록에 없다.

줄 수만으로는 정해지지 않았다

표의 결정 요인 열을 보면 줄 수가 결정 변수가 아니라는 점이 드러난다. 가장 큰 덩어리인 API 라이브러리 약 22,830줄은 크기 때문이 아니라 성격 때문에 남았다. 스트리밍 응답이 흐르는 경로가 Python 인터프리터 락을 잡으면 안 되기 때문이다. 반대로 CLI 1,160줄은 작아서가 아니라 인자 파싱과 출력 서식이라는 접착 코드여서 옮겼다.

GUI는 사정이 달랐다. 9,838줄이라는 크기와 테스트 295개는 옮기기에 부담이 큰 쪽이었다. 계획은 이 이동의 첫째 근거로 사용자 결정을 적었고, 이어서 호출 주기를 근거로 달았다. GUI가 네이티브 함수를 부르는 주기가 5초마다 사용량 갱신, 250ms마다 트레이 폴링이라서, 호출마다 JSON 문자열을 만들고 푸는 비용이 화면 반응에 닿지 않는다고 판단했다. 이 판단도 호출 비용을 재서 낸 결론이 아니고 호출 주기에서 추론한 것이다.

핵심 판단: 줄 수는 “옮기는 비용”을 보여 줄 뿐 “어디에 둘지”는 말하지 않는다. 배치는 그 코드가 OS 수준 작업인지, 락을 잡으면 안 되는 핫패스인지, 접착 코드인지로 갈렸다.

이 절차를 요약하면 다음과 같다.

  1. 단위마다 줄 수와 테스트 수를 센다.
  2. 단위마다 결정 요인을 한 문장으로 적는다. “크다”는 요인이 아니다.
  3. 핫패스와 OS 수준 작업은 Rust에 두고, 접착 코드와 화면 코드는 Python으로 보낸다.
  4. 경계를 건너는 값의 형식과 호출 주기를 정한다.
  5. 옮기는 쪽의 동작은 기존 바이너리에서 뽑은 골든 출력으로 고정한다.

경계 모양: JSON 문자열과 GIL 해제

계획 문서는 경계의 모양도 정했다. 확장 모듈은 PyO3 기반 cdylib이고 abi3-py313으로 빌드한다. 허브를 감싼 클래스와 두 개의 진입 함수(서버 실행, MCP 표준입출력 서버)를 노출한다. 확장은 멀티스레드 tokio 런타임 하나를 소유하고, 각 메서드는 그 런타임 위에서 막힌 채 기다리며 그동안 GIL을 놓는다. 값은 JSON 문자열로 건너고, 얇은 Python 계층이 그것을 데이터클래스로 푼다.

위에서 아래로 세 단계가 화살표로 이어진다. 맨 위는 데이터클래스로 값을 푸는 Python 진입점이고, 가운데 노란색 단계는 값이 문자열로 건너가는 JSON 문자열 경계다. 맨 아래는 허브와 tokio 런타임을 가진 Rust 코어다.
Python과 Rust 사이를 건너는 것은 JSON 문자열 한 겹뿐이라는 점이 경계 설계의 핵심이다.

위 그림은 위에서 아래로 Python 쪽 진입점, JSON 경계, Rust 쪽 코어가 놓인 순서를 보여 준다.

이 설계에서 기각한 대안이 두 가지 있다. 하나는 비동기 런타임을 파이썬 이벤트 루프와 잇는 PyO3 확장 라이브러리다. 새 의존성이 필요하고 Qt 이벤트 루프와 asyncio를 묶게 되는데, 그 묶음이 필요하다는 측정이 없었다. 다른 하나는 Rust 값을 Python 객체로 직접 바꾸는 변환 라이브러리다. 이미 쓰는 직렬화 라이브러리로 JSON을 만들 수 있어서 의존성을 늘릴 이유가 없었다. 첫 번째 기각은 측정된 필요가 없다는 이유이고, 두 번째는 이미 있는 도구로 되는데 의존성을 더한다는 이유다.

이 설계가 공식 문서와 맞는지 2026-11-10에 PyO3 가이드의 병렬성 장을 읽고 대조했다. 가이드는 “The Python::detach method can be used to allow the Python interpreter to do other work while the Rust work is ongoing.”이라고 쓴다. 같은 장의 예제는 순차 Rust 함수를 detach 안에서 부르고 파이썬 스레드 둘로 돌린다. 가이드가 실은 2020년 중반 기계의 벤치마크에서 스레드 둘로 두 번 돌린 평균은 8.45ms, 한 번 돌린 순차 버전의 평균은 8.00ms였다. 이 숫자는 가이드 예제의 값이지 내 앱의 값이 아니며, 내 앱의 호출 경로는 재지 않았다. 읽으면서 이름 차이도 보였다. 내가 읽은 main 문서는 이 메서드를 detach라고 부르는데, 계획 문서는 allow_threads라고 적었다. 두 이름이 같은 동작의 개명인지는 이번에 확인하지 않았다.

모듈 이름도 경계의 일부로 다뤘다. maturin 문서의 프로젝트 레이아웃 장은 혼합 프로젝트에서 tool.maturin.python-source를 쓰는 구조를 설명하면서 “This structure is recommended to avoid a common ImportError pitfall”이라고 적는다. 같은 문서는 최종 사용자가 Rust 함수를 직접 쓰지 못하게 하려면 모듈에 밑줄이 붙은 다른 이름을 주라고 안내한다. 계획의 설정이 이 안내와 같은 방향이다. 아래는 같은 구조를 가상의 패키지 이름으로 옮긴 합성 예시다.

# 합성 예시: 패키지 이름은 가상이다
[tool.maturin]
python-source = "python"
module-name = "myapp._native"

Python 패키지가 공개 표면이고, 밑줄 모듈은 그 안에서만 부르는 내부 경계가 된다. 내 해석으로는 언어 경계가 이름으로도 드러나므로, 나중에 어떤 함수를 Python으로 가져와도 공개 표면이 바뀌지 않는다. 기록에서 그렇게 옮긴 사례는 확인되지 않는다.

Qt 메인 스레드 규칙

GUI를 Python으로 옮기면서 규칙 하나를 계획에 못 박았다. 네이티브 호출은 Qt 메인 스레드에서 부르지 않는다. 화면은 스레드 풀 작업자에게 호출을 맡기고 결과를 시그널로 받는다. 화면 상태와 서식은 Qt를 import하지 않는 순수 Python 프레젠터가 쥐게 해서, 디스플레이 없이 시험할 수 있게 했다. Qt가 필요한 시험은 오프스크린 플랫폼으로 돌렸다.

그런데 이 규칙은 계획에 있었는데도 논리 리뷰에서 위반이 나왔다. 첫 GUI 슬라이스의 논리 리뷰가 허브를 Qt 메인 스레드에서 쓰는 경로를 지적했고, 세 번째 슬라이스에서도 DST, 정렬, Qt 스레드 항목이 지적됐다. 두 경우 모두 정정은 한 번씩이었다. 규칙이 문서에 있다는 것과 코드가 지킨다는 것은 별개였고, 그 간격을 메운 것은 리뷰였다. 메인 스레드 위반이 왜 문제인지는 동시성 문제 3가지에서 다룬 상태 공유 문제와 이어지지만, 이번 기록에는 실제로 화면이 멈췄다는 관찰이 없다. 지적은 코드 경로 위주였다.

전환 중 부딪힌 문제

경계를 그은 뒤 막힌 일은 대부분 경계 바깥에서 나왔다. 종료 기록에서 이 글의 주제와 닿는 것만 표로 모았다.

전환 중 나온 문제와 처리(종료 기록 기준)
문제드러난 곳처리
Windows에서 줄바꿈이 CRLF로 바뀐 골든 파일CI.gitattributes로 해결
환경 변수 SYSTEMROOT와 ntpath/posixpath 문제CI코드 수정으로 해결
Qt 메인 스레드에서 허브 사용, DST·정렬·Qt 스레드 항목논리 리뷰각각 한 번 정정
패키징 슬라이스에서 Pillow와 과다 삭제 지적논리 리뷰한 번 정정
파일당 400줄 제한CIGUI 소스 한 파일을 분리

골든 파일 문제는 줄 수 계산과 관계가 깊다. 옮기는 쪽의 동작을 기존 바이너리에서 뽑은 출력으로 고정했기 때문에 파일이 그 출력과 한 글자도 다르지 않아야 했다. Windows 체크아웃이 줄바꿈을 바꾸면 같은 동작이 다른 파일로 보인다. 줄바꿈 정책 자체는 여기서 더 파지 않는다. 셸 정리 작업이 다른 작업자의 잠금을 지운 사고도 이 실행에서 있었지만, 언어 경계와는 무관해서 이 글의 범위 밖이다.

종료 기록은 SYSTEMROOT와 경로 모듈 문제를 원인까지 적지 않고 “수정으로 해결”이라고만 남겼다. 그래서 이 글도 어떤 경로를 어떻게 잘못 만들었는지는 쓰지 않는다. 다만 이 두 문제의 이름이 Windows 환경에 묶여 있다는 점은 기록에서 읽힌다. 접착 코드를 Python으로 옮기면 그 코드가 OS마다 다른 경로·환경 규칙을 직접 만지게 된다. 옮긴 쪽의 시험을 Windows에서도 돌려야 한다는 것이 이번에 얻은 점검 항목이다.

계획 자체도 한 번 실패했다. GPT 계열 모델에 맡긴 계획 검증이 한 번 실패했고, 나는 슬라이스 4의 소유 경로와 Docker 검증 방식을 한 번 고쳤다. 그 뒤 재검증은 하지 않았다. 이런 교차 검증 구조는 서로 다른 벤더가 코드를 교차 검증하는 구조에서 먼저 정리했다.

패키징 크기를 재 보니

크기는 계획 문서의 위험 항목에도 올라 있었다. 거기에는 Docker 이미지의 60MB 예산을 슬라이스 4에서 다시 재야 한다고 적혀 있었다. 종료 기록은 측정 크기와 함께 200,000,000바이트 예산을 비교 기준으로 적었다. 예산이 60MB에서 이 값으로 어떻게 바뀌었는지는 기록에 없다. 두 값을 같은 예산의 앞뒤로 읽을 수는 없어서, 아래 표는 종료 기록의 값만 옮긴다.

종료 시점에 측정한 산출물 크기
산출물크기기준
macOS 앱 번들93.1 MB측정값만 기록
macOS dmg42.7 MB측정값만 기록
Docker 이미지178,412,686 B예산 200,000,000 B
Windows 릴리스 산출물47,335,842 B릴리스 실행의 산출물

Docker 이미지는 예산 안에서 21,587,314바이트 여유가 남았다. 이 여유는 내가 두 값을 뺀 것이다. 반면 이전 Rust 전용 구성의 크기 기록은 가지고 있지 않아서 “Python 전환으로 몇 퍼센트 커졌다”는 문장은 쓸 수 없다. macOS 릴리스 작업은 태그나 수동 실행에서만 돌아서 그 릴리스 실행에서는 건너뛰었고, 관련 이슈가 열려 있다. 번들 크기 측정은 그 작업과 별개로 한 값이다.

확인하지 못한 것

한계를 사실, 추정, 권장으로 나눈다.

  • 사실: 경계는 줄 수와 단위별 결정 요인으로 정했고, 릴리스 실행에서 Windows 산출물이 만들어졌다. 종료 시점에 이슈 16개를 열었고 그중 4개를 수정으로 닫았다.
  • 사실: JSON 경계의 호출 비용을 측정하지 않았다. GUI 호출 주기가 5초와 250ms라는 사실에서 추론했을 뿐이다.
  • 사실: 이동한 Python의 실제 줄 수는 기록에 없다. 5,000~7,000줄은 계획 단계의 추정이다.
  • 추정: JSON 문자열 경계가 이 주기에서는 충분하다고 본다. 호출 주기가 훨씬 짧아지는 화면이 생기면 다시 따져야 한다.
  • 권장: 이 방식을 따르려면 줄 수와 함께 단위별 결정 요인, 경계 호출 주기, 크기 예산을 먼저 적는다. 나는 이 절차가 일반적으로 옳다고 주장하지 않는다. 한 앱, 한 번의 전환에서 쓴 방법이다.

이 기록에서 가져온 점검은 세 가지다. 옮길 코드를 줄 수가 아니라 락과 OS와 접착 여부로 나누었는가. 경계를 건너는 값과 호출 주기를 적어 두었는가. 옮긴 쪽을 기존 출력으로 고정하고 그 출력이 플랫폼마다 같은 바이트인가. 같은 질문을 프로세스 사이 통신 설계에 적용한 글로는 실시간 자막 앱의 IPC 설계법이 있다. 전체 글 목록은 프로그래밍 카테고리에서 볼 수 있다.

자주 묻는 질문

Rust 앱의 메인을 Python으로 바꿀 때 어디까지 Rust에 남기나?

이번 전환에서는 테스트된 순수 코어, OS 수준 프로세스 처리, GIL을 쥐면 안 되는 SSE·HTTP 핫패스를 Rust에 남겼다. 인자 파싱과 출력 서식 같은 접착 코드와 GUI는 Python으로 옮겼다. 줄 수는 약 4.09만 줄 대 약 1.1만 줄이었다.

PyO3 확장과 Python 사이는 무엇으로 값을 주고받나?

JSON 문자열이다. 직렬화 라이브러리가 이미 있었고 새 의존성이 없었다. Python 쪽의 얇은 계층이 JSON을 데이터클래스로 푼다. 호출 비용은 재지 않았고, GUI 호출 주기가 5초와 250ms라는 점으로 충분하다고 판단했다.

Qt GUI에서 네이티브 호출은 어느 스레드에서 부르나?

메인 스레드가 아니라 스레드 풀 작업자에서 부르고, 결과는 시그널로 받는다. 계획에 이 규칙을 적었지만 논리 리뷰에서 허브를 메인 스레드에서 쓰는 경로가 한 번 지적됐다.