김신건의 로그 - 위키 / python

[Python] asyncio: 비동기 프로그래밍

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

asyncio 는 Python 의 표준 비동기 I/O 라이브러리 (3.4+). event loop 위에서 coroutine 을 스케줄링. async def 로 정의한 함수가 코루틴이 되고, await 키워드로 제어권을 이벤트 루프에 돌려준다.

단일 스레드이지만 I/O 대기 중 다른 코루틴을 실행해 높은 동시성을 달성한다. CPU 집약적 작업에는 적합하지 않다.

사용 상황

상황	asyncio	대안
네트워크 요청 다수 병렬 처리	✅	-
DB 쿼리 동시 실행	✅	-
WebSocket / 스트리밍 서버	✅	-
CPU 집약 계산	❌	[[py-multiprocessing]]
블로킹 파일 I/O	주의	aiofiles 또는 executor
스레드 기반 동시성	선택	[[py-threading]]

이벤트 루프 메커니즘

flowchart TD
    A["asyncio.run()으로 시작"] --> B[이벤트 루프 생성]
    B --> C[실행 가능한 코루틴 선택]
    C --> D{await 도달?}
    D -->|아직 없음| E[코루틴 계속 실행]
    D -->|I/O await| F[코루틴 일시 정지]
    D -->|sleep await| G[타이머 등록 후 반환]
    E --> H[코루틴 완료]
    F --> I[I/O 완료 시 재개]
    G --> I
    I --> C
    H --> J{더 실행할 Task?}
    J -->|있음| C
    J -->|없음| K[이벤트 루프 종료]

핵심: 이벤트 루프는 단일 스레드. 코루틴은 await 지점에서만 제어권을 넘긴다. 블로킹 호출이 하나라도 있으면 전체 루프가 멈춘다.

기본

import asyncio

async def fetch(url):
    await asyncio.sleep(1)
    return f"result for {url}"

async def main():
    result = await fetch("https://example.com")
    print(result)

asyncio.run(main())

asyncio.run() 은 새 이벤트 루프를 만들고, 전달한 코루틴이 끝나면 루프를 닫는다. 프로그램 진입점에서 한 번만 호출해야 한다.

병렬 실행

gather

async def main():
    results = await asyncio.gather(
        fetch("url1"),
        fetch("url2"),
        fetch("url3"),
    )
    # results = [res1, res2, res3]

세 요청이 병렬 실행. 결과 순서는 인자 순서와 동일. 하나가 예외를 던지면 다른 Task 는 취소되지 않는다 (return_exceptions=True 옵션으로 예외를 결과에 포함 가능).

as_completed

async def main():
    tasks = [fetch(u) for u in urls]
    for future in asyncio.as_completed(tasks):
        result = await future
        print(result)  # 완료된 순서

완료 순서가 중요할 때 사용.

Task 생성과 생명주기

flowchart LR
    A["create_task()"] --> B[실행 대기]
    B --> C[실행 중]
    C --> D[I/O 대기]
    D --> B
    C --> E[완료]
    C --> F[취소됨]
    D --> F

task = asyncio.create_task(fetch(url))
# ...다른 일...
result = await task

create_task 는 즉시 이벤트 루프에 등록해 백그라운드 실행. await 는 필요할 때 결과 수집. Task 를 await 하지 않으면 예외가 무시되어 디버깅이 어렵다.

Semaphore 로 동시 실행 제한

외부 API 요청 수 제한 등에 활용.

sem = asyncio.Semaphore(10)

async def limited_fetch(url):
    async with sem:
        return await fetch(url)

async def main():
    await asyncio.gather(*[limited_fetch(u) for u in urls])

async context manager

async with 는 동기 with 의 비동기 버전. __aenter__ / __aexit__ 프로토콜.

import aiofiles

async def write_file(path, data):
    async with aiofiles.open(path, 'w') as f:
        await f.write(data)

직접 구현:

class AsyncDB:
    async def __aenter__(self):
        self.conn = await connect()
        return self.conn

    async def __aexit__(self, exc_type, exc, tb):
        await self.conn.close()

async def main():
    async with AsyncDB() as conn:
        await conn.execute("SELECT 1")

contextlib.asynccontextmanager 를 사용하면 더 간단하다.

from contextlib import asynccontextmanager

@asynccontextmanager
async def managed_resource():
    resource = await acquire()
    try:
        yield resource
    finally:
        await release(resource)

자세히는 [[py-context-manager]] 참고.

asyncio.timeout / wait_for

# wait_for (3.4+)
try:
    result = await asyncio.wait_for(fetch(url), timeout=5.0)
except asyncio.TimeoutError:
    print("timed out")

# timeout context manager (3.11+)
try:
    async with asyncio.timeout(5.0):
        result = await fetch(url)
except asyncio.TimeoutError:
    print("timed out")

TaskGroup (Python 3.11+)

async def main():
    async with asyncio.TaskGroup() as tg:
        task1 = tg.create_task(fetch("url1"))
        task2 = tg.create_task(fetch("url2"))
    # 블록 종료 시 모두 완료됨
    # 하나가 실패하면 나머지도 취소되고 ExceptionGroup 발생
    print(task1.result(), task2.result())

gather 보다 구조화된 취소 처리. 하나가 실패하면 나머지도 정리된다. Python 3.11+ 에서 권장.

asyncio.Queue

코루틴 간 안전한 데이터 전달 (스레드 safe 불필요).

async def producer(queue: asyncio.Queue):
    for i in range(5):
        await queue.put(i)
    await queue.put(None)  # 종료 신호

async def consumer(queue: asyncio.Queue):
    while True:
        item = await queue.get()
        if item is None:
            break
        print(f"consumed: {item}")
        queue.task_done()

async def main():
    q = asyncio.Queue(maxsize=3)
    await asyncio.gather(producer(q), consumer(q))

취소 처리

async def long_task():
    try:
        await asyncio.sleep(100)
    except asyncio.CancelledError:
        print("취소됨, 정리 작업 실행")
        raise  # 반드시 재전파

async def main():
    task = asyncio.create_task(long_task())
    await asyncio.sleep(1)
    task.cancel()
    try:
        await task
    except asyncio.CancelledError:
        print("태스크 취소 완료")

[!WARNING] CancelledError 를 삼켜버리면 Task 가 취소된 것처럼 보이지 않아 TaskGroup / gather 취소 체인이 망가진다. 반드시 재전파.

run_in_executor: 블로킹 코드 연동

import asyncio
from concurrent.futures import ThreadPoolExecutor

executor = ThreadPoolExecutor(max_workers=4)

async def main():
    loop = asyncio.get_event_loop()
    # 블로킹 함수를 스레드 풀에서 실행
    result = await loop.run_in_executor(executor, blocking_function, arg1)

requests.get(), time.sleep(), 동기 DB 드라이버 등 교체 불가능한 블로킹 함수에 사용.

함정

동기 코드 블로킹: time.sleep() 대신 await asyncio.sleep(). 다른 블로킹 함수는 run_in_executor 로.
event loop 하나: asyncio.run() 을 중첩하면 안 됨. Jupyter 는 이미 loop 있어서 nest_asyncio 또는 await 직접 사용 필요.
취소 처리: asyncio.CancelledError 반드시 전파.
Task 미 await: create_task 후 await 하지 않으면 예외가 Task exception was never retrieved 경고로만 남는다.
gather vs TaskGroup: Python 3.11+ 에서는 구조화된 취소가 필요할 때 TaskGroup 선호.
블로킹 I/O 혼용: open(), requests.get() 같은 동기 I/O 는 이벤트 루프를 블로킹. 비동기 라이브러리 사용 필수.

실전 라이브러리

라이브러리	용도
aiohttp	HTTP client / server
asyncpg	PostgreSQL (고성능)
motor	MongoDB
httpx	HTTP client (sync/async 모두 지원)
FastAPI	웹 프레임워크
Starlette	FastAPI 기반 ASGI 프레임워크
aiofiles	비동기 파일 I/O
redis.asyncio	Redis 비동기 클라이언트

[Python] Comprehension: list, dict, set, generator

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

**Comprehension(컴프리헨션)**은 iterable로부터 list/set/dict/generator를 선언적·간결하게 만드는 문법이다. 일반 for+append 보다 30-50% 빠르며 (전용 바이트코드 LIST_APPEND 등), Pythonic 코드의 핵심 관용구다.

4가지 형태

[expr for x in iter if cond]        # list
{expr for x in iter if cond}        # set
{k: v for x in iter if cond}        # dict
(expr for x in iter if cond)        # generator (괄호: lazy)

평가 순서 시각화

flowchart LR
    I["iterable 소스"] --> F["for x in iter"]
    F -->|"cond 있으면"| C["if cond (필터)"]
    F -->|"cond 없으면"| E["expr 계산"]
    C -->|"True"| E
    C -->|"False"| F
    E --> R["결과 컬렉션에 추가"]
    R --> F

중첩 for 는 왼쪽이 바깥 루프다.

flowchart LR
    A["for x in A (바깥)"] --> B["for y in B (안쪽)"]
    B --> E["(x, y) 추가"]
    E --> B
    B --> A

list comprehension

<CodeWithOutput language=“python” outputLanguage=“text” code={`squares = [x ** 2 for x in range(5)] print(squares)

evens = [x for x in range(10) if x % 2 == 0] print(evens)

변환 + 필터 동시

upper_long = [s.upper() for s in [“hi”, “world”, “py”] if len(s) > 2] print(upper_long)

중첩 for

pairs = [(x, y) for x in range(2) for y in range(2)] print(pairs)

2차원 → 1차원 (flatten)

matrix = [[1, 2], [3, 4], [5, 6]] flat = [x for row in matrix for x in row] print(flat)} output={[0, 1, 4, 9, 16] [0, 2, 4, 6, 8] [‘WORLD’] [(0, 0), (0, 1), (1, 0), (1, 1)] [1, 2, 3, 4, 5, 6]`} />

중첩 for 순서

[(x, y) for x in A for y in B]
# 동등한 일반 for
result = []
for x in A:
    for y in B:
        result.append((x, y))

왼쪽 for가 바깥 루프. 헷갈리면 일반 for로 바꿔서 확인.

조건부 표현식

if는 필터, if-else는 표현식 변환.

# 필터 (수만 통과)
[x for x in nums if x > 0]

# 변환 (모두 통과, 값만 바뀜)
[x if x > 0 else 0 for x in nums]

dict comprehension

<CodeWithOutput language=“python” outputLanguage=“text” code={`squares = {x: x ** 2 for x in range(5)} print(squares)

dict 뒤집기

d = {“a”: 1, “b”: 2} inverted = {v: k for k, v in d.items()} print(inverted)

필터링

filtered = {k: v for k, v in d.items() if v > 1} print(filtered)} output={{0: 0, 1: 1, 2: 4, 3: 9, 4: 16} {1: ‘a’, 2: ‘b’} {‘b’: 2}`} />

set comprehension

generator expression

**괄호()**로 감싸면 generator를 반환한다. 메모리 효율적인 lazy 시퀀스.

거대한 데이터를 처리할 때는 항상 generator 먼저 고려. list 컴프리헨션을 메모리에 들고 있을 이유가 없으면 괄호로 바꿔라.

성능: list comp vs for loop vs map

방법	CPython 속도	메모리
list comprehension	기준 (1.0x)	즉시
일반 for + append	~1.3-1.5x 느림	즉시
`map()` + lambda	~1.1-1.2x 느림	lazy
`map()` + 내장 함수	~0.9x (약간 빠름)	lazy
generator expression	기준 (1.0x)	lazy (훨씬 적음)

# list comp
[x ** 2 for x in xs if x > 0]

# map + filter (역사적 대안)
list(map(lambda x: x ** 2, filter(lambda x: x > 0, xs)))

CPython에서 lambda 호출 비용이 크기 때문에 list comp가 거의 항상 빠르다. map(operator.add, ...)처럼 lambda 없이 내장 함수만 쓰면 map이 비등하거나 더 빠를 수 있다.

Walrus(`:=`)와 결합

같은 비싼 계산을 필터와 표현식에서 두 번 하지 않게.

# WRONG: f(x)를 두 번 호출
results = [f(x) for x in xs if f(x) is not None]

# 3.8+
results = [y for x in xs if (y := f(x)) is not None]

async comprehension (3.6+)

async def fetch_all():
    return [await fetch(url) async for url in urls()]

# async generator
async def squares():
    async for n in numbers():
        yield n ** 2

async 컨텍스트(코루틴 함수 내부)에서만 가능.

실전 패턴

JSON 필드 추출

users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
names = [u["name"] for u in users if u["id"] > 0]
id_map = {u["id"]: u["name"] for u in users}

중복 제거 (순서 유지)

seen = set()
unique = [x for x in items if not (x in seen or seen.add(x))]

set.add() 가 None 반환하므로 or seen.add(x) 트릭으로 순서 유지 dedup.

중첩 dict 평탄화

data = {"a": {"x": 1, "y": 2}, "b": {"x": 3, "y": 4}}
flat = {f"{outer}_{inner}": v
        for outer, inner_d in data.items()
        for inner, v in inner_d.items()}
# {'a_x': 1, 'a_y': 2, 'b_x': 3, 'b_y': 4}

그룹핑 (itertools 없이)

from collections import defaultdict
words = ["apple", "banana", "avocado", "cherry", "blueberry"]
by_first = defaultdict(list)
for w in words:
    by_first[w[0]].append(w)

# 컴프리헨션으로 표현 (가독성 주의)
by_first2 = {k: [w for w in words if w[0] == k]
             for k in {w[0] for w in words}}

첫 번째 방식이 O(n), 두 번째가 O(n^2)이다. 가독성을 위해 복잡도 희생하지 말 것.

가독성 한계

너무 복잡하면 일반 for로 바꿔라. 일반적 규칙:

중첩 3단계 이상 → for로 분해
조건 2개 이상 + 변환 복잡 → 함수로 추출
한 줄 80자 초과 → 부분식 변수로 추출 또는 for

# 나쁨: 한 줄에 너무 많음
result = [transform(x) for sublist in matrix for x in sublist if x > 0 and not is_blacklisted(x) and ...]

# 좋음
def is_valid(x):
    return x > 0 and not is_blacklisted(x)

result = [transform(x)
          for sublist in matrix
          for x in sublist
          if is_valid(x)]

스코프 (3.x)

Python 3 컴프리헨션은 자체 스코프를 가진다. 변수 누출 없음.

x = 99
squares = [x ** 2 for x in range(5)]
print(x)    # 99 (덮어쓰지 않음)

Python 2에서는 누출됐지만 3에서 수정됨.

함정

[!WARNING] 비싼 호출 반복: 필터와 표현식에서 같은 함수를 두 번 호출하지 말 것.

# WRONG: 매 반복마다 expensive_call() 두 번 호출
[expensive_call(x) for x in xs if expensive_call(x).is_ok]

# OK: walrus operator 활용
[y for x in xs if (y := expensive_call(x)).is_ok]

[!WARNING] generator를 두 번 소비: generator expression은 한 번만 소비 가능.

gen = (x ** 2 for x in range(5))
list(gen)   # [0, 1, 4, 9, 16]
list(gen)   # [] (소진됨)

[!WARNING] 순회 중 변경: dict/set comprehension 내부에서 소스를 변경하면 안 됨.

[Python] dict: 해시 맵과 삽입 순서 보장

koa (김신건) — Thu, 16 Jul 2026 00:00:00 GMT

정의

dict는 Python의 해시 맵 자료구조다. Python 3.7부터 삽입 순서를 언어 사양으로 보장한다(이전엔 CPython 3.6 구현 디테일이었음). 평균 O(1) 조회·삽입·삭제. 키는 해시 가능해야 한다(tuple/str/frozenset O, list/dict/set X).

내부 구조 (compact dict, 3.6+)

flowchart TB
    subgraph HT["해시 테이블 (indices 배열)"]
        H0["slot 0: -"]
        H1["slot 1: 2"]
        H2["slot 2: 0"]
        H3["slot 3: -"]
        H4["slot 4: 1"]
    end
    subgraph EA["entries 배열 (삽입 순서)"]
        E0["0: hash=..., key='a', val=1"]
        E1["1: hash=..., key='b', val=2"]
        E2["2: hash=..., key='c', val=3"]
    end
    H2 --> E0
    H4 --> E1
    H1 --> E2

해시 테이블: 슬롯마다 entries 배열의 인덱스만 저장
entries 배열: 실제 (hash, key, value) 를 삽입 순서대로 저장
삽입 순서 보장 + 메모리 절약 동시 달성 (이전 CPython 대비 ~50% 절약)

생성

empty = {}
d1 = {"a": 1, "b": 2}
d2 = dict(a=1, b=2)             # 키워드 인수 (str 키만)
d3 = dict([("a", 1), ("b", 2)]) # 튜플 시퀀스
d4 = dict.fromkeys(["a", "b", "c"], 0)  # {'a': 0, 'b': 0, 'c': 0}

# 컴프리헨션
squares = {x: x ** 2 for x in range(5)}

기본 연산

뷰: keys / values / items

d = {"a": 1, "b": 2}

d.keys()      # dict_keys(['a', 'b'])
d.values()    # dict_values([1, 2])
d.items()     # dict_items([('a', 1), ('b', 2)])

중요: 뷰는 동적이다. dict가 바뀌면 뷰도 즉시 반영된다.

순회

d = {"a": 1, "b": 2, "c": 3}

for k in d:                # 키 순회 (기본)
    print(k)

for k, v in d.items():     # 키-값 동시
    print(k, v)

for v in d.values():
    print(v)

[!WARNING] 순회 중 변경 금지: 순회 중 dict를 변경하면 RuntimeError: dictionary changed size during iteration.

# WRONG
for k in d:
    if d[k] < 0:
        del d[k]          # RuntimeError

# CORRECT: 키 리스트로 복사
for k in list(d.keys()):
    if d[k] < 0:
        del d[k]

# 또는 컴프리헨션으로 새 dict 생성
d = {k: v for k, v in d.items() if v >= 0}

defaultdict / Counter

표준 라이브러리 collections의 자주 쓰이는 dict 서브클래스.

Counter 산술

from collections import Counter

a = Counter(["cat", "dog", "cat"])
b = Counter(["dog", "bird"])

print(a + b)        # Counter({'cat': 2, 'dog': 2, 'bird': 1})
print(a - b)        # Counter({'cat': 2})
print(a & b)        # Counter({'dog': 1})   # min(a, b)
print(a | b)        # Counter({'cat': 2, 'dog': 1, 'bird': 1})  # max(a, b)

setdefault와 get

get(k, default)는 dict를 변경하지 않고 기본값 반환. setdefault(k, default)는 키가 없으면 추가까지.

d = {}
v = d.setdefault("count", 0)   # d = {"count": 0}, v = 0
d["count"] += 1                # d = {"count": 1}

# 두 줄 = defaultdict(int)["count"] += 1 한 줄

dict 병합 (3.9+)

PEP 584 도입.

a = {"x": 1, "y": 2}
b = {"y": 99, "z": 3}

merged = a | b               # {'x': 1, 'y': 99, 'z': 3}
a |= b                       # a 직접 갱신

# 3.9 이전:
merged = {**a, **b}

ChainMap: 계층적 조회

collections.ChainMap 은 여러 dict를 체인으로 연결. 앞에서부터 순서대로 키 검색.

from collections import ChainMap

defaults = {"color": "red", "verbose": False}
env     = {"verbose": True}
cli     = {"output": "json"}

config = ChainMap(cli, env, defaults)
print(config["color"])    # "red" (defaults 에서)
print(config["verbose"])  # True (env 에서 오버라이드)
print(config["output"])   # "json" (cli 에서)

# 실전: argparse + 환경변수 + 기본값 계층

해시 가능성

키는 __hash__를 구현해야 한다. 가변 객체(list, dict, set)는 해시 불가능.

{[1, 2]: "x"}              # TypeError: unhashable type: 'list'
{(1, 2): "x"}              # OK
{frozenset([1, 2]): "x"}   # OK

해시값과 동등성은 일관되어야 한다(a == b → hash(a) == hash(b)). 직접 만든 클래스를 키로 쓰려면 __eq__와 __hash__를 함께 구현.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __eq__(self, other):
        return (self.x, self.y) == (other.x, other.y)

    def __hash__(self):
        return hash((self.x, self.y))   # tuple 해시 재활용

d = {Point(0, 0): "origin"}

내부 구조 간단히

Open addressing + perturbation probing
3.6+ compact dict: 해시 테이블에는 인덱스만, 실제 항목은 별도 배열에 순서대로 저장 → 메모리 절약 + 순서 보존
load factor 약 2/3 도달 시 리사이즈

import sys
sys.getsizeof({})              # 64 (3.12 기준)
sys.getsizeof({"a": 1})        # 184

실전 패턴

dict를 클래스처럼: TypedDict

from typing import TypedDict

class User(TypedDict):
    name: str
    age: int

u: User = {"name": "Alice", "age": 30}
# 정적 타입 검사 지원, 런타임엔 일반 dict

조건부 키 포함

# 3.9+ 전: 조건 키 추가하려면 두 번 작성
config = {}
if debug:
    config["verbose"] = True

# 3.9+ 병합 연산자 활용
config = {"host": "localhost"} | ({"verbose": True} if debug else {})

함수형: dict → 변환

inventory = {"apple": 5, "banana": 0, "cherry": 3}

# 0 제거
available = {k: v for k, v in inventory.items() if v > 0}

# 값 변환
doubled = {k: v * 2 for k, v in inventory.items()}

# 키 정렬
sorted_inv = dict(sorted(inventory.items(), key=lambda kv: kv[1], reverse=True))

성능 함정

[!CAUTION] 매우 큰 dict에서 키 정렬이 필요하면 sorted(d) 매번 호출보다 sortedcontainers.SortedDict 검토.

키 충돌이 심한 사용자 정의 객체는 O(n) 가능 → __hash__ 잘 분포되게 구현
dict 대신 __slots__ + 클래스: 메모리 1/3, 속도 약간 빠름 (필드 고정 시)
dict.get() vs try/except KeyError: 키 존재 확률 낮으면 예외 방식이 더 빠름

[Python] int: 임의 정밀도 정수

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Python의 int는 **임의 정밀도 정수(arbitrary precision integer)**다. C의 int32/int64처럼 비트 폭이 고정되지 않으며, 메모리가 허용하는 한 무한히 큰 정수를 표현한다. 내부는 PyLongObject 구조체로, 30비트 단위의 디지트 배열로 구현되어 있다.

CPython 내부 구조: PyLongObject

Python 3.12부터 int 내부 구조가 크게 최적화되었다.

flowchart TD
    A["PyLongObject"] --> B["ob_refcnt\n(Py_ssize_t)"]
    A --> C["ob_type\n(*PyTypeObject = &PyLong_Type)"]
    A --> D["lv_tag (uintptr_t)\n3.12+ compact representation"]
    D --> E["sign: 2 bits"]
    D --> F["ndigits: 상위 bits"]
    A --> G["ob_digit[]\n30-bit limbs (LSB first)"]
    G --> H["digit[0] (최하위)"]
    G --> I["digit[1]"]
    G --> J["..."]

3.12 이전: `ob_size`

/* CPython 3.11 이전 */
typedef struct {
    PyObject_VAR_HEAD  /* ob_refcnt, ob_type, ob_size */
    digit ob_digit[1]; /* 30비트 limb 배열 */
} PyLongObject;

ob_size가 양수면 양수, 음수면 음수, 0이면 0.

3.12+: Compact Representation

/* CPython 3.12+ */
typedef struct {
    uintptr_t lv_tag;  /* 하위 3비트: tag, 나머지: ndigits / 값 */
    digit ob_digit[1];
} PyLongObject;

Compact int: limb 1개(-2^30 ~ 2^30-1)이면 ob_digit을 별도 메모리 없이 인라인 저장. 일반 정수의 메모리 풋프린트 30% 감소.

Small Int Cache: -5 ~ 256

CPython은 -5 ~ 256 범위의 정수를 인터프리터 시작 시 미리 생성해 캐싱한다. 같은 값이면 동일한 객체를 반환한다.

flowchart LR
    A["정수 리터럴 또는\n`int()` 호출"] --> B{"-5 <= n <= 256?"}
    B -->|"Yes"| C["small_ints[] 캐시에서\n기존 객체 반환"]
    B -->|"No"| D["새 PyLongObject 할당"]
    C --> E["ob_refcnt만 증가"]
    D --> F["heap 메모리 사용"]

왜 -5 ~ 256인가

CPython 소스 Objects/longobject.c:

#define NSMALLPOSINTS   257   /* 0 ~ 256 */
#define NSMALLNEGINTS   5    /* -5 ~ -1 */
static PyLongObject small_ints[NSMALLNEGINTS + NSMALLPOSINTS];

-5는 일반적인 오프셋(-1 같은 에러 코드)에 쓰이고, 256은 바이트 값(0x00~0xFF)과 ASCII 범위를 커버하기 위한 설계.

[!IMPORTANT] is는 객체 동일성 비교다. 정수 동등성 비교는 항상 == 사용. 캐시 범위가 구현 세부사항이므로 is에 의존하는 코드는 이식성이 없다.

기본 사용

2 ** 1000도 오버플로 없이 동작한다. C/Java라면 long도 표현 못 한다.

C long vs Python int

항목	C `int64_t`	Python `int`
크기	64비트 고정	무제한 (메모리 한계)
오버플로	정의되지 않은 동작 / 래핑	없음
메모리	8 bytes	28 bytes (작은 int 기본)
속도	레지스터 연산	객체 할당 + GC
사용처	시스템/네이티브 코드	Python 연산

