파이썬 프로젝트의 엔트리 포인트(Entry Point, 진입점)

 

 

파이썬을 공부하다보면 프로그램을 시작하는 부분은 그리 신경을 쓰지 않습니다.

그냥 코드를 작성해서 실행하거나.. 기껏해야 if __name__ == "__main__": 블록을 이용하게 됩니다.

사실 if __name__ == "__main__": 블록이 엔트리 포인트(Entry Point,진입점)로 사용되기 때문에 틀렸다거나 문제가 있는 것은 아닙니다만..

프로그래밍 작업에 참고하기 위하여 오픈소스 프로젝트 등을 살펴보다 보면 해당 코드 블록은 어딘가의 구석에 처박혀있고 프로젝트 루트에서는 잘 보이지 않는 경우가 많죠.

그래서 이번 포스트에서는 파이썬 프로젝트의 엔트리 포인트 지정 방법에 대하여 살펴보도록 하겠습니다.

 

파이썬 프로젝트에서 엔트리 포인트는 일반적으로 다음의 세 가지 방식으로 지정됩니다.

 

1. setup.py 또는 pyproject.toml

• 파이썬 프로젝트를 패키지로 배포할 때, setup.py 또는 pyproject.toml 파일을 이용하여 entry_points 또는 scripts 항목에서 명시적으로 지정합니다.
• 패키지의 경우 각 모듈 별로 다른 엔트리 포인트를 사용하는 일이 많기 때문에 이러한 방식을 사용합니다.
• 이 파일 자체가 엔트리 포인트는 아니며, 패키지의 메타데이터의 설치 방법, 그리고 실행 가능한 명령어(콘솔 스크립트) 등을 정의하고 있습니다.

 

2. main.py

• 폴더(패키지)의 내부에 __main__.py 파일을 저장해 두고 python -m "프로젝트명" 의 방식으로 실행할 때 사용합니다.
• main.py 파일이 바로 진입점, 즉 엔트리 포인트가 되는 것입니다.

 

3. 직접 실행되는 파일

• if __name__ == "__main__": 블록이 있는 파일이 엔트리 포인트가 됩니다.
• 흔히 if __name__ == "__main__": 블록이 있는 경우는 직접 실행하는 파일이 되고 없는 경우, 즉 패키지나 모듈의 구성 파일 어느 곳에도 해당 블록이 없는 경우에는 해당 모듈은 다른 모듈, 코드에서 import 하기 위해 작성된 모듈로 취급됩니다.

 

이처럼 다양한 방법으로 엔트리 포인트를 지정하여 사용하고 있는데, 2번과 3번의 경우는 많은 예제 코드에서 쉽게 접할 수 있기 때문에 여기에서는 1번 방식, 즉 setup.py 및 pyproject.toml을 사용하는 방법을 알아보겠습니다.

 

setup.py 

1. setup.py의 역할

 

setup.py 파일은 앞에서도 잠깐 언급한 것처럼 파이썬 프로젝트를 패키지화 하는데 중요한 역할을 하고 있습니다.

특히 다음과 같은 역할을 수행합니다.

• 프로젝트를 패키지로 만들어 배포할 수 있게 한다.
• 패키지의 메타 데이터(이름, 버전, 설명 등)를 정의한다.
• 의존성 패키지를 관리한다.
• 콘솔 명령어(엔트리 포인트를 가리킴)를 생성할 수 있도록 지정한다.

 

2. setup.py의 기본 구조와 엔트리 포인트 정의하기

 

setup.py 파일은 주로 setuptools 모듈의 setup() 함수를 사용하여 작성합니다.

포함되는 정보는 패키지의 이름, 버전, 작성자, 설명 등의 메타 데이터로 구성됩니다.

그리고 엔트리 포인트는 패키지 설치 시 콘솔에서 실행할 수 있는 명령어를 정의합니다.

 

from setuptools import setup, find_packages

