파이썬 패키지 배포 Wheel(*.whl) 파일 특징과 사용방법

파이썬 패키지 배포 Wheel(*.whl) 파일 특징과 사용방법

Wheel 파일은 Python 패키지 배포 시스템의 일환으로 개발되었습니다. 과거에는 Python 패키지를 배포할 때 주로 sdist (소스 배포) 형식이 사용되었습니다. 그러나 sdist 형식은 사용자가 패키지를 설치할 때마다 소스 코드를 컴파일해야 하는 단점이 있었습니다. 이는 설치 속도가 느려지고, 컴파일 과정에서 다양한 오류가 발생할 수 있는 문제를 초래했습니다. 이를 해결하기 위해 PEP 427이 제안되었고, 여기서 Wheel 파일 형식이 정의되었습니다. 주요 목표는 다음과 같습니다.

 

• 설치 속도 향상: 컴파일 과정을 생략함으로써 패키지 설치 속도를 크게 향상시키는 것.
• 호환성 개선: 다양한 플랫폼과 Python 버전 간의 호환성을 유지하면서도 일관된 설치 환경을 제공하는 것.
• 사용성 향상: 패키지 배포와 설치 과정을 단순화하고, 패키지 관리의 복잡성을 줄이는 것.

결과적으로 Wheel 파일은 이러한 목표를 달성하면서, 현재 Python 생태계에서 널리 사용되는 패키지 배포 형식이 되었습니다. 이러한 Wheel 파일의 특징과 사용방법에 대해서 정리합니다.

 

1. Python Wheel 파일의 특징

1) 빠른 설치

Wheel 파일은 이미 컴파일된 바이너리 형식으로 제공되기 때문에, 소스 코드에서 패키지를 빌드하는 과정이 생략됩니다. 이는 설치 속도를 크게 향상시키며, 특히 큰 패키지나 컴파일이 필요한 패키지의 경우 그 이점이 더 큽니다.

 

2) 플랫폼 독립성

많은 Wheel 파일은 플랫폼 독립적으로 설계되어 있어, 동일한 Wheel 파일을 여러 운영 체제에서 사용할 수 있습니다. 이는 패키지 배포와 관리의 복잡성을 줄여줍니다.

 

3) 종속성 해결

Wheel 파일에는 패키지의 종속성 정보가 포함되어 있어, 설치 시 추가적인 종속성 설치가 필요하지 않습니다. 이는 설치 오류를 줄이고, 전체적인 사용자 경험을 개선합니다.

 

4) 표준화된 형식

Wheel은 PEP 427에 정의된 표준 형식입니다. 이는 패키지의 배포와 설치 과정을 일관되고 신뢰성 있게 만들어 줍니다. 표준화된 형식 덕분에, 다양한 도구와 환경에서 일관된 방식으로 패키지를 처리할 수 있습니다.

반응형

2. Wheel 파일의 구조

Python Wheel 파일은 zip 형식으로 압축된 파일로, 패키지 배포에 필요한 모든 파일과 메타데이터를 포함하고 있습니다. Wheel 파일의 구조는 PEP 427에 정의되어 있으며, 다음과 같이 디렉토리 3가지와 파일로 구성됩니다.

package_name-version-py_version-none-any.whl
│
├── package_name/
│   ├── __init__.py
│   ├── module.py
│   └── ...
├── package_name_version.dist-info/
│   ├── METADATA
│   ├── WHEEL
│   ├── entry_points.txt
│   └── ...
└── package_name_version.data/
    └── data_files

 

 

• 패키지 소스 코드 디렉토리  :이 디렉토리는 실제 패키지 소스 코드를 포함합니다. 패키지 소스 파일은 일반적으로 다음과 같은 구조를 가집니다. 패키지 이름과 동일한 디렉토리가 생성되며, 그 안에 패키지의 모든 소스 코드 파일이 포함됩니다.

package_name/
├── __init__.py
├── module1.py
└── module2.py

 

• .dist-info 디렉토리 : .dist-info 디렉토리는 패키지 메타데이터를 포함하는 디렉토리입니다. 이 디렉토리에는 다음과 같은 파일이 포함됩니다.
  • METADATA: 패키지 메타데이터가 포함된 파일로, 패키지 이름, 버전, 작성자, 의존성 정보 등을 포함합니다.
  • WHEEL: Wheel 파일의 형식과 버전 정보를 포함하는 파일입니다.
  • RECORD: 패키지에 포함된 모든 파일의 목록과 해당 파일의 해시값 및 크기가 포함된 파일입니다. 설치 후 무결성 검증에 사용됩니다.
  • entry_points.txt: (선택사항) 패키지의 엔트리 포인트를 정의하는 파일입니다. 엔트리 포인트는 패키지가 제공하는 스크립트나 플러그인을 정의합니다.
  • top_level.txt: (선택사항) 패키지의 최상위 모듈이나 패키지의 목록을 포함하는 파일입니다.