NumPy np.int64는 C int64_t를 래핑해 고정 크기 + 고속 배열 연산을 제공. int 단독 계산보다 배열 연산은 100배+ 빠를 수 있다.

진법 리터럴

binary = 0b1010      # 2진수: 10
octal  = 0o17        # 8진수: 15
hexa   = 0xff        # 16진수: 255
under  = 1_000_000   # 가독성 언더스코어 (PEP 515)

진법 변환 함수:

<CodeWithOutput language=“python” outputLanguage=“text” code={`n = 255 print(bin(n)) # 2진 print(oct(n)) # 8진 print(hex(n)) # 16진

print(int(“ff”, 16)) # 16진 문자열 -> int print(int(“1010”, 2)) # 2진 문자열 -> int} output={0b11111111 0o377 0xff 255 10`} />

정수 연산

연산자	의미	예시
`+`, `-`, `*`	사칙연산	`5 + 3 == 8`
`/`	부동소수 나눗셈	`7 / 2 == 3.5`
`//`	몫 (floor division)	`7 // 2 == 3`, `-7 // 2 == -4`
`%`	나머지	`7 % 2 == 1`
`**`	거듭제곱	`2 ** 10 == 1024`
`divmod(a, b)`	몫/나머지 동시	`divmod(7, 2) == (3, 1)`

//는 수학적 floor라 음수에서 0으로 자르는 C와 다르다.

비트 연산

int는 무한 길이 2의 보수로 비트 연산을 지원한다.

a = 0b1100   # 12
b = 0b1010   # 10

print(a & b)     # 8  (AND)
print(a | b)     # 14 (OR)
print(a ^ b)     # 6  (XOR)
print(~a)        # -13 (NOT: -(a+1))
print(a << 2)    # 48
print(a >> 1)    # 6

비트 조작 패턴

# 특정 비트 설정/해제/토글
n = 0b1100

# 비트 k 설정 (set)
k = 1
n |= (1 << k)     # 0b1110

# 비트 k 해제 (clear)
n &= ~(1 << k)    # 0b1100

# 비트 k 토글
n ^= (1 << k)     # 0b1110

# 비트 k 읽기
bit = (n >> k) & 1

# 최하위 비트 제거 (Brian Kernighan)
n &= n - 1

# 2의 거듭제곱 여부
is_pow2 = n > 0 and (n & (n - 1)) == 0

유용한 메서드 (3.12+ 기준)

n = 255
n.bit_length()             # 8 (2진수 표현에 필요한 비트 수)
n.bit_count()              # 8 (3.10+: 1인 비트 개수, popcount)
n.to_bytes(2, "big")       # b'\x00\xff'
n.to_bytes(2, "little")    # b'\xff\x00'
int.from_bytes(b"\x00\xff", "big")   # 255

# 3.11+: bit_count (popcount)
(0b10110).bit_count()      # 3

# sys.int_info
import sys
print(sys.int_info)
# sys.int_info(bits_per_digit=30, sizeof_digit=4, ...)

bool은 int의 서브클래스

True와 False는 각각 int(1), int(0)이다.

sum(condition_list)로 조건을 만족하는 원소 수를 세는 관용구가 흔히 쓰인다.

성능 노트

64비트 이하 정수는 거의 C와 비슷한 속도지만, 매번 객체를 할당하므로 NumPy int64 배열이 훨씬 빠르다.
거대한 정수 곱셈은 Karatsuba 알고리즘을 사용 (n이 작으면 초등 알고리즘, 매우 크면 Toom-Cook 3-way).
Python 3.11+에서 int(s) 변환의 DoS 방지 패치: 4300자 이상 기본 ValueError.

# 3.11+: 큰 문자열 int 변환 제한
import sys
print(sys.get_int_max_str_digits())   # 4300 (기본)
sys.set_int_max_str_digits(0)         # 제한 해제 (위험)

함정

`is`로 정수 비교

# WRONG
def is_admin(level):
    return level is 1   # SyntaxWarning (3.8+)

# OK
def is_admin(level):
    return level == 1

[!WARNING] is는 객체 ID 비교. 캐시 범위(-5~256) 밖에서는 동일 값이어도 False. 정수/문자열 비교는 항상 ==.

정수 나눗셈

result = 7 / 2     # 3.5 (float!)
result = 7 // 2    # 3   (int)

Python 2 코드 포팅 시 /가 정수 나눗셈이었던 동작이 3에서 변경됨. 타입이 중요하다면 // 명시.

오버플로 없는 정수의 메모리

import sys
print(sys.getsizeof(0))          # 24 bytes
print(sys.getsizeof(2 ** 30))    # 28 bytes
print(sys.getsizeof(2 ** 60))    # 32 bytes
print(sys.getsizeof(2 ** 300))   # 68 bytes

큰 수는 그만큼 메모리를 차지한다. 암호화 등 큰 수 연산 대량 수행 시 메모리 감시.

[Python] Metaclass: type, __init_subclass__

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Metaclass는 “클래스의 클래스”다. 일반 클래스가 인스턴스의 행동을 결정하듯, metaclass는 클래스 자체의 행동(생성, 속성, 메서드 추가)을 결정한다. 모든 클래스의 기본 metaclass는 type.

class C: pass
print(type(C))         # <class 'type'>
print(type(C()))       # <class 'C'>
print(type(type))      # <class 'type'> (type의 type은 자기자신)

“Metaclasses are deeper magic than 99% of users should ever worry about.” - Tim Peters

대부분 __init_subclass__나 클래스 데코레이터로 해결 가능하다. metaclass는 정말 필요할 때만.

클래스 생성 프로토콜

class 문이 실행될 때 Python이 수행하는 단계.

flowchart TD
    A["class Foo(Base, metaclass=Meta): ..."] --> B["metaclass 결정\n(Base.__class__ 또는 metaclass= 인수)"]
    B --> C["Meta.__prepare__ 호출\n(네임스페이스 딕셔너리 생성)"]
    C --> D["클래스 본문 실행\n(def, 속성 할당 등 namespace 채움)"]
    D --> E["Meta.__new__ 호출\n(클래스 객체 생성)"]
    E --> F["Meta.__init__ 호출\n(클래스 객체 초기화)"]
    F --> G["descriptor __set_name__ 호출"]
    G --> H["Base.__init_subclass__ 호출"]
    H --> I["Foo 클래스 완성"]

type 활용 (간단)

type(name, bases, namespace)로 클래스를 동적 생성한다.

D = type("D", (), {"x": 1, "greet": lambda self: "hi"})
d = D()
print(d.x, d.greet())    # 1 hi

# 다음과 동등
class D:
    x = 1
    def greet(self): return "hi"

metaclass 정의

type을 상속해 metaclass 클래스를 만들고, 클래스 선언 시 metaclass= 인자로 지정.

class Logged(type):
    def __new__(mcs, name, bases, namespace):
        print(f"creating class {name}")
        return super().__new__(mcs, name, bases, namespace)

class User(metaclass=Logged):    # 클래스 생성 시 출력
    pass

class Admin(User):                # 출력 (서브클래스도 전파)
    pass

Logged.__new__는 클래스가 만들어질 때 한 번 호출. 클래스 데코레이터와 비슷하지만 서브클래스에도 자동 전파된다는 차이.

metaclass 메서드의 호출 시점

class Meta(type):
    @classmethod
    def __prepare__(mcs, name, bases, **kwargs):
        # 1. 클래스 본문을 담을 네임스페이스 딕셔너리 반환
        # OrderedDict 등 커스텀 딕셔너리를 반환하면 본문 순서 보존
        return super().__prepare__(name, bases, **kwargs)

    def __new__(mcs, name, bases, namespace, **kwargs):
        # 2. 클래스 객체 생성 (가장 먼저)
        return super().__new__(mcs, name, bases, namespace)

    def __init__(cls, name, bases, namespace, **kwargs):
        # 3. 클래스 객체 초기화 (__new__ 다음)
        super().__init__(name, bases, namespace)

    def __call__(cls, *args, **kwargs):
        # 4. 클래스를 호출해 인스턴스 만들 때 (Cls(...))
        instance = super().__call__(*args, **kwargs)
        return instance

`__init_subclass__` (PEP 487, 3.6+)

대부분의 metaclass 용도는 __init_subclass__로 대체 가능. 더 간단하고 사용자 친화적.

class Plugin:
    registry: dict[str, type] = {}

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        Plugin.registry[cls.__name__] = cls

class AuthPlugin(Plugin): pass
class CachePlugin(Plugin): pass

print(Plugin.registry)
# {'AuthPlugin': <class '__main__.AuthPlugin'>, 'CachePlugin': <class '__main__.CachePlugin'>}

서브클래스가 정의될 때마다 부모의 __init_subclass__가 호출된다. 자동 등록, 인터페이스 검사, 클래스 변환 등 대부분의 metaclass 패턴을 커버.

키워드 인수로 데이터 전달

class Validated:
    def __init_subclass__(cls, *, max_size: int = 100, **kwargs):
        super().__init_subclass__(**kwargs)
        cls._max_size = max_size

    def validate(self, data):
        if len(data) > self._max_size:
            raise ValueError(f"Size exceeds {self._max_size}")

class SmallBuffer(Validated, max_size=10): pass
class LargeBuffer(Validated, max_size=10000): pass

print(SmallBuffer._max_size)   # 10
print(LargeBuffer._max_size)   # 10000

실제 metaclass 사용 사례

1. ABCMeta (abc.ABC 내부)

from abc import ABC, ABCMeta, abstractmethod

class Shape(ABC):   # ABC = class ABC(metaclass=ABCMeta)
    @abstractmethod
    def area(self) -> float: ...

    @abstractmethod
    def perimeter(self) -> float: ...

class Circle(Shape):
    def __init__(self, radius: float):
        self.radius = radius

    def area(self) -> float:
        import math
        return math.pi * self.radius ** 2

    def perimeter(self) -> float:
        import math
        return 2 * math.pi * self.radius

# Shape() -> TypeError: Can't instantiate abstract class
# Circle() -> OK (abstractmethod 모두 구현)
c = Circle(5)
print(f"area={c.area():.2f}")

ABCMeta의 __new__가 @abstractmethod로 마킹된 메서드를 수집해 __abstractmethods__ frozenset에 저장. type.__call__이 이 집합이 비어있지 않으면 TypeError.

자세히: [[py-collections-abc]]

2. Django ORM `ModelBase`

# Django 내부 (단순화)
class ModelBase(type):
    def __new__(mcs, name, bases, attrs):
        # 1. 클래스 속성에서 Field 인스턴스 수집
        new_class = super().__new__(mcs, name, bases, attrs)
        fields = {k: v for k, v in attrs.items()
                  if isinstance(v, Field)}
        # 2. _meta (Options 객체) 초기화
        new_class._meta = Options(new_class, fields)
        # 3. Manager 생성 (objects)
        new_class.objects = Manager(new_class)
        return new_class

class Model(metaclass=ModelBase):
    pass

# 사용자 코드
class User(models.Model):          # ModelBase.__new__ 호출
    name = models.CharField()
    email = models.EmailField()
# User._meta.fields = {'name': CharField, 'email': EmailField}
# User.objects = Manager(User)

ModelBase가 Field 인스턴스를 스캔해 SQL 컬럼 메타데이터 구성, Manager 자동 생성. class User(models.Model): 선언만으로 ORM이 작동하는 이유.

3. Singleton

class Singleton(type):
    _instances: dict = {}

    def __call__(cls, *args, **kwargs):
        if cls not in cls._instances:
            cls._instances[cls] = super().__call__(*args, **kwargs)
        return cls._instances[cls]

class Config(metaclass=Singleton):
    def __init__(self, env: str = "production"):
        self.env = env

a = Config("dev")
b = Config("staging")   # 무시됨, 이미 생성된 인스턴스 반환
print(a is b)    # True
print(a.env)     # dev

metaclass의 __call__은 클래스 호출(Config(...)) 자체를 가로챔.

4. Enum

enum.Enum의 metaclass EnumMeta가 클래스 본문의 모든 클래스 속성을 멤버로 변환하고, 인스턴스화를 막고, 이름/값 룩업을 구축.

from enum import Enum

class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

print(Color.RED)           # Color.RED
print(Color(2))            # Color.GREEN
print(Color["BLUE"])       # Color.BLUE
print(type(Color))         # <class 'EnumType'>

자세히: [[py-enum]]

descriptor와 metaclass

__set_name__은 클래스 생성 시(metaclass 처리 후) 각 descriptor에 호출된다.

class Typed:
    def __set_name__(self, owner, name):
        self.name = name        # 'age' 등 필드명 자동 설정

    def __set__(self, obj, value):
        if not isinstance(value, int):
            raise TypeError(f"{self.name} must be int")
        obj.__dict__[self.name] = value

class Person:
    age = Typed()   # __set_name__ 호출: self.name = 'age'

p = Person()
p.age = 25   # OK
p.age = "25" # TypeError: age must be int

자세히: [[py-descriptor]]

metaclass 충돌

다중 상속 시 metaclass가 호환되지 않으면 TypeError.

class M1(type): pass
class M2(type): pass

class A(metaclass=M1): pass
class B(metaclass=M2): pass

class C(A, B): pass
# TypeError: metaclass conflict:
#   the metaclass of a derived class must be a (non-strict) subclass
#   of the metaclasses of all its bases

해결: 두 metaclass를 묶는 새 metaclass 정의.

class CombinedMeta(M1, M2): pass
class C(A, B, metaclass=CombinedMeta): pass

실제로는 ABCMeta와 사용자 metaclass 충돌이 흔한 상황. ABCMeta를 상속하거나 __init_subclass__로 대체해 충돌 자체를 피하는 게 낫다.

함정

metaclass가 적용될 때

class Meta(type):
    def __new__(mcs, name, bases, namespace):
        print(f"Meta.__new__: {name}")
        return super().__new__(mcs, name, bases, namespace)

class Base(metaclass=Meta):    # "Meta.__new__: Base"
    pass

class Sub(Base):               # "Meta.__new__: Sub" (서브클래스도!)
    pass

[!WARNING] metaclass는 해당 클래스뿐 아니라 모든 서브클래스에도 자동 적용된다. 서드파티 라이브러리 클래스를 상속할 때 예상치 못한 metaclass가 실행될 수 있다.

`prepare` 리턴값의 함정

class OrderedMeta(type):
    @classmethod
    def __prepare__(mcs, name, bases, **kwargs):
        from collections import OrderedDict
        return OrderedDict()   # 3.7+ dict는 이미 순서 보장이라 불필요

    def __new__(mcs, name, bases, namespace, **kwargs):
        # namespace가 OrderedDict임
        return super().__new__(mcs, name, bases, dict(namespace))

Python 3.7부터 일반 dict가 삽입 순서를 보존하므로 OrderedDict 반환은 불필요.

클래스 데코레이터로 충분한 경우

# metaclass 불필요
class Meta(type):
    def __new__(mcs, name, bases, ns):
        ns["created"] = True
        return super().__new__(mcs, name, bases, ns)

# 클래스 데코레이터로 동일 효과 (더 단순)
def add_created(cls):
    cls.created = True
    return cls

@add_created
class MyClass: pass

[!CAUTION] 클래스 데코레이터로 해결되면 metaclass 대신 데코레이터를 사용하라. metaclass는 서브클래스 전파가 필요하거나, __prepare__로 네임스페이스를 제어해야 할 때, 또는 ORM처럼 클래스 본문 파싱이 필요할 때만 정당화된다.

언제 쓰면 안 되는가

요구사항	metaclass 대신
단순 데이터 클래스	`@dataclass`
추상 메서드 강제	`abc.ABC`
서브클래스 등록	`__init_subclass__`
클래스 속성 변환	클래스 데코레이터
Singleton	모듈 변수, `__new__` 오버라이드
인터페이스 검사 (정적)	`typing.Protocol`

라이브러리 제작자가 사용자의 클래스 선언 문법을 마법처럼 변환할 때(ORM, 직렬화, DSL) 진가를 발휘한다.

[Python] tuple: 불변 시퀀스와 NamedTuple

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

tuple은 불변(immutable) 시퀀스다. list와 거의 같은 API를 가지나 생성 후 변경 불가하며, 그 덕에 dict 키나 set 원소로 사용 가능하다(해시 가능). 함수의 다중 반환값, 좌표/레코드 같은 고정 구조에 흔히 쓰인다.

CPython 내부 구조: PyTupleObject

flowchart LR
    A["PyTupleObject"] --> B["ob_refcnt"]
    A --> C["ob_type\n(tuple_type)"]
    A --> D["ob_size (n)"]
    A --> E["ob_item[0]"]
    A --> F["ob_item[1]"]
    A --> G["..."]
    E -.->|"포인터"| H["PyObject A"]
    F -.->|"포인터"| I["PyObject B"]

ob_item[]: PyObject* 포인터 배열. 원소 자체가 아닌 참조를 저장
불변이라 한 번 생성된 배열은 교체 불가
CPython 튜플 캐시: 빈 () 은 싱글턴. 길이 0~20의 튜플은 free list로 재활용

import sys

# 빈 튜플은 싱글턴
a = ()
b = ()
print(a is b)   # True

# 메모리 비교: tuple < list
lst = [1, 2, 3, 4, 5]
tup = (1, 2, 3, 4, 5)
print(sys.getsizeof(lst))   # 104 bytes (over-allocation)
print(sys.getsizeof(tup))   # 80 bytes (딱 필요한 만큼)

생성

empty = ()
single = (1,)        # 콤마 필수! (1)는 그냥 괄호 묶인 표현식
pair = (1, 2)
triple = 1, 2, 3     # 괄호 없이도 됨 (tuple packing)
from_iter = tuple([1, 2, 3])

함정: (1)은 int, (1,)만 tuple.

불변성

t = (1, 2, 3)
t[0] = 99   # TypeError: 'tuple' object does not support item assignment

하지만 내부에 가변 객체가 있으면 그 객체는 변경 가능하다.

t = ([1, 2], [3, 4])
t[0].append(99)        # 리스트 자체는 변경 가능
print(t)               # ([1, 2, 99], [3, 4])

따라서 “tuple이 hashable이다”는 항상 참이 아니다. 내부에 list가 들어 있으면 hash(t)는 TypeError.

hash((1, 2))           # OK
hash((1, [2, 3]))      # TypeError: unhashable type: 'list'

언패킹 (Tuple Unpacking)

가장 강력하고 흔히 쓰이는 기능.

중첩 언패킹

# 행렬 처리
matrix = [(1, 2), (3, 4), (5, 6)]
for x, y in matrix:
    print(f"({x}, {y})")

# 깊은 중첩
((a, b), c) = ((1, 2), 3)
print(a, b, c)   # 1 2 3

# enumerate와 언패킹
for idx, (key, val) in enumerate({"a": 1, "b": 2}.items()):
    print(idx, key, val)

메서드 (불변이라 단 2개)

t = (1, 2, 3, 2, 1)
t.count(2)     # 2
t.index(3)     # 2 (처음 등장 인덱스)

읽기 연산(len, in, 슬라이스, min/max/sum)은 list와 동일.

NamedTuple: 이름 있는 필드

collections.namedtuple 또는 typing.NamedTuple로 필드명을 부여한다. 작은 데이터 클래스가 필요할 때 dataclass보다 가볍다.

타입 힌트가 필요하면 typing.NamedTuple:

from typing import NamedTuple

class User(NamedTuple):
    id: int
    name: str
    age: int = 0    # 기본값

u = User(1, "Alice")
print(u.id, u.name)    # 1 Alice
print(u._fields)       # ('id', 'name', 'age')

typing.NamedTuple은 collections.namedtuple을 클래스 문법으로 감싼 것. 내부는 동일한 tuple 서브클래스.

TypedDict: dict에 타입 구조 부여

typing.TypedDict는 특정 키/타입 구조를 가진 dict를 타입 힌트 수준에서 검사한다. 런타임에는 일반 dict.

from typing import TypedDict, Required, NotRequired

class UserInfo(TypedDict):
    id: int
    name: str
    email: NotRequired[str]   # 선택 필드 (3.11+)

# 사용
user: UserInfo = {"id": 1, "name": "Alice"}  # OK
user2: UserInfo = {"id": 2}   # mypy 오류: 'name' 필드 누락

tuple vs list vs dataclass vs NamedTuple vs TypedDict

타입	가변	해시	필드명	타입 힌트	메모리	용도
`tuple`	X	O	X	-	최소	고정 레코드, 다중 반환
`list`	O	X	X	-	보통	동적 컬렉션
`namedtuple`	X	O	O	제한적	최소+	가벼운 불변 레코드
`NamedTuple`	X	O	O	O	최소+	타입 힌트 불변 레코드
`dataclass`	O	X	O	O	보통	일반 데이터 클래스
`dataclass(frozen=True)`	X	O	O	O	보통	메서드/검증이 필요한 불변
`TypedDict`	O	X	O	O (정적만)	dict 동일	JSON-like dict 타입 표기

자세히: [[py-dataclass]], [[py-typeddict-protocol]]

hashable 활용

# 튜플을 set 원소 / dict 키로
seen = set()
for x, y in points:
    if (x, y) in seen:
        continue
    seen.add((x, y))

# 2D 좌표 grid
grid = {(0, 0): "start", (1, 1): "wall"}
print(grid.get((0, 0)))   # start

# functools.lru_cache: 튜플 인수는 바로 캐시 키
from functools import lru_cache

@lru_cache(maxsize=None)
def shortest_path(start: tuple, end: tuple) -> int:
    ...

함수 리턴값 관용구

Python 함수는 사실상 항상 튜플을 반환한다(다중 값 = 튜플).

def stats(xs):
    return min(xs), max(xs), sum(xs) / len(xs)

lo, hi, avg = stats([1, 2, 3, 4, 5])
result = stats([1, 2, 3])   # (1, 3, 2.0) 튜플

메모리 최적화

import dis

# 상수 튜플: 컴파일 타임에 LOAD_CONST 한 번
dis.dis("x = (1, 2, 3)")    # LOAD_CONST  (1, 2, 3)

# 리스트: 매번 BUILD_LIST (3개 로드 + 빌드)
dis.dis("x = [1, 2, 3]")    # BUILD_LIST

`slots`와 tuple 조합

class Point:
    __slots__ = ("x", "y")   # dict 없이 고정 슬롯

    def __init__(self, x, y):
        self.x = x
        self.y = y

# vs NamedTuple: 둘 다 메모리 효율적이나 NamedTuple은 불변 + 시퀀스 API

대용량 데이터 처리

# list보다 tuple 순회가 약간 빠름 (size 고정, over-allocation 없음)
import timeit
n = 1_000_000
xs_list = list(range(n))
xs_tuple = tuple(range(n))

# 순회 속도 거의 동일 (접근 패턴이 동일)
# 생성/메모리 차이가 주요 이점

함정

단일 원소 튜플의 콤마

t = (42)    # int, 튜플 아님!
t = (42,)   # tuple (1,)
t = 42,     # tuple, 괄호 없어도 됨

[!WARNING] (42)는 int(42)와 동일. 단일 원소 튜플은 반드시 뒤에 쉼표 필요. (42,) 또는 42,.

내부 가변 객체와 해시

t = (1, [2, 3])
hash(t)   # TypeError: unhashable type: 'list'

# dict 키나 set 원소로 사용 불가
d = {t: "value"}   # TypeError

[!WARNING] 내부 리스트가 있으면 tuple도 unhashable. dict 키/set 원소로 쓰려면 내부 원소까지 모두 hashable이어야 한다.

`_replace()`는 새 객체 반환

p = Point(x=1, y=2)
p._replace(x=99)   # 새 Point(x=99, y=2) 반환
print(p)           # Point(x=1, y=2) - 원본 변경 없음

[Python] 기본 문법: 들여쓰기, 주석, 변수

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Python은 들여쓰기(indentation)로 블록을 구분하는 언어다. C/Java의 중괄호 {} 대신 일관된 들여쓰기 수준이 블록 스코프를 결정한다. PEP 8은 공백 4칸을 권장하며 탭과 공백 혼용은 TabError를 발생시킨다.

flowchart LR
    A["Python 문법"] --> B["리터럴"]
    A --> C["제어 흐름"]
    A --> D["정의문"]
    B --> B1["int / float / str"]
    B --> B2["list / dict / tuple"]
    C --> C1["if / for / while"]
    C --> C2["match / case"]
    D --> D1["def / class"]
    D --> D2["import"]

들여쓰기 규칙

같은 블록 안에서는 들여쓰기 폭이 동일해야 한다. 다음은 IndentationError를 던진다.

def bad():
    x = 1
     y = 2   # IndentationError: unexpected indent

주석과 Docstring

한 줄 주석: #
여러 줄 “주석”: 실제로는 docstring("""...""")을 사용. 문자열 리터럴이라 GC된다.

# 한 줄 주석
def add(a, b):
    """두 수를 더한다.

    이런 형식의 docstring은 help(add)로 확인할 수 있다.
    """
    return a + b

Docstring 형식 비교

형식	특징	사용처
Google Style	`Args:`, `Returns:` 섹션	Google, 대부분 오픈소스
NumPy Style	밑줄 구분선 사용	과학 라이브러리 (NumPy, SciPy)
Sphinx (reStructuredText)	`:param x:`, `:type x:`	Python 공식 문서

# Google Style (권장)
def divide(a: float, b: float) -> float:
    """두 수를 나눈다.

    Args:
        a: 피제수.
        b: 제수. 0이면 안 된다.

    Returns:
        a를 b로 나눈 결과.

    Raises:
        ZeroDivisionError: b가 0일 때.
    """
    return a / b

