파이썬 프로젝트 만들기 — 졸업작

26편의 도구가 다 모이는 자리. 1편의 파이썬 설치부터 26편의 자동 포맷까지 — 27편을 거치며 본인은 이미 "한 폴더짜리 진짜 프로젝트" 를 만들 준비가 끝났습니다. 27편은 그 도구들을 한 자리에 묶어 GitHub 에 올릴 수 있는 결과물을 만들고, 입문서 졸업 인증을 합니다.

27편을 마치면 ① 권장 폴더 구조(src 레이아웃) ② pyproject.toml 완성형 ③ CLI 진입점 ④ 테스트·README·라이선스 ⑤ GitHub Actions CI ⑥ 앞으로의 학습 — 이게 진짜 시작점입니다.

권장 폴더 구조 — src 레이아웃

myapp/
├── src/
│   └── myapp/
│       ├── __init__.py
│       ├── cli.py
│       └── core.py
├── tests/
│   ├── __init__.py
│   └── test_core.py
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── .pre-commit-config.yaml
└── .github/
    └── workflows/
        └── ci.yml

src 레이아웃 의 핵심 — 코드를 src/패키지명/ 안에. 테스트가 실수로 설치 안 된 로컬 모듈을 import 하는 사고를 막아주고, 패키징도 깔끔. 2026년 신규 프로젝트의 표준입니다.

pyproject.toml — 한 파일에 모든 설정

# pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "myapp"
version = "0.1.0"
description = "주제 한 줄 설명"
readme = "README.md"
requires-python = ">=3.12"
license = {text = "MIT"}
authors = [{name = "준성", email = "[email protected]"}]
dependencies = [
    "requests>=2.31",
    "pandas>=2.2",
]

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

[project.scripts]
myapp = "myapp.cli:main"           # CLI 명령어 등록

[tool.ruff]
line-length = 100
target-version = "py312"
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--cov=src/myapp --cov-report=term-missing"

옛 setup.py + setup.cfg + requirements.txt + pytest.ini 가 이 한 파일로 통합. 의존성·메타데이터·도구 설정·CLI 진입점이 한 자리.

# 개발 설치 — 코드 수정이 즉시 반영
(.venv) $ pip install -e ".[dev]"

# 그러면 어디서든 명령 실행 가능
$ myapp --help
$ pytest
$ ruff check .

CLI 진입점 — myapp 명령으로 실행

# src/myapp/cli.py
import argparse
import logging
from .core import process

def main() -> int:
    ap = argparse.ArgumentParser(prog="myapp")
    ap.add_argument("input", help="입력 파일")
    ap.add_argument("-o", "--out", default="output.csv")
    ap.add_argument("-v", "--verbose", action="store_true")
    args = ap.parse_args()

    logging.basicConfig(
        level=logging.DEBUG if args.verbose else logging.INFO,
        format="%(asctime)s [%(levelname)s] %(message)s",
    )

    n = process(args.input, args.out)
    print(f"처리 완료: {n} 건")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

pyproject.toml 의 [project.scripts] 가 이 함수를 myapp 명령으로 등록. 설치한 사람은 myapp data.csv -o out.csv 한 줄로 실행. 22편의 자동화 스크립트가 정식 도구로 진화하는 자리입니다.

README·LICENSE·.gitignore

# README.md — 누구나 5분에 시작할 수 있게
# myapp

CSV 매출 데이터를 일자별 합계로 요약합니다.

## 설치
$ pip install -e ".[dev]"

## 사용
$ myapp sales.csv -o summary.csv

## 개발
$ pytest
$ ruff check . && ruff format .

## 라이선스
MIT (LICENSE 파일 참조)

# .gitignore — 깃에 안 올라가야 할 것들
.venv/
__pycache__/
*.pyc
.pytest_cache/
.ruff_cache/
.coverage
htmlcov/
dist/
build/
*.egg-info/
.env

GitHub Actions CI — 자동 검증

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install -e ".[dev]"
      - run: ruff check .
      - run: ruff format --check .
      - run: pytest

PR 마다 자동으로 ① 의존성 설치 ② 린트 ③ 포맷 확인 ④ 테스트 실행. 빨간 X 면 머지 못 함. 본인 혼자 작업하더라도 6개월 뒤 본인을 구합니다.

27편 졸업 + 앞으로의 길

27편을 끝낸 본인은 이제 혼자 작은 도구를 만들고 GitHub 에 공개할 수 있습니다. 매출 리포트 자동 생성기, 웹 크롤러, API 라우터, 데이터 정리 CLI — 본인 회사에서 한 번씩 마주칠 잡일을 한 주 안에 코드로 만들 수 있어요.

한 갈래를 골라 작은 프로젝트를 한 달에 하나씩 6개월 만들면 본인 GitHub 가 곧 이력서. 어디서든 통합니다.

27편 시리즈를 끝까지 읽어주셔서 감사합니다. 본인의 첫 GitHub 프로젝트가 곧 다음 글의 영감이 됩니다 — 본인이 만든 도구·삽질·교훈을 다시 글로 적으면 그게 28편이 돼요. 학습은 만드는 것에서 끝나지 않고, 가르치는 것에서 비로소 완성됩니다.