도구
로그인
한국어

코드 배우기파이썬

파이썬 프로젝트 구조 잡기

파이썬 3.12 기준

파이썬 src 배치·pyproject.toml·venv·uv·tests 뼈대를 골라 zip 으로 받아요.

프로젝트 뼈대 만들기

만들 것과 꾸러미 도구(pip 또는 uv)를 고르면 폴더 나무·파일마다 하는 일·계층 그림이 바뀌어요. 파일을 누르면 시작 코드가 보이고, zip 으로 받아 돌려 봐요.

만들 것
꾸러미 도구
테스트

폴더 나무 파일 8개

  • src/hello_app/
  • tests/

src/hello_app/__main__.py

python -m 으로 돌릴 때의 시작점이에요. argparse 로 인수를 읽어 규칙 함수에 넘기고 결과만 찍어요. 규칙은 여기 두지 않아요.

import argparseimport sys from .greeting import make_greeting def main(argv=None):    parser = argparse.ArgumentParser(prog="hello-app", description="Say hello")    parser.add_argument("name", nargs="?", default="world")    parser.add_argument("--shout", action="store_true", help="print in capitals")    args = parser.parse_args(argv)    try:        text = make_greeting(args.name, shout=args.shout)    except ValueError as e:        print(f"error: {e}", file=sys.stderr)        return 2    print(text)    return 0 if __name__ == "__main__":    sys.exit(main())

계층 그림

적어 둔 버전 Python 3.10+ · pytest 8 · setuptools 68 이상(pip) · hatchling(uv). 꾸러미 파일은 zip 에 넣지 않았어요. pip 나 uv 가 처음 설치할 때 받아요.

src 배치 표준 폴더

자리들어가는 것
src/<패키지>/프로그램 코드. import <패키지> 로 부르는 이름이 폴더 이름이에요.
__init__.py패키지 폴더 안에 두는 파일. 이 폴더가 패키지라는 표시이고, 밖에 보여 줄 이름을 여기서 가져와 둬요.
__main__.py역시 패키지 폴더 안. python -m <패키지> 로 실행할 때 처음 도는 파일.
tests/테스트 코드(pytest). 배포 꾸러미에는 들어가지 않아요.
pyproject.toml프로젝트 이름·버전·필요한 파이썬 버전·의존 꾸러미·빌드 방법을 적는 파일.
.venv/이 프로젝트만 사용하는 가상환경. 내 컴퓨터에서 만들고 git 에는 올리지 않아요.

코드를 src/ 아래에 두면 설치한 패키지로만 불러와서 "내 컴퓨터에서만 되는" 일을 줄여요. 테스트도 설치된 모습으로 시험해요.

계층 나누기

요청을 받는 곳, 규칙을 판단하는 곳, 자료를 넣고 꺼내는 곳을 다른 모듈에 둬요. 웹 API 라면 api.py → service.py → repository.py 차례로 부르고, 거꾸로는 부르지 않아요.

이렇게 나누면 저장소를 메모리에서 DB 로 바꿔도 서비스 코드는 그대로이고, 서비스 규칙은 서버를 띄우지 않고 pytest 로 시험해요.

  • api.py 는 요청을 읽고 응답을 만들 뿐 계산하지 않아요.
  • service.py 는 규칙을 판단해요. HTTP 가 무엇인지 몰라요.
  • repository.py 는 저장하고 꺼내요. typing.Protocol 로 꼴을 정해 두면 메모리·DB 구현을 바꿔 끼워요.

이름 짓기

프로젝트 이름(pyproject 의 name)은 hello-app 처럼 - 를 사용해도 되지만, 패키지(폴더) 이름은 import 해야 하니 hello_app 처럼 밑줄을 사용해요.

  • 모듈·패키지·함수·변수는 소문자와 밑줄(snake_case), 클래스는 CapWords 로 써요.
  • json.py, random.py, test.py 처럼 표준 라이브러리와 같은 이름의 파일을 만들지 마세요. 내 파일이 먼저 불려 와서 이상한 오류가 나요.
  • 비밀번호·API 키는 코드에 적지 말고 환경 변수(os.environ)로 받아요.

자주 사용하는 설계 꼴 넷과 의존성 주입

파이썬은 함수를 값처럼 넘길 수 있어서 클래스를 덜 사용해도 되는 꼴이 많아요. 모두 Python 3.12 로 돌려 본 코드예요.

싱글톤 · 하나만 있어야 할 때

__new__ 에서 처음 만든 객체를 기억해 두고 다음부터는 그것을 돌려줘요. a 와 b 는 같은 객체라 b 로 바꾼 값이 a 에서도 보여요.

파이썬에서는 모듈 자체가 한 번만 불려 오기 때문에, 모듈 안에 객체 하나를 만들어 두고 가져다 사용하는 쪽이 더 흔하고 간단해요.

class Settings:    _one = None     def __new__(cls):        if cls._one is None:            cls._one = super().__new__(cls)            cls._one.mode = "production"        return cls._one  a = Settings()b = Settings()b.mode = "test"print(a is b)print(a.mode)