setup(
    name="my_package",           # 패키지 이름
    version="0.1.0",             # 패키지 버전
    author="AiDA",               # 작성자
    author_email="aida@aidalab.com",     # 이메일
    description="간단한 패키지 설명",       # 간단한 설명
    long_description=open("README.md").read(),     # 상세 설명
    long_description_content_type="text/markdown", # 상세 설명 파일의 형태
    
    url="https://github.com/username/my_package",  # 프로젝트 URL
    
    # packages=find_packages(),    # 패키지 찾기 : 규모가 큰 프로젝트의 경우에 권장하는 방법
    py_modules=["my_module"],    # 패키지의 모듈 목록 : 규모가 작은 프로젝트의 경우
                                                 # 단일 모듈인 경우의 예시임(다중 모듈인 경우는 리스트 내용이 추가됨)
                                                 
    entry_points={  # 콘솔 스크립트 및 기타 진입점 정의
        "console_scripts": [
            "say-hello=my_module:say_hello",  # 명령어=모듈:함수
        ],
    },
    
    classifiers=[                # 패키지 분류 정보
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires=">=3.6",     # Python 버전 요구사항
    install_requires=[                 # 의존성 패키지 목록
        "requests>=2.25.0",
        "numpy>=1.19.0",
    ],

    package_data={		# 패키지에 포함될 데이터 파일        
        "my_package": ["*.txt", "*.rst"],		# my_package 패키지의 모든 .txt, .rst 파일 포함
        "my_package.data": ["*.json"],			# my_package/data 디렉토리의 모든 .json 파일 포함
        "my_package.templates": ["*.html"],		# my_package/templates 디렉토리의 모든 .html 파일 포함
        "my_package.static.images": ["*.png", "*.jpg", "*.gif"],		# my_package/static/images 디렉토리의 모든 이미지 파일 포함
    },
)

 

위의 예시 코드에서 지정한 엔트리 포인트는 "say-hello"라는 명령어를 생성하고, 이 명령어는 "my_module"의 "say_hello" 함수를 호출합니다.

그리고 매개변수 packages와 py_modules는 프로젝트의 규모, 모듈의 개수에 따라 선택하여 사용할 수 있습니다.

 

 

3. setup.py이 적용된 프로젝트의 일반적인 구조

 

 

 

4. 패키지의 빌드 및 설치

 

setup.py 파일을 작성하고 나면 패키지를 빌드하고 설치할 수 있게 됩니다.

패키지의 빌드 및 설치는 다음과 같은 명령어를 이용하여 수행할 수 있습니다.

# 소스 및 바이너리 배포 패키지 생성
python setup.py sdist bdist_wheel

# 패키지 설치
python setup.py install

 

 

이상의 방법으로 setup.py 파일을 패키지 관리 및 엔트리 포인트의 설정에 사용할 수 있습니다.

다음은 pyproject.toml을 사용하는 방식을 알아보겠습니다.

 

pyproject.toml 

1. pyproject.toml이란?

 

pyproject.toml 파일은 최신 파이썬 패키징 시스템의 핵심으로, setup.py를 대체하는 현대적인 방식이라고 할 수 있습니다.

pyproject.toml은 PEP 518에서 도입된 파이썬 프로젝트 설정 파일로, 프로젝트의 메타데이터와 의존성을 TOML 형식으로 관리하고 있으며, 이는 기존의 `setup.py`나 `requirements.txt`보다 더 체계적인 방식을 제공합니다.

아직 setup.py 방식을 유지하고 있는 프로젝트도 많이 있지만 서서히 pyproject.toml 파일을 사용하는 방식으로 바뀌고 있습니다.

 

pyproject.toml 방식의 장점은 다음과 같습니다.

 

• 통합된 프로젝트 설정: 메타데이터, 의존성, 빌드 시스템 등 모든 설정을 한 파일에서 관리할 수 있습니다.
• 개발 및 런타임 의존성 분리: 개발용과 배포용 의존성을 명확하게 구분할 수 있습니다.
• 다양한 빌드 시스템 지원: setuptools 외에도 poetry, hatch 등 다양한 빌드 시스템을 사용할 수 있습니다.
• 표준화된 형식: TOML 형식으로 일관된 구조를 제공합니다.

 

2. 기본 구조

 

(1) 빌드 시스템으로 setuptools을 사용할 경우

[build-system]								# 빌드 시스템을 명시적으로 지정할 수 있음
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "0.1.0"
description = "A sample Python project"
authors = [
    {name = "스카이", email = "example@example.com"}
]
readme = "README.md"
requires-python = ">=3.7"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.dependencies]
requests = "^2.25.1"

