파이썬 모듈: 재사용 가능한 코드의 최소 단위

모듈이란

파이썬에서 모듈은 함수, 변수, 클래스를 담고 있는 .py 파일 하나를 말합니다.

정의 자체는 단순하지만, 모듈을 제대로 이해하면 코드의 재사용성을 높이고 프로젝트 구조를 훨씬 깔끔하게 만들 수 있습니다.

같은 기능을 여러 파일에 중복으로 작성하지 않아도 되고, 필요한 곳에서 불러다 쓰기만 하면 됩니다.

모듈 이름 짓는 규칙

이름을 어떻게 짓느냐가 나중에 import할 때 가독성에 큰 영향을 줍니다.
파이썬 컨벤션 기준으로 정리하면 이렇습니다.

• 소문자로 작성합니다. MyModule.py보다 mymodule.py가 맞습니다.
• 짧고 명확하게 씁니다. calc.py, dataprocessing.py처럼 기능이 바로 읽히는 이름이 좋습니다.
• 단어 구분이 필요하면 밑줄(_)을 씁니다. data_processing.py, user_management.py처럼 작성합니다.

모듈 import 방법

모듈을 불러오는 방법은 크게 세 가지입니다.

각각 언제 어떻게 쓰는지 직접 비교해보면 차이가 명확하게 드러납니다.

아래처럼 add와 subtract 함수를 담은 mymodule.py가 있다고 가정합니다.

# mymodule.py
def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

방법 1: 모듈 전체를 import

import mymodule

mymodule.add(5, 3)       # 8
mymodule.subtract(5, 3)  # 2

 

함수 앞에 모듈 이름을 붙여야 합니다.

어디서 온 함수인지 명확히 보인다는 장점이 있습니다.

 

방법 2: 특정 함수만 import

from mymodule import add, subtract

add(5, 3)       # 8
subtract(5, 3)  # 2

 

모듈 이름 없이 함수를 바로 쓸 수 있습니다.

필요한 것만 골라서 가져올 수 있어 코드가 간결해집니다.

 

방법 3: 모듈 전체를 한 번에 import (*)

from mymodule import *

 

모듈 안의 모든 것을 가져오지만, 어떤 함수가 어디서 왔는지 추적하기 어려워지기 때문에 큰 프로젝트에서는 권장하지 않는 방식입니다.

세 가지 방법 중 어떤 걸 쓸지는 상황에 따라 다르지만, 개인적으로는 명확성 때문에 방법 1이나 2를 주로 씁니다.

if __name__ == "__main__": 가 필요한 이유

파이썬에서 모든 모듈은 __name__이라는 내장 변수를 가집니다.

이 변수의 값이 상황에 따라 달라집니다.

• 해당 파일을 직접 실행하면 → __name__이 "__main__"이 됩니다.
• 해당 파일을 다른 파일에서 import하면 → __name__이 파일 이름(모듈명)이 됩니다.

이게 왜 중요한지는 아래 두 파일을 비교해보면 바로 알 수 있습니다.

 

이 구문 없이 작성한 경우

# mymodule_bad.py
def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

print("Add:", add(5, 3))
print("Subtract:", subtract(5, 3))

 

이 파일을 직접 실행하면 당연히 출력이 잘 됩니다.

문제는 이 모듈을 다른 파일에서 import할 때도 print가 실행된다는 점입니다.

다른 파일에서 단순히 add 함수만 가져다 쓰고 싶었을 뿐인데, 불필요한 출력이 같이 따라옵니다.

 

이 구문을 넣은 경우

# mymodule_good.py
def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

if __name__ == "__main__":
    print("Add:", add(5, 3))
    print("Subtract:", subtract(5, 3))

이렇게 하면 직접 실행할 때만 if 블록 안의 코드가 실행되고, 다른 파일에서 import할 때는 함수 정의만 가져옵니다.

이 구문이 결국 "이 파일이 직접 실행될 때"와 "라이브러리로 불려올 때"를 구분하는 스위치 역할을 한다고 보면 됩니다.

모듈에 변수와 클래스도 담기

모듈 안에는 함수만 넣는 게 아니라 변수나 클래스도 함께 넣을 수 있습니다.

# mymodule2.py
PI = 3.14159

def add(a, b):
    return a + b

class Calculator:
    def __init__(self):
        self.value = 0

    def add(self, amount):
        self.value += amount
        return self.value

    def reset(self):
        self.value = 0
        return self.value

 

이렇게 하면 mymodule2.PI처럼 변수도, mymodule2.Calculator()처럼 클래스도 외부에서 그대로 가져다 쓸 수 있습니다.

다른 디렉토리에 있는 모듈 사용하기

모듈 파일이 같은 디렉토리에 있으면 아무 문제 없이 import됩니다.

그런데 모듈을 별도 디렉토리에 분리해두면 ModuleNotFoundError를 만나게 됩니다.

파이썬이 해당 경로를 모듈 탐색 범위로 알고 있지 않기 때문입니다.

 

파이썬이 모듈을 찾는 범위는 sys.path에 등록된 경로들입니다.

import sys
print(sys.path)  # 파이썬이 모듈을 탐색하는 경로 목록

이 문제를 해결하는 방법은 두 가지입니다.

 

방법 1: 코드 안에서 sys.path에 경로 추가

import sys
import os

sys.path.append(os.path.abspath('mymodules'))
import mymodule3

코드 안에서 직접 경로를 넣는 방식이라 이식성은 좀 떨어지지만 빠르게 테스트할 때 편합니다.

 

방법 2: 환경변수 PYTHONPATH 설정

export PYTHONPATH="경로/mymodules"

셸에서 환경변수로 잡아두면 해당 세션에서는 어디서든 해당 디렉토리 안의 모듈을 바로 import할 수 있습니다.

프로젝트를 체계적으로 관리할 때는 .bashrc에 등록해두는 편이 더 깔끔합니다.

내장 모듈 활용

파이썬 표준 라이브러리에는 별도 설치 없이 바로 쓸 수 있는 모듈들이 많습니다.

자주 쓰이는 것들만 정리하면 이렇습니다.

import math
print(math.sqrt(16))   # 4.0
print(math.pi)         # 3.141592653589793

import datetime
now = datetime.datetime.now()
print(now)   # 현재 날짜와 시간

import sys
print(sys.version)   # 파이썬 버전

 

이 외에도 json, re, collections, itertools 등 표준 라이브러리에만 해도 웬만한 작업은 다 커버됩니다.

외부 패키지를 설치하기 전에 표준 라이브러리에 이미 있는 게 아닌지 먼저 확인하는 습관이 생겼습니다.

서드파티 모듈 설치 및 사용

표준 라이브러리에 없는 기능이 필요하다면 외부 패키지를 설치해서 씁니다. 3편에서 Poetry 환경을 세팅해뒀다면 아래처럼 설치합니다.

poetry add requests

설치 후에는 일반 모듈처럼 import해서 쓰면 됩니다.

import requests

response = requests.get("https://api.github.com")
print(response.status_code)

실행할 때는 Poetry 가상환경 안에서 해야 합니다.

poetry run python script.py
# 또는 가상환경을 직접 활성화 후 실행
source .venv/bin/activate
python script.py
deactivate