변수와 할당

Python은 동적 타이핑이다. 변수 선언이 없고, 할당과 동시에 이름이 객체에 바인딩된다.

<CodeWithOutput language=“python” outputLanguage=“text” code={`x = 42 # int x = “hello” # 같은 이름이 다른 타입 객체를 가리킴 y, z = 1, 2 # 튜플 언패킹 a = b = c = 0 # 체인 할당 (모두 같은 객체)

print(type(x), x) print(y, z) print(a is b, b is c)} output={<class ‘str’> hello 1 2 True True`} />

x = 42는 “x라는 라벨을 정수 객체 42에 붙인다”는 의미. “x라는 메모리 슬롯에 42를 쓴다”가 아니다. 이 차이는 가변/불변 객체 동작을 이해할 때 핵심이다.

f-string (PEP 498, 3.6+)

f"..." 문자열은 중괄호 {} 안의 표현식을 평가해 삽입한다.

Python 3.12에서 f-string 파서가 PEG 기반으로 완전 재작성 (PEP 701). 중첩 f-string, 백슬래시 내부 사용 가능.

# 3.12+: 중첩 f-string
values = [1, 2, 3]
print(f"{'|'.join(str(v) for v in values)}")   # 1|2|3

# 3.12+: 백슬래시 내부 허용
print(f"{'hello\nworld'!r}")   # 'hello\\nworld'

자세히: [[py-string-formatting]]

타입 힌트 (PEP 484, 526, 3.5+)

타입 힌트는 런타임에 무시되지만 mypy/pyright 등으로 정적 검증 가능.

# 변수 타입 힌트 (PEP 526, 3.6+)
count: int = 0
name: str

# 함수 시그니처
def greet(name: str, times: int = 1) -> str:
    return (name + " ") * times

# 컬렉션: 3.9+ 내장 제네릭
def process(items: list[int]) -> dict[str, int]:
    return {str(i): i for i in items}

# 유니온: 3.10+ 단축 문법
def parse(value: str | int | None) -> int:
    if value is None:
        return 0
    return int(value)

# typing 모듈 고급
from typing import TypeVar, Generic, Protocol

T = TypeVar("T")

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

자세히: [[py-typing]]

Walrus Operator `:=` (PEP 572, 3.8+)

expression 자리에서 할당 수행. while/comprehension/if 조건에서 중복 계산 방지.

import re

# 정규식 매칭 결과를 조건과 본문 양쪽에서 재사용
data = "ID:12345"
if m := re.match(r"ID:(\d+)", data):
    print(f"ID found: {m.group(1)}")   # ID found: 12345

# 대용량 파일 청크 읽기
with open("large.bin", "rb") as f:
    while chunk := f.read(8192):
        process(chunk)

# comprehension에서 비싼 계산 재사용
results = [y for x in data_list if (y := expensive(x)) is not None]

자세히: [[py-operators]]

match/case (PEP 634, 3.10+)

구조적 패턴 매칭. switch와 달리 구조체 분해, 타입 검사, guard까지 지원.

<CodeWithOutput language=“python” outputLanguage=“text” code={`def classify(command): match command: case “quit”: return “종료” case “hello” | “hi”: return “인사” case str(s) if len(s) > 10: return f”긴 명령: {s[:10]}…” case _: return f”알 수 없음: {command}”

print(classify(“quit”)) print(classify(“hi”)) print(classify(“thisisaverylongcommand”)) print(classify(“unknown”))} output={종료 인사 긴 명령: thisisaver… 알 수 없음: unknown`} />

# 구조체 분해 패턴
from dataclasses import dataclass

@dataclass
class Point:
    x: float
    y: float

def describe(obj):
    match obj:
        case Point(x=0, y=0):
            return "원점"
        case Point(x=x, y=0):
            return f"x축 위 ({x})"
        case Point(x=0, y=y):
            return f"y축 위 ({y})"
        case Point(x=x, y=y):
            return f"일반 점 ({x}, {y})"
        case list() as xs if len(xs) == 0:
            return "빈 리스트"
        case _:
            return "기타"

print(describe(Point(3, 0)))   # x축 위 (3)
print(describe(Point(1, 2)))   # 일반 점 (1, 2)

자세히: [[py-pattern-matching]]

식별자(Identifier) 규칙

영문/유니코드 문자, 숫자, _ 사용 가능 (숫자로 시작 불가)
대소문자 구분: value와 Value는 다른 변수
예약어 35개(if, for, class, True, None, match, case, …)는 사용 불가
관례:
- snake_case: 변수/함수
- PascalCase: 클래스
- _leading_underscore: 내부용 (모듈 외부 노출 방지)
- __double_underscore__: 매직 메서드/속성 (dunder)
- __name_mangling: 클래스 내 이름 맹글링 (서브클래스 충돌 방지)

라인 연속

긴 한 줄은 백슬래시 \ 또는 괄호 안에서 자동으로 연속된다.

total = 1 + 2 + 3 + \
        4 + 5 + 6      # 백슬래시 연속

items = [
    "apple",
    "banana",
    "cherry",          # 괄호/대괄호 안은 자유 줄바꿈
]

PEP 8은 괄호 활용을 백슬래시보다 권장한다.

PEP 8 핵심 스타일

들여쓰기: 공백 4칸
한 줄 최대 79자(주석은 72자)
함수/클래스 정의 사이 빈 줄 2줄
메서드 사이 빈 줄 1줄
연산자 양옆 공백 1칸: a + b, a == b
함수 호출 시 키워드 인수 = 양옆 공백 없음: f(x=1)
import는 표준 라이브러리, 서드파티, 로컬 3그룹으로 분리

# import 순서 (PEP 8)
import os
import sys

import numpy as np
import pandas as pd

from myproject import utils

ruff, black, isort 등 포매터로 자동 적용 가능.

함정

탭과 공백 혼용

# 탭 + 공백 혼용 시 Python 3에서 TabError
def mixed():
	x = 1    # 탭
    y = 2    # 공백  -> TabError

[!WARNING] Python 3은 탭/공백 혼용을 엄격히 금지한다. 에디터의 “탭을 공백으로 변환” 옵션 활성화 필수.

기본 인수의 가변 객체

# WRONG: 기본 인수가 한 번만 평가됨
def append_to(item, lst=[]):
    lst.append(item)
    return lst

print(append_to(1))   # [1]
print(append_to(2))   # [1, 2] (예상: [2])

# OK: None 기본값 패턴
def append_to(item, lst=None):
    if lst is None:
        lst = []
    lst.append(item)
    return lst

[!WARNING] 기본 인수로 [], {}, set() 같은 가변 객체를 쓰면 호출 간에 공유된다. 항상 None을 사용하고 함수 본문에서 초기화.

Python

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Python은 Guido van Rossum이 1991년 발표한 인터프리터 방식의 동적 타이핑 언어다. 읽기 쉬운 문법과 방대한 라이브러리 생태계로 웹 백엔드, 데이터 분석, 머신러닝, 스크립팅, DevOps 등 거의 모든 분야에서 쓰인다.

CPython (C로 구현된 공식 구현체) 외에도 PyPy (JIT 컴파일), Jython (JVM), MicroPython (임베디드) 등이 있으나 생태계 대부분은 CPython 기준이다.

CPython 실행 흐름

소스 코드가 결과로 변환되기까지 5단계.

flowchart TD
    A[".py 소스 파일"] --> B["토크나이저"]
    B --> C["파서"]
    C --> D["AST"]
    D --> E["컴파일러"]
    E --> F[".pyc 바이트코드"]
    F --> G["CPython VM (ceval.c)"]
    G --> H["실행 결과"]
    F -->|"캐시 재사용"| G

토크나이저: 소스를 토큰 스트림으로 분해 (Lib/tokenize.py)
파서: 문법 규칙으로 Parse Tree 생성 (3.9+부터 PEG 파서)
AST: ast 모듈로 검사·변환 가능한 트리
컴파일러: compile() → PyCodeObject 생성 (Python/compile.c)
VM: 스택 기반 인터프리터. dis 모듈로 바이트코드 확인 가능

import dis
dis.dis("x = 1 + 2")
#   0 LOAD_CONST   0 (3)
#   2 STORE_NAME   0 (x)

3.11부터 Specializing Adaptive Interpreter(SAI)가 바이트코드를 런타임에 특화 최적화한다.

구현체 비교

구현체	기반	특징	사용처
CPython	C	공식 참조 구현, 최고 호환성	범용
PyPy	RPython/JIT	CPU-bound 코드 5-50배 빠름	장기 실행 서버, 수치 계산
MicroPython	C (경량)	마이크로컨트롤러 타깃, 표준 라이브러리 일부	IoT, RP2040, ESP32
GraalPy	GraalVM	JVM 위에서 실행, Java 상호운용	엔터프라이즈
Jython	Java	JVM, Java 라이브러리 직접 호출	Java 통합 (레거시)

[!IMPORTANT] C 확장(numpy, pandas, Pillow)은 CPython ABI에 의존한다. PyPy로 교체하면 C 확장 호환성을 별도로 확인해야 한다.

언어 특성

인터프리터 방식: 소스를 bytecode로 컴파일 후 VM에서 실행 (.pyc 파일)
동적 타이핑: 변수의 타입을 런타임에 결정. 선언 불필요
들여쓰기 문법: 중괄호 대신 indentation (공백 4칸)으로 블록 구분
GIL (Global Interpreter Lock): CPython은 한 번에 하나의 스레드만 Python bytecode 실행 가능
모든 것이 객체: 함수, 클래스, 모듈 모두 first-class object

핵심 개념

Duck Typing

“오리처럼 걷고 오리처럼 울면 오리다”. 객체의 타입이 아니라 메서드/속성 존재 여부로 동작 결정.

def process(item):
    item.read()  # item이 file-like object이기만 하면 됨

[[py-collections-abc]]의 Protocol로 덕 타이핑을 정적으로 표현할 수 있다.

List Comprehension / Generator

squares = [x**2 for x in range(10)]           # list
gen = (x**2 for x in range(10))               # generator (lazy)
filtered = [x for x in data if x > 0]

자세히: [[py-comprehension]], [[py-iterator-generator]]

Decorator

함수를 감싸는 함수. AOP, 권한 검증, 로깅 등에 활용.

@app.route('/users')
def get_users():
    ...

자세히: [[py-decorator]]

GIL과 동시성

CPython의 Global Interpreter Lock은 메모리 관리 단순화를 위해 한 번에 한 스레드만 Python bytecode를 실행하게 제한한다.

sequenceDiagram
    participant T1 as "Thread 1"
    participant GIL
    participant T2 as "Thread 2"
    T1 ->> GIL: "acquire"
    GIL -->> T1: "granted"
    T1 ->> T1: "바이트코드 실행"
    T1 ->> GIL: "release (100 opcodes 또는 I/O)"
    T2 ->> GIL: "acquire"
    GIL -->> T2: "granted"
    T2 ->> T2: "바이트코드 실행"

상황	권장 방법	이유
I/O 위주 (네트워크, DB)	`asyncio` / `threading`	I/O 대기 중에는 GIL 해제됨
CPU 위주 (계산, 인코딩)	`multiprocessing`	별도 프로세스로 GIL 우회
짧은 스크립트	단일 스레드	간단함

NumPy, Pillow 같은 C extension은 GIL을 해제하고 실행하므로 멀티스레드 효과를 볼 수 있다.

Python 3.13부터 No-GIL(Free-threaded) 빌드가 실험적으로 제공된다 (PEP 703). python3.13t 바이너리로 활성화.

자세히: [[py-gil]], [[py-asyncio]], [[py-threading]], [[py-multiprocessing]]

타입 힌트

Python 3.5+부터 typing 모듈로 선택적 타입 표기 가능. 런타임에는 무시되지만 mypy, pyright 같은 정적 분석기로 검증할 수 있다.

def add(a: int, b: int) -> int:
    return a + b

from typing import Optional
def find_user(user_id: int) -> Optional[str]:
    ...

# 3.10+ 유니온 단축 문법
def greet(name: str | None = None) -> str:
    return f"Hello, {name or 'world'}"

Pydantic, dataclasses 로 런타임 검증 + 자동 직렬화를 결합하는 패턴이 FastAPI 등에서 표준이다.

자세히: [[py-typing]], [[py-dataclass]]

버전별 주요 기능

버전	주요 추가
3.8	walrus operator (`:=`), `f`-string `=` 디버깅, `math.prod`
3.9	`list[int]` 내장 제네릭, `dict
3.10	`match/case` 패턴 매칭, `X
3.11	Specializing Adaptive Interpreter, 예외 노트, `tomllib`
3.12	f-string 완전 재작성, `@override`, `TypeVarTuple`
3.13	No-GIL 빌드(실험), JIT 컴파일러(실험), 개선된 REPL

표준 라이브러리 주요 카테고리

카테고리	대표 모듈
데이터 구조	`collections`, `heapq`, `bisect`, `array`
파일/IO	`pathlib`, `os`, `shutil`, `io`
직렬화	`json`, `pickle`, `csv`, `tomllib`, `struct`
네트워크	`urllib`, `http`, `socket`, `ssl`
동시성	`asyncio`, `threading`, `multiprocessing`, `concurrent.futures`
텍스트	`re`, `textwrap`, `string`, `difflib`
디버깅/프로파일링	`tracemalloc`, `cProfile`, `pdb`, `dis`
날짜/시간	`datetime`, `zoneinfo`

패키지 관리

도구	용도	파일
`pip`	패키지 설치 (PyPI)	`requirements.txt`
`venv`	가상 환경 (프로젝트별 의존성 격리)	-
`poetry`	의존성 + 빌드 + 배포 통합	`pyproject.toml`
`uv`	Rust 기반 초고속 pip/venv 대체	`pyproject.toml`

requirements.txt는 버전 lock 없이 top-level만 나열. poetry.lock이나 uv.lock으로 재현 가능한 빌드 보장.

자세히: [[py-venv-packaging]]

주요 사용처

웹 백엔드: Django (전통적 MVC), FastAPI (비동기 + 타입 힌트), Flask (경량)
데이터/ML: NumPy, pandas, scikit-learn, PyTorch, TensorFlow
스크립팅: 파일 처리, CLI 도구 (Click, Typer), 자동화
DevOps: Ansible, SaltStack, CI/CD 스크립트

함정

GIL은 스레드 안전성을 보장하지 않는다

counter = 0

def increment():
    global counter
    for _ in range(100000):
        counter += 1   # read-modify-write, GIL 사이에 끊길 수 있음

import threading
threads = [threading.Thread(target=increment) for _ in range(10)]
for t in threads: t.start()
for t in threads: t.join()
print(counter)   # 1000000 아닐 수 있음

[!WARNING] counter += 1은 LOAD/ADD/STORE 3개 바이트코드로 GIL이 각 사이에서 양보 가능. 원자적 연산이 필요하면 threading.Lock 또는 queue.Queue 사용.

정수 비교는 `==` 사용

a = 1000
b = 1000
print(a is b)   # CPython에서 False (캐시 범위 밖)
print(a == b)   # True (항상)

is는 객체 동일성. [[py-int]] 참조.

동적 임포트 순환

A가 B를 임포트하고 B가 A를 임포트하면 ImportError. 인터페이스를 분리하거나 함수 내부로 임포트를 이동하라.

자세히: [[py-import-system]]

[Python] @property, getter, setter, deleter

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

@property는 메서드를 속성처럼 접근할 수 있게 해주는 데코레이터다. 호출자는 obj.name처럼 보지만 내부적으로는 함수가 실행되어 계산되거나 검증된 값을 반환한다. Java의 getter/setter에 해당하지만 호출 측 코드를 바꾸지 않고 도입할 수 있다.

기본 사용

class Circle:
    def __init__(self, radius):
        self.radius = radius

    @property
    def area(self):
        return 3.14159 * self.radius ** 2

c = Circle(5)
print(c.area)    # 78.53975 (메서드 호출이 아닌 속성 접근)
c.area = 100     # AttributeError: can't set attribute

c.area는 함수 호출처럼 보이지 않지만 매번 area(self)를 실행. 의도하지 않은 부수효과나 비싼 계산은 피해야 한다.

getter / setter / deleter

class Temperature:
    def __init__(self, celsius):
        self._celsius = celsius

    @property
    def celsius(self):
        return self._celsius

    @celsius.setter
    def celsius(self, value):
        if value < -273.15:
            raise ValueError("below absolute zero")
        self._celsius = value

    @celsius.deleter
    def celsius(self):
        del self._celsius

    @property
    def fahrenheit(self):
        return self._celsius * 9 / 5 + 32

t = Temperature(25)
print(t.celsius, t.fahrenheit)    # 25 77.0
t.celsius = 30                     # setter 호출
print(t.fahrenheit)                # 86.0
t.celsius = -300                   # ValueError

setter는 @property_name.setter로 등록. deleter는 거의 안 씀.

언제 property를 쓰나

1. 검증 (validation)

class User:
    @property
    def email(self):
        return self._email

    @email.setter
    def email(self, value):
        if "@" not in value:
            raise ValueError("invalid email")
        self._email = value.lower()

직접 self.email = "..." 할당해도 검증이 자동.

2. 파생값 (computed)

class Box:
    def __init__(self, w, h, d):
        self.w, self.h, self.d = w, h, d

    @property
    def volume(self):
        return self.w * self.h * self.d

box.volume은 매번 신선하게 계산. 불일치 위험 없음.

3. 마이그레이션 (호환성 유지)

class User:
    def __init__(self, name):
        self.name = name

    @property
    def full_name(self):    # 새 API로 가는 도중 호환
        return self.name

기존 코드가 user.name을 쓰던 것을 깨지 않으면서 user.full_name도 노출.

property vs 직접 속성

Pythonic 가이드: 처음부터 property로 만들지 말고, 필요할 때 도입하라.

# 처음엔 그냥
class User:
    def __init__(self, name):
        self.name = name

# 나중에 검증이 필요해지면 코드 호환성 유지하며 추가
class User:
    def __init__(self, name):
        self.name = name        # setter 통과

    @property
    def name(self):
        return self._name

    @name.setter
    def name(self, value):
        if not value:
            raise ValueError("name required")
        self._name = value

호출자 코드 변경 0줄. Java처럼 처음부터 getter/setter 쓰지 않는 이유.

cached_property

functools.cached_property (3.8+)는 첫 호출 결과를 인스턴스 속성에 저장 → 이후 일반 속성 조회 속도.

from functools import cached_property

class DataSet:
    def __init__(self, data):
        self.data = data

    @cached_property
    def mean(self):
        print("computing")
        return sum(self.data) / len(self.data)

d = DataSet([1, 2, 3])
d.mean   # "computing" 후 2.0
d.mean   # 캐시 (출력 없음)
del d.mean    # 무효화
d.mean   # 다시 "computing"

@property와 달리 캐시되므로 불변 데이터나 명시적 무효화 의도가 있을 때만 사용.

slots와의 충돌

__slots__는 __dict__를 막아 메모리를 절감. property는 클래스 속성이라 영향 없지만, cached_property는 인스턴스 __dict__에 저장하므로 __slots__ 사용 시 슬롯에 포함시켜야 한다.

class C:
    __slots__ = ("_x", "computed")    # cached_property 이름도 포함

    @cached_property
    def computed(self): ...

descriptor와의 관계

property는 사실 data descriptor의 표준 구현체다. __get__, __set__, __delete__ 메서드가 있다. 더 복잡한 동작이 필요하면 직접 descriptor 작성. py-descriptor 페이지 참고.

import inspect
print(inspect.getmembers(property))    # __get__, __set__, __delete__ 확인

함정과 팁

1. property 안에서 self.속성 호출하면 무한 재귀

class C:
    @property
    def value(self):
        return self.value    # 무한 재귀

# 백킹 변수 분리 필요
class C:
    @property
    def value(self):
        return self._value

2. setter 없는 property는 read-only

class C:
    @property
    def x(self):
        return 1

c = C()
c.x = 99    # AttributeError

3. 비싼 계산은 명시 호출이 낫다

# property로 감추면 c.area를 무심코 N번 호출 시 N번 계산
c.area + c.area + c.area  # 3번 계산

# 명시 메서드면 사용자가 의식
c.compute_area()

cached_property나 일반 메서드 중 선택.

4. 호출자가 함수인 줄 모르고 비교

if obj.is_ready:    # property라 매번 호출
    ...

# 자주 쓰는 비싼 계산이면 캐시 또는 명시 메서드
ready = obj.is_ready
if ready:
    ...

[Python] argparse, click, typer: CLI 만들기

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Python에서 CLI를 만드는 옵션은 세 가지가 주류:

argparse (stdlib): 표준, 외부 의존성 없음
click (third-party): 데코레이터 기반, 강력한 옵션 처리
typer (third-party): 타입 힌트로 자동 CLI 생성 (FastAPI 만든 사람이 만듦)

argparse 기본

import argparse

parser = argparse.ArgumentParser(
    prog="my-tool",
    description="Process some integers.",
    epilog="See https://example.com for more.",
)

parser.add_argument("filename", help="Input file")           # 위치 인자
parser.add_argument("-v", "--verbose", action="store_true")  # 플래그
parser.add_argument("--count", type=int, default=1)          # 옵션
parser.add_argument("--format", choices=["json", "csv"], default="json")

args = parser.parse_args()
print(args.filename, args.verbose, args.count, args.format)

실행:

my-tool data.csv -v --count 5 --format json

args.filename, args.verbose 처럼 attribute로 접근.

add_argument 옵션

인자	의미
`type=int`	자동 형변환
`default=...`	기본값
`required=True`	필수
`nargs="?"`	0 또는 1개
`nargs="+"`	1개 이상
`nargs="*"`	0개 이상
`nargs=3`	정확히 3개
`action="store_true"`	플래그 (값 없이 True)
`action="count"`	횟수 카운트 (`-vvv` → 3)
`action="append"`	리스트로 누적
`choices=[...]`	허용 값 제한
`dest="..."`	저장 attribute 이름
`help="..."`	도움말

서브 커맨드

git처럼 mytool init, mytool build 등.

import argparse

parser = argparse.ArgumentParser()
subs = parser.add_subparsers(dest="cmd", required=True)

p_init = subs.add_parser("init", help="Initialize project")
p_init.add_argument("--name", required=True)

p_build = subs.add_parser("build", help="Build project")
p_build.add_argument("--release", action="store_true")

args = parser.parse_args()

if args.cmd == "init":
    init(args.name)
elif args.cmd == "build":
    build(release=args.release)

디스패치 패턴

각 서브 커맨드 함수를 매핑.

def cmd_init(args):
    print(f"init {args.name}")

def cmd_build(args):
    print(f"build (release={args.release})")

p_init.set_defaults(func=cmd_init)
p_build.set_defaults(func=cmd_build)

args = parser.parse_args()
args.func(args)

click

데코레이터 기반. argparse보다 간결하고 검증·도움말이 더 부드럽다.

import click

@click.command()
@click.argument("filename")
@click.option("-v", "--verbose", is_flag=True)
@click.option("--count", type=int, default=1)
def main(filename, verbose, count):
    """Process some integers."""
    print(filename, verbose, count)

if __name__ == "__main__":
    main()

서브 커맨드:

import click

@click.group()
def cli(): pass

@cli.command()
@click.option("--name", required=True)
def init(name):
    print(f"init {name}")

@cli.command()
@click.option("--release", is_flag=True)
def build(release):
    print(f"build {release}")

if __name__ == "__main__":
    cli()

click.echo, click.confirm, click.prompt, click.progressbar 같은 헬퍼가 많음.

typer

click 기반인데 타입 힌트로 CLI 자동 생성. argparse가 가진 보일러플레이트 거의 없음.

import typer

app = typer.Typer()

@app.command()
def hello(name: str, count: int = 1, verbose: bool = False):
    """Greet NAME COUNT times."""
    for _ in range(count):
        msg = f"Hello, {name}"
        if verbose:
            msg += " (verbose)"
        typer.echo(msg)

if __name__ == "__main__":
    app()

실행:

python script.py hello Alice --count 3 --verbose
python script.py hello --help    # 자동 생성된 도움말

typer는 함수 시그니처에서 옵션 이름·타입·기본값을 추출. --name은 인자 위치, --count는 키워드.

typer 서브 커맨드

app = typer.Typer()

@app.command()
def init(name: str):
    ...

@app.command()
def build(release: bool = False):
    ...

if __name__ == "__main__":
    app()

복잡한 옵션은 typer.Option/typer.Argument로 메타데이터 추가.

import typer

def main(
    name: str = typer.Argument(..., help="Your name"),
    count: int = typer.Option(1, "--count", "-c", help="How many times"),
    verbose: bool = typer.Option(False, "--verbose", "-v"),
):
    ...

if __name__ == "__main__":
    typer.run(main)

환경 변수 통합

# argparse
parser.add_argument("--api-key", default=os.environ.get("API_KEY"))

# click
@click.option("--api-key", envvar="API_KEY")

# typer
def main(api_key: str = typer.Option(..., envvar="API_KEY")):
    ...

설치 파일과 entry point

pyproject.toml에 진입점을 등록하면 pip install 후 시스템에서 명령어로 호출 가능.

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

pip install -e .
my-tool --help

my_package.cli:main은 모듈 경로 + 호출할 함수.

비교 표

항목	argparse	click	typer
의존성	stdlib	외부	외부 (click 위)
학습 곡선	중	낮	낮
타입 힌트 활용	X	X	O
검증	직접 작성 많음	내장	내장
도움말 자동 생성	기본	풍부	풍부
색상/프로그레스	X	내장	내장
자동완성	X	옵션	자동