실행 결과

Truetest

팩토리 · 무엇을 만들지 한 곳에서 정할 때

확장자를 보고 알맞은 읽기 함수를 골라 줘요. 함수를 사전에 담아 두면 새 형식은 사전에 한 줄만 더하면 돼요. 대소문자도 여기서 한 번에 맞춰요.

import json  def parse_csv(text):    return text.strip().split(",")  def parse_json(text):    return list(json.loads(text).values())  PARSERS = {"csv": parse_csv, "json": parse_json}  def parser_for(filename):    ext = filename.rsplit(".", 1)[-1].lower()    if ext not in PARSERS:        raise ValueError(f"no parser for .{ext}")    return PARSERS[ext]  print(parser_for("users.CSV")("lee,29,busan"))print(parser_for("user.json")('{"name": "lee", "age": 29}'))

실행 결과

['lee', '29', 'busan']['lee', 29]

전략 · 바꿔 끼우는 계산 방법

할인 규칙을 함수로 만들어 Checkout 에 넘겨요. 파이썬에서는 함수가 곧 값이라 전략마다 클래스를 만들 필요가 없어요. coupon(3000) 처럼 설정이 필요한 규칙은 함수를 돌려주는 함수로 만들어요.

def no_discount(price):    return price  def member(price):    return round(price * 0.9)  def coupon(amount):    return lambda price: max(0, price - amount)  class Checkout:    def __init__(self, rule=no_discount):        self.rule = rule     def total(self, prices):        return self.rule(sum(prices))  cart = [12000, 8000]for rule in (no_discount, member, coupon(3000)):    print(Checkout(rule).total(cart))

실행 결과

200001800017000

옵서버 · 일이 생기면 알려 주기

재입고 같은 일이 생기면 등록해 둔 함수들을 차례로 불러요. 받는 쪽은 람다든 list.append 같은 보통 메서드든 상관없어요.

class Shelf:    def __init__(self):        self.listeners = []     def subscribe(self, fn):        self.listeners.append(fn)     def restock(self, item):        for fn in self.listeners:            fn(item)  log = []shelf = Shelf()shelf.subscribe(lambda item: print(f"Text: {item} is back"))shelf.subscribe(log.append)shelf.restock("mouse")print("Log:", log)

실행 결과

Text: mouse is backLog: ['mouse']

의존성 주입 · 필요한 것을 생성자로 받기

Greeter 는 사용자 저장소를 스스로 만들지 않고 생성자로 받아요. 실행할 때는 MemoryUsers 를, 시험에서는 find() 만 가진 FakeUsers 를 넣어요. 물려받지 않아도 덕 타이핑으로 맞아요.

FastAPI 의 Depends 같은 기능도 결국 이렇게 필요한 객체를 찾아 넣는 일을 해요.

class MemoryUsers:    def __init__(self):        self.names = {1: "Hana"}     def find(self, user_id):        return self.names.get(user_id)  class Greeter:    def __init__(self, users):        self.users = users     def greet(self, user_id):        name = self.users.find(user_id) or "guest"        return f"Hi, {name}"  class FakeUsers:    def find(self, user_id):        return "Tester"  app = Greeter(MemoryUsers())print(app.greet(1))print(app.greet(7))print(Greeter(FakeUsers()).greet(1))

실행 결과

Hi, HanaHi, guestHi, Tester

확인 문제

문제 1

git 에 올리지 않는 폴더는?

답과 까닭 보기

답: 3. .venv/ .venv/ 는 내 컴퓨터에 깔린 꾸러미가 들어 있는 가상환경이라 사람마다 다시 만들어요. .gitignore 에 넣어 둬요.

문제 2

src 배치 패키지 hello_app 을 설치한 뒤 실행하는 알맞은 명령은?

답과 까닭 보기

답: 3. python -m hello_app python -m 패키지 는 설치된 패키지의 __main__.py 를 돌려요. 파일 경로로 돌리면 패키지 안의 from . import 같은 상대 가져오기가 깨져요. 버전이 정해진 .venv 안에서 돌려요.

자주 묻는 것

requirements.txt 와 pyproject.toml 은 뭐가 다른가요?

pyproject.toml 은 프로젝트 이름·버전·필요한 꾸러미를 적는 표준 파일이에요. requirements.txt 는 pip 로 한 번에 설치할 목록이라 버전을 하나로 정해 적을 때 사용해요.

가상환경(venv)은 만들어야 하나요?

프로젝트마다 꾸러미 버전이 달라도 서로 부딪히지 않아요. python -m venv .venv 로 만들고, .venv 는 git 에 올리지 않아요.

uv 와 pip 중 무엇을 고르나요?

pip 는 파이썬에 들어 있어 따로 깔 게 없어요. uv 는 따로 설치해야 하지만 가상환경 만들기·설치·잠금 파일을 한 도구로 하고 pip 보다 빨라요.