[PYTHON] 파이썬 패키지 만들기 : 기획부터 PyPI 배포까지 완벽 정복

[PYTHON] 파이썬 패키지 만들기

 

 

많은 개발자들이 파이썬으로 유용한 기능을 구현하지만, 이를 재사용 가능한 패키지로 구성하지 못하는 경우가 많다. 단순한 스크립트를 넘어서, 다른 개발자와 공유 가능한 구조화된 파이썬 패키지를 만드는 것은 개발자로서의 역량을 한 단계 끌어올리는 중요한 경험이다. 본 글에서는 실무에서 바로 활용 가능한 Python 패키지를 직접 설계하고, PyPI(Python Package Index)에 배포하는 방법까지 단계별로 안내한다. 오픈소스에 기여하거나 내부 라이브러리를 배포하고 싶은 개발자에게 실질적인 가치를 제공한다.

1. Python 패키지란?

파이썬에서 패키지는 관련 모듈을 논리적으로 묶은 디렉토리 구조를 의미한다. 외부에서 import mypackage와 같이 호출할 수 있으며, 코드 재사용성과 유지보수성을 극대화할 수 있다.

• 단일 기능 모듈 → 패키지로 확장 가능
• 복잡한 프로젝트를 계층적으로 정리 가능
• PyPI에 등록하여 전 세계 개발자와 공유 가능

2. 기본 디렉토리 구조

my_package/
├── my_package/
│   ├── __init__.py
│   ├── core.py
│   └── utils.py
├── tests/
│   └── test_core.py
├── README.md
├── LICENSE
├── setup.py
└── pyproject.toml
  

위 구조는 PyPI 업로드 기준에 맞는 가장 기본적인 구성이다. __init__.py는 해당 디렉토리가 패키지임을 알리는 역할을 하며, setup.py와 pyproject.toml은 패키징 및 설치 메타정보를 정의한다.

3. setup.py 설정하기

from setuptools import setup, find_packages

setup(
    name='my-package',
    version='0.1.0',
    author='홍길동',
    author_email='hong@example.com',
    description='텍스트 분석을 위한 유틸리티',
    long_description=open('README.md').read(),
    long_description_content_type='text/markdown',
    url='https://github.com/hong/my-package',
    packages=find_packages(),
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
    ],
    python_requires='>=3.7',
    install_requires=[
        'numpy',
        'pandas'
    ],
)
  

핵심 포인트: 패키지 이름과 버전, 의존 라이브러리, README 설명을 명확히 작성해야 한다.

4. pyproject.toml 구성하기

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"
  

pyproject.toml은 최신 패키지 표준(PEP 518)을 따르기 위해 필수적이다. 빌드 도구를 명시적으로 지정하고, pip이나 build 명령어가 이 정보를 읽어 패키징을 수행한다.

5. README와 LICENSE 작성

• README.md: 사용법, 설치법, 기능 소개 포함
• LICENSE: 오픈소스 사용 조건 명시 (MIT, Apache 2.0 등)

팁: Markdown 기반으로 작성하면 PyPI에서 깔끔하게 렌더링된다.

6. 테스트 코드 작성

# tests/test_core.py
import unittest
from my_package import core

class TestCore(unittest.TestCase):
    def test_add(self):
        self.assertEqual(core.add(2, 3), 5)
  

테스트는 unittest 또는 pytest로 작성 가능하며, 패키징 전 반드시 모든 테스트가 통과하도록 구성해야 한다.

7. 패키징 및 PyPI 배포

pip install build twine
python -m build
python -m twine upload dist/*
  

• python -m build: wheel(.whl)과 sdist(.tar.gz) 생성
• twine upload: PyPI 계정으로 업로드

주의: 업로드 전에 dist, build, *.egg-info 디렉토리를 항상 삭제하고 재생성하는 것이 권장된다.

8. PyPI 배포용 계정 만들기

PyPI (https://pypi.org)에서 무료 계정을 만들고, .pypirc 파일에 인증 정보를 저장하면 이후 업로드 과정이 간편해진다.

[pypi]
username = __token__
password = pypi-xxxxxx...
  

9. 주요 비교 요약표

구성 요소	설명	필수 여부
setup.py	패키지 메타데이터 및 빌드 정의	필수
pyproject.toml	빌드 시스템 정의 (PEP 518)	권장
__init__.py	패키지 인식 파일	필수
README.md	사용자 가이드 및 설명서	권장
LICENSE	오픈소스 라이선스 명시	권장

10. 실무 팁

• 의존성 관리: 가급적 requirements.txt와 분리하여, 최소 의존성만 install_requires에 포함
• 버전 관리: __version__을 패키지 최상단에 명시하고, setup.py와 연동
• 패키지명 유일성 확보: PyPI 등록 전 검색으로 중복 확인
• 도커와 연계: 배포 패키지를 도커 이미지에 포함시켜 테스트 가능

결론: 코드의 품질은 구조에서 나온다

파이썬 패키지화는 단순히 코드를 묶는 수준이 아닌, 코드의 철학과 유지보수성을 담는 작업이다. 일회용 스크립트를 넘어, 구조화된 패키지를 만드는 습관은 당신을 ‘개발자’가 아닌 ‘소프트웨어 엔지니어’로 거듭나게 할 것이다. 시작은 작게, 구조는 단단하게. 이제 여러분도 PyPI에 이름을 올릴 준비가 되었다.

---

출처 (References)

• Python Packaging Authority
• Python Docs - setup.py
• Real Python - Publish Package to PyPI