package_name-version.dist-info/
├── METADATA
├── WHEEL
├── RECORD
├── entry_points.txt
└── top_level.txt

 

• .data 디렉토리 : .data 디렉토리는 추가적인 데이터 파일을 포함하는 디렉토리입니다. 이 디렉토리는 선택사항이며, 특정한 데이터 파일이 있을 경우에만 사용됩니다. 이 디렉토리는 보통 다음과 같은 구조를 가집니다.
  • purelib: 순수 Python 파일이 포함된 디렉토리입니다.
  • platlib: 플랫폼 특정 파일이 포함된 디렉토리입니다. 예를 들어, C 확장 모듈 등.
  • data: 기타 데이터 파일이 포함된 디렉토리입니다.

package_name-version.data/
├── purelib/
│   └── additional_file.dat
├── platlib/
│   └── platform_specific_file.so
└── data/
    └── some_other_data_file.dat

 

 

* 파일 구조 예시 ( my_package-1.0.0-py3-none-any.whl)

다음과 같은 구조의 파일 구조를 같는 my_package-1.0.0-py3-none-any.whl를 예로 들겠습니다.

my_package-1.0.0-py3-none-any/
├── my_package/
│   ├── __init__.py
│   └── core.py
├── my_package-1.0.0.dist-info/
│   ├── METADATA
│   ├── WHEEL
│   ├── RECORD
│   ├── entry_points.txt
│   └── top_level.txt
└── my_package-1.0.0.data/
    ├── purelib/
    │   └── additional_file.dat
    ├── platlib/
    │   └── platform_specific_file.so
    └── data/
        └── some_other_data_file.dat

 

이 때 각각의 METADATA, WHEEL, RECORD는 이렇게 작성할 수 있습니다.

 

1) METADATA

Metadata-Version: 2.1
Name: my_package
Version: 1.0.0
Summary: A brief description of my package
Home-page: https://example.com/my_package
Author: Your Name
Author-email: your.email@example.com
License: MIT

 

2) WHEEL

Wheel-Version: 1.0
Generator: bdist_wheel (0.36.2)
Root-Is-Purelib: true
Tag: py3-none-any

 

3) RECORD

my_package/__init__.py,sha256=abc123...,123
my_package/core.py,sha256=def456...,456
my_package-1.0.0.dist-info/METADATA,sha256=ghi789...,789

 

3. Wheel 파일 생성 방법

Wheel 파일을 생성하려면 wheel 패키지를 설치한 후, setup.py 파일이 있는 디렉토리에서 bdist_wheel 명령어를 사용하면 됩니다. 

 

1) 필수 도구 설치 : wheel 패키지를 설치해야 합니다.

pip install wheel

 

 

2) 'setup.py' 파일 생성 : 패키지 메타데이터와 설정 정보를 포함시킵니다.

from setuptools import setup, find_packages

setup(
    name='your_package_name',      # 패키지 이름
    version='0.1',                 # 패키지 버전
    packages=find_packages(),      # 포함할 패키지 자동 탐색
    install_requires=[             # 의존성 패키지 목록
        # 예: 'requests', 'numpy',
    ],
    author='Your Name',            # 작성자
    author_email='your.email@example.com',  # 작성자 이메일
    description='A description of your package',  # 패키지 설명
    url='https://github.com/yourusername/your-repo',  # 패키지 URL
    classifiers=[                  # 패키지 분류
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
    python_requires='>=3.6',       # 지원하는 파이썬 버전
)

 

3) 'bdist_wheel' 명령어로 wheel 파일 생성 : setup.py 파일이 있는 디렉토리에서 다음 명령어를 실행하여 Wheel 파일을 생성합니다. 이 명령어를 실행하면 dist 디렉토리에 .whl 파일이 생성됩니다.

python setup.py bdist_wheel

 

4. Wheel 패키지 배포 방법

생성된 Wheel 파일을 PyPI에 배포하려면 twine 패키지를 사용합니다.

 

1) 'twine' 패키지 설치

pip install twine

 

2) PyPI에 Wheel 파일 업로드

twine upload dist/*

 

5. Wheel 패키지 설치 방법

1) 로컬 Wheel 파일 설치 : 만약 로컬에 Wheel 파일이 있다면, pip 명령어를 사용하여 설치할 수 있습니다.

pip install path/to/your_package.whl

 

2) URL에서 Wheel 파일 설치 : 인터넷에 있는 Wheel 파일을 직접 설치할 수도 있습니다.

pip install https://example.com/your_package.whl

 

3) PyPI에서 Wheel 파일 설치 : 대부분의 경우, Wheel 파일은 PyPI(Python Package Index)에 업로드되어 있습니다. PyPI에서 Wheel 파일을 설치하는 방법은 일반적인 pip install 명령어와 동일합니다. pip는 자동으로 PyPI에서 해당 패키지의 최신 버전을 검색하고, Wheel 파일을 다운로드하여 설치합니다.

pip install package_name

 

 

* 참고 사이트 : https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#wheels