브라우저에서 Python을 실행하는 일은 더 이상 낯설지 않습니다. Pyodide는 CPython을 WebAssembly로 컴파일해 브라우저 안에서 Python 코드를 실행하게 합니다.1 Emscripten 기반 적응 덕분에 numpy, pandas, scipy, matplotlib 같은 과학 계산 라이브러리도 사용할 수 있고, pandas는 wasm 패키지로 제공됩니다.1
하지만 브라우저 기반 Python 앱에서 더 어려운 질문은 실행 그 자체가 아닙니다. 데이터를 어디에 저장하고, 새로고침 뒤에도 유지되며, 여러 브라우저에서 같은 방식으로 동작하는지 확인하는 일입니다.
OPFS + Pyodide test harness는 바로 이 지점을 검증하기 위한 작은 실험 도구입니다. 핵심은 “브라우저에서 Python이 돈다”가 아니라 “브라우저 안 Python 앱이 로컬 파일 시스템처럼 데이터를 안정적으로 다룰 수 있는가”입니다.
핵심은 Python 실행보다 저장소 검증이다
OPFS는 웹앱이 브라우저 안에서 사용할 수 있는 원본별 사설 파일 시스템입니다. LocalStorage보다 큰 데이터나 파일형 데이터를 다루는 데 적합하며, 로컬 RAG 예시에서는 벡터 인덱스 저장소로도 사용됩니다.2
이번 테스트 하네스는 OPFS에 파일을 저장하고, 목록을 확인하고, 다시 읽는 흐름을 시험합니다. 여기에 Pyodide의 sqlite3를 사용해 OPFS 안의 test.db에 SQL을 실행하는 과정도 포함됩니다.3
즉 이 도구가 확인하려는 질문은 분명합니다.
브라우저 안에서 실행되는 Python 앱이 SQLite 파일을 수정하고, 그 결과를 새로고침 뒤에도 유지할 수 있는가?
여기서 test harness는 완성된 제품 기능이 아닙니다. 특정 브라우저와 환경에서 실행, 저장, 읽기, 로그 확인을 반복하기 위한 검증 장치입니다. 따라서 이 도구의 가치는 화려한 데모가 아니라 브라우저별 동작 차이를 드러내는 데 있습니다.
오프라인 Python 도구는 어떻게 가능해지는가
Pyodide와 PWA를 결합하면 네트워크에 의존하지 않는 브라우저 기반 Python 도구 체인을 만들 수 있습니다.1 기본 구조는 비교적 단순합니다.
Python 스크립트는 Pyodide가 실행한다.
화면은 HTML, CSS, JavaScript가 담당한다.
Service Worker는 HTML, JS, CSS, Pyodide wasm 파일, Python 패키지 같은 정적 자산을 캐시한다.1
이 구조가 동작하면 사용자는 설치형 데스크톱 앱 없이도 브라우저에서 Python 기반 도구를 사용할 수 있습니다. 개발자는 Python 생태계와 웹 배포 방식을 함께 활용할 수 있고, 데이터 처리를 서버로 보내지 않는 형태의 앱도 설계할 수 있습니다.
다만 첫 실행부터 완전히 오프라인인 것은 아닙니다. Pyodide의 wasm 파일과 Python 패키지는 크기가 작지 않아 최초 로드에는 네트워크가 필요합니다.1 대신 한 번 리소스가 캐시되면, 이후에는 네트워크가 없어도 새로고침과 기능 실행이 가능합니다.1
이때 OPFS는 캐시된 실행 환경과 별개로, 앱이 생성하거나 수정한 데이터를 저장하는 축이 됩니다. Pyodide가 코드를 실행하고 Service Worker가 실행 자산을 캐시한다면, OPFS는 사용 중 만들어진 파일과 데이터베이스를 유지하는 역할을 맡는 셈입니다.
제품화의 기준은 “가능하다”가 아니라 “반복 가능하다”
OPFS가 있다고 해서 곧바로 안전한 로컬 데이터 앱이 되는 것은 아닙니다. 중요한 기준은 한 번 성공했는지가 아니라, 지원하려는 브라우저에서 같은 흐름이 반복 가능하게 동작하는지입니다.
Pyodide 쪽에서도 OPFS 관련 코드가 Chrome에서는 되고 Firefox에서는 안 되는 사례가 논의된 바 있습니다.4 여기에 Safari까지 포함하면 확인해야 할 항목은 더 늘어납니다. 파일 생성, 읽기, 수정, 새로고침 후 유지, 권한 처리, 저장소 정리 정책까지 모두 실제 환경에서 검증해야 합니다.
사용자 경험도 함께 설계해야 합니다. OPFS는 사용자의 일반 폴더를 직접 다루는 전통적인 파일 접근 방식과 다릅니다. 따라서 사용자가 데이터를 어디까지 믿고 저장할 수 있는지 이해할 수 있도록 가져오기, 내보내기, 백업, 초기화 같은 UI가 필요합니다.
이 테스트 하네스에서 배울 점
OPFS + Pyodide test harness의 의미는 작지만 분명합니다. 브라우저는 이제 Python 코드를 실행하는 공간을 넘어, 로컬 데이터를 다루는 작업 공간으로 확장되고 있습니다.
다만 실제 제품에 적용하려면 “내 브라우저에서 된다”로는 부족합니다. Pyodide 실행 환경, Service Worker 캐시, OPFS 저장소가 지원 대상 브라우저에서 일관되게 맞물리는지 먼저 검증해야 합니다.
이 테스트 하네스는 그 검증을 시작하는 실용적인 출발점입니다. 브라우저 기반 Python 앱을 만들고 있다면, 기능을 더하기 전에 먼저 저장, 읽기, 새로고침, 브라우저 차이를 확인하는 작은 하네스를 마련하는 것이 제품 안정성에 더 가까운 선택입니다.
참고
1Building an Offline-Capable PWA with Pyodide
2Build a Private AI Search on Your Device: Local RAG in the Browser
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.