Python 강좌 / 프로그램을 패키지로 만들고 배포하기

Python 강좌

Python 프로그램은 pyproject.toml에 프로젝트·빌드 정보를 적고 wheel 같은 배포 파일로 만들 수 있습니다. 배포 파일을 깨끗한 가상환경에 설치해 import와 실행 명령이 동작하는지 확인해야 소스 폴더에서만 되는 문제를 찾을 수 있습니다.

모듈 이름과 배포 이름

이 예제의 설치 배포 이름은 expensekit-demo이고 import 이름은 expensekit입니다. 하이픈이 있는 배포 이름과 Python 모듈 이름은 같을 필요가 없습니다. src 구조는 프로젝트 루트에서 우연히 소스가 바로 import되어 설치 누락을 가리는 문제를 줄이는 데 도움이 됩니다.

관련 동작과 지원 조건은 프로그램을 패키지로 만들고 배포하기 관련 공식 문서에서 확인할 수 있습니다.

아래 이름은 로컬 실습용입니다. 공개 패키지 저장소의 이름 사용 가능 여부나 소유권을 확인한 것은 아니며, 이 과정에서는 업로드하지 않고 로컬 빌드·설치까지만 수행합니다.

프로젝트 전체 파일

src/expensekit/__init__.py 파일의 전체 내용입니다.

def total(amounts):
    if any(type(x) is not int or x < 0 for x in amounts):
        raise ValueError("invalid amount")
    return sum(amounts)

src/expensekit/cli.py 파일의 전체 내용입니다.

import argparse
from . import total

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("amounts", type=int, nargs="+")
    args = parser.parse_args()
    print(total(args.amounts))

if __name__ == "__main__":
    main()

pyproject.toml 파일의 전체 내용입니다.

[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"

[project]
name = "expensekit-demo"
version = "0.1.0"
description = "Local expense sum example"
requires-python = ">=3.12"

[project.scripts]
expense-total = "expensekit.cli:main"

[tool.setuptools.packages.find]
where = ["src"]

빌드하고 새 환경에 설치하기

pyproject.toml이 있는 폴더에서 빌드 도구를 설치하고 배포 파일을 만듭니다. 가상환경 경로는 프로젝트 소스와 분리해 관리합니다.

python -m pip install build
python -m build

dist에 wheel과 소스 배포 파일이 생성됩니다. 새 가상환경을 만들고 그 환경의 Python으로 아래 wheel을 설치합니다. 활성화하지 않았다면 Windows는 .venv-check\Scripts\python.exe, macOS·Ubuntu는 .venv-check/bin/python을 명시합니다.

python -m venv .venv-check

Windows PowerShell에서는 새 환경의 실행 파일로 설치합니다.

.\.venv-check\Scripts\python.exe -m pip install dist/expensekit_demo-0.1.0-py3-none-any.whl

macOS·Ubuntu에서는 다음 명령을 사용합니다.

.venv-check/bin/python -m pip install dist/expensekit_demo-0.1.0-py3-none-any.whl

위 마지막 명령의 python은 반드시 새 검증 환경의 Python이어야 합니다. 설치 뒤 프로젝트 밖의 새 폴더로 이동해 다음 동작을 확인합니다.

python -c "from expensekit import total; print(total([3500,8000,2500]))"
python -m expensekit.cli 3500 8000 2500

두 결과 모두 14000이어야 합니다. project.scripts는 expense-total 명령 별칭도 만듭니다. 해당 환경을 활성화한 터미널에서 별칭을 사용할 수 있으며, 별칭의 경로 또는 실행 문제가 있을 때는 위의 모듈 실행으로 같은 main 진입점을 호출할 수 있습니다.

설치 누락과 공개 배포의 추가 조건

소스 폴더에서만 import가 되고 밖에서는 실패한다면 실제 설치 환경·패키지 검색 설정·wheel 포함 파일을 확인합니다. 외부 의존성이 있다면 project.dependencies에 선언하고 Python 지원 범위와 맞는지 검증합니다. 개발 도구를 런타임 의존성으로 무조건 넣지 않습니다.

공개 배포에는 이름 충돌 확인, 라이선스·저자 정보, README, 포함 파일과 비밀정보 점검, 저장소 인증과 릴리스 정책이 추가로 필요합니다. 설치 검증이 끝났다는 이유로 자동으로 공개 업로드하지 않습니다.

Python 강좌