작은 스크립트는 argparse, 다듬어진 CLI 도구는 click/typer 권장.

함정

1. argparse의 부정 가능한 플래그

# 단방향만
parser.add_argument("--verbose", action="store_true")

# 양방향 (3.9+)
parser.add_argument("--verbose", action=argparse.BooleanOptionalAction)
# 이제 --verbose / --no-verbose 둘 다 지원

2. 위치 인자와 옵션 순서

parser.add_argument("filename")
parser.add_argument("--verbose", action="store_true")

# OK
mytool data.csv --verbose
mytool --verbose data.csv

# 단, nargs="+"인 위치 인자가 있으면 옵션은 그 앞에
parser.add_argument("files", nargs="+")
mytool --verbose a.csv b.csv    # OK
mytool a.csv b.csv --verbose    # 모호함, 위치 인자에 흡수될 수 있음

3. choices와 type 동시

parser.add_argument("--level", choices=[1, 2, 3], type=int)
# 입력 문자열을 type으로 변환 후 choices 검사

순서 중요: type 적용 → choices 검사.

4. 인수 파싱 후 검증

argparse는 add_argument 단계 외에서 복잡한 cross-field 검증을 못 함. parse 후 직접 체크.

args = parser.parse_args()
if args.foo and args.bar:
    parser.error("--foo and --bar are mutually exclusive")

또는 add_mutually_exclusive_group().

[Python] Async Generator, async for, async with

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Python의 비동기 모델은 코루틴 + iterator의 조합으로 확장된다. 동기 generator가 lazy 시퀀스를 만들듯, async generator는 각 값 사이에 await가 가능한 lazy 비동기 시퀀스를 만든다.

async def + yield: async generator
async for: async iterator 순회
async with: async context manager

PEP 492 (async/await), PEP 525 (async generators), PEP 530 (async comprehensions).

async generator

import asyncio

async def fetch_pages(urls):
    for url in urls:
        page = await fetch(url)      # 매 페이지마다 await
        yield page                    # 호출자에게 yield

async def main():
    async for page in fetch_pages(urls):
        process(page)

asyncio.run(main())

async def 안에 yield가 있으면 호출 결과는 async generator 객체. async for로 순회하면서 각 await이 이벤트 루프에 양보.

async for

async for는 __aiter__()/__anext__()를 구현한 객체에서 사용 가능.

class AsyncCounter:
    def __init__(self, end):
        self.end = end

    def __aiter__(self):
        self.cur = 0
        return self

    async def __anext__(self):
        if self.cur >= self.end:
            raise StopAsyncIteration
        await asyncio.sleep(0.1)
        self.cur += 1
        return self.cur - 1

async def main():
    async for x in AsyncCounter(3):
        print(x)

asyncio.run(main())

대부분의 경우 클래스를 직접 작성하지 않고 async def + yield로 충분.

async comprehension

async def main():
    # async list comprehension
    pages = [await fetch(u) async for u in urls()]

    # 또는 async generator를 가져옴
    results = [item async for item in async_gen()]

    # async dict comprehension
    cache = {url: page async for url, page in fetch_with_url()}

    # async set, generator도 가능

async for 또는 await를 컴프리헨션 내에서 쓸 때 필요. 일반 컴프리헨션 안에 await만 있으면 컴프리헨션 자체는 동기, 호출 함수가 async여야 함.

async context manager

__aenter__, __aexit__로 비동기 자원 관리.

import aiohttp

async def main():
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as resp:
            text = await resp.text()

@asynccontextmanager (contextlib)로 함수 기반:

from contextlib import asynccontextmanager

@asynccontextmanager
async def db_connection():
    conn = await create_connection()
    try:
        yield conn
    finally:
        await conn.close()

async def main():
    async with db_connection() as conn:
        await conn.query("SELECT 1")

실용 예제

페이지네이션 API 스트리밍

async def list_all_repos(client, org):
    page = 1
    while True:
        repos = await client.get(f"/orgs/{org}/repos?page={page}")
        if not repos:
            break
        for repo in repos:
            yield repo
        page += 1

async def main():
    async for repo in list_all_repos(client, "python"):
        print(repo["name"])
        if repo["fork"]:
            continue

호출자는 한 페이지씩 받아 처리. 메모리에 전체 안 들고 있음. 페이지 사이 await으로 다른 작업 가능.

큐에서 비동기로 처리

import asyncio

async def consume(queue):
    while True:
        item = await queue.get()
        if item is None:    # 종료 신호
            break
        await process(item)
        queue.task_done()

async def main():
    queue = asyncio.Queue()
    workers = [asyncio.create_task(consume(queue)) for _ in range(5)]

    for item in items:
        await queue.put(item)

    for _ in workers:
        await queue.put(None)
    await asyncio.gather(*workers)

SSE / WebSocket 스트림

async def stream_events(url):
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as resp:
            async for line in resp.content:
                if line.startswith(b"data: "):
                    yield json.loads(line[6:])

async def main():
    async for event in stream_events("..."):
        handle(event)

함정

1. 동기 for vs async for

# WRONG: 동기 for로 async iterator
async def bad():
    for x in async_gen():    # TypeError: 'async_generator' object is not iterable
        ...

# OK
async def good():
    async for x in async_gen():
        ...

2. async generator에서 await asyncio.sleep(0) 없으면 양보 안 함

async def bad():
    for i in range(10 ** 6):
        yield i        # await 없음 → 이벤트 루프 점유

async def good():
    for i in range(10 ** 6):
        if i % 1000 == 0:
            await asyncio.sleep(0)    # 양보
        yield i

순수 yield는 awaitable이지만 빠르게 끝남. 명시적 양보(await asyncio.sleep(0))가 필요할 수 있음.

3. asyncio.gather와 async generator

# WRONG: gather는 awaitable 받음, async generator는 아님
results = await asyncio.gather(*async_gen())   # TypeError

# CORRECT
results = [x async for x in async_gen()]

4. close 안 하면 자원 누수

agen = async_gen()
async for x in agen:
    if cond:
        break
# break 후 agen이 close 안 됨

# 명시 close
await agen.aclose()

# 또는 await 가능한 GC 대기

anyio 같은 라이브러리가 더 안전한 wrapper 제공.

5. async generator 내부에서 yield 중 예외

async def gen():
    try:
        yield 1
        yield 2
    finally:
        print("cleanup")     # 항상 호출 (close 시에도)

generator close 시 GeneratorExit이 yield 지점에서 발생 → try/finally가 자원 정리.

동기 generator와 비교

	동기 generator	async generator
정의	`def + yield`	`async def + yield`
호출 결과	generator	async generator
순회	`for x in gen`	`async for x in gen`
return	StopIteration	StopAsyncIteration (자동)
사용 위치	어디서나	async 컨텍스트
양보	yield에서만	await에서 (yield는 호출자에게 값)

언제 async generator를 쓰나

외부 자원 페이지네이션 (HTTP, DB, S3 등) - 매 페이지가 비동기 I/O
WebSocket / SSE 스트리밍
큐 / 이벤트 스트림 처리
백프레셔 적용 (소비 속도에 맞춰 생산)

CPU 작업이나 단순 변환에는 동기 generator + asyncio.to_thread 조합이 더 명확할 수 있다.

[Python] asyncio: 이벤트 루프, async/await

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

asyncio는 Python 표준 라이브러리의 단일 스레드 이벤트 루프 기반 비동기 I/O 프레임워크다. async def로 코루틴을 정의하고 await로 다른 코루틴/awaitable 완료를 기다린다. I/O 바운드 작업(네트워크, 디스크, DB)에서 수천~수만 개 연결을 효율적으로 다룬다.

CPU 바운드 작업엔 부적합 → multiprocessing 또는 concurrent.futures.ProcessPoolExecutor 사용.

hello world

import asyncio

async def hello():
    print("hello")
    await asyncio.sleep(1)
    print("world")

asyncio.run(hello())

asyncio.run()이 이벤트 루프를 생성/실행/종료한다. 진입점은 이거 하나.

동시 실행: gather, TaskGroup

세 작업이 동시에 시작되어 가장 오래 걸리는 B(2초)에 맞춰 끝남. 순차 실행이었으면 4초.

TaskGroup (3.11+, PEP 654)

async def main():
    async with asyncio.TaskGroup() as tg:
        tg.create_task(fetch("A", 1))
        tg.create_task(fetch("B", 2))
        tg.create_task(fetch("C", 1))
    # 블록 종료 시 모든 task 완료 대기

gather보다 안전: 한 작업 실패 시 형제 작업을 자동 취소하고 ExceptionGroup으로 묶어 전파. 신규 코드는 TaskGroup 권장.

Task 생성

task = asyncio.create_task(fetch("X", 1))
# 코루틴은 즉시 스케줄링되어 실행 시작 (이벤트 루프가 양보받을 때)

result = await task           # 완료 대기
print(task.done())
task.cancel()                 # CancelledError 던짐

await 가능한 객체 (Awaitable)

Coroutine (async def로 만든 것)
Task (asyncio.create_task)
Future (asyncio.Future)
__await__을 구현한 객체

async def use():
    await asyncio.sleep(1)        # coroutine
    await asyncio.create_task(f()) # task
    await future                   # future

동기 코드를 비동기 컨텍스트에서 실행

이벤트 루프를 막는 동기 함수는 스레드 풀에 위임.

import asyncio
import time

def blocking():
    time.sleep(2)
    return "done"

async def main():
    result = await asyncio.to_thread(blocking)
    print(result)

asyncio.run(main())

to_thread(3.9+)는 run_in_executor(None, fn)의 편의 래퍼.

CPU 집약 작업은 ProcessPoolExecutor로:

from concurrent.futures import ProcessPoolExecutor

async def heavy():
    loop = asyncio.get_running_loop()
    with ProcessPoolExecutor() as pool:
        return await loop.run_in_executor(pool, compute, big_data)

타임아웃과 취소

try:
    async with asyncio.timeout(5):    # 3.11+
        await long_running()
except TimeoutError:
    print("timed out")

# 또는 3.11 이전
try:
    await asyncio.wait_for(long_running(), timeout=5)
except asyncio.TimeoutError:
    ...

asyncio.timeout()는 컨텍스트 매니저로 더 안전. wait_for는 wrapping 한 작업을 직접 cancel.

async 컨텍스트 매니저 / iterator

async with aiohttp.ClientSession() as session:
    async with session.get(url) as resp:
        text = await resp.text()

async for line in stream:
    process(line)

각각 __aenter__/__aexit__, __aiter__/__anext__ 구현.

동기화 프리미티브

asyncio도 thread와 비슷한 동기화 도구 제공 (모두 코루틴용).

lock = asyncio.Lock()
event = asyncio.Event()
sem = asyncio.Semaphore(10)
queue = asyncio.Queue(maxsize=100)

async with lock:
    critical()

await event.wait()
event.set()

async with sem:    # 동시 10개 제한
    await fetch()

await queue.put(item)
item = await queue.get()

코루틴 호출 vs await

async def f(): return 1

# WRONG: 코루틴 객체만 만들고 await 안 함 → 경고 "never awaited"
f()

# GOOD
result = await f()

async def 호출은 코루틴 객체 반환만. 실제 실행은 await(또는 task로 만든 후 루프가 실행).

흔한 함정

1. 블로킹 호출이 이벤트 루프 정지

async def bad():
    time.sleep(5)       # 이벤트 루프 5초 정지! 모든 동시 작업 멈춤

async def good():
    await asyncio.sleep(5)

open(), requests.get(), DB 동기 드라이버, CPU 집약 루프 모두 위험. 대안: aiohttp, asyncpg, to_thread.

2. async와 sync 혼용 시 한쪽이 다른 쪽 못 부름

async 함수에서 sync 함수: 그냥 호출 OK
sync 함수에서 async 함수: asyncio.run() 또는 새 루프 필요
라이브러리 작성자: 두 버전 모두 지원하기 위해 anyio 등 활용

3. CancelledError를 삼키지 말 것

async def task():
    try:
        await long()
    except Exception:    # CancelledError도 잡힘 (3.8+에선 BaseException)
        pass

CancelledError는 BaseException으로 분리(3.8+)되어 except Exception:엔 안 잡힘. 그래도 절대 명시적으로 무시 금지.

4. 다중 await의 순서

# 순차: 총 2초
await f1()
await f2()

# 동시: 총 max 시간
await asyncio.gather(f1(), f2())

동기 vs 비동기 모델 비교

모델	동시성	적합한 작업	비용
threading	OS 스레드	I/O (GIL 때문에 CPU는 X)	스레드당 메모리
multiprocessing	별도 프로세스	CPU 집약	프로세스 오버헤드
asyncio	단일 스레드 코루틴	I/O 대량 동시	가장 가벼움
free-threaded (3.13+)	OS 스레드, GIL 없음	CPU+I/O	실험적

[Python] bytes, bytearray, memoryview

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Python에서 바이너리 데이터는 세 가지 타입으로 다룬다.

bytes: 불변 바이트 시퀀스. 0~255 정수의 immutable 배열.
bytearray: 가변 바이트 시퀀스. bytes의 mutable 형제.
memoryview: 다른 객체의 메모리 버퍼를 복사 없이 보는 뷰.

bytes 리터럴

b1 = b"hello"               # ASCII
b2 = b"\\x00\\xff\\x7f"     # 16진 이스케이프
b3 = b"\\n\\t"              # 제어 문자
b4 = bytes([72, 101, 108, 108, 111])   # 정수 시퀀스
b5 = bytes(5)               # b'\\x00\\x00\\x00\\x00\\x00' (영바이트)

# 비ASCII 문자는 안됨: b"안녕"은 SyntaxError

str과 bytes 변환

문자열은 추상 유니코드, bytes는 실제 바이트. 변환에는 인코딩이 필요하다.

잘못된 인코딩 시 UnicodeDecodeError. errors= 인자로 처리 전략 지정.

b = b"\\xff\\xfe"
b.decode("utf-8")                          # UnicodeDecodeError
b.decode("utf-8", errors="ignore")         # ""
b.decode("utf-8", errors="replace")        # "\ufffd\ufffd"

bytes 메서드

str과 거의 같은 메서드를 갖는다 (split, replace, startswith 등).

중요: bytes 메서드 인자도 bytes여야 한다. b.find("world")는 TypeError.

bytearray: 가변 버전

ba = bytearray(b"hello")
ba[0] = 72                      # OK (정수 할당)
ba.append(33)                   # b'Hello!' 끝에 !
ba.extend(b" world")
print(ba)                       # bytearray(b'Hello! world')

# bytes로 변환
b = bytes(ba)

대용량 바이너리 처리 시 bytes 연결 반복(b1 + b2)은 매번 새 객체 생성으로 느리다. bytearray.extend() 또는 io.BytesIO를 사용.

from io import BytesIO
buf = BytesIO()
for chunk in chunks:
    buf.write(chunk)
data = buf.getvalue()

인덱싱 함정

bytes의 단일 인덱싱은 정수를 반환한다. 슬라이싱은 bytes를 반환.

C/Go의 byte slice와 다른 점. b[0] == "a"는 False, b[0] == ord("a")는 True.

16진/Base64 변환

b = b"hello"

b.hex()              # '68656c6c6f'
bytes.fromhex("68656c6c6f")    # b'hello'

import base64
base64.b64encode(b)              # b'aGVsbG8='
base64.b64decode(b"aGVsbG8=")    # b'hello'

struct: 바이너리 포맷 변환

C 구조체 같은 고정 포맷 직렬화.

포맷 코드: i=int32, q=int64, f=float32, d=double, s=char[n]. <=little-endian, >=big-endian.

memoryview: 복사 없는 뷰

큰 bytes/bytearray의 일부를 잘라 다른 함수에 넘길 때 b[100:200]은 복사를 만든다. memoryview(b)[100:200]은 복사 없이 뷰만.

대용량 네트워크 버퍼·파일 처리에서 메모리 절감에 유용.

언제 무엇을 쓰나

용도	선택
네트워크 페이로드, 파일 읽기	`bytes`
인코딩 후 변경 필요	`bytearray`
큰 버퍼의 일부만 처리	`memoryview`
C 구조체 ↔ 바이트 변환	`struct`
수치 배열, 산술 연산	`numpy.ndarray`
이미지/오디오	`bytes` + 라이브러리 (Pillow, soundfile)

타입 관계

flowchart LR
    STR["str (유니코드)"] -->|".encode()"| B["bytes (불변)"]
    B -->|".decode()"| STR
    B -->|"bytearray(b)"| BA["bytearray (가변)"]
    BA -->|"bytes(ba)"| B
    B -->|"memoryview(b)"| MV["memoryview (뷰)"]
    BA -->|"memoryview(ba)"| MV
    MV -->|"bytes(mv)"| B

성능 고려사항

bytes 연결 반복은 느리다

# 나쁜 예: O(n^2) - 매번 새 객체 생성
result = b""
for chunk in chunks:
    result += chunk

# 좋은 예 1: bytearray
result = bytearray()
for chunk in chunks:
    result.extend(chunk)
final = bytes(result)

# 좋은 예 2: join
final = b"".join(chunks)

memoryview 슬라이싱 vs bytes 슬라이싱

대용량 데이터를 여러 chunk 로 나눌 때 b[1000:2000] 은 복사 발생. memoryview(b)[1000:2000] 은 복사 없이 뷰만 반환해 메모리를 아낀다.

from io import BytesIO

# 스트림 방식: 대용량 파일 분할 전송
def chunked_read(path: str, chunk_size: int = 65536):
    with open(path, "rb") as f:
        while chunk := f.read(chunk_size):
            yield chunk

실용 패턴

네트워크 프로토콜 파싱

import struct

def parse_packet(data: bytes) -> dict:
    # 헤더: version(1B), type(1B), length(2B big-endian), checksum(4B)
    header_fmt = ">BBHi"
    header_size = struct.calcsize(header_fmt)
    version, ptype, length, checksum = struct.unpack(
        header_fmt, data[:header_size]
    )
    payload = data[header_size : header_size + length]
    return {
        "version": version,
        "type": ptype,
        "payload": payload,
        "checksum": checksum,
    }

소켓 메시지 송수신 (길이 프리픽스 방식)

import socket, struct

def send_msg(sock: socket.socket, msg: str) -> None:
    payload = msg.encode("utf-8")
    header = struct.pack(">I", len(payload))   # 4B 길이
    sock.sendall(header + payload)

def recv_msg(sock: socket.socket) -> str:
    raw_len = sock.recv(4)
    length = struct.unpack(">I", raw_len)[0]
    buf = bytearray()
    while len(buf) < length:
        chunk = sock.recv(length - len(buf))
        if not chunk:
            raise ConnectionError("연결 끊김")
        buf.extend(chunk)
    return buf.decode("utf-8")

함정

bytes 비교 시 인코딩 불일치

s = "안녕"
utf8  = s.encode("utf-8")
euckr = s.encode("euc-kr")
utf8 == euckr    # False (같은 문자, 다른 바이트)

항상 인코딩을 명시. 네트워크/파일에서 받은 데이터의 인코딩은 별도 확인 필요.

단일 인덱싱은 int

b = b"ABC"
b[0]              # 65 (int, b'A' 아님)
b[0] == "A"       # False
b[0] == ord("A")  # True

b[0:1] 슬라이싱은 bytes 반환.

bytearray.append 에는 정수만

ba = bytearray()
ba.append(65)       # ✓ OK
ba.append(b"A")     # ❌ TypeError
ba.extend(b"A")     # ✓ iterable 가능
ba += b"B"          # ✓ 가능

bytes 는 비ASCII 리터럴 불가

b"안녕"    # ❌ SyntaxError
"안녕".encode("utf-8")   # ✓ 변환 필요

[Python] class 기초: 정의, init, self

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

클래스 정의

class Point:
    """2D 점."""

    def __init__(self, x, y):    # 생성자 (정확히는 초기화)
        self.x = x
        self.y = y

    def distance(self, other):
        dx = self.x - other.x
        dy = self.y - other.y
        return (dx ** 2 + dy ** 2) ** 0.5

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

p = Point(3, 4)
q = Point(0, 0)
print(p.distance(q))    # 5.0
print(p)                # Point(3, 4)

self

Python 메서드의 첫 번째 인수는 인스턴스 자신이다. 관례적으로 self라 부른다(언어가 강제하진 않지만 PEP 8 권장).

class C:
    def method(self_or_anything):    # 동작하지만 비권장
        pass

호출 시 p.method()는 내부적으로 C.method(p)로 바인딩된다. 메서드 = 첫 인수가 인스턴스인 함수.

init: 초기화

__init__은 인스턴스가 만들어진 후 호출되어 속성을 초기화한다. 실제 생성은 __new__. 99%의 경우 __init__만 정의.

class User:
    def __init__(self, name, age=0):
        self.name = name
        self.age = age
        self._login_count = 0    # 관례: _ 접두 = 내부용

u = User("Alice", 30)

__init__은 항상 None을 반환해야 한다. return 값이 있으면 TypeError.

클래스 변수 vs 인스턴스 변수

	정의 위치	공유
클래스 변수	클래스 본문 (메서드 밖)	모든 인스턴스 공유
인스턴스 변수	`__init__` 등에서 `self.xxx = ...`	인스턴스별

함정: 가변 클래스 변수는 모든 인스턴스가 공유한다.

class Bad:
    items = []           # 공유됨!
    def add(self, x):
        self.items.append(x)

a, b = Bad(), Bad()
a.add(1)
b.add(2)
print(a.items)   # [1, 2]  (!!)

class Good:
    def __init__(self):
        self.items = []   # 인스턴스별

메서드 종류

인스턴스 메서드

기본. self를 첫 인수로.

class C:
    def instance_method(self, x):
        return self.value + x

클래스 메서드 `@classmethod`

cls를 첫 인수로. 클래스 자체를 다룬다. 팩토리 메서드로 자주 사용.

class Date:
    def __init__(self, y, m, d):
        self.y, self.m, self.d = y, m, d

    @classmethod
    def from_string(cls, s):
        y, m, d = map(int, s.split("-"))
        return cls(y, m, d)         # 서브클래스 대응

d = Date.from_string("2026-06-20")

정적 메서드 `@staticmethod`

인스턴스도 클래스도 안 받는다. 사실상 네임스페이스 정리 목적.

class MathUtil:
    @staticmethod
    def clamp(x, lo, hi):
        return max(lo, min(hi, x))

MathUtil.clamp(5, 0, 10)

대부분의 경우 모듈 수준 함수가 더 Pythonic. staticmethod는 클래스 안에 두는 게 의미적으로 명확할 때만.

속성 접근과 동적 속성

Python 객체는 기본적으로 속성 동적 추가가 가능하다.

이를 막으려면 __slots__ (메모리 절감 효과도).

class Point:
    __slots__ = ("x", "y")
    def __init__(self, x, y):
        self.x, self.y = x, y

p = Point(1, 2)
p.z = 3   # AttributeError

repr vs str

class User:
    def __init__(self, name):
        self.name = name

    def __repr__(self):
        return f"User({self.name!r})"    # 개발자용 (재현 가능)

    def __str__(self):
        return f"User: {self.name}"      # 사용자용 (보기 좋음)

u = User("Alice")
print(repr(u))   # User('Alice')
print(str(u))    # User: Alice
print(u)         # User: Alice (str 우선)

__str__이 없으면 __repr__을 폴백한다. 항상 __repr__을 정의하는 게 좋다 (디버깅, 로그, 리스트 출력 시 사용됨).

비교와 해싱

기본 ==는 객체 동일성. 값 비교를 원하면 __eq__ 구현.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented
        return (self.x, self.y) == (other.x, other.y)

    def __hash__(self):
        return hash((self.x, self.y))

__eq__ 정의하면 __hash__가 자동으로 None이 되어 hashable이 아니게 된다. set/dict 키로 쓰려면 같이 정의.

대부분 @dataclass로 자동 생성하는 게 편함.

클래스도 객체

class C: pass

print(type(C))         # <class 'type'>
print(isinstance(C, type))   # True

# 동적 생성
D = type("D", (), {"x": 1})
print(D().x)           # 1

클래스는 type의 인스턴스. metaclass 개념의 출발점.

[Python] collections: Counter, deque, defaultdict, OrderedDict, ChainMap

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

collections 모듈은 dict/list/tuple/set의 특수화 컨테이너를 제공한다. 표준 라이브러리에 있는 데이터 구조 도구함의 핵심.

클래스	용도
`Counter`	해시 가능한 객체의 빈도
`deque`	양끝 O(1) 큐/스택
`defaultdict`	키 부재 시 자동 기본값
`OrderedDict`	순서 보존 dict + 추가 메서드
`ChainMap`	여러 dict를 하나로
`namedtuple`	필드명 있는 불변 튜플
`UserDict`/`UserList`/`UserString`	서브클래싱 친화

Counter

빈도 계산의 표준.

Counter.update()는 합하기 (덮어쓰기가 아닌 누적). 인자는 iterable이나 mapping.

deque (Double-ended Queue)

양끝에서 O(1) 추가/삭제. list의 insert(0, ...) / pop(0)는 O(n)이라 부적합.

from collections import deque

d = deque([1, 2, 3], maxlen=5)
d.append(4)              # 오른쪽 O(1)
d.appendleft(0)          # 왼쪽 O(1)
d.pop()                  # 오른쪽 O(1)
d.popleft()              # 왼쪽 O(1)
d.rotate(2)              # 오른쪽으로 2칸 (-는 왼쪽)
d.extendleft([1, 2, 3])  # 역순으로 왼쪽에 붙음

