Python Academy · 강의

프로젝트 구조와 pyproject.toml

Q: “프로젝트 구조와 pyproject.toml” 강의는 무료인가요?

네 — “프로젝트 구조와 pyproject.toml” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Python Academy 강의 전체를 잠금 해제할 수 있습니다. Python Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

Q: “프로젝트 구조와 pyproject.toml”에서 뭘 배우나요?

패키지 구성하기 브라우저에서 직접 실행하는 실습 코드로 Python Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Q: Python Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Python Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

Q: “프로젝트 구조와 pyproject.toml” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

Q: 이 Python Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Python Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

패키지 구성하기

프로젝트 구조와 pyproject.toml은(는) CoddyKit의 무료 Python Academy 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Python Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Python Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

코드를 패키지로 만드는 이유

스크립트는 자신의 컴퓨터에서 실행되지만, 패키지는 pip install을 사용할 수 있는 누구나 설치할 수 있습니다. 패키징을 하면 코드가 들어 있는 폴더가 배포 가능하고 버전 관리되며 재사용 가능한 단위로 바뀝니다.

첫 단계는 깔끔한 프로젝트 구조와 설정 파일을 마련하는 것입니다.

src 구조

권장 구조에서는 가져올 수 있는 코드를 src/ 디렉터리 아래에 둡니다.

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.md 및 tests/

src 구조를 사용하면 프로젝트 루트의 코드가 아니라 설치된 복사본을 실수로 가져오는 일을 막을 수 있습니다.

init.py 파일

__init__.py는 디렉터리를 가져올 수 있는 패키지로 표시하며, 패키지를 처음 가져올 때 실행됩니다. 주요 이름을 가져와 공개 API를 노출하는 곳이기도 합니다.

내용이 비어 있는 __init__.py만으로도 패키지를 만들 수 있습니다.

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

pyproject.toml이란

pyproject.toml은 최신 파이썬 패키징을 위한 단일 표준 설정 파일(PEP 518/621)입니다. 대부분의 프로젝트에서 기존의 setup.py를 대신하며, 빌드 도구가 이 파일을 읽습니다.

이 파일은 대괄호로 묶은 섹션과 키 = 값 형식의 줄을 사용하는 TOML 형식입니다.

build-system 테이블

[build-system] 테이블은 도구에 패키지를 빌드하는 방법을 알려 줍니다. 일반적인 선택은 다음과 같습니다.

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

다른 백엔드로는 Hatchling과 Flit이 있지만, 기본 개념은 같습니다.

project 테이블

[project] 테이블에는 name, version, description, authors, readme, requires-python, dependencies와 같은 메타데이터가 들어 있습니다. 사용자가 PyPI에서 보는 정보가 바로 이것입니다.

패키지의 신분증이라고 생각하면 됩니다.

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

이름 지정 규칙

패키지 이름은 PyPI에서 고유해야 하며 정규화 규칙을 따릅니다. 대소문자를 구분하지 않고, 하이픈과 밑줄을 같은 것으로 취급합니다. 업로드할 때 이름이 충돌하지 않도록 이름을 확정하기 전에 사용 가능 여부를 확인하세요.

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

종속성 선언하기

실행 시 필요한 종속성은 dependencies 아래에 'requests>=2.28,<3'와 같은 버전 제약 조건과 함께 나열합니다. 선택적 추가 기능은 [project.optional-dependencies] 아래에 넣으며, pip install mytool[dev]로 설치할 수 있습니다.

패키지가 다른 패키지와 함께 사용할 수 있도록 안전한 범위에서 제약 조건을 최대한 느슨하게 유지하세요.

진입점

명령줄 도구를 배포하려면 [project.scripts]에 mytool = 'mypackage.cli:main'과 같은 항목을 추가합니다. 설치한 후 mytool을 입력하면 해당 함수가 실행됩니다. black이나 pytest 같은 명령줄 인터페이스가 명령을 제공하는 방식도 이와 같습니다.

코드가 아닌 파일 포함하기

데이터 파일(템플릿, JSON)은 자동으로 포함되지 않습니다. 빌드 백엔드에서 패키지 데이터를 설정하여 파일이 휠 안에 포함되도록 해야 합니다. 이 설정을 잊으면 로컬에서는 작동하지만 설치 후에는 오류가 나는 문제가 흔히 발생합니다.

개발을 위한 편집 가능 설치

개발하는 동안에는 pip install -e .을 사용해 패키지를 편집 가능 모드로 설치합니다. 소스의 변경 사항이 다시 설치하지 않아도 즉시 적용됩니다. 이를 위해서는 올바른 pyproject.toml이 필요하므로, 일찍 설정해야 하는 또 다른 이유가 됩니다.

패키지를 반복적으로 수정할 때 편집 가능 설치는 가장 빠른 피드백 순환을 제공합니다.

빠른 확인

프로젝트 구조 지식을 테스트해 보세요.

요약

패키지 구조를 구성했습니다.

src 구조를 사용하고 __init__.py로 패키지를 표시합니다
pyproject.toml은 표준 설정 파일이며 [build-system]과 [project]를 포함합니다
name, version, requires-python, dependencies를 선언합니다
명령줄 인터페이스를 위한 [project.scripts] 진입점을 추가하고 패키지 데이터를 설정합니다

자주 묻는 질문