2025년 9월 17일한국어

파이썬 패키지 관리를 위한 setup.py와 pyproject.toml을 심층 비교하고, 모범 사례, 마이그레이션 전략, 최신 도구를 다룹니다.

파이썬 패키지 구조: Setup.py 대 Pyproject.toml - 종합 가이드

수년간 setup.py 파일은 파이썬 패키지 관리의 초석이었습니다. 하지만 환경이 발전하면서 pyproject.toml이 현대적인 대안으로 부상했습니다. 이 종합 가이드에서는 두 접근 방식의 차이점을 탐색하여, 어떤 것이 당신의 프로젝트에 적합한지 이해하고 파이썬 패키지를 효과적으로 관리하는 방법을 돕습니다.

기본 사항 이해하기

파이썬 패키지란 무엇인가?

파이썬 패키지는 파이썬 코드를 조직하고 배포하는 방법입니다. 관련 모듈을 디렉토리 계층 구조로 그룹화하여 코드를 더 모듈화하고 재사용 가능하며 유지보수하기 쉽게 만듭니다. 패키지는 다른 사람들과 코드를 공유하고 프로젝트의 의존성을 관리하는 데 필수적입니다.

패키지 메타데이터의 역할

패키지 메타데이터는 패키지 이름, 버전, 작성자, 의존성, 진입점(entry points) 등 패키지에 대한 필수 정보를 제공합니다. 이 메타데이터는 pip와 같은 패키지 관리자가 패키지를 설치, 업그레이드 및 관리하는 데 사용됩니다. 역사적으로 setup.py는 이 메타데이터를 정의하는 주요 방법이었습니다.

Setup.py: 전통적인 접근 방식

Setup.py란 무엇인가?

setup.py는 setuptools 라이브러리를 사용하여 패키지의 구조와 메타데이터를 정의하는 파이썬 스크립트입니다. 이는 동적으로 실행되는 파일로, 파이썬 코드를 실행하여 패키지를 구성한다는 의미입니다.

Setup.py의 주요 구성 요소

일반적인 setup.py 파일은 다음 구성 요소를 포함합니다:

패키지 이름: 패키지의 이름 (예: my_package).
버전: 패키지의 버전 번호 (예: 1.0.0).
작성자 및 유지보수자 정보: 패키지의 작성자 및 유지보수자에 대한 세부 정보.
의존성: 패키지가 의존하는 다른 패키지 목록 (예: requests >= 2.20.0).
진입점(Entry Points): 명령줄 스크립트 또는 패키지로 들어오는 다른 진입점에 대한 정의.
패키지 데이터: 패키지에 포함되어야 하는 비코드 파일 (예: 설정 파일, 데이터 파일).

Setup.py 예시

```python from setuptools import setup, find_packages setup( name='my_package', version='1.0.0', author='John Doe', author_email='john.doe@example.com', description='A simple Python package', packages=find_packages(), install_requires=[ 'requests >= 2.20.0', ], entry_points={ 'console_scripts': [ 'my_script = my_package.module:main', ], }, classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], ) ```

Setup.py의 장점

익숙함: 전통적이고 잘 알려진 접근 방식이므로 많은 개발자가 이미 익숙합니다.
유연성: 파이썬 스크립트이기 때문에 높은 수준의 유연성을 제공합니다. 복잡한 로직을 수행하고 필요에 따라 빌드 프로세스를 사용자 정의할 수 있습니다.
확장성: Setuptools는 풍부한 기능 집합을 제공하며 사용자 정의 명령 및 확장 기능으로 확장할 수 있습니다.

Setup.py의 단점

동적 실행: setup.py의 동적인 특성은 빌드 과정에서 임의의 코드를 실행하므로 보안 위험이 될 수 있습니다.
암묵적 의존성: setup.py는 종종 setuptools 자체와 같은 암묵적 의존성에 의존하여 불일치와 오류를 유발할 수 있습니다.
복잡성: 복잡한 프로젝트의 경우 setup.py가 커지고 유지 관리하기 어려워질 수 있습니다.
제한적인 선언적 구성: 많은 패키지 메타데이터가 선언적이 아닌 명령적으로 정의되어 추론하기가 더 어렵습니다.

Pyproject.toml: 현대적인 대안

Pyproject.toml이란 무엇인가?

