[Python 시리즈 19편] 표준 라이브러리 탐색과 패키징 기초

비동기까지 다루었다면, 이제 Python이 기본으로 제공하는 표준 라이브러리와 배포 흐름을 둘러볼 차례입니다. "표준 라이브러리"와 "패키징"이라는 말이 거창해 보여도, 사실은 "이미 포함된 모듈 골라 쓰기"와 "폴더를 압축해 나누기"에 가깝습니다. 이번 글은 필수 도구→pyproject 정리→빌드 순서로 부담을 낮췄습니다.

이번 글에서 새로 나오는 용어

표준 라이브러리: Python이 기본으로 제공하는 모듈 묶음으로 추가 설치 없이 사용할 수 있음
wheel: 빌드가 끝난 상태로 배포되는 .whl 파일 형식의 패키지
sdist: 소스 배포본으로 사용자가 설치할 때 빌드를 다시 수행하는 .tar.gz 아카이브
uv build: pyproject 기반 프로젝트에서 wheel과 sdist를 한 번에 만들어 주는 명령

개념 정리

학습 메모

소요 시간: 80~90분(선택 확장 제외)

준비물: pyproject·uv 경험, 테스트·로깅 세팅, CLI 작성 경험

학습 목표: 표준 모듈 2~3개를 프로젝트에 적용하고 uv build까지 따라 해 배포 준비 흐름 익히기

표준 라이브러리는 Python이 기본으로 제공하는 모듈 묶음입니다.
pyproject.toml은 프로젝트 메타데이터와 의존성을 기록하는 공식 파일입니다.
uv build는 wheel·sdist를 만들어 배포 준비를 돕습니다.
wheel은 사전 빌드된 패키지이고 sdist는 소스 배포본입니다.
Core 파트에서 필수 도구만 익히고, Optional 표시가 있는 섹션은 필요할 때 참고하세요.

코드로 이해하기

꼭 알아둘 표준 모듈 (Core)

pathlib: 경로를 객체로 다룹니다.

from pathlib import Path

project_root = Path(__file__).parent
for path in project_root.glob("*.md"):
    print(path.stem)

dataclasses: 반복적인 초기화 코드를 줄입니다.

from dataclasses import dataclass


@dataclass
class Report:
    title: str
    data: list[dict]

datetime: 시간대·기간 계산을 처리합니다. zoneinfo와 함께 사용하면 표준 타임존을 적용할 수 있습니다.
collections: Counter, defaultdict, deque 등 자료구조를 제공합니다.
logging: 일관된 로그 출력 포맷을 제공합니다.

pyproject.toml 구조 리뷰 (Core)

이전에 Typer CLI에서 살짝 다뤘던 pyproject.toml을 정식으로 살펴봅니다.

[project]
name = "mealbot"
version = "0.1.0"
description = "급식 알림 CLI"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
  "typer",
  "httpx",
]

[project.optional-dependencies]
dev = ["mypy", "pytest"]

[project.urls]
homepage = "https://example.com"

project 섹션은 PEP 621 형식으로 메타데이터를 정의합니다.
optional-dependencies를 통해 pip install mealbot[dev]처럼 선택적 그룹을 설치할 수 있습니다.
혹시 모든 필드를 채우기 부담스럽다면 name, version, dependencies 세 줄부터 적고 나머지는 천천히 추가하세요.

빌드와 배포 흐름 (Core → Plus)

최근에는 uv, hatch, pdm 등 다양한 빌드 프런트엔드가 존재하지만, 핵심 흐름은 동일합니다.

uv build  # wheel, sdist 생성
uv publish --token $PYPI_TOKEN

wheel 파일은 바이너리 패키지, sdist는 소스 배포본입니다.
프라이빗 배포라면 사내 패키지 인덱스나 Git URL을 사용할 수도 있습니다.
"build"라는 단어가 어렵다면, 단순히 dist/ 폴더 안에 압축 파일 두 개를 만드는 작업이라고 생각하면 부담이 줄어듭니다.

direction: right

code: "src/
테스트 통과"
pyproject: "pyproject.toml
메타데이터"
build: "uv build
wheel/sdist"
dist: "dist/
.whl .tar.gz"
publish: "uv publish
PyPI/TestPyPI"

code -> pyproject: "버전·의존성 기록"
pyproject -> build: "빌드 설정"
build -> dist: "결과 파일 생성"
dist -> publish: "업로드"
publish -> code: "다음 릴리스에 피드백"

시각화를 참고하면 "코드를 정리→메타데이터 작성→빌드→배포" 단계가 명확히 끊어져 있어 체크리스트로 옮기기도 쉽습니다.

표준 라이브러리만으로 CLI 배포하기 (Optional)



def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("school_code")
    args = parser.parse_args()
    print(args.school_code)


if __name__ == "__main__":
    main()

Typer 같은 프레임워크 없이도 argparse, logging, pathlib 조합만으로 손쉬운 CLI를 만들 수 있습니다. 필요하면 zipapp으로 단일 실행 파일을 만들 수도 있습니다. 이미 Typer를 쓰고 있다면 이 예시는 참고용으로만 읽어도 됩니다.

배포 체크리스트 (Optional)

python -m build 또는 uv build로 패키지 생성
uvx twine check dist/*로 메타데이터 검증
TestPyPI에 먼저 업로드하고 설치 테스트
README, 예제, 라이선스 포함 여부 확인

왜 중요할까

표준 라이브러리를 충분히 활용하면 의존성을 줄이고 유지보수를 쉽게 할 수 있습니다.
pyproject.toml은 패키지 메타데이터의 공식 저장소입니다.
빌드·배포 과정을 스크립트나 CI로 자동화하면 품질이 일정해집니다.

실습

따라 하기: pathlib, dataclasses, argparse 중 두 가지 이상을 사용해 작은 CLI를 만들고 uv run으로 실행합니다.
확장하기: pyproject.toml에 optional-dependencies를 추가하고 uv build까지 수행해 dist/에 생성된 파일을 확인합니다.
디버깅: uv build 후 uvx twine check에서 경고를 일부러 만들어 보고, 메타데이터(설명, readme 링크)를 채워 해결합니다.
완료 기준: 표준 모듈 활용 예제와 빌드 로그를 모두 남겼고 선택 확장 섹션은 필요 시 따로 연습할 항목으로 정리했을 때입니다.

마무리

마지막 편에서는 지금까지 배운 문법을 모아 작은 프로젝트를 완성하고 발전 방법을 제안합니다.