TanixLu/pyfuze

pyfuze

설명

pyfuze는 Python 프로젝트를 단일 실행 파일로 패키징합니다.

이 프로젝트는 주로 cosmopolitan과 uv를 기반으로 구축되었습니다.

패키징 모드

Bundle 모드는 애플리케이션을 Python과 모든 종속성과 함께 패키징합니다. 패키징된 동일한 플랫폼에서만 실행되며, 가장 높은 호환성을 제공합니다. 패키지는 런타임에 --unzip-path로 내용을 추출합니다.

Online 모드는 더 작고 크로스 플랫폼인 패키지를 생성합니다. 런타임에 패키지를 추출하고 필요한 종속성을 --unzip-path로 다운로드합니다(인터넷 연결 필요). 이렇게 하면 패키지가 가볍고 다양한 시스템에 적응할 수 있습니다.

Portable 모드는 추출이나 인터넷 연결이 필요 없는 독립 실행형 크로스 플랫폼 실행 파일을 만듭니다. 순수 Python 프로젝트와 종속성만 지원합니다. 이 모드는 cosmos-4.0.2.zip 릴리스의 python.com을 기반으로 하며, 현재 Python 버전 3.12.3으로 고정되어 있습니다.

크로스 플랫폼 지원

online 모드의 크로스 플랫폼 기능은 주로 uv에 의해 제한됩니다: https://docs.astral.sh/uv/reference/policies/platforms/

portable 모드의 크로스 플랫폼 지원은 APE 사양 자체에 따라 달라집니다: https://github.com/jart/cosmopolitan/blob/master/ape/specification.md

요약하면, 두 모드 모두 macOS(ARM64 및 AMD64), Linux(AMD64) 및 Windows(AMD64)에서 실행될 것으로 예상됩니다.

설치

pip install pyfuze

또는 uvx로 직접 실행할 수 있습니다:

uvx pyfuze -h

사용법

Usage: pyfuze [OPTIONS] PYTHON_PROJECT

  Package Python projects into executables.