maxlen 지정 시 한쪽이 차면 반대편 원소가 자동 제거 → 슬라이딩 윈도우, 최근 N개 캐시에 유용.

recent = deque(maxlen=10)
for event in stream:
    recent.append(event)    # 항상 최근 10개만

큐(FIFO)로 쓰려면 append + popleft. 스택(LIFO)도 가능 (append + pop).

defaultdict

키가 없을 때 자동으로 기본 인스턴스 생성. 그룹핑·카운팅에 표준.

<CodeWithOutput language=“python” outputLanguage=“text” code={`from collections import defaultdict

리스트 그룹핑

words = [“apple”, “banana”, “avocado”, “blueberry”] by_first = defaultdict(list) for w in words: by_first[w[0]].append(w) print(dict(by_first))

카운터 (Counter가 더 편함)

freq = defaultdict(int) for ch in “hello”: freq[ch] += 1 print(dict(freq))

중첩 dict

matrix = defaultdict(lambda: defaultdict(int)) matrix[“a”][“b”] += 1 print(dict(matrix))} output={{‘a’: [‘apple’, ‘avocado’], ‘b’: [‘banana’, ‘blueberry’]} {‘h’: 1, ‘e’: 1, ‘l’: 2, ‘o’: 1} {‘a’: defaultdict(<class ‘int’>, {‘b’: 1})}`} />

생성자 인자는 호출 가능한 객체. int → 0, list → [], set → set(), lambda: ... → 임의.

함정: 키 부재 시 자동 생성되므로 단순 조회만 했는데 키가 추가될 수 있다.

d = defaultdict(list)
print(d["x"])    # []
print(d)         # {'x': []}  (!! 추가됨)

# 조회만 원하면
print(d.get("x"))   # None, dict 변경 없음

OrderedDict

Python 3.7+ 부터 일반 dict도 삽입 순서 보장. 그래도 OrderedDict가 가지는 추가 기능:

move_to_end(key, last=True): 키를 끝(또는 앞)으로
popitem(last=True): LIFO/FIFO 선택
동등성 비교가 순서까지 고려 (OrderedDict(a=1, b=2) != OrderedDict(b=2, a=1), dict는 같다고 판단)
LRU 캐시 같은 자료구조 직접 구현 시 유용

from collections import OrderedDict

class LRUCache:
    def __init__(self, capacity):
        self.cap = capacity
        self.d = OrderedDict()

    def get(self, key):
        if key not in self.d:
            return None
        self.d.move_to_end(key)
        return self.d[key]

    def put(self, key, value):
        if key in self.d:
            self.d.move_to_end(key)
        self.d[key] = value
        if len(self.d) > self.cap:
            self.d.popitem(last=False)    # FIFO 제거

functools.lru_cache가 대부분의 경우 더 빠르고 안전.

ChainMap

여러 dict를 하나의 뷰로 합친다. 변경은 첫 번째에만.

활용: 설정 우선순위 (CLI > env > config > default), 스코프 시뮬레이션, 임시 컨텍스트.

namedtuple

py-tuple 페이지에서 자세히. 짧게:

from collections import namedtuple

Point = namedtuple("Point", ["x", "y"])
p = Point(3, 4)
print(p.x, p[1], p._asdict())

@dataclass와 typing.NamedTuple이 더 강력. 기존 코드 호환 외엔 새로 namedtuple 쓰지 않아도 됨.

UserDict / UserList / UserString

내장 타입을 상속하는 대신 이걸 상속하면 안전하게 메서드 오버라이드 가능. (내장 dict/list 직접 상속은 일부 내부 메서드가 우회되는 함정이 있음.)

from collections import UserDict

class CaseInsensitiveDict(UserDict):
    def __setitem__(self, key, value):
        super().__setitem__(key.lower(), value)

    def __getitem__(self, key):
        return super().__getitem__(key.lower())

d = CaseInsensitiveDict()
d["Hello"] = 1
print(d["HELLO"])    # 1

자주 결합되는 패턴

그래프 BFS

from collections import deque, defaultdict

graph = defaultdict(list)
visited = set()
q = deque([start])
while q:
    node = q.popleft()
    if node in visited: continue
    visited.add(node)
    q.extend(graph[node])

윈도우 최대값 (deque + 단조 큐)

def max_window(nums, k):
    q, out = deque(), []
    for i, x in enumerate(nums):
        while q and nums[q[-1]] < x:
            q.pop()
        q.append(i)
        if q[0] <= i - k:
            q.popleft()
        if i >= k - 1:
            out.append(nums[q[0]])
    return out

N-gram 빈도

from collections import Counter

def ngrams(seq, n):
    return zip(*(seq[i:] for i in range(n)))

text = "abracadabra"
print(Counter(ngrams(text, 2)).most_common(3))

[Python] collections.abc: 추상 컬렉션 인터페이스

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

collections.abc는 컬렉션의 추상 베이스 클래스를 제공한다. 사용자 정의 컬렉션이 빌트인과 같은 인터페이스를 구현했음을 명시하거나, isinstance 검사에 사용. PEP 3119.

타입 힌트에서도 자주 보임 (Sequence[int]는 list[int]보다 일반적).

주요 ABC 계층

Container          __contains__
Hashable           __hash__
Iterable           __iter__
Iterator           __next__, __iter__       ← Iterable
Reversible         __reversed__              ← Iterable
Sized              __len__
Callable           __call__
Collection         __contains__, __iter__, __len__   ← Iterable, Container, Sized

Sequence           __getitem__, __len__              ← Reversible, Collection
                   index, count, __iter__, __contains__, __reversed__
MutableSequence    __setitem__, __delitem__, insert  ← Sequence
                   append, extend, pop, remove, clear

Set                __contains__, __iter__, __len__   ← Collection
                   __le__, __lt__, __eq__, __ne__, __gt__, __ge__
                   __and__, __or__, __sub__, __xor__, isdisjoint
MutableSet         add, discard                       ← Set
                   clear, pop, remove

Mapping            __getitem__, __len__, __iter__    ← Collection
                   __contains__, keys, items, values, get, __eq__, __ne__
MutableMapping     __setitem__, __delitem__          ← Mapping
                   pop, popitem, clear, update, setdefault

MappingView        __len__
ItemsView          __iter__, __contains__            ← MappingView, Set
KeysView           __contains__, __iter__            ← MappingView, Set
ValuesView         __iter__, __contains__            ← MappingView

Awaitable          __await__
Coroutine          send, throw, close                 ← Awaitable
AsyncIterable      __aiter__
AsyncIterator      __anext__, __aiter__              ← AsyncIterable
AsyncGenerator     asend, athrow                     ← AsyncIterator

isinstance 검사

from collections.abc import Iterable, Sequence, Mapping

isinstance([1, 2, 3], Iterable)     # True
isinstance("abc", Iterable)          # True
isinstance({"a": 1}, Iterable)       # True (키 순회)
isinstance(42, Iterable)             # False

isinstance([1, 2, 3], Sequence)     # True
isinstance({1, 2, 3}, Sequence)     # False (순서 없음)
isinstance("abc", Sequence)          # True
isinstance(b"abc", Sequence)         # True

isinstance({}, Mapping)             # True
isinstance({}.keys(), Set)           # True (set처럼 다룰 수 있음)

빌트인 타입들은 자동으로 적절한 ABC에 등록됨.

타입 힌트에 활용

함수 인자를 구체 타입(list, dict)으로 제한하지 말고 ABC로.

from collections.abc import Iterable, Mapping, Sequence

def sum_all(xs: Iterable[int]) -> int:
    return sum(xs)
# list, tuple, set, generator 모두 받음

def show(items: Sequence[str]) -> None:
    for i, x in enumerate(items):
        print(i, x)
# list, tuple만 (인덱싱 가능)

def update_settings(s: Mapping[str, int]) -> None:
    for k, v in s.items():
        ...
# dict뿐 아니라 임의 mapping

라이브러리 함수는 가능한 한 일반적 ABC. 호출자가 다양한 타입을 자유롭게 넘길 수 있다.

typing.Iterable 등은 collections.abc.Iterable의 별칭 (3.9+).

직접 컬렉션 만들기

ABC를 상속해 일부 메서드만 구현하면 나머지가 자동 제공.

from collections.abc import MutableSequence

class IntList(MutableSequence):
    def __init__(self):
        self._items = []

    def __getitem__(self, i):
        return self._items[i]

    def __setitem__(self, i, v):
        if not isinstance(v, int):
            raise TypeError("int only")
        self._items[i] = v

    def __delitem__(self, i):
        del self._items[i]

    def __len__(self):
        return len(self._items)

    def insert(self, i, v):
        if not isinstance(v, int):
            raise TypeError("int only")
        self._items.insert(i, v)

# append, extend, pop, remove, clear, reverse, __contains__, __iter__,
# index, count 등은 ABC가 자동 제공

lst = IntList()
lst.append(1)
lst.append(2)
lst.extend([3, 4])
print(list(lst), len(lst))     # 자동
lst.remove(2)

abstractmethod만 구현하면 나머지가 무료. 다만 효율적인 직접 구현이 더 나을 수 있음.

가상 서브클래스 (register)

명시적 상속 없이 ABC 호환 표현.

from collections.abc import Sized

class MyContainer:
    def __init__(self):
        self.size = 0
    def __len__(self):
        return self.size

Sized.register(MyContainer)
isinstance(MyContainer(), Sized)    # True

또는 __subclasshook__로 자동 등록 (모든 ABC가 이 방식 사용).

Hashable의 의미

from collections.abc import Hashable

isinstance("abc", Hashable)    # True
isinstance((1, 2), Hashable)   # True
isinstance([1, 2], Hashable)   # False (mutable)
isinstance({1, 2}, Hashable)   # False
isinstance(frozenset(), Hashable)    # True

__hash__가 None이면 Hashable 아님. 가변 컨테이너 검사에 활용.

비교: typing vs collections.abc

# typing (3.9 이전)
from typing import Iterable, List, Dict
def f(xs: Iterable[int]) -> List[int]: ...

# 3.9+ collections.abc + 내장 generic
from collections.abc import Iterable
def f(xs: Iterable[int]) -> list[int]: ...

3.9+에선 typing.Iterable 대신 collections.abc.Iterable이 표준.

자주 보는 활용

duck typing 명시

def process(items):
    if isinstance(items, Mapping):
        for k, v in items.items():
            handle(k, v)
    elif isinstance(items, Iterable):
        for x in items:
            handle(x)
    else:
        raise TypeError

dict이냐 list이냐 같은 구체 검사보다 인터페이스로.

dict의 view를 set처럼

a = {"x": 1, "y": 2}
b = {"y": 99, "z": 3}

a.keys() & b.keys()    # {"y"}  (set 연산이 가능!)

dict.keys()는 KeysView (Set의 서브클래스). 자연스럽게 집합 연산.

Mapping 인터페이스 구현

from collections.abc import Mapping

class CaseInsensitiveDict(Mapping):
    def __init__(self, data=None):
        self._data = {}
        if data:
            for k, v in dict(data).items():
                self[k.lower()] = v

    def __setitem__(self, k, v):
        self._data[k.lower()] = v

    def __getitem__(self, k):
        return self._data[k.lower()]

    def __iter__(self):
        return iter(self._data)

    def __len__(self):
        return len(self._data)

MutableMapping을 상속하면 update, pop, setdefault, items, keys, values, get 등 모두 무료.

함정

1. Sequence ≠ Iterable

def f(xs: Sequence[int]) -> int:
    return xs[0]    # 인덱싱 필요

# generator는 Iterable이지만 Sequence는 아님
f(x for x in [1, 2, 3])    # 타입 체커 에러 또는 런타임 인덱싱 실패

인덱싱이 필요하면 Sequence. 한 번 순회만이면 Iterable.

2. Set 부분집합 검사

{1, 2} <= {1, 2, 3}    # True (Set은 < <= 비교 정의)

list와 다른 의미라 헷갈리지 말 것.

3. dict의 itertools 호환

dict.items()는 Iterable이라 itertools.chain, map 등에 전달 가능.

import itertools
list(itertools.chain(d1.items(), d2.items()))

[Python] concurrent.futures: ThreadPoolExecutor, ProcessPoolExecutor

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

concurrent.futures는 threading과 multiprocessing 위에 고수준 Executor 인터페이스를 제공한다. 워커 풀, Future 객체, map/submit API로 동기 코드처럼 병렬 작업을 작성할 수 있다.

두 Executor

from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor

# I/O 바운드 → 스레드
with ThreadPoolExecutor(max_workers=10) as ex:
    results = list(ex.map(fetch, urls))

# CPU 바운드 → 프로세스
with ProcessPoolExecutor(max_workers=4) as ex:
    results = list(ex.map(compute_hash, files))

선택 기준은 threading/multiprocessing 페이지와 동일.

submit + Future

submit은 작업을 큐에 넣고 Future 즉시 반환. result()로 완료 대기.

from concurrent.futures import ThreadPoolExecutor

def fetch(url):
    import requests
    return requests.get(url).text

with ThreadPoolExecutor(max_workers=5) as ex:
    futures = [ex.submit(fetch, u) for u in urls]
    for f in futures:
        result = f.result(timeout=30)
        process(result)

f.result() 호출 시 완료 대기. 작업 예외도 여기서 전파됨.

as_completed

완료 순서로 결과 받기.

from concurrent.futures import ThreadPoolExecutor, as_completed

with ThreadPoolExecutor(max_workers=5) as ex:
    futures = {ex.submit(fetch, u): u for u in urls}
    for f in as_completed(futures):
        url = futures[f]
        try:
            data = f.result()
            print(f"{url}: ok")
        except Exception as e:
            print(f"{url}: {e}")

오래 걸리는 작업이 빠른 작업을 막지 않음. 진행 상황 표시 / 빠른 결과부터 처리에 유용.

map

submit + as_completed의 편의 래퍼. 순서 보존.

with ThreadPoolExecutor() as ex:
    for url, data in zip(urls, ex.map(fetch, urls)):
        print(url, len(data))

map(timeout=N)은 한 작업이 N초 초과 시 TimeoutError.

chunksize 인자는 ProcessPoolExecutor에서만 유의미 (IPC 비용 줄임).

Future 메서드

f = ex.submit(fn, arg)

f.result(timeout=None)    # 결과 (블록)
f.exception(timeout=None) # 예외 (None이면 정상)
f.done()                  # bool
f.running()
f.cancelled()
f.cancel()                # 시작 전이면 cancel, 후이면 False
f.add_done_callback(cb)   # 완료 시 cb(f) 호출

콜백 패턴:

def on_done(f):
    try:
        print("result:", f.result())
    except Exception as e:
        print("error:", e)

f = ex.submit(work)
f.add_done_callback(on_done)

예외 처리

def risky():
    raise ValueError("oops")

with ThreadPoolExecutor() as ex:
    f = ex.submit(risky)
    try:
        f.result()
    except ValueError as e:
        print("caught:", e)

작업 안 예외는 Future에 저장. result() 호출 시 재발생. exception()은 던지지 않고 반환.

map은 첫 예외에서 iteration 중단 → 나머지 결과 누락.

타임아웃

import concurrent.futures

with ThreadPoolExecutor() as ex:
    f = ex.submit(slow_work)
    try:
        result = f.result(timeout=5)
    except concurrent.futures.TimeoutError:
        # 주의: 작업이 실제로 중단되지 않음, 결과 무시만
        ...

result(timeout)은 대기 타임아웃일 뿐 작업 자체를 중지하지 않는다 (Python 스레드는 강제 종료 불가). 진짜 중단이 필요하면 작업 안에서 자체 플래그 확인.

wait

여러 Future를 한 번에 대기.

from concurrent.futures import wait, ALL_COMPLETED, FIRST_COMPLETED, FIRST_EXCEPTION

futures = [ex.submit(work, i) for i in range(10)]

done, not_done = wait(futures, timeout=10, return_when=FIRST_COMPLETED)
for f in done:
    print(f.result())

return_when:

ALL_COMPLETED (기본): 모두 완료
FIRST_COMPLETED: 하나라도 완료
FIRST_EXCEPTION: 하나라도 예외

ProcessPoolExecutor 함정

if __name__ == "__main__": 가드 필수 (Windows/spawn)
워커에 전달되는 함수/인자는 pickle 가능해야
큰 데이터 전달 시 직렬화 비용 큼
자식 프로세스의 import time 비용 (spawn 모드)

if __name__ == "__main__":
    with ProcessPoolExecutor() as ex:
        results = list(ex.map(work, data))

워커 수 결정

import os

# CPU 바운드
ProcessPoolExecutor(max_workers=os.cpu_count())

# I/O 바운드 (스레드)
ThreadPoolExecutor(max_workers=os.cpu_count() * 5)    # 또는 더 많이
ThreadPoolExecutor(max_workers=min(32, (os.cpu_count() or 1) + 4))  # 3.8+ 기본

I/O 바운드는 스레드가 대기에 많아 더 많아도 됨. CPU는 코어 수 근처.

진행 표시 (tqdm)

from concurrent.futures import ThreadPoolExecutor, as_completed
from tqdm import tqdm

with ThreadPoolExecutor() as ex:
    futures = [ex.submit(fetch, u) for u in urls]
    for f in tqdm(as_completed(futures), total=len(urls)):
        process(f.result())

자주 보는 패턴

다운로드 워커 풀

from concurrent.futures import ThreadPoolExecutor
import requests

def download(url, dest):
    r = requests.get(url, stream=True)
    with open(dest, "wb") as f:
        for chunk in r.iter_content(64 * 1024):
            f.write(chunk)
    return dest

with ThreadPoolExecutor(max_workers=10) as ex:
    futures = {ex.submit(download, u, f"out/{i}.bin"): i for i, u in enumerate(urls)}
    for f in as_completed(futures):
        i = futures[f]
        try:
            f.result()
            print(f"{i} done")
        except Exception as e:
            print(f"{i} failed: {e}")

CPU 병렬 변환

from concurrent.futures import ProcessPoolExecutor

def compress_image(path):
    img = Image.open(path)
    img.thumbnail((1024, 1024))
    out = path.replace(".jpg", "_small.jpg")
    img.save(out, optimize=True)
    return out

if __name__ == "__main__":
    paths = list(Path("photos").glob("*.jpg"))
    with ProcessPoolExecutor() as ex:
        for out in ex.map(compress_image, paths, chunksize=10):
            print(out)

시간 제한 + 폴백

from concurrent.futures import ThreadPoolExecutor, TimeoutError

with ThreadPoolExecutor() as ex:
    f = ex.submit(primary_api)
    try:
        result = f.result(timeout=2)
    except TimeoutError:
        f.cancel()
        result = fallback_api()

(작업 cancel은 시작 전만 효과. 시작 후엔 작업이 자체 중단 메커니즘 필요.)

asyncio와의 통합

asyncio.run_in_executor로 동기 함수를 비동기 컨텍스트에서 실행.

import asyncio
from concurrent.futures import ThreadPoolExecutor

async def main():
    loop = asyncio.get_running_loop()
    with ThreadPoolExecutor() as ex:
        result = await loop.run_in_executor(ex, blocking_io_call)

asyncio.run(main())

3.9+ 편의 함수: asyncio.to_thread(fn, *args) (내부적으로 default executor).

[Python] Context Manager: with, enter, contextlib

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Context manager는 __enter__와 __exit__ 메서드를 가진 객체로, with 문을 통해 자원 획득/해제를 안전하게 묶는다. 파일·락·DB 트랜잭션·임시 설정처럼 “들어가면 반드시 나와야 하는” 작업의 표준 패턴.

with 기본

with open("file.txt") as f:
    data = f.read()
# f.close() 자동 호출 (예외 발생해도)

with open("x.txt") as r, open("y.txt", "w") as w:
    w.write(r.read())

with 블록은 다음과 거의 동등:

mgr = open("file.txt")
f = mgr.__enter__()
try:
    data = f.read()
except BaseException as e:
    if not mgr.__exit__(type(e), e, e.__traceback__):
        raise
else:
    mgr.__exit__(None, None, None)

클래스로 만들기

import time

class Timer:
    def __init__(self, label):
        self.label = label

    def __enter__(self):
        self.start = time.perf_counter()
        return self                # as 변수에 바인딩 (필수 아님)

    def __exit__(self, exc_type, exc_value, traceback):
        elapsed = time.perf_counter() - self.start
        print(f"{self.label}: {elapsed:.4f}s")
        return False               # 예외 재발생 (True면 삼킴)

with Timer("work"):
    sum(range(10 ** 6))

__exit__ 반환값:

falsy: 예외 전파 (정상)
truthy: 예외 삼킴 (드물게 의도적으로)

contextlib.contextmanager

함수에 @contextmanager 데코레이터를 붙이고 yield 한 번. 클래스보다 훨씬 간단.

yield 전 = __enter__, yield 후 = __exit__. try/finally로 정리 보장.

yield value처럼 값을 넘기면 with ... as v로 받을 수 있다.

@contextmanager
def temp_dir():
    import tempfile, shutil, os
    path = tempfile.mkdtemp()
    try:
        yield path
    finally:
        shutil.rmtree(path)

with temp_dir() as d:
    print(d)    # /tmp/...

표준 라이브러리에서 자주 보는 context manager

자원	매니저
파일	`open(path)`
락	`threading.Lock()`, `multiprocessing.Lock()`
DB 커넥션	`sqlite3.connect()` (with 시 트랜잭션)
HTTP 세션	`requests.Session()`, `httpx.Client()`
잠시 stdout 가리기	`contextlib.redirect_stdout(buf)`
예외 묵살	`contextlib.suppress(KeyError)`
임시 디렉터리	`tempfile.TemporaryDirectory()`
변경 가능한 상태 잠시 변경	`unittest.mock.patch(...)`

from contextlib import suppress

with suppress(FileNotFoundError):
    os.remove("temp")

ExitStack: 동적 컨텍스트 합치기

여러 자원을 동적 개수로 묶을 때 (체이닝 with 문법은 컴파일 시점 고정).

from contextlib import ExitStack

paths = ["a.txt", "b.txt", "c.txt"]
with ExitStack() as stack:
    files = [stack.enter_context(open(p)) for p in paths]
    process(files)
# 모든 파일 자동 close (역순으로)

콜백도 등록 가능:

with ExitStack() as stack:
    stack.callback(print, "cleanup 1")
    stack.callback(print, "cleanup 2")
    work()
# 등록 역순으로 cleanup 2, cleanup 1 실행

async with (async context manager)

비동기 자원 관리. __aenter__, __aexit__.

import aiohttp

async def fetch_all(urls):
    async with aiohttp.ClientSession() as session:
        for url in urls:
            async with session.get(url) as resp:
                yield await resp.text()

@asynccontextmanager로 함수 기반 작성:

from contextlib import asynccontextmanager

@asynccontextmanager
async def db_session():
    conn = await connect()
    try:
        yield conn
    finally:
        await conn.close()

예외 처리

__exit__에서 예외 정보 검사 후 선택적 처리.

class IgnoreKeyError:
    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_value, tb):
        if exc_type is KeyError:
            print(f"ignoring {exc_value}")
            return True       # 예외 삼킴
        return False          # 다른 예외는 전파

with IgnoreKeyError():
    d = {}
    d["missing"]              # 삼켜짐

데코레이터로 쓰기

contextlib.ContextDecorator 상속 또는 @contextmanager 함수는 자체가 데코레이터로 작동.

@contextmanager
def trace(name):
    print(f"enter {name}")
    yield
    print(f"exit {name}")

@trace("work")
def work():
    print("working")

work()
# enter work
# working
# exit work

자주 만드는 패턴

임시 환경변수

import os
from contextlib import contextmanager

@contextmanager
def env(**kwargs):
    old = {k: os.environ.get(k) for k in kwargs}
    os.environ.update(kwargs)
    try:
        yield
    finally:
        for k, v in old.items():
            if v is None:
                os.environ.pop(k, None)
            else:
                os.environ[k] = v

with env(API_KEY="test-key"):
    run_test()

임시 작업 디렉터리

@contextmanager
def cwd(path):
    old = os.getcwd()
    os.chdir(path)
    try:
        yield
    finally:
        os.chdir(old)

with cwd("/tmp"):
    run_in_tmp()

함정

exit에서 예외 발생

__exit__ 자신이 예외를 던지면 그게 우선 전파되고, with 본문 예외는 __context__로 묻힌다. 깨끗한 cleanup이 필요하면 try로 보호.

contextmanager 함수에서 yield 누락 또는 두 번

yield가 없으면 일반 함수
yield가 두 번이면 RuntimeError: generator didn't stop

with 안 return

def f():
    with open(...) as f:
        return f.read()    # OK: with가 자동 정리 후 반환

return은 with의 __exit__을 거친다.

[Python] contextvars: 비동기 친화 컨텍스트 변수

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

contextvars(PEP 567, 3.7+)는 현재 코드 실행 컨텍스트에 묶이는 변수다. threading의 local()처럼 동작하지만 asyncio 코루틴·태스크 경계도 정확히 인식. 비동기 코드에서 “현재 사용자”, “request id”, “DB 트랜잭션” 같은 컨텍스트 정보를 안전하게 전달.

ContextVar 기본

from contextvars import ContextVar

current_user: ContextVar[str] = ContextVar("current_user", default="anonymous")

print(current_user.get())          # 'anonymous'
token = current_user.set("Alice")  # 새 값 설정
print(current_user.get())          # 'Alice'
current_user.reset(token)          # 복원
print(current_user.get())          # 'anonymous'