[project.optional-dependencies]
dev = [
    "pytest>=6.0",
    "black>=21.5b2",
]

[project.urls]
"Homepage" = "https://github.com/username/my_package"
"Bug Tracker" = "https://github.com/username/my_package/issues"

[project.scripts]
my-script = "my_package.cli:main"

 

 

(2) 빌드 시스템으로 Poetry를 사용할 경우

[tool.poetry]
name = "my_package"
version = "0.1.0"
description = "A sample Python project"
authors = ["스카이 <example@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.25.1"

[tool.poetry.dev-dependencies]
pytest = "^6.2.3"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

 

Poetry는 명령어를 통해 의존성 관리와 패키지 게시 등의 작업을 간편하게 수행할 수 있게 해 줍니다.

 

 

3. 패키지 빌드 및 배포

 

(1) 빌드 시스템으로 setuptools을 사용할 경우

# 빌드
python -m build

# PyPI에 배포
python -m twine upload dist/*

 

 

(2) 빌드 시스템으로 Poetry를 사용할 경우

# 빌드 및 배포
poetry build
poetry publish

 

 

4. setup.py와의 차이점

pyproject.toml은 setup.py의 모든 기능을 대체할 수 있으며, 더 현대적이고 명확한 구조를 제공합니다.

두 방식 사이의 주요 차이점은 다음과 같습니다.

 

• TOML 형식을 채택하여 더 읽기 쉬운 구조를 가집니다.
• 빌드 시스템을 명시적으로 지정할 수 있습니다.
• 개발 및 런타임 의존성에 대한 정보를 명확하게 분리할 수 있습니다.
• 다양한 도구(black, pytest 등)의 설정을 한 파일에 통합할 수 있습니다.

 

 

pyproject.toml의 도입을 제안하는 PEP 518은 파이썬 소프트웨어 패키지가 빌드 시스템을 실행하기 위한 최소 빌드 시스템 요구사항을 어떻게 명시해야 하는지를 정의한 파이썬 표준 제안을 말합니다. (PEP: Python Enhancement Proposal)

PEP 518로 인하여 pip 19버전부터는 더 이상 setup.py만을 사용해 패키지를 빌드할 필요가 없어지고, 다양한 빌드 시스템을 유연하게 선택할 수 있게 되었습니다.

 

아직 setup.py 방식을 유지하고 있는 프로젝트도 많지만 pyproject.toml 방식에 어떤 문제가 있어서라기보다 기존의 시스템을 바꾸는 작업에 따른 부담, 새로운 방식의 도입에 따르는 학습 내용의 증가 등을 피하고자 하는 이유가 많은 편입니다.

물론 pyproject.toml 방식이 완벽한 것은 아니지만 기존 방식을 많이 개선하고, 또 새 방식의 도입 사례가 증가하고 있는만큼 새로운 프로젝트를 시작한다면, `setup.py` 대신 `pyproject.toml`을 사용할 것을 권장하고 있습니다.

특히 Poetry와 같은 현대적인 의존성 관리 도구와 함께 사용한다면 프로젝트의 관리가 훨씬 편리해질 것으로 보입니다.

 

 

여기까지 해서 파이썬 프로젝트의 엔트리 포인트 지정 방법에 대하여 살펴보았습니다.

파이썬 프로젝트를 위해서는 기본적으로 알아야 하는 내용이면서도 단순히 책과 같은 교재로 실습만 하고 본격적인 배포용 파이썬 프로젝트를 진행해보지 않았다면 사실 알기 어려운 내용이기도 합니다.

학습의 범위를 벗어나 제대로 개발 작업을 하기 위해서는 알아야 할 더 많은 것들이 있다는 것을 새삼 느끼게 하네요.