Options:
  --mode TEXT                     사용 가능한 모드:

                                  - bundle(기본값): Python과 모든 종속성을 포함합니다. 동일한 플랫폼에서만 실행됩니다. 가장 높은 호환성. 런타임에 --unzip-path로 추출합니다.

                                  - online: 작고 크로스 플랫폼. 런타임에 --unzip-path로 추출하고 종속성을 다운로드합니다(인터넷 필요).

                                  - portable: 독립 실행형 크로스 플랫폼 실행 파일. 추출 및 인터넷이 필요 없습니다. 순수 Python과 --output-name, --entry, --reqs, --include, --exclude만 지원합니다.

  --output-name TEXT              출력 실행 파일 이름 [기본값: <project_name>.com]
  --entry TEXT                    진입 Python 파일. 프로젝트가 폴더인 경우 사용합니다. [기본값: main.py]
  --reqs TEXT                     종속성을 지정하기 위해 requirements.txt 파일을 추가합니다(쉼표로 구분된 문자열 또는 파일 경로 입력)
  --include TEXT                  추가 파일이나 폴더를 포함합니다(예: config.ini) (source[::destination]) (반복 가능)
  --exclude TEXT                  프로젝트 파일이나 폴더를 제외합니다(예: build.py) (반복 가능).
  --unzip-path TEXT               bundle 및 online 모드의 압축 풀기 경로 (기본값: /tmp/<project_name>)
  --python TEXT                   Python 버전을 지정하기 위해.python-version 파일을 추가합니다(예: 3.11)
  --pyproject FILE                프로젝트 종속성을 지정하기 위해 pyproject.toml을 포함합니다
  --uv-lock FILE                  종속성을 잠그기 위해 uv.lock 파일을 포함합니다
  --win-gui                       Windows에서 콘솔 창을 숨깁니다
  --env TEXT                      INSTALLER_DOWNLOAD_URL, UV_PYTHON_INSTALL_MIRROR 및 UV_DEFAULT_INDEX와 같은 환경 변수를 추가합니다(key=value) (반복 가능)
  --uv-install-script-windows TEXT
                                  Windows용 UV 설치 스크립트 URI (URL 또는 로컬 경로) [기본값: https://astral.sh/uv/install.ps1]
  --uv-install-script-unix TEXT   Unix용 UV 설치 스크립트 URI (URL 또는 로컬 경로) [기본값: https://astral.sh/uv/install.sh]
  -d, --debug                     디버그 로깅 활성화
  -v, --version                   버전을 표시하고 종료합니다.
  -h, --help                      이 메시지를 표시하고 종료합니다.

예제

Portable 모드

portable 모드를 사용하여 독립 실행형 크로스 플랫폼 실행 파일을 생성합니다. simple.py와 같은 간단한 스크립트에 가장 적합합니다.

pyfuze./examples/simple.py --mode portable --reqs requests

Bundle 모드

이 명령은 bundle 모드를 사용하여 dist 폴더에 complex.com을 생성합니다. complex는 폴더 기반 프로젝트이므로 --entry를 사용하여 진입 파일을 지정합니다.

--pyproject 및 --uv-lock을 통해 pyproject.toml과 uv.lock을 포함하여 프로젝트의 종속성을 정의합니다.

기본적으로 pyfuze는 프로젝트 디렉토리의 모든 Python 파일과 패키지(즉, init.py가 있는 폴더)를 재귀적으로 패키징합니다.

--include 플래그는 config.txt와 같은 추가 파일을 포함하고, --exclude는 build.py와 같은 파일을 건너뜁니다.

기본 추출 경로는 /tmp/complex이지만, 여기서는 --unzip-path를 사용하여 로컬 ./complex 디렉토리로 설정합니다. 이는 임시 디렉토리가 지워질 수 있으므로 재부팅 후에도 config.txt와 같은 파일을 보존하려는 경우 유용합니다. 또는 Python 스크립트가 config.txt를 Windows의 %LocalAppData%와 같은 영구 위치로 복사하도록 할 수 있습니다.

마지막으로 --win-gui 옵션은 Windows에서 콘솔 창을 숨겨 GUI 애플리케이션에 이상적입니다.

pyfuze./examples/complex \
  --entry app.py \
  --pyproject./examples/complex/pyproject.toml \
  --uv-lock./examples/complex/uv.lock \
  --include./examples/complex/config.txt \
  --exclude./examples/complex/build.py \
  --unzip-path complex \
  --win-gui

Online 모드

online 모드를 사용하여 더 작고 크로스 플랫폼인 패키지를 생성합니다. 런타임에 Python과 종속성을 다운로드하려면 인터넷 연결이 필요합니다.

제한된 네트워크에서 안정성을 높이기 위해 --uv-install-script-windows, --uv-install-script-unix 및 --env를 사용하여 미러 URL을 지정할 수 있습니다.

pyfuze./examples/complex \
  --entry app.py \
  --pyproject./examples/complex/pyproject.toml \
  --uv-lock./examples/complex/uv.lock \
  --include./examples/complex/config.txt \
  --exclude./examples/complex/build.py \
  --unzip-path complex \
  --win-gui \
  --mode online \
  --uv-install-script-windows <uv-windows-installer-mirror-url> \
  --uv-install-script-unix <uv-unix-installer-mirror-url> \
  --env INSTALLER_DOWNLOAD_URL=<uv-binary-mirror-url> \
  --env UV_PYTHON_INSTALL_MIRROR=<python-install-mirror-url> \
  --env UV_DEFAULT_INDEX=<pypi-mirror-url>

작업 디렉토리

기본 작업 디렉토리는 <unzip-path>/src입니다.

pyfuze 실행 파일이 있는 디렉토리로 전환하려면 PYFUZEEXECUTABLEPATH 환경 변수를 사용할 수 있습니다:

import os
os.chdir(os.path.dirname(os.environ["PYFUZE_EXECUTABLE_PATH"]))

사용자가 실행 파일을 호출한 디렉토리로 전환하려면 PYFUZEINVOKEDIR 환경 변수를 사용할 수 있습니다:

import os
os.chdir(os.environ["PYFUZE_INVOKE_DIR"])

참고

pyfuze는 어떤 종류의 코드 암호화 또는 난독화도 수행하지 않습니다.

라이선스

pyfuze는 MIT 라이선스 하에 배포됩니다.

연락처

• 버그 신고 및 기능 요청은 GitHub Issues를 통해 해주세요.
• Discord에서 토론하세요.
• QQ 그룹: 1054869699