set()은 Token 반환. reset(token)으로 이전 값 복원.

코루틴 간 격리

import asyncio
from contextvars import ContextVar

request_id: ContextVar[str] = ContextVar("request_id")

async def handle(req_id):
    request_id.set(req_id)
    await asyncio.sleep(0.1)
    print(f"handler {req_id} sees {request_id.get()}")

async def main():
    await asyncio.gather(
        handle("req-1"),
        handle("req-2"),
        handle("req-3"),
    )

asyncio.run(main())
# handler req-1 sees req-1
# handler req-2 sees req-2
# handler req-3 sees req-3

각 태스크가 자체 컨텍스트를 가져 서로 침범 X. threading.local에 해당하지만 코루틴 단위.

왜 글로벌 변수가 안 되나

# WRONG
current_user = "anonymous"    # 글로벌

async def handler1():
    current_user = "Alice"     # 다른 코루틴이 덮어쓸 수 있음
    await long_work()
    print(current_user)        # 다른 코루틴이 바꿨을 수도

# CORRECT
current_user_var = ContextVar("current_user")

async def handler1():
    current_user_var.set("Alice")    # 자신의 컨텍스트만
    await long_work()
    print(current_user_var.get())     # 항상 Alice

함수 인자로 매번 전달하면 깔끔하지만 깊은 호출 스택에서 번거로움. 컨텍스트 변수는 “어디서나 접근, 자동 격리”.

Context: 명시적 스냅샷

copy_context()는 현재 모든 ContextVar 값의 스냅샷을 반환.

from contextvars import copy_context, ContextVar

x = ContextVar("x", default=0)

def show():
    print("x =", x.get())

ctx = copy_context()
x.set(1)
show()                  # 1 (현재 컨텍스트)
ctx.run(show)           # 0 (스냅샷)

ctx.run(fn)은 그 스냅샷 안에서 fn 실행. 컨텍스트가 격리된 채로 실행됨.

실용 예제

request id 로깅

from contextvars import ContextVar
import logging

request_id: ContextVar[str] = ContextVar("request_id", default="-")

class ContextFilter(logging.Filter):
    def filter(self, record):
        record.request_id = request_id.get()
        return True

logger = logging.getLogger()
logger.addFilter(ContextFilter())
formatter = logging.Formatter("%(asctime)s [%(request_id)s] %(message)s")
# 로그 출력 시 현재 컨텍스트의 request_id 자동 포함

async def handle(req):
    request_id.set(req.id)
    logger.info("processing")
    await do_work()
    logger.info("done")

flask/FastAPI 미들웨어에서 request id 설정 → 모든 하위 함수의 로그에 자동 표시.

현재 사용자

from contextvars import ContextVar

current_user: ContextVar[User | None] = ContextVar("current_user", default=None)

def get_current_user():
    user = current_user.get()
    if user is None:
        raise Unauthorized
    return user

# 미들웨어
async def auth_middleware(request, call_next):
    user = await authenticate(request)
    token = current_user.set(user)
    try:
        return await call_next(request)
    finally:
        current_user.reset(token)

비즈니스 로직 어디서나 get_current_user() 호출. flask의 g, Django의 request.user와 비슷한 패턴.

DB 트랜잭션

from contextvars import ContextVar

current_tx: ContextVar = ContextVar("tx", default=None)

class transaction:
    async def __aenter__(self):
        self.tx = await db.begin()
        self.token = current_tx.set(self.tx)
        return self.tx

    async def __aexit__(self, *exc):
        if exc[0] is None:
            await self.tx.commit()
        else:
            await self.tx.rollback()
        current_tx.reset(self.token)

def get_tx():
    tx = current_tx.get()
    if tx is None:
        raise RuntimeError("no transaction")
    return tx

async def update_user(id, data):
    tx = get_tx()
    await tx.execute("UPDATE users ...")

with transaction(): 안의 모든 비동기 호출이 같은 트랜잭션 공유.

threading.local vs ContextVar

	`threading.local`	`ContextVar`
격리 단위	OS 스레드	코드 실행 컨텍스트 (코루틴 포함)
비동기 친화	X (asyncio에서 깨짐)	O
Token (reset)	X	O
스냅샷	X	copy_context
추천 시점	동기 멀티스레드	asyncio, 또는 둘 다

asyncio + threading.local은 코루틴이 같은 스레드를 공유하므로 값이 섞임. ContextVar는 코루틴 task 경계에서 격리.

ContextVar와 일반 함수

ContextVar는 동기 코드에서도 동작 (스레드 별 별도).

import threading
from contextvars import ContextVar

x = ContextVar("x", default=0)

def worker(name):
    x.set(name)
    print(f"thread {name}: x = {x.get()}")

threads = [threading.Thread(target=worker, args=(i,)) for i in range(3)]
for t in threads: t.start()
for t in threads: t.join()

스레드별 독립. local을 ContextVar로 대체 가능.

함정

1. 코루틴 시작 전 set이 안 보일 수 있음

import asyncio
from contextvars import ContextVar

x = ContextVar("x", default=0)

async def child():
    print(x.get())

async def main():
    x.set(99)
    await child()         # 99 (자식이 부모 컨텍스트 상속)

asyncio.run(main())

asyncio.create_task는 생성 시점의 컨텍스트를 복사. 이후 부모의 set은 자식에 안 보임.

async def main():
    task = asyncio.create_task(child())    # 이 시점의 컨텍스트 캡처
    x.set(99)                               # task에는 안 보임
    await task

2. ContextVar의 기본값과 set 안 한 경우

x = ContextVar("x")          # 기본값 없음
x.get()                       # LookupError!

x = ContextVar("x", default=0)
x.get()                       # 0

기본값 없으면 set 안 한 컨텍스트에서 LookupError.

3. reset Token 잘못된 사용

token1 = x.set(1)
token2 = x.set(2)
x.reset(token1)    # ValueError: 다른 컨텍스트의 토큰

토큰은 정확히 그 set 호출과 페어. 보통 try/finally 또는 컨텍스트 매니저로 보호.

4. 동기 코드에서 의도치 않은 공유

# 단일 스레드 + 동기 코드
x.set(1)
some_function()       # 안에서 x.get() 호출 시 1 보임
x.reset(token)

명시적 reset 없으면 함수 종료 후에도 값 남음. 미들웨어/데코레이터 패턴 권장.

비동기 컨텍스트 매니저 패턴

from contextlib import asynccontextmanager
from contextvars import ContextVar

current_user = ContextVar("current_user")

@asynccontextmanager
async def user_context(user):
    token = current_user.set(user)
    try:
        yield user
    finally:
        current_user.reset(token)

async def handle(request):
    async with user_context(request.user):
        await process()    # process 내부에서 current_user.get() OK

[Python] cProfile, timeit, perf: 성능 프로파일링

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Python 성능 분석 도구 선택지.

timeit (stdlib): 작은 코드 조각 벤치마크
cProfile (stdlib): 함수 호출 단위 프로파일링, deterministic
profile (stdlib): cProfile의 순수 Python 버전 (느림)
py-spy (third-party): sampling profiler, 프로덕션 안전
scalene (third-party): CPU + GPU + 메모리 통합

timeit: 마이크로 벤치마크

import timeit

# CLI
# python -m timeit -s "x = list(range(1000))" "x.copy()"

# 코드
t = timeit.timeit("sum(range(100))", number=10000)
print(f"{t * 1000:.3f}ms total")

t = timeit.repeat("sum(range(100))", number=10000, repeat=5)
print(f"best of 5: {min(t) * 1000:.3f}ms")

number는 한 라운드의 반복 횟수. repeat는 라운드 수. min(repeat)이 보통 가장 신뢰할 만한 값 (시스템 노이즈).

setup vs stmt

timeit.timeit(
    stmt="x.copy()",
    setup="x = list(range(1000))",
    number=10000,
)

setup은 측정에서 제외. 매 라운드 한 번 실행.

IPython %timeit

%timeit sum(range(100))
# 880 ns ± 5 ns per loop (mean ± std. dev. of 7 runs, ...)

%%timeit
x = list(range(1000))
x.sort()
# 셀 단위 측정

자동으로 반복 횟수 조정.

비교

import timeit

t1 = timeit.timeit("sum([x for x in xs])", setup="xs = list(range(1000))", number=10000)
t2 = timeit.timeit("sum(x for x in xs)",   setup="xs = list(range(1000))", number=10000)
t3 = timeit.timeit("sum(xs)",              setup="xs = list(range(1000))", number=10000)
print(t1, t2, t3)

마이크로 벤치는 미세한 환경 차이에 민감. 여러 번 측정 후 최솟값 비교.

cProfile: 함수 단위 프로파일링

import cProfile

cProfile.run("main()", "profile.out")    # 실행 후 파일 저장

# 또는 직접
pr = cProfile.Profile()
pr.enable()
main()
pr.disable()
pr.print_stats("cumulative")

CLI:

python -m cProfile -o profile.out script.py
python -m cProfile -s cumulative script.py    # 누적 시간 정렬

pstats: 결과 분석

import pstats

p = pstats.Stats("profile.out")
p.sort_stats("cumulative").print_stats(20)    # 상위 20개

p.sort_stats("tottime").print_stats(20)       # 자기 시간만
p.print_callers("hot_function")                # 누가 hot_function을 부르는가
p.print_callees("hot_function")                # hot_function이 누구를 부르는가

주요 열:

열	의미
ncalls	호출 횟수
tottime	함수 자체 시간 (하위 호출 제외)
percall	tottime / ncalls
cumtime	누적 시간 (하위 호출 포함)
percall	cumtime / ncalls

최적화 타겟: tottime이 큰 것 (이 함수 안에서 시간 소비). cumtime은 누가 비싼 호출을 하는지 보는 용도.

시각화: snakeviz / gprof2dot

pip install snakeviz
snakeviz profile.out    # 브라우저에서 인터랙티브 sunburst

pip install gprof2dot
gprof2dot -f pstats profile.out | dot -Tpng > profile.png    # 콜 그래프

콜 그래프와 누적 시간을 시각적으로 보면 hot path가 즉시 드러난다.

py-spy: sampling profiler

cProfile은 매 호출에 후킹 → 5-30% 오버헤드.

py-spy는 별도 프로세스에서 주기적으로 스택 샘플링 → 거의 0 오버헤드. 프로덕션 안전.

pip install py-spy

py-spy record -o profile.svg -- python script.py    # FlameGraph
py-spy top --pid 12345                               # top 명령
py-spy dump --pid 12345                              # 현재 스택

이미 실행 중인 프로세스에 attach 가능. 디버깅에 강력.

scalene: CPU + 메모리 통합

pip install scalene

scalene script.py
scalene --html --outfile profile.html script.py

CPU 시간뿐 아니라 메모리 할당, GPU 사용까지 한 번에 분석. line-level 통계.

line_profiler

함수 단위가 아닌 줄 단위 CPU 프로파일.

pip install line_profiler

@profile    # kernprof 데코레이터
def hot_function():
    x = [i ** 2 for i in range(1000)]    # 줄별 시간
    y = sum(x)
    return y

kernprof -l -v script.py

특정 함수가 hot하다는 걸 cProfile로 찾은 뒤 줄 단위 분석에.

자주 보는 패턴

Hot path 식별

cProfile로 전체 실행 → tottime 상위 함수 식별
line_profiler 또는 py-spy로 그 함수 내부 분석
최적화 → 다시 측정 (회귀 방지)

알고리즘 비교

import timeit

def algo_a(data): ...
def algo_b(data): ...

setup = "from __main__ import algo_a, algo_b, data; data = list(range(10000))"

a = min(timeit.repeat("algo_a(data)", setup=setup, number=100, repeat=5))
b = min(timeit.repeat("algo_b(data)", setup=setup, number=100, repeat=5))
print(f"A: {a:.4f}s, B: {b:.4f}s, speedup: {a/b:.2f}x")

CI에 회귀 검출

import pytest

@pytest.mark.benchmark(group="parsing")
def test_parse_speed(benchmark):
    result = benchmark(parse, sample_data)
    assert result.is_valid

pytest-benchmark로 자동 비교. 회귀 발견 시 CI fail.

비동기 코드 프로파일

cProfile은 async도 측정 가능. 단 단일 코루틴의 cumulative time이 진짜 그 시간이 아니라 await가 진행되는 동안 다른 작업이 진행된 시간도 포함될 수 있음.

py-spy는 async profiling 좀 더 자연스러움.

최적화 원칙

측정 먼저 (“Premature optimization is the root of all evil”)
알고리즘 우선: O(n^2) → O(n log n) 이 마이크로 최적화보다 훨씬 큼
stdlib과 numpy/pandas 활용: 순수 Python 루프보다 C 구현이 100x+ 빠름
JIT/C extension: 정말 hot한 부분은 Cython, mypyc, PyPy, 또는 Rust extension

흔한 hot spot 패턴

큰 list in 검사 → set 변환 (O(n) → O(1))
문자열 누적 += → "".join(...) (O(n^2) → O(n))
반복 dict lookup → 로컬 변수에 캐싱
Python 루프 → numpy/pandas 벡터화
동기 I/O 직렬 → asyncio 또는 threading
pickle 자주 사용 → MessagePack 또는 marshal

함정

1. 캐시 효과로 첫 호출이 느림

%timeit my_func()       # 첫 호출은 import, JIT 등 비용 포함

warm up 후 측정. repeat + min.

2. 너무 작은 코드의 마이크로벤치

%timeit x + y           # 호출 오버헤드가 측정의 대부분

미세한 차이는 의미 없음. 실제 워크로드 측정이 우선.

3. 옵티마이저가 죽은 코드 제거

%timeit [x ** 2 for x in range(100)]    # 결과 안 쓰면 컴파일러가 제거?

CPython 인터프리터는 그런 최적화 약함이라 보통 측정됨. 그래도 결과를 변수에 할당하거나 sink로 쓰는 게 안전.

4. 다른 프로세스가 CPU 점유

벤치마크 중 다른 프로그램이 무거우면 결과 오염. min 사용으로 어느 정도 보정.

5. cProfile의 오버헤드

cProfile 자체 비용으로 측정값이 부풀려짐. 절대값보다 상대 비율에 집중.

도구 선택 가이드

작업	도구
마이크로벤치 (코드 한 줄)	timeit
함수 단위 핫스팟	cProfile
줄 단위 분석	line_profiler
프로덕션 / 무료 sampling	py-spy
CPU + 메모리 통합	scalene
회귀 검출 (CI)	pytest-benchmark
시각화	snakeviz, gprof2dot, flamegraph
메모리만	tracemalloc, memory_profiler

[Python] csv, io: CSV와 텍스트 스트림

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

csv는 표준 라이브러리의 CSV 파서. io는 텍스트/바이너리 스트림 추상화. CSV 처리는 작은 파일이면 csv 모듈, 큰 데이터셋이면 pandas.read_csv나 polars.read_csv가 적합.

기본 읽기

import csv

with open("data.csv", newline="") as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)         # ['col1', 'col2', 'col3'] 형태 list

중요: open()에 newline="" 권장. CSV 표준은 \r\n 종결인데 Python의 universal newline이 일부 케이스에서 파싱을 망친다. csv 모듈이 자체적으로 행 분리 처리하므로 newline=""으로 두는 게 안전.

DictReader: 헤더 기반

import csv

with open("data.csv", newline="") as f:
    reader = csv.DictReader(f)
    for row in reader:
        print(row["name"], row["age"])

첫 줄이 헤더라고 가정. 각 행이 dict로 옴 (3.8+ 부터는 일반 dict, 이전엔 OrderedDict).

쓰기

import csv

with open("out.csv", "w", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["name", "age"])
    writer.writerows([
        ["Alice", 30],
        ["Bob", 25],
    ])

DictWriter로 dict 쓰기:

