Python 패키지 빌드 및 배포를 위한 Setuptools 활용

Setuptools 소개

Setuptools는 Python 패키지를 보다 효율적으로 빌드하고 배포할 수 있도록 도와주는 핵심 도구입니다. 특히 외부 종속성(dependency)을 포함하는 복잡한 패키지의 경우, 자동화된 설치 및 관리 기능을 제공하여 개발자 경험을 크게 향상시킵니다. 이 도구는 오랜 시간 동안 Python 생태계의 표준 빌드 시스템으로 자리 잡아왔으며, pip과 긴밀하게 통합되어 있습니다.

기본 설치 및 설정

최신 Python 배포판에는 일반적으로 pip와 함께 Setuptools가 기본 포함되어 있으므로 추가 설치 없이 사용할 수 있습니다. 버전 확인은 다음 명령어로 수행할 수 있습니다:

pip show setuptools

출력 예시는 다음과 같습니다:

Name: setuptools
Version: 65.6.3
Location: /usr/local/lib/python3.10/site-packages
Requires: packaging, wheel

setup.py 작성하기

패키지 메타데이터를 정의하는 핵심 파일인 setup.py를 작성합니다. 간단한 예제는 다음과 같습니다:

from setuptools import setup

setup(
    name='greeting',
    version='0.1.0',
    description='간단한 인사말 출력 모듈',
    author='Developer Kim',
    author_email='dev.kim@example.com',
    url='https://github.com/devkim/greeting',
    py_modules=['greet'],
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
    ],
)

여기서 사용된 주요 매개변수는 다음과 같습니다:

name: PyPI에 등록될 패키지 이름
version: 버전 번호 (PEP 440 규칙 준수)
py_modules: 단일 Python 파일로 구성된 모듈 목록
classifiers: 패키지 속성을 설명하는 분류 태그

빌드 및 설치 프로세스

모듈 빌드는 다음 명령으로 수행됩니다:

python setup.py build

이 명령은 현재 디렉터리에 build/ 폴더를 생성하고 소스 코드를 복사합니다. 반면 설치 명령은 빌드 과정을 자동으로 포함하며, 최종적으로 .egg 형식의 배포 가능한 아카이브를 생성합니다:

python setup.py install --record install_log.txt

--record 옵션은 설치된 모든 파일 경로를 기록하여 추후 수동 제거 시 유용하게 사용할 수 있습니다.

배포 가능한 패키지 생성

Setuptools는 두 가지 주요 배포 형식을 지원합니다.

소스 배포 (sdist)

플랫폼 독립적인 소스 코드 아카이브를 생성합니다:

python setup.py sdist

생성된 .tar.gz 파일은 다양한 환경에서 설치 가능하며, 기본 압축 형식은 gzip을 사용한 tar 아카이브입니다.

빌드된 배포 (bdist)

특정 플랫폼용으로 미리 컴파일된 바이너리 패키지를 생성합니다:

python setup.py bdist_wheel

이 명령은 dist/ 디렉터리 내에 .whl 확장자를 가진 Wheel 파일을 생성합니다.

Wheel vs Egg 포맷 비교

현재 권장되는 배포 형식은 Wheel이며, 기존의 Egg 형식을 대체하고 있습니다. 주요 차이점은 다음과 같습니다:

Wheel은 PEP 427에 의해 공식적으로 정의된 표준 형식입니다.
Wheel은 설치 시 .pyc 파일을 포함하지 않아 더 작은 크기를 유지합니다.
Wheel은 .dist-info 디렉터리를 사용하고, Egg는 .egg-info를 사용합니다.
pip은 기본적으로 Wheel 설치를 우선 처리합니다.

실제 설치 테스트는 다음과 같이 수행할 수 있습니다:

pip install dist/greeting-0.1.0-py3-none-any.whl
pip show greeting
pip uninstall greeting

PyPI에 패키지 업로드

공개 저장소에 패키지를 배포하려면 먼저 빌드하고, 이후 twine 도구를 사용해 안전하게 업로드하는 것이 권장됩니다:

python setup.py sdist bdist_wheel
twine upload dist/*

이 방식은 직접 upload 명령을 사용하는 것보다 보안상 더 안전합니다.

추가 고려 사항

프로젝트 루트에 README.md, LICENSE 파일을 포함하면 패키지 정보의 완전성을 높일 수 있으며, setup.cfg 또는 pyproject.toml 파일을 사용하여 설정을 선언적으로 관리하는 것도 좋은 방법입니다.

태그: setuptools python-packaging wheel sdist bdist

6월 23일 03:55에 게시됨

괴물 클럽