pyproject.toml은 TOML(Tom's Obvious, Minimal Language) 형식을 사용하여 패키지의 빌드 시스템과 메타데이터를 정의하는 설정 파일입니다. 이는 선언적 접근 방식으로, 어떻게 달성할지가 아닌 무엇을 달성하고 싶은지를 명시하는 것을 의미합니다.

Pyproject.toml의 주요 섹션

일반적인 pyproject.toml 파일은 다음 섹션을 포함합니다:

[build-system]: 사용할 빌드 시스템을 정의합니다 (예: setuptools, poetry, flit).
[project]: 프로젝트 이름, 버전, 설명, 작성자, 의존성 등 프로젝트에 대한 메타데이터를 포함합니다.
[tool.poetry] 또는 [tool.flit]: 도구별 구성을 위한 섹션입니다 (예: Poetry, Flit).

Pyproject.toml 예시 (Setuptools 사용)

```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = [ { name = "John Doe", email = "john.doe@example.com" } ] dependencies = [ "requests >= 2.20.0", ] [project.scripts] my_script = "my_package.module:main" [project.optional-dependencies] dev = [ "pytest", "flake8", ] [project.classifiers] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] homepage = "https://example.com" repository = "https://github.com/example/my_package" ```

Pyproject.toml 예시 (Poetry 사용)

```toml [tool.poetry] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = ["John Doe "] license = "MIT" readme = "README.md" [tool.poetry.dependencies] python = ">=3.7,<3.12" requests = ">=2.20.0" [tool.poetry.dev-dependencies] pytest = "^6.0" flake8 = "^3.9" [build-system] requires = ["poetry-core>=1.0.0"] build-backend = "poetry.core.masonry.api" ```

Pyproject.toml의 장점

선언적 구성: pyproject.toml은 패키지 메타데이터를 정의하는 선언적인 방법을 제공하여 이해하고 유지 관리하기가 더 쉽습니다.
표준화된 빌드 시스템: 사용할 빌드 시스템을 명시하여 여러 환경에서 일관된 빌드를 보장합니다.
개선된 의존성 관리: Poetry 및 Pipenv와 같은 도구는 pyproject.toml과 원활하게 통합되어 강력한 의존성 관리 기능을 제공합니다.
보안 위험 감소: 정적 설정 파일이므로 빌드 과정에서 코드를 동적으로 실행하는 것과 관련된 보안 위험을 제거합니다.
최신 도구와의 통합: pyproject.toml은 Poetry, Pipenv, Flit과 같은 최신 파이썬 패키징 도구의 표준입니다.

Pyproject.toml의 단점

학습 곡선: 개발자는 새로운 구문(TOML)과 패키지 관리에 대한 새로운 사고방식을 배워야 할 수 있습니다.
제한된 유연성: 복잡한 로직이 필요한 고도로 사용자 정의된 빌드 프로세스에는 적합하지 않을 수 있습니다.
도구 의존성: 특정 빌드 시스템(예: Setuptools, Poetry, Flit)을 선택하고 사용법을 배워야 합니다.

Setup.py와 Pyproject.toml 비교

setup.py와 pyproject.toml의 주요 차이점을 요약한 표는 다음과 같습니다:

기능	Setup.py	Pyproject.toml
구성 스타일	명령형 (파이썬 코드)	선언형 (TOML)
빌드 시스템	암묵적 (Setuptools)	명시적 (`[build-system]`에 명시)
보안	잠재적으로 덜 안전함 (동적 실행)	더 안전함 (정적 구성)
의존성 관리	기본 (`install_requires`)	고급 (Poetry, Pipenv와 통합)
도구	전통적 (Setuptools)	현대적 (Poetry, Pipenv, Flit)
유연성	높음	중간
복잡성	복잡한 프로젝트의 경우 높을 수 있음	일반적으로 낮음

마이그레이션 전략: Setup.py에서 Pyproject.toml로

setup.py에서 pyproject.toml로 마이그레이션하는 것은 어려워 보일 수 있지만, 장기적인 유지보수성과 일관성을 위한 가치 있는 투자입니다. 사용할 수 있는 몇 가지 전략은 다음과 같습니다:

1. 최소한의 Pyproject.toml로 시작하기

빌드 시스템을 지정하는 기본 pyproject.toml 파일을 만든 다음 setup.py의 메타데이터를 pyproject.toml로 점진적으로 마이그레이션합니다.

```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" ```

2. Pyproject.toml과 함께 Setuptools 사용하기

Setuptools를 빌드 시스템으로 계속 사용하되, 프로젝트 메타데이터는 pyproject.toml에 정의합니다. 이를 통해 익숙한 도구를 계속 사용하면서 pyproject.toml의 이점을 활용할 수 있습니다.

3. Poetry와 같은 최신 도구로 마이그레이션하기

Poetry나 Pipenv와 같은 최신 도구로 마이그레이션하는 것을 고려해 보세요. 이러한 도구는 포괄적인 의존성 관리 기능을 제공하며 pyproject.toml과 원활하게 통합됩니다.

예시: Poetry로 마이그레이션하기

Poetry 설치: pip install poetry
프로젝트에서 Poetry 초기화: poetry init (이 과정은 pyproject.toml 파일 생성을 안내합니다)
의존성 추가: poetry add requests (또는 다른 의존성들)
패키지 빌드: poetry build

4. 자동 마이그레이션을 위한 도구 사용하기

일부 도구는 마이그레이션 과정을 자동화하는 데 도움이 될 수 있습니다. 예를 들어, setup.py 파일을 pyproject.toml 파일로 변환하는 도구를 사용할 수 있습니다.

파이썬 패키지 관리를 위한 모범 사례

1. 가상 환경 사용하기

항상 가상 환경을 사용하여 프로젝트의 의존성을 시스템 전반의 파이썬 설치와 격리하세요. 이는 충돌을 방지하고 프로젝트가 올바른 의존성을 갖도록 보장합니다.

venv 사용 예시:

```bash python3 -m venv .venv source .venv/bin/activate # On Linux/macOS .venv\Scripts\activate # On Windows ```

conda 사용 예시:

```bash conda create -n myenv python=3.9 conda activate myenv ```

2. 의존성을 정확하게 명시하기

버전 제약 조건을 사용하여 의존성의 호환 가능한 버전을 명시하세요. 이는 호환되지 않는 라이브러리 업데이트로 인한 예기치 않은 동작을 방지합니다. 의존성 관리를 위해 pip-tools와 같은 도구를 사용하세요.

의존성 명시 예시:

``` requests >= 2.20.0, < 3.0.0 ```

3. 일관된 빌드 시스템 사용하기

빌드 시스템(예: Setuptools, Poetry, Flit)을 선택하고 그것을 고수하세요. 이는 여러 환경에서 일관된 빌드를 보장하고 패키징 과정을 단순화합니다.

4. 패키지 문서화하기

패키지에 대한 명확하고 간결한 문서를 작성하세요. 이는 사용자가 패키지 사용법을 이해하는 데 도움이 되고 다른 사람들이 프로젝트에 기여하기 쉽게 만듭니다. Sphinx와 같은 도구를 사용하여 코드에서 문서를 생성하세요.

5. 지속적 통합(CI) 사용하기

CI 시스템(예: GitHub Actions, Travis CI, GitLab CI)을 설정하여 코드 변경 시 패키지를 자동으로 빌드, 테스트 및 배포하세요. 이는 패키지가 항상 작동 상태를 유지하도록 돕습니다.

GitHub Actions 설정 예시:

```yaml name: Python Package on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install poetry poetry install - name: Lint with flake8 run: | poetry run flake8 . - name: Test with pytest run: | poetry run pytest ```

6. PyPI에 패키지 게시하기

Python Package Index(PyPI)에 패키지를 게시하여 세상과 공유하세요. 이를 통해 다른 사람들이 쉽게 패키지를 설치하고 사용할 수 있습니다.

PyPI에 게시하는 단계:

PyPI와 TestPyPI에 계정을 등록합니다.
twine 설치: pip install twine.
패키지 빌드: poetry build 또는 python setup.py sdist bdist_wheel.
TestPyPI에 패키지 업로드: twine upload --repository testpypi dist/*.
PyPI에 패키지 업로드: twine upload dist/*.

실제 사용 사례

몇몇 인기 있는 파이썬 프로젝트가 pyproject.toml을 어떻게 사용하고 있는지 살펴보겠습니다:

Poetry: 자체 패키지 관리를 위해 pyproject.toml을 사용합니다.
Black: 타협 없는 코드 포맷터인 Black 또한 pyproject.toml을 활용합니다.
FastAPI: 파이썬으로 API를 구축하기 위한 현대적이고 빠른(고성능) 웹 프레임워크도 이를 사용합니다.

결론

pyproject.toml은 파이썬 패키지 관리의 현대적인 표준을 대표하며, 패키지 메타데이터를 정의하고 의존성을 관리하는 선언적이고 안전한 방법을 제공합니다. setup.py가 우리에게 오랫동안 좋은 서비스를 제공했지만, pyproject.toml로 마이그레이션하는 것은 장기적인 유지보수성, 일관성 및 최신 도구와의 통합을 위한 가치 있는 투자입니다. 모범 사례를 채택하고 올바른 도구를 활용함으로써 파이썬 패키징 워크플로우를 간소화하고 고품질의 재사용 가능한 패키지를 만들 수 있습니다.