with open("out.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=["name", "age"])
    writer.writeheader()
    writer.writerow({"name": "Alice", "age": 30})
    writer.writerows([{"name": "Bob", "age": 25}])

extrasaction="ignore"로 사전에 추가 키 있을 때 무시 가능.

Dialect: 구분자, 인용

import csv

# TSV
csv.reader(f, delimiter="\t")

# 세미콜론 (유럽)
csv.reader(f, delimiter=";")

# 인용 항상
csv.writer(f, quoting=csv.QUOTE_ALL)

# 인용 최소 (필요할 때만)
csv.writer(f, quoting=csv.QUOTE_MINIMAL)   # 기본

# 인용 비숫자
csv.writer(f, quoting=csv.QUOTE_NONNUMERIC)

Dialect로 묶어서 재사용:

csv.register_dialect("myapp", delimiter="|", quoting=csv.QUOTE_MINIMAL)
csv.reader(f, dialect="myapp")

Sniffer: 자동 감지

import csv

with open("unknown.csv", newline="") as f:
    sample = f.read(2048)
    f.seek(0)
    dialect = csv.Sniffer().sniff(sample)
    has_header = csv.Sniffer().has_header(sample)
    reader = csv.reader(f, dialect)

완벽하지 않지만 알 수 없는 입력 처리 시 시작점으로 유용.

큰 파일 스트리밍

import csv

with open("big.csv", newline="") as f:
    reader = csv.reader(f)
    next(reader)        # 헤더 건너뛰기
    for row in reader:
        if int(row[2]) > threshold:
            process(row)

reader는 iterator라 메모리 일정 (한 행씩). 수십 GB도 처리 가능.

배치 처리는 itertools.batched(3.12+) 와 결합:

from itertools import batched

with open("big.csv", newline="") as f:
    reader = csv.reader(f)
    next(reader)
    for batch in batched(reader, 1000):
        bulk_insert(batch)

io 모듈: 메모리 내 파일

io.StringIO / io.BytesIO로 디스크 없이 파일 인터페이스 객체 생성.

import io
import csv

# 메모리에 CSV 쓰기
buf = io.StringIO()
writer = csv.writer(buf)
writer.writerow(["a", "b"])
writer.writerow([1, 2])

result = buf.getvalue()
print(result)
# 'a,b\r\n1,2\r\n'

# 메모리에서 CSV 읽기
src = io.StringIO("name,age\nAlice,30\n")
reader = csv.DictReader(src)
for row in reader:
    print(row)

테스트, HTTP 응답 생성, 메모리 내 변환에 유용.

BytesIO는 바이너리 버전 (이미지, 파케이, gzip 등).

import gzip
import io

# 메모리에서 gzip 압축
buf = io.BytesIO()
with gzip.open(buf, "wb") as gz:
    gz.write(b"hello")
compressed = buf.getvalue()

# 메모리에서 압축 해제
src = io.BytesIO(compressed)
with gzip.open(src, "rb") as gz:
    data = gz.read()

인코딩

기본은 시스템 기본 (locale.getpreferredencoding()). 보통 utf-8이지만 항상 명시 권장.

with open("data.csv", encoding="utf-8", newline="") as f:
    ...

# Windows에서 종종 cp949 / euc-kr 인코딩
with open("data.csv", encoding="euc-kr", newline="") as f:
    ...

# BOM 처리
with open("data.csv", encoding="utf-8-sig", newline="") as f:
    ...

utf-8-sig는 BOM(\ufeff)을 자동으로 제거. Excel이 만든 CSV에 종종 있음.

CSV의 함정

1. 큰따옴표 안의 콤마/줄바꿈

name,quote
Alice,"hello, world"
Bob,"line 1
line 2"

표준 CSV는 큰따옴표로 escape. csv.reader가 자동 처리.

2. 큰따옴표 안의 큰따옴표

""로 escape. csv.reader가 자동 처리.

name,quote
Alice,"she said ""hi"""

3. 숫자 vs 문자열

CSV는 모든 값이 문자열. 변환은 직접.

for row in reader:
    age = int(row["age"])
    price = float(row["price"])

또는 csv.QUOTE_NONNUMERIC (read 시 자동 float 변환, 깨지기 쉬움 - 권장 X).

4. 빈 값 처리

name,age
Alice,30
Bob,

빈 셀은 "" (빈 문자열)로 옴. None이 아님.

age = int(row["age"]) if row["age"] else None

5. 한국어 + Windows + Excel

가장 흔한 인코딩 문제. Windows Excel은 종종 cp949/euc-kr 또는 BOM 있는 UTF-8 출력. 입력은 일반 utf-8 못 읽음.

해결:

읽을 때 encoding="utf-8-sig" (BOM 자동 처리)
쓸 때 Excel 호환 원하면 encoding="utf-8-sig" (BOM 포함)

pandas와 비교

	csv 모듈	pandas
메모리	일정 (스트리밍)	전체 로드
속도 (작은)	빠름	약간 느림
속도 (큰)	느림 (Python 수준)	빠름 (C)
타입 변환	직접	자동 추론
정렬, 필터, 그룹화	직접	한 줄
의존성	stdlib	무거움
대용량 (수 GB)	OK (스트리밍)	메모리 부족 가능

규칙: 100MB 이하 + 분석 필요 → pandas. 스트리밍 + 단순 변환 → csv. 수 GB → polars 또는 csv 스트리밍 + 청크.

대안

polars: 빠른 DataFrame 라이브러리. pl.read_csv 매우 빠름.
pyarrow.csv: 멀티스레드 CSV 파서. pandas보다 빠름.
DuckDB: SQL로 CSV 직접 쿼리 가능.

import duckdb
df = duckdb.sql("SELECT * FROM 'big.csv' WHERE age > 30").df()

[Python] dataclass: 자동 생성 메서드를 갖춘 데이터 클래스

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

@dataclass(3.7+, PEP 557)는 클래스에 __init__, __repr__, __eq__ 등 상용구 메서드를 자동 생성해주는 데코레이터다. 데이터 컨테이너 클래스를 한 줄 데코레이터 + 필드 어노테이션만으로 만들 수 있다.

기본 사용

자동 생성: __init__(self, x, y), __repr__, __eq__. 수동 작성이라면 20줄 넘는 보일러플레이트.

옵션

@dataclass(
    init=True,        # __init__ 생성 (기본 True)
    repr=True,        # __repr__ 생성
    eq=True,          # __eq__ 생성
    order=False,      # __lt__/__le__/__gt__/__ge__ 생성
    unsafe_hash=False,
    frozen=False,     # 불변 (속성 변경 불가)
    match_args=True,  # __match_args__ 생성 (3.10+, match 문 위치 매칭)
    kw_only=False,    # 모든 필드를 키워드 전용으로 (3.10+)
    slots=False,      # __slots__ 사용 (3.10+, 메모리 절감)
)
class C: ...

frozen=True: 불변 dataclass

@dataclass(frozen=True)
class Point:
    x: int
    y: int

p = Point(1, 2)
p.x = 99    # FrozenInstanceError

# hashable이 됨 → dict 키, set 원소 가능
points = {Point(0, 0), Point(1, 1)}

frozen=True는 __setattr__을 가로채 예외를 던진다. __hash__도 자동 생성.

field() 함수

기본값, 비교 제외, factory 등 세부 설정.

가변 기본값(list, dict, set)은 반드시 default_factory. 직접 tags: list = []라고 쓰면 ValueError (dataclass가 검출).

post_init

__init__ 종료 직후 호출. 파생 필드 계산이나 검증.

from dataclasses import dataclass

@dataclass
class Rect:
    width: float
    height: float
    area: float = 0.0    # 파생값

    def __post_init__(self):
        self.area = self.width * self.height
        if self.width <= 0 or self.height <= 0:
            raise ValueError("dimensions must be positive")

r = Rect(3, 4)
print(r)    # Rect(width=3, height=4, area=12)

InitVar: init에만 쓰이는 필드

from dataclasses import dataclass, field, InitVar

@dataclass
class User:
    name: str
    password: InitVar[str] = ""
    password_hash: str = field(init=False, default="")

    def __post_init__(self, password):
        self.password_hash = hash_password(password)

# password는 인스턴스 속성으로 저장되지 않음
u = User("Alice", "secret")
print(u.password_hash)

order=True: 비교 연산자 자동 생성

필드 순서대로 튜플 비교.

@dataclass(order=True)
class Version:
    major: int
    minor: int
    patch: int

v1 = Version(1, 2, 0)
v2 = Version(1, 2, 3)
print(v1 < v2)    # True
print(sorted([v2, v1]))

비교에서 제외하려면 field(compare=False).

slots=True (3.10+)

__slots__를 자동 생성. 메모리 절감 + 속도 향상(약 20-30%) + 동적 속성 추가 차단.

@dataclass(slots=True)
class Point:
    x: int
    y: int

p = Point(1, 2)
p.z = 3    # AttributeError

3.10 이전엔 직접 __slots__ = ("x", "y") 작성 후 별도 dataclass와 결합 필요. 3.10+는 한 옵션으로 끝.

상속

@dataclass
class Base:
    a: int
    b: int = 0

@dataclass
class Child(Base):
    c: int = 0
    # d: int   # ERROR: 기본값 있는 필드(b) 뒤에 기본값 없는 필드 불가

서브클래스가 부모 기본값 있는 필드 뒤에 무 기본값 필드를 추가하면 에러. 3.10+ kw_only=True로 회피 가능.

@dataclass(kw_only=True)
class Child(Base):
    d: int    # OK: 모든 필드가 키워드 전용

asdict / astuple / fields / replace

dataclass vs namedtuple vs TypedDict

	dataclass	namedtuple	TypedDict
가변	O (default) / X (frozen)	X	O (dict 기반)
메서드 정의	O (편함)	O (별로)	X
메모리	보통 / slots: 적음	적음	dict 만큼
비교	자동 (eq, order)	자동 (튜플)	직접
인덱싱	X	O	X
용도	일반 데이터 클래스	불변 레코드	API 페이로드 스키마

pydantic과의 차이

dataclass: 런타임 검증 없음, 타입 힌트는 문서 역할
pydantic.BaseModel: 런타임 검증, 직렬화, JSON 스키마 생성

도메인 모델이나 API 입력 처리엔 pydantic, 내부 자료구조엔 dataclass.

[Python] datetime, timezone, zoneinfo

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

datetime 모듈은 날짜·시각·기간 처리를 제공한다. 핵심 클래스:

date: 연-월-일
time: 시-분-초-마이크로초 (날짜 정보 없음)
datetime: date + time
timedelta: 기간 (날짜 간 차이)
timezone: UTC 오프셋 기반 타임존
zoneinfo.ZoneInfo (3.9+): IANA 타임존 DB (“Asia/Seoul” 등)

naive vs aware

가장 중요한 구분.

naive datetime: 타임존 정보 없음. tzinfo is None
aware datetime: 타임존 정보 있음. UTC 환산 가능

from datetime import datetime, timezone

naive = datetime(2026, 6, 20, 12, 0)
print(naive.tzinfo)        # None

aware = datetime(2026, 6, 20, 12, 0, tzinfo=timezone.utc)
print(aware.tzinfo)        # UTC

서버/저장은 aware UTC가 표준. naive는 로컬 표현이나 입력 파싱 직후 등 한정적으로만.

# UTC now (aware) - 권장
now = datetime.now(timezone.utc)

# 로컬 now (naive) - 비권장 (TZ 모호)
now = datetime.now()

생성

strptime 포맷 코드: %Y 4자리 연도, %m 월, %d 일, %H 24시, %M 분, %S 초, %z UTC 오프셋, %Z 타임존 이름.

출력: isoformat과 strftime

dt = datetime(2026, 6, 20, 14, 30, tzinfo=timezone.utc)

print(dt.isoformat())              # '2026-06-20T14:30:00+00:00'
print(dt.strftime("%Y-%m-%d %H:%M %z"))   # '2026-06-20 14:30 +0000'
print(dt.strftime("%A, %B %d"))    # 'Saturday, June 20'

ISO 8601 형식이 직렬화 표준. isoformat()을 우선.

timedelta

기간 표현. datetime 간 뺄셈 결과.

timedelta 인자: days, hours, minutes, seconds, microseconds, milliseconds, weeks. 모두 누적.

zoneinfo (3.9+, PEP 615)

IANA 타임존 DB 기반 정확한 타임존 처리. pytz를 대체.

윈도우에선 별도 패키지 필요: pip install tzdata.

일광절약시간(DST)

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

ny = ZoneInfo("America/New_York")
spring = datetime(2026, 3, 8, 1, 30, tzinfo=ny)  # 02:00에 03:00으로 점프
later = spring + timedelta(hours=2)
print(later)    # 2026-03-08 04:30 EDT

zoneinfo가 DST 전환을 자동 처리. timezone 오프셋이 시기별로 다르다.

astimezone vs replace

dt = datetime(2026, 6, 20, 14, 0, tzinfo=ZoneInfo("UTC"))

# astimezone: 같은 순간을 다른 TZ로 표현
dt.astimezone(ZoneInfo("Asia/Seoul"))     # 2026-06-20 23:00 KST

# replace: TZ만 바꿈 (실제 순간이 달라짐!) - 위험
dt.replace(tzinfo=ZoneInfo("Asia/Seoul")) # 2026-06-20 14:00 KST (다른 순간!)

replace는 naive에 TZ를 입힐 때만 사용. 이미 aware인 dt를 다른 TZ로 보려면 항상 astimezone.

UNIX timestamp 변환

from datetime import datetime, timezone

# datetime → timestamp
ts = datetime.now(timezone.utc).timestamp()
print(ts)    # 1750395600.123456 (float)

# timestamp → datetime
dt = datetime.fromtimestamp(ts, tz=timezone.utc)
print(dt)

# naive timestamp는 로컬 TZ로 해석되어 혼란 위험
naive = datetime.fromtimestamp(ts)   # 로컬 TZ 해석

timestamp()는 항상 UTC epoch 초. 안전.

비교와 정렬

datetime은 비교 가능. 단 naive와 aware 비교는 TypeError.

now = datetime.now(timezone.utc)
later = now + timedelta(hours=1)
print(now < later)    # True

# WRONG: 혼합
naive = datetime.now()
aware = datetime.now(timezone.utc)
naive < aware    # TypeError

자주 보는 함정

1. `datetime.utcnow()` 비권장

# 비권장 (naive 반환)
datetime.utcnow()      # tzinfo=None인데 사실 UTC 시각... 함정!

# 권장
datetime.now(timezone.utc)    # aware UTC

3.12+ 부터 utcnow()는 deprecated.

2. `datetime.fromtimestamp()` 기본은 로컬 TZ

datetime.fromtimestamp(ts)               # 로컬 TZ로 해석 → naive
datetime.fromtimestamp(ts, tz=timezone.utc)   # UTC aware (권장)

3. ISO 파싱 한계

fromisoformat(3.7+)은 엄격한 ISO 8601만. 3.11+에서 더 관대해졌지만 여전히 Z(UTC) 제대로 처리하려면 3.11+ 필요.

# 3.10 이하에선 'Z' 안 됨
datetime.fromisoformat("2026-06-20T14:30:00Z")   # ValueError (3.10-)
datetime.fromisoformat("2026-06-20T14:30:00+00:00")   # OK

전 버전 호환은 dateutil.parser.parse 또는 pendulum.

4. month/year 더하기

timedelta엔 months나 years가 없다 (월/년은 길이 가변).

# 한 달 후?
from dateutil.relativedelta import relativedelta
dt + relativedelta(months=1)

# 또는 직접 계산
def add_months(dt, months):
    year = dt.year + (dt.month - 1 + months) // 12
    month = (dt.month - 1 + months) % 12 + 1
    day = min(dt.day, last_day_of_month(year, month))
    return dt.replace(year=year, month=month, day=day)

time vs datetime

모듈	용도
`time`	낮은 수준, UNIX timestamp, monotonic clock
`datetime`	사람이 읽는 날짜·시각
`calendar`	달력 (월 길이, 윤년)

import time
time.time()              # UNIX timestamp (float)
time.monotonic()         # 단조 증가 (시간 차이 측정용, 절대 시각 아님)
time.perf_counter()      # 고해상도 (성능 측정)
time.sleep(0.5)

벤치마크엔 perf_counter. 사용자 시각 표시엔 datetime.

[Python] Descriptor: get, set, delete

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Descriptor는 __get__, __set__, __delete__ 중 하나 이상을 구현한 클래스다. 다른 클래스의 클래스 속성으로 사용되면 그 속성 접근이 descriptor의 메서드를 통해 라우팅된다. @property, @classmethod, @staticmethod, 모든 메서드가 사실 descriptor.

종류

Data descriptor: __set__ 또는 __delete__ 존재 (보통 __get__도)
Non-data descriptor: __get__만 존재

차이는 속성 조회 우선순위:

Data descriptor > 인스턴스 __dict__ > Non-data descriptor

기본 예제

class Logged:
    def __init__(self, name=""):
        self.name = name

    def __set_name__(self, owner, name):    # 3.6+
        self.name = name

    def __get__(self, instance, owner):
        if instance is None:
            return self
        print(f"GET {self.name}")
        return instance.__dict__.get(self.name)

    def __set__(self, instance, value):
        print(f"SET {self.name} = {value}")
        instance.__dict__[self.name] = value

class Account:
    balance = Logged()
    name = Logged()

a = Account()
a.name = "Alice"      # SET name = Alice
a.balance = 1000      # SET balance = 1000
print(a.balance)      # GET balance / 1000

set_name (3.6+)

클래스 본문이 처리될 때 descriptor의 owner 클래스와 attribute 이름을 주입. PEP 487. 없으면 descriptor가 자기 이름을 알기 어렵다.

class Field:
    def __set_name__(self, owner, name):
        self.public_name = name
        self.private_name = "_" + name

검증 디스크립터 (실용)

class Validator:
    def __set_name__(self, owner, name):
        self.private_name = "_" + name

    def __get__(self, instance, owner):
        return getattr(instance, self.private_name, None)

    def __set__(self, instance, value):
        self.validate(value)
        setattr(instance, self.private_name, value)

    def validate(self, value):
        raise NotImplementedError

class Positive(Validator):
    def validate(self, value):
        if value <= 0:
            raise ValueError("must be positive")

class String(Validator):
    def validate(self, value):
        if not isinstance(value, str):
            raise TypeError("must be string")

class Product:
    name = String()
    price = Positive()
    stock = Positive()

p = Product()
p.name = "book"
p.price = 1000
p.stock = -1     # ValueError

각 클래스 속성을 한 줄로 검증·저장 동작 정의. ORM, Django Field, Pydantic 등의 핵심 메커니즘.

property가 사실 descriptor

class property:               # 의사 코드
    def __init__(self, fget=None, fset=None, fdel=None):
        self.fget, self.fset, self.fdel = fget, fset, fdel

    def __get__(self, instance, owner):
        if instance is None: return self
        return self.fget(instance)

    def __set__(self, instance, value):
        if self.fset is None:
            raise AttributeError("can't set")
        self.fset(instance, value)

@property가 만드는 객체가 __get__/__set__/__delete__를 모두 가진 data descriptor.

함수도 descriptor

class A:
    def method(self):
        pass

a = A()
print(A.method)         # <function A.method>
print(a.method)         # <bound method A.method of <A object>>

a.method가 bound method가 되는 마법은 함수 객체가 __get__을 가진 non-data descriptor이기 때문이다.

def f(): pass
f.__get__(instance, owner)  # bound method 반환

classmethod / staticmethod도 descriptor

class C:
    @classmethod
    def cm(cls): pass

    @staticmethod
    def sm(): pass

print(type(C.__dict__["cm"]))   # <class 'classmethod'>
print(type(C.__dict__["sm"]))   # <class 'staticmethod'>

각각 __get__에서 cls 바인딩 / 그대로 함수 반환을 수행.

속성 조회 순서 (data descriptor 우선)

obj.attr 조회 시 (간단화):

type(obj).__mro__에서 attr 검색
- data descriptor면 즉시 그 __get__ 호출 후 종료
obj.dict[attr] 있으면 반환
type(obj).__mro__의 검색 결과
- non-data descriptor면 __get__ 호출
- 일반 클래스 속성이면 그대로 반환
__getattr__ 호출
AttributeError

class D:
    def __get__(self, instance, owner): return "from descriptor"
    def __set__(self, instance, value): pass

class C:
    x = D()

c = C()
c.__dict__["x"] = "instance attr"
print(c.x)   # "from descriptor" (data descriptor가 인스턴스보다 우선)

class E:
    def __get__(self, instance, owner): return "from non-data"

class F:
    x = E()

f = F()
f.__dict__["x"] = "instance attr"
print(f.x)   # "instance attr" (non-data descriptor는 인스턴스 우선)

메서드/슬롯과의 차이

함수는 매 호출마다 새 bound method 생성 (메서드 객체 재사용 안 함)
__slots__ 클래스의 슬롯은 사실 C 레벨에서 만들어진 data descriptor
__init_subclass__, ABC도 descriptor와 클래스 본문 메커니즘 활용

함정

1. descriptor 자체에 상태 저장 금지

class BadField:
    def __get__(self, instance, owner):
        return self.value

    def __set__(self, instance, value):
        self.value = value    # 모든 인스턴스가 공유!

descriptor 인스턴스는 클래스 단위 1개. 상태는 반드시 instance.__dict__에.

2. instance가 None인 경우 처리

클래스에서 직접 접근 시 instance가 None.

class D:
    def __get__(self, instance, owner):
        if instance is None:
            return self       # 클래스 접근: descriptor 자체 반환
        return ...

3. dataclass 필드와 descriptor

@dataclass는 디스크립터를 인식해 기본값 처리에 사용. 3.10+ 에서 PEP 487 활용 패턴 개선.

언제 직접 만드나

같은 검증/변환을 여러 속성에 재사용
ORM/직렬화 프레임워크의 Field 추상
게으른 초기화 + 인스턴스 캐싱
타입 강제, 기본값 동적 결정

단순 검증이면 property로 충분. descriptor는 여러 클래스/속성에 재사용할 때 진가.

[Python] enum: Enum, IntEnum, Flag, StrEnum

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

enum은 고정된 이름-값 매핑을 정의하는 표준 모듈. 마법 숫자나 문자열 상수를 타입화된 멤버로 대체해 타입 안정성·가독성·IDE 지원을 얻는다.

Enum 기본

from enum import Enum

class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

print(Color.RED)            # Color.RED
print(Color.RED.name)       # 'RED'
print(Color.RED.value)      # 1
print(Color(1))             # Color.RED (값으로 lookup)
print(Color["RED"])         # Color.RED (이름으로 lookup)

# 동등성
print(Color.RED == Color.RED)   # True
print(Color.RED is Color.RED)   # True (singleton)
print(Color.RED == 1)           # False! (Enum과 int는 다름)

Enum 멤버는 싱글톤. 같은 멤버는 항상 같은 객체.

순회

for c in Color:
    print(c.name, c.value)

print(list(Color))
print(len(Color))

선언 순서대로 순회.

auto()

값을 자동 할당.

from enum import Enum, auto

class Status(Enum):
    PENDING = auto()
    APPROVED = auto()
    REJECTED = auto()

print(Status.PENDING.value)    # 1

값에 의미가 없고 멤버 식별만 중요할 때 권장. 명시 값은 그대로.

IntEnum: int과 비교 가능

from enum import IntEnum

class HttpStatus(IntEnum):
    OK = 200
    NOT_FOUND = 404
    SERVER_ERROR = 500

print(HttpStatus.OK == 200)         # True
print(HttpStatus.OK < HttpStatus.NOT_FOUND)
print(int(HttpStatus.OK))            # 200

기존 int 비교 코드와 호환 시 유용. 단 타입 안전성 약간 손해 (int와 자유롭게 비교됨).

StrEnum (3.11+)

from enum import StrEnum

class Env(StrEnum):
    DEV = "dev"
    STAGING = "staging"
    PROD = "prod"

print(Env.DEV == "dev")          # True
print(f"{Env.DEV}")              # 'dev' (str과 동등)

JSON, 환경변수, 설정 값으로 자연스럽게.

3.11 이전엔 직접:

class Env(str, Enum):
    DEV = "dev"

Flag, IntFlag: 비트 조합

from enum import Flag, auto

class Permission(Flag):
    READ = auto()      # 1
    WRITE = auto()     # 2
    EXEC = auto()      # 4

# 조합
all_perm = Permission.READ | Permission.WRITE | Permission.EXEC
print(all_perm)                # Permission.READ|WRITE|EXEC

# 검사
print(Permission.READ in all_perm)        # True
print(Permission.WRITE in Permission.READ) # False

# 비트 연산
ro = all_perm & ~Permission.WRITE
print(ro)                       # Permission.READ|EXEC

권한, 옵션 플래그 등 비트마스크를 타입화. C의 enum + bitfield보다 안전.

IntFlag는 int 비교 가능 버전.

메서드 추가

Enum 멤버에 메서드 정의 가능 (self로 멤버 접근).

class Direction(Enum):
    NORTH = (0, 1)
    SOUTH = (0, -1)
    EAST = (1, 0)
    WEST = (-1, 0)

    def move(self, x, y):
        dx, dy = self.value
        return x + dx, y + dy

    def opposite(self):
        opposites = {
            Direction.NORTH: Direction.SOUTH,
            Direction.SOUTH: Direction.NORTH,
            Direction.EAST: Direction.WEST,
            Direction.WEST: Direction.EAST,
        }
        return opposites[self]

print(Direction.NORTH.move(0, 0))      # (0, 1)
print(Direction.EAST.opposite())        # Direction.WEST

unique 데코레이터

중복 값 금지.

from enum import Enum, unique

@unique
class Status(Enum):
    OK = 1
    GOOD = 1     # ValueError: duplicate values

기본 Enum은 중복 허용 (alias 생성). @unique로 강제.

매칭 (3.10+ match문)

def handle(status: Status):
    match status:
        case Status.PENDING:
            return "wait"
        case Status.APPROVED | Status.REJECTED:
            return "done"

가독성 좋고 누락된 멤버를 타입 체커가 잡아줄 수 있음.

함정

1. == vs is

Color.RED == Color.RED    # True (값 비교)
Color.RED is Color.RED    # True (싱글톤)

둘 다 True지만 is가 의도 명확 + 빠름.

2. Enum + int 비교

class Color(Enum):
    RED = 1

Color.RED == 1    # False

int 비교가 필요하면 IntEnum 또는 .value 명시.

3. 멤버 할당 후 클래스 속성 추가 금지

class Color(Enum):
    RED = 1
    DEFAULT = "red"     # 이건 alias (값이 같다면) 또는 멤버

값이 같은 두 이름은 alias. 별도 메타데이터를 두려면 _member_map_ 직접 만지지 말고 별도 dict.

4. JSON 직렬화

기본 json.dumps는 Enum을 모름.

import json
from enum import Enum

class Color(Enum):
    RED = "red"

# WRONG
json.dumps(Color.RED)    # TypeError

# 옵션 1: value 명시
json.dumps(Color.RED.value)

# 옵션 2: default 함수
json.dumps({"color": Color.RED}, default=lambda o: o.value if isinstance(o, Enum) else o)

# 옵션 3: StrEnum (3.11+)
class Color(StrEnum):
    RED = "red"
json.dumps(Color.RED)    # '"red"'  (자동)

자주 보는 활용

API 응답 코드

class ErrorCode(IntEnum):
    INVALID_INPUT = 1001
    NOT_FOUND = 1002
    UNAUTHORIZED = 1003

raise APIError(code=ErrorCode.NOT_FOUND, message="...")

Django/SQLAlchemy choices

class OrderStatus(models.TextChoices):    # Django
    PENDING = "pending", "Pending Approval"
    APPROVED = "approved", "Approved"
    SHIPPED = "shipped", "Shipped"

ORM이 enum의 (value, label) 튜플을 인식해 admin 등에서 라벨 표시.

환경별 설정

from enum import StrEnum
import os

class Env(StrEnum):
    DEV = "dev"
    PROD = "prod"

env = Env(os.environ.get("APP_ENV", "dev"))
if env is Env.PROD:
    enable_strict_mode()

[Python] float, Decimal, Fraction

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Python의 실수 산술은 세 가지 타입을 제공한다.

float: IEEE 754 double precision (64비트). C double과 동일. 빠르지만 부정확.
decimal.Decimal: 임의 정밀도 십진수. 금융·통화 계산용. 느리지만 정확.
fractions.Fraction: 분수 표현. 유리수 정확 계산. 가장 느림.

float: IEEE 754 double

0.1과 0.2는 2진 부동소수로 정확히 표현되지 않는다. 누적 오차가 발생한다.

부동소수 비교

직접 == 대신 math.isclose()를 써라.

특수 값

import math
math.inf       # 양의 무한대
-math.inf      # 음의 무한대
math.nan       # Not a Number

float("inf")
float("-inf")
float("nan")

math.isnan(math.nan)   # True
math.isinf(math.inf)   # True
# NaN은 자기 자신과도 != 다.
math.nan == math.nan   # False

float 정보

import sys
sys.float_info
# epsilon=2.22e-16, mant_dig=53, max=1.79e+308, min=2.22e-308

Decimal: 정확한 십진 산술

중요: Decimal(0.1)은 float를 통하므로 부정확. 반드시 문자열로 생성 Decimal("0.1").

금융 계산 예시

from decimal import Decimal, ROUND_HALF_UP

price = Decimal("19.99")
tax_rate = Decimal("0.13")
tax = (price * tax_rate).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
total = price + tax
# Decimal('22.59')

Fraction: 유리수 정확 계산

Fraction(0.1)은 float의 실제 비트 표현을 분수로 옮긴 결과다. 문자열 입력이 안전하다.

언제 무엇을 쓰나

상황	선택
과학 계산, ML, 통계	`float` (NumPy 권장)
금융, 통화, 회계	`Decimal`
기호 수학, 유리수 정확 비교	`Fraction`
빠른 정수 산술	`int` (임의 정밀도)

변환

int(3.7)          # 3 (소수 버림)
float("3.14")     # 3.14
float("inf")      # inf
Decimal("1.5")
Fraction("3/7")

round(3.14159, 2) # 3.14
round(2.5)        # 2 (bankers' rounding: 짝수로)
round(3.5)        # 4

round()는 bankers’ rounding(반올림이 정확히 0.5일 때 짝수로)을 쓴다. 일반적인 사사오입은 decimal.Decimal.quantize(..., ROUND_HALF_UP).

IEEE 754 double precision 구조

flowchart LR
    S["부호 1bit"] --> E["지수 11bit"] --> M["가수 52bit"]

비트	필드	의미
63	부호	0 양수, 1 음수
62-52	지수	biased exponent (바이어스 1023)
51-0	가수	fraction, 암묵 leading 1

float 유효 십진 자릿수: 약 15.9자리. sys.float_info.epsilon = 2.22e-16.

math 모듈 주요 함수

import math

# 반올림 계열
math.floor(3.7)     # 3 (내림)
math.ceil(3.2)      # 4 (올림)
math.trunc(-3.7)    # -3 (0 방향)
round(3.14159, 2)   # 3.14

# 근사 비교
math.isclose(0.1 + 0.2, 0.3)               # True
math.isclose(1e6, 1e6 + 1, rel_tol=1e-6)  # True (상대 오차 기준)

# 특수 값 판별
math.isnan(float('nan'))   # True
math.isinf(float('inf'))   # True
math.isfinite(42.0)        # True

# 수학 함수
math.sqrt(2)           # 1.4142...
math.log(math.e)       # 1.0
math.log2(8)           # 3.0
math.log10(1000)       # 3.0
math.pow(2, 10)        # 1024.0 (항상 float)

# 정밀 합산
math.fsum([0.1, 0.2, 0.7])   # 1.0 (sum() 과 달리 누적 오차 방지)

성능 비교

import timeit

# float: 가장 빠름
timeit.timeit('0.1 + 0.2', number=10_000_000)
# ~0.3s

# Decimal: 약 10배 느림
timeit.timeit(
    'Decimal("0.1") + Decimal("0.2")',
    setup='from decimal import Decimal',
    number=10_000_000,
)
# ~3s

# Fraction: 약 30배 느림
timeit.timeit(
    'Fraction(1,10) + Fraction(1,5)',
    setup='from fractions import Fraction',
    number=1_000_000,
)
# ~1s per million

타입	상대 속도	정밀도	주요 용도
`float`	1x (기준)	53비트 이진	과학/ML/통계
`Decimal`	~10x 느림	임의 정밀도 10진	금융/통화/회계
`Fraction`	~30x 느림	완전 유리수	기호 수학
`int`	float 급	임의 정밀도 정수	정수 산술

부동소수 흔한 함정

[!WARNING]

직접 == 비교: 0.1 + 0.2 == 0.3 은 False. math.isclose() 사용.

Decimal(0.1) 초기화: float 경유로 오염. 반드시 Decimal("0.1").

금융 계산에 float: 19.99 * 0.13 에서 센트 오차 발생. Decimal 필수.

round(2.5) = 2: bankers’ rounding. 사사오입은 Decimal.quantize(ROUND_HALF_UP).

NaN 비교: nan == nan 은 False. math.isnan() 으로 확인.

루프 누적 오차: 반복 합산 시 math.fsum() 사용 권장.

[Python] functools: cache, partial, reduce, singledispatch

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

functools는 함수형 프로그래밍 도구와 함수 변환 데코레이터를 제공하는 표준 라이브러리. 메모이제이션, 부분 적용, 디스패치, 데코레이터 메타데이터 등을 다룬다.

lru_cache / cache

함수 결과를 메모이제이션. 같은 인자엔 한 번만 계산.

from functools import lru_cache, cache

@cache                      # 3.9+: 무제한 캐시
def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)

@lru_cache(maxsize=128)     # LRU eviction, 기본 128
def expensive(x, y):
    return slow_compute(x, y)

fib(100)
fib.cache_info()      # CacheInfo(hits=98, misses=101, ...)
fib.cache_clear()

인자는 해시 가능해야 (list 못 받음)
캐시 키는 위치/키워드 인자 둘 다 포함 → f(1, 2)와 f(a=1, b=2)는 다른 캐시
인스턴스 메서드에 쓰면 self가 키에 포함 → 인스턴스 살아 있는 동안 메모리 점유. 약한 참조 캐시는 별도 구현 필요

cached_property

@property + 캐싱. 인스턴스의 __dict__에 저장.

from functools import cached_property

class DataSet:
    def __init__(self, data):
        self.data = data

    @cached_property
    def stats(self):
        return {"mean": sum(self.data) / len(self.data),
                "max": max(self.data)}

d = DataSet([1, 2, 3])
d.stats       # 계산
d.stats       # 캐시
del d.stats   # 무효화

불변 데이터 가정. 데이터가 바뀌면 캐시 직접 비워야 함.

partial / partialmethod

함수의 일부 인자를 미리 채워 새 함수 생성.

from functools import partial

def power(base, exp):
    return base ** exp

square = partial(power, exp=2)
cube = partial(power, exp=3)

print(square(5))    # 25
print(cube(5))      # 125

# 콜백에 인자 미리 주입
button.on_click(partial(handle_click, user_id=42))

람다보다 빠르고 introspection 친화적 (partial은 .func, .args, .keywords 노출).

partialmethod는 클래스 메서드에 사용:

from functools import partialmethod

class Service:
    def _request(self, method, url): ...
    get = partialmethod(_request, "GET")
    post = partialmethod(_request, "POST")

reduce

iterable을 누적해 단일 값으로 축약. Python 3에서 functools로 이동.

from functools import reduce

reduce(lambda a, b: a + b, [1, 2, 3, 4])     # 10
reduce(lambda a, b: a + b, [1, 2, 3], 100)   # 106 (초기값)

# 보통 sum, min, max, math.prod로 충분
sum([1, 2, 3, 4])                # 10
import math
math.prod([1, 2, 3, 4])           # 24

reduce는 가독성이 낮아 권장도가 낮음. 명시적 for나 전용 함수 우선.

singledispatch

함수의 첫 번째 인자 타입에 따라 다른 구현으로 디스패치. 단일 디스패치 다형성.

타입 별로 함수를 추가할 수 있어 isinstance-체인을 깔끔하게 대체. 메서드 버전은 singledispatchmethod.

from functools import singledispatchmethod

class Renderer:
    @singledispatchmethod
    def render(self, obj):
        return repr(obj)

    @render.register
    def _(self, obj: str):
        return f"text: {obj}"

wraps

데코레이터에서 원본 함수 메타데이터 보존. py-decorator 참고.

from functools import wraps

def log(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        ...
        return fn(*args, **kwargs)
    return wrapper

wraps는 __name__, __doc__, __qualname__, __module__, __wrapped__ 복사.

update_wrapper

@wraps의 동작을 수동으로. 클래스 기반 데코레이터에서 유용.

from functools import update_wrapper

class Decorator:
    def __init__(self, fn):
        self.fn = fn
        update_wrapper(self, fn)

    def __call__(self, *args, **kwargs):
        return self.fn(*args, **kwargs)

total_ordering

__eq__와 비교 메서드 중 하나만 정의하면 나머지 자동 생성.

from functools import total_ordering

@total_ordering
class Version:
    def __init__(self, *parts):
        self.parts = parts

    def __eq__(self, other):
        return self.parts == other.parts

    def __lt__(self, other):
        return self.parts < other.parts

# __le__, __gt__, __ge__ 자동 생성

성능은 직접 구현보다 약간 느림. @dataclass(order=True)가 더 편함.

reduce + operator

reduce와 operator 모듈 결합으로 람다 제거.

from functools import reduce
import operator

reduce(operator.add, [1, 2, 3, 4])    # 10
reduce(operator.mul, [1, 2, 3, 4])    # 24

# operator는 itemgetter, attrgetter도 제공
from operator import itemgetter, attrgetter
sorted(items, key=itemgetter("price"))    # lambda d: d["price"] 와 동등
sorted(users, key=attrgetter("name"))     # lambda u: u.name

주의: 가변 인자와 캐시

from functools import lru_cache

@lru_cache
def f(xs):
    return sum(xs)

f([1, 2, 3])    # TypeError: unhashable type: 'list'
f((1, 2, 3))    # OK

list/dict는 해시 안 되므로 tuple/frozenset로 변환해 넘기거나 캐시 안 씀.

캐시 무효화 패턴

@cache
def lookup(key):
    return slow_query(key)

# 캐시 비우기
lookup.cache_clear()

# 특정 키만 무효화는 직접 dict로 구현해야 함 (lru_cache는 단일 키 삭제 미지원)

세밀한 제어가 필요하면 cachetools 라이브러리 또는 직접 dict.

[Python] hashlib, secrets, hmac: 해시와 암호 보안

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

암호학 관련 표준 모듈 3개.

hashlib: 해시 함수 (SHA-256, MD5, BLAKE2 등)
secrets: 암호학적으로 안전한 난수 (random은 비안전)
hmac: HMAC 메시지 인증

암호화(대칭/비대칭 암호)는 표준 라이브러리에 없음 → cryptography 패키지 사용.

hashlib 기본

import hashlib

data = b"hello world"

print(hashlib.sha256(data).hexdigest())
print(hashlib.sha512(data).hexdigest())
print(hashlib.md5(data).hexdigest())     # 보안 X, 무결성 체크만
print(hashlib.blake2b(data).hexdigest())

해시는 단방향. 같은 입력 → 같은 출력. 작은 입력 변경에도 출력 완전 변경.

update로 큰 데이터 처리

import hashlib

h = hashlib.sha256()
with open("big.iso", "rb") as f:
    while chunk := f.read(64 * 1024):
        h.update(chunk)
print(h.hexdigest())

스트리밍 처리. 메모리 일정.

3.11+ 편의 함수:

with open("big.iso", "rb") as f:
    digest = hashlib.file_digest(f, "sha256")
print(digest.hexdigest())

알고리즘 선택

알고리즘	권장
SHA-256, SHA-512	일반 무결성, 디지털 서명
BLAKE2b, BLAKE3	빠르고 안전 (SHA-3 대안)
SHA-3	차세대 표준
MD5, SHA-1	충돌 발견됨, 보안 X (체크섬용만)
bcrypt, scrypt, Argon2	비밀번호 해싱 전용

hashlib.algorithms_guaranteed   # OS 무관 항상 지원
hashlib.algorithms_available    # 시스템 의존

비밀번호 해싱 - 일반 해시 절대 사용 X

# WRONG: 비밀번호에 일반 해시
hashlib.sha256(password.encode()).hexdigest()
# → GPU로 초당 수십억 시도 가능 (브루트 포스)

비밀번호는 **느린 KDF (Key Derivation Function)**을 써야 한다.

표준 라이브러리: scrypt, pbkdf2

import hashlib
import secrets

salt = secrets.token_bytes(16)
password = b"my-secret-password"

# scrypt (느림, 메모리 hard)
key = hashlib.scrypt(password, salt=salt, n=2**14, r=8, p=1, dklen=32)

# pbkdf2 (느림 = 보안)
key = hashlib.pbkdf2_hmac("sha256", password, salt, iterations=600_000)

저장: salt + iterations + hash. 검증 시 같은 salt/iter로 다시 계산해 비교.

Argon2 (현대 권장)

pip install argon2-cffi

from argon2 import PasswordHasher

ph = PasswordHasher()
hash = ph.hash("password")
print(hash)
# $argon2id$v=19$m=65536,t=3,p=4$...

try:
    ph.verify(hash, "password")
    print("OK")
except VerifyMismatchError:
    print("Wrong password")

Argon2는 비밀번호 해싱 전용 최신 표준 (OWASP 권장).

secrets: 안전한 난수

random 모듈은 비결정 시드에서도 통계용. 보안엔 secrets.

import secrets

# 토큰 생성
print(secrets.token_bytes(16))            # 16바이트
print(secrets.token_hex(16))              # 32자 hex
print(secrets.token_urlsafe(16))          # URL 안전 문자열

# 정수
print(secrets.randbelow(100))             # 0 ~ 99
print(secrets.choice([1, 2, 3, 4]))       # 랜덤 선택

# 비밀번호 생성
import string
alphabet = string.ascii_letters + string.digits
password = "".join(secrets.choice(alphabet) for _ in range(20))

세션 토큰, API 키, 비밀번호 재설정 토큰 등에 사용.

hmac: 메시지 인증

해시 + 비밀 키로 메시지가 변조 안 됐고 발신자가 키 소유자임을 검증.

import hmac
import hashlib

key = b"shared-secret"
message = b"transfer 100 to alice"

# 서명 생성
signature = hmac.new(key, message, hashlib.sha256).hexdigest()
print(signature)

# 검증
received_signature = signature
expected = hmac.new(key, message, hashlib.sha256).hexdigest()

if hmac.compare_digest(received_signature, expected):
    print("authentic")
else:
    print("tampered")

compare_digest

타이밍 공격 방지. 두 문자열 길이 무관 일정 시간 비교. 일반 == 쓰면 안 됨.

# WRONG: 타이밍 공격 가능 (다른 문자 위치 따라 시간 다름)
if signature == expected:
    ...

# CORRECT
if hmac.compare_digest(signature, expected):
    ...

자주 보는 패턴

파일 무결성 (체크섬)

import hashlib

def file_sha256(path):
    h = hashlib.sha256()
    with open(path, "rb") as f:
        while chunk := f.read(64 * 1024):
            h.update(chunk)
    return h.hexdigest()

print(file_sha256("download.iso"))
# 공식 사이트 해시와 비교

CSRF 토큰

import secrets

def generate_csrf_token():
    return secrets.token_urlsafe(32)

# 폼에 hidden field로
# 제출 시 세션의 토큰과 hmac.compare_digest로 비교

API 서명 (HMAC)

import hmac
import hashlib
import time

def sign_request(secret, method, path, body, ts):
    msg = f"{method}\n{path}\n{ts}\n{body}".encode()
    return hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()

# 클라이언트
ts = str(int(time.time()))
sig = sign_request(SECRET, "POST", "/api/transfer", "amount=100", ts)
# Header: X-Timestamp: ts, X-Signature: sig

# 서버 검증
expected = sign_request(SECRET, "POST", "/api/transfer", "amount=100", ts)
if not hmac.compare_digest(sig, expected):
    raise Unauthorized

AWS Signature V4, GitHub Webhook 등이 이 패턴.

비밀번호 저장 (Argon2)

from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError

ph = PasswordHasher()

# 가입
def register(username, password):
    hash = ph.hash(password)
    db.save_user(username, hash)

# 로그인
def login(username, password):
    user = db.get_user(username)
    try:
        ph.verify(user.hash, password)
        if ph.check_needs_rehash(user.hash):    # 옵션 변경 시 재해시
            user.hash = ph.hash(password)
            db.update(user)
        return user
    except VerifyMismatchError:
        return None

보안 체크리스트

비밀번호는 절대 일반 해시 X. Argon2 / scrypt / pbkdf2.
토큰·세션은 secrets. random 금지.
HMAC 검증은 hmac.compare_digest. == 금지.
MD5/SHA-1은 보안용 X. 무결성 체크만.
솔트는 사용자별 고유. 전역 솔트 의미 없음.
솔트는 secrets.token_bytes로. 시간/이름 기반 X.
비밀 키는 환경변수 / KMS / Vault. 코드에 하드코딩 X.

[Python] heapq, bisect, array

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

heapq: min-heap

heapq는 리스트를 min-heap 구조로 다루는 함수 모음. 클래스가 아니라 일반 list 위에서 동작.

기본

import heapq

h = []
heapq.heappush(h, 5)
heapq.heappush(h, 1)
heapq.heappush(h, 3)
heapq.heappush(h, 2)

print(heapq.heappop(h))    # 1 (최소)
print(heapq.heappop(h))    # 2
print(h)                    # [3, 5] (내부 표현, 정렬 X)

heappush/heappop 모두 O(log n). 단순 list로는 정렬에 O(n log n) 또는 최소 검색에 O(n).

리스트를 heap으로 변환

heapify(xs)는 in-place O(n). 내부 배열은 heap 속성만 만족, 일반 정렬 아님.

nlargest / nsmallest

import heapq

heapq.nlargest(3, [1, 5, 2, 8, 3])     # [8, 5, 3]
heapq.nsmallest(3, [1, 5, 2, 8, 3])    # [1, 2, 3]

# key 함수
heapq.nlargest(2, students, key=lambda s: s.score)

전체를 정렬할 필요 없이 top-N만 가져온다. N이 작으면 매우 효율적 (O(n log k)).

max-heap

heapq는 min-heap만. max-heap이 필요하면 부호 뒤집기.

import heapq

h = []
heapq.heappush(h, -5)       # 음수로 저장
heapq.heappush(h, -1)
heapq.heappush(h, -3)

print(-heapq.heappop(h))    # 5 (최대)

튜플 키도 가능:

# (-priority, item) 형태
heapq.heappush(h, (-priority, item))
_, item = heapq.heappop(h)

우선순위 큐 with 동률

같은 우선순위에서 삽입 순서 보존하려면 카운터 추가.

import heapq
import itertools

counter = itertools.count()
pq = []

def push(priority, item):
    heapq.heappush(pq, (priority, next(counter), item))

def pop():
    priority, _, item = heapq.heappop(pq)
    return item

push(3, "task3")
push(1, "task1")
push(3, "task3.5")
print(pop())    # task1
print(pop())    # task3 (먼저 들어간 것)
print(pop())    # task3.5

객체끼리 비교가 불가능할 때 동률 시 TypeError 방지 효과도.

heappushpop / heapreplace

heapq.heappushpop(h, x)   # push 후 pop (한 번에 더 효율적)
heapq.heapreplace(h, x)   # pop 후 push (역순)

heapreplace는 비어 있으면 IndexError.

merge: 정렬된 시퀀스 병합

import heapq

a = [1, 3, 5, 7]
b = [2, 4, 6, 8]
c = [0, 9]

list(heapq.merge(a, b, c))    # [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

각 입력이 이미 정렬되어 있다고 가정. iterator라 메모리 효율적.

bisect: 정렬된 리스트의 이진 탐색

import bisect

xs = [1, 3, 5, 7, 9]

print(bisect.bisect_left(xs, 5))    # 2 (== 5의 가장 왼쪽 인덱스)
print(bisect.bisect_right(xs, 5))   # 3 (== 5의 가장 오른쪽 이후)
print(bisect.bisect(xs, 5))         # 3 (bisect_right와 동일)

# 정렬 유지하며 삽입
bisect.insort(xs, 4)
print(xs)                            # [1, 3, 4, 5, 7, 9]

O(log n) 이진 탐색 + O(n) 삽입(리스트 이동). 작은 리스트엔 빠르고 명확.

응용: rank, sorted insert

import bisect

# 점수 → 등급
def grade(score, thresholds=[60, 70, 80, 90]):
    """thresholds 기준 등급 반환"""
    grades = "FDCBA"
    i = bisect.bisect_left(thresholds, score)
    return grades[i]    # 잘못 - inverted

# 더 흔한 패턴: 정렬 순위
def rank(arr, x):
    return bisect.bisect_left(sorted(arr), x)

key 인자 (3.10+)

import bisect

users = [{"age": 20}, {"age": 25}, {"age": 30}]
bisect.bisect_left(users, 26, key=lambda u: u["age"])    # 2

이전엔 키 시퀀스 별도 유지가 필요했음.

array: 컴팩트한 동질 배열

list는 PyObject 포인터 배열이라 int 하나에도 28바이트(+ 포인터 8바이트) 정도. array.array는 C 타입으로 저장 → 메모리 1/4 ~ 1/8.

from array import array

a = array("i", [1, 2, 3, 4, 5])    # signed int
a.append(6)
a.extend([7, 8])

print(len(a), a.itemsize, a.itemsize * len(a))

타입 코드:

코드	C 타입	크기
`b` / `B`	signed/unsigned char	1
`h` / `H`	short	2
`i` / `I`	int	2 또는 4
`l` / `L`	long	4 또는 8
`q` / `Q`	long long	8
`f`	float	4
`d`	double	8
`u`	wchar_t	2 또는 4

list 대비 메모리 절감 효과는 큼. 그러나 산술 연산은 여전히 Python 수준. 수치 계산은 numpy가 압도적.

import array
import numpy as np

# array.array: 메모리 절감만
a = array.array("i", range(100000))

# numpy: 메모리 + 속도 (벡터 연산)
b = np.arange(100000)
b * 2 + 1    # 한 번에 벡터 연산

비교: 언제 무엇을 쓰나

자료구조	용도
`list`	일반 가변 시퀀스
`tuple`	불변 시퀀스, 해시 가능
`collections.deque`	양끝 O(1) 큐/스택
`heapq` (list 위에)	min-heap 우선순위 큐
`sortedcontainers.SortedList`	정렬 유지 O(log n) 삽입/삭제
`bisect` + `list`	정렬된 list 이진 탐색
`array.array`	메모리 효율적 동질 배열
`numpy.ndarray`	수치 연산 + 메모리 효율
`dict`, `set`	해시 기반 O(1)
`collections.OrderedDict`	LRU 캐시 베이스

sortedcontainers (third-party 추천)

pip install sortedcontainers

from sortedcontainers import SortedList, SortedDict, SortedSet

sl = SortedList([3, 1, 4, 1, 5])
sl.add(2)            # 정렬 유지 삽입 O(log n)
print(sl[0])         # 최소 O(1)
print(sl[-1])        # 최대 O(1)
print(sl.index(4))   # 위치
sl.remove(1)         # 삭제 O(log n)

표준 라이브러리엔 없지만 알고리즘 문제·실무에서 자주 유용. 내부적으로 list의 list로 구현 → 평균 매우 빠름.

자주 보는 패턴

top-k 스트리밍

import heapq

def top_k(stream, k):
    h = []
    for x in stream:
        if len(h) < k:
            heapq.heappush(h, x)
        elif x > h[0]:
            heapq.heapreplace(h, x)
    return sorted(h, reverse=True)

전체 스트림을 메모리에 안 들고 top-k만 유지. O(n log k).

k-way merge

import heapq

def kway_merge(*sorted_iters):
    return list(heapq.merge(*sorted_iters))

외부 정렬(external sort)에서 자주 등장하는 패턴.

Dijkstra 알고리즘

import heapq

def dijkstra(graph, start):
    dist = {start: 0}
    pq = [(0, start)]
    while pq:
        d, u = heapq.heappop(pq)
        if d > dist.get(u, float('inf')): continue
        for v, w in graph[u].items():
            nd = d + w
            if nd < dist.get(v, float('inf')):
                dist[v] = nd
                heapq.heappush(pq, (nd, v))
    return dist

우선순위 큐의 대표적 응용.

[Python] import 시스템과 패키지

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Python import 시스템은 **모듈(.py 파일)과 패키지(디렉터리)**를 메모리에 로드하고 네임스페이스에 바인딩한다. CPython은 한 번 로드한 모듈을 sys.modules 캐시에 보관해 재import 시 디스크를 다시 읽지 않는다.

모듈 vs 패키지

모듈(module): 단일 .py 파일
패키지(package): __init__.py를 포함한 디렉터리(또는 namespace package)
namespace 패키지: __init__.py 없이 디렉터리만 (PEP 420)

myapp/
    __init__.py       # 일반 패키지
    main.py
    utils/
        __init__.py
        text.py
        date.py

import 구문 4가지

import math                          # 모듈 전체
import numpy as np                   # 별칭
from collections import deque        # 특정 이름만
from typing import List, Optional    # 여러 이름
from os.path import *                # 별표 import (비권장)

from M import x는 M 모듈을 일단 로드한 후 그 안의 x 이름만 현재 네임스페이스에 바인딩한다. 모듈 자체는 sys.modules에 있지만 현재 스코프에서 접근 불가.

검색 경로: sys.path

import할 때 Python은 다음 순서로 모듈을 찾는다.

빌트인 모듈 (math, sys, …)
sys.path 리스트의 각 디렉터리
namespace 패키지 폴백

import sys
print(sys.path)
# ['', '/path/to/script-dir', ...stdlib..., '...site-packages...']

sys.path[0]은 스크립트의 디렉터리(또는 REPL 시 '' = 현재 디렉터리). 여기에 영향받아 import 동작이 달라진다.

PYTHONPATH 환경 변수

export PYTHONPATH=/extra/lib:$PYTHONPATH
python myscript.py

설치 없이 임시 경로 추가 시 유용. 배포에는 권장 안 함.

import 메커니즘 (간략)

import M이 실행되면 sys.modules에 M이 있는지 확인
있으면 그 객체 반환 (캐시 히트)
없으면 finders → loaders 체인을 통해 모듈을 찾고 로드
sys.modules[M]에 등록
모듈 코드(전역 명령문들)를 위→아래로 실행
현재 네임스페이스에 M 바인딩

import sys
print("math" in sys.modules)    # 첫 import 후 True

init.py 역할

패키지를 일반 패키지로 표시 (없으면 namespace package)
패키지 초기화 코드 (import 시 실행됨)
__all__ 정의 (별표 import 노출 목록)
편의 import 재노출

# myapp/utils/__init__.py
from .text import slugify, normalize
from .date import to_iso, parse_iso

__all__ = ["slugify", "normalize", "to_iso", "parse_iso"]

이렇게 하면 from myapp.utils import slugify 가능.

절대 import vs 상대 import

# 절대 import (권장)
from myapp.utils.text import slugify

# 상대 import (패키지 내부)
from .text import slugify          # 같은 패키지
from ..models import User           # 한 단계 위
from ...common import config        # 두 단계 위

상대 import는 패키지 안에서만 동작. 스크립트로 직접 실행 시(python utils/text.py) ImportError.

PEP 8은 명시성을 위해 절대 import 권장, 단 큰 코드베이스에선 상대가 리팩토링에 강함.

main

스크립트로 실행되는지 import되는지 구분.

# myapp/cli.py
def main():
    print("Running CLI")

if __name__ == "__main__":
    main()

python -m myapp.cli나 python myapp/cli.py 실행 시 __name__ == "__main__". import 시는 모듈 이름.

python -m M은 M을 모듈로 import 후 그 안의 __main__ 블록 실행. 패키지에선 __main__.py를 본다.

init.py 부작용 함정

# myapp/__init__.py
print("loading myapp")    # import myapp만 해도 출력됨

from .heavy_module import *  # 초기화가 느려짐

패키지 import 시 항상 실행되므로 느린 / 부작용 있는 코드 금지. 무거운 import는 함수 안으로 옮기거나 lazy 로딩.

순환 import (Circular Import)

# a.py
from b import B
class A: pass

# b.py
from a import A
class B: pass

import a는 b를 import → b는 a를 import (아직 미완료) → 부분 모듈을 받음 → A 미정의 → ImportError.

해결법

함수 안 import (지연 평가):

# a.py
class A:
    def use_b(self):
        from b import B    # 함수 호출 시 import
        return B()

공통 모듈로 분리:

# common.py
class Shared: pass

# a.py, b.py
from common import Shared

인터페이스 분리: ABC/Protocol로 의존 방향 뒤집기.

import 캐시 무효화

import importlib
import mymodule

# 코드 수정 후 다시 로드 (REPL/주피터에서 유용)
importlib.reload(mymodule)

테스트/디버깅 외엔 거의 안 씀. 진짜 자동 재로딩은 watcher 라이브러리 사용.

namespace 패키지 (PEP 420)

__init__.py 없는 디렉터리도 import 가능. 여러 디렉터리를 같은 패키지 이름 아래 합칠 수 있음.

plugin_a/myapp/plugins/
plugin_b/myapp/plugins/

sys.path에 둘 다 있으면 myapp.plugins에서 양쪽이 합쳐 보인다. 플러그인 시스템에 유용.

site-packages와 pip

pip install requests           # site-packages에 설치
python -c "import requests; print(requests.__file__)"

site-packages는 sys.path에 자동으로 추가되는 디렉터리. 가상 환경(venv) 사용 시 환경별로 격리.

python -m venv .venv
source .venv/bin/activate
pip install requests

좋은 import 관례 (PEP 8)

파일 최상단에 모아두기
순서: 표준 라이브러리 → 서드파티 → 로컬, 각 그룹 사이 빈 줄
한 줄에 하나(여러 이름 import는 from 문으로)
절대 import 우선, 필요시 명시적 상대 import
별표 import(from m import *) 피하기

import os
import sys
from pathlib import Path

import numpy as np
import pandas as pd

from myapp.utils import slugify
from myapp.models import User

김신건의 로그 - 위키 / python

[Python] asyncio: 비동기 프로그래밍

정의

사용 상황

이벤트 루프 메커니즘

기본

병렬 실행

gather

as_completed

Task 생성과 생명주기

Semaphore 로 동시 실행 제한

async context manager

asyncio.timeout / wait_for

TaskGroup (Python 3.11+)

asyncio.Queue

취소 처리

run_in_executor: 블로킹 코드 연동

함정

실전 라이브러리

관련 위키

[Python] Comprehension: list, dict, set, generator

정의

4가지 형태

평가 순서 시각화

list comprehension

변환 + 필터 동시

중첩 for

2차원 → 1차원 (flatten)

중첩 for 순서

조건부 표현식

dict comprehension

dict 뒤집기

필터링

set comprehension

generator expression

성능: list comp vs for loop vs map

Walrus(:=)와 결합

async comprehension (3.6+)

실전 패턴

JSON 필드 추출

중복 제거 (순서 유지)

중첩 dict 평탄화

그룹핑 (itertools 없이)

가독성 한계

스코프 (3.x)

함정

관련 위키

[Python] dict: 해시 맵과 삽입 순서 보장

정의

내부 구조 (compact dict, 3.6+)

생성

기본 연산

뷰: keys / values / items

순회

defaultdict / Counter

Counter 산술

setdefault와 get

dict 병합 (3.9+)

ChainMap: 계층적 조회

해시 가능성

내부 구조 간단히

실전 패턴

dict를 클래스처럼: TypedDict

조건부 키 포함

함수형: dict → 변환

성능 함정

관련 위키

[Python] int: 임의 정밀도 정수

정의

CPython 내부 구조: PyLongObject

3.12 이전: ob_size

3.12+: Compact Representation

Small Int Cache: -5 ~ 256

왜 -5 ~ 256인가

기본 사용

C long vs Python int

진법 리터럴

정수 연산

비트 연산

비트 조작 패턴

Walrus(`:=`)와 결합

3.12 이전: `ob_size`

`is`로 정수 비교

`__init_subclass__` (PEP 487, 3.6+)

2. Django ORM `ModelBase`

`prepare` 리턴값의 함정

`slots`와 tuple 조합

`_replace()`는 새 객체 반환

Walrus Operator `:=` (PEP 572, 3.8+)