[Python 학습] 2-11 코드가 길어질 때 필수! 파이썬 모듈과 import 사용법 완전 정복 (feat. 파일 나누기 & 에러 해결)

안녕하세요! 파이썬 공부를 하다 보면 처음에는 몇 십 줄짜리 코드로 시작하지만, 기능이 하나둘 늘어나면서 어느새 코드가 수백, 수천 줄을 넘어가곤 합니다.

"이 많은 함수를 한 파일에서 다 관리해야 하나?" "내가 만든 함수를 다른 파일에서 간편하게 불러와서 쓸 순 없을까?" "파이썬에 내장된 날짜 계산이나 난수 생성 기능은 대체 어디에 숨어 있는 거지?"

혹시 이런 고민을 해보신 적이 있으신가요?

프로그램이 커지기 시작하면 한 파일 안에 너무 많은 함수와 변수가 모이게 되어 내가 원하는 코드를 찾고 수정하기가 점점 더 힘들어집니다. 이때 구원투수처럼 등장하는 개념이 바로 파이썬 모듈과 import입니다. 오늘 글에서는 코드를 똑똑하게 나누고 재사용하는 방법부터 입문자들이 가장 자주 마주치는 import 에러 해결법까지 아주 쉽게 정리해 드릴게요! 😉

---

1. 💡 맛있는 비유로 쉽게 이해하는 '모듈'과 'import'

모듈이라는 단어가 처음에는 낯설게 느껴질 수 있지만, 실생활의 예시로 생각하면 정말 단순합니다.

• 함수(Function): 요리책 안의 레시피 한 개에 해당합니다. (특정 기능 한 가지를 수행하는 코드 덩어리)
• 모듈(Module): 비슷한 주제의 레시피들을 가득 모아둔 요리책 한 권입니다. 파이썬에서는 단순히 코드를 모아둔 하나의 .py 파일이 바로 모듈이 됩니다.
• import: 책장에서 나에게 필요한 요리책을 꺼내어 참고하는 행동입니다. 다른 파일에 있는 코드를 현재 파일에서 사용할 수 있게 연결해 주는 통로 역할을 하죠.
• 표준 라이브러리: 파이썬을 설치할 때 기본적으로 무료 제공되는 공용 도구함입니다.
• 사용자 정의 모듈: 내가 직접 만든 도구들을 정리해 둔 개인 도구함입니다.

매번 똑같은 코드를 복사해서 붙여넣는 대신, 파일 하나에 코드를 잘 정리해 두고 필요한 곳에서 import를 사용하면 코드 재사용성이 비약적으로 상승하게 됩니다.

---

2. 📁 파이썬 코드 파일 나누기: 왜 해야 할까요?

단순히 "코드가 깔끔해 보여서"만은 아닙니다. 실무 개발에서 파일을 역할별로 모듈화하는 데에는 명확한 이유가 있습니다.

1. 가독성과 유지보수 향상: 코드가 길어질수록 오류가 났을 때 원인을 찾기 어렵습니다. 기능을 기능별 파일로 분리하면 수정해야 할 범위가 대폭 줄어듭니다.
2. 역할과 책임의 분리: 실무에서는 보통 다음과 같이 프로젝트 구조를 설계하여 각 파일에 분명한 역할을 부여합니다.
   • main.py: 프로그램의 시작점이자 전체적인 실행 흐름을 제어하는 파일
   • calculator.py: 다양한 계산 관련 함수들을 모아둔 파일
   • file_utils.py: 파일을 읽고 쓰는 처리를 전담하는 파일
   • validators.py: 입력값의 유효성을 검증하는 파일
3. 코드 재사용과 협업: 잘 나누어 둔 모듈은 다른 프로젝트에서도 그대로 가져와 쓸 수 있고, 여러 개발자가 역할을 나누어 동시에 작업하기 편리해집니다.

---

3. 🛠️ 파이썬 표준 라이브러리 vs 사용자 정의 모듈

파이썬에서는 크게 두 가지 모듈을 활용할 수 있습니다.

① 이미 만들어져 제공되는 '파이썬 표준 라이브러리'

파이썬은 개발자가 모든 것을 바닥부터 직접 만들지 않도록, 검증된 도구 세트들을 기본 제공합니다. 외부에서 별도로 다운로드받아 설치할 필요 없이 바로 import만 해서 쓸 수 있는 아주 유용한 기능들이 많습니다.

• math: 수학 계산 (예: 루트 계산 math.sqrt())
• random: 난수 생성 및 무작위 값 추출
• datetime: 날짜와 시간 다루기
• json: 웹 통신에 자주 쓰이는 데이터 포맷 처리

# 표준 라이브러리 사용 예시
import random [3, 14]

number = random.randint(1, 10)  # 1부터 10 사이의 난수 생성 [3, 14]
print(number)

② 내가 직접 만들어 쓰는 '사용자 정의 모듈'

특별한 등록 절차가 없어도, 직접 작성한 .py 파일은 그 자체로 훌륭한 모듈이 됩니다.

예를 들어, 같은 폴더에 아래 두 개의 파일을 준비해 봅시다.

• greetings.py (모듈 파일)

def say_hello(name): [12]
    return f"안녕하세요, {name}님" [12]

• main.py (실행 파일)

from greetings import say_hello [12]

message = say_hello("민수") [12]
print(message)  # 출력: 안녕하세요, 민수님 [12]

이처럼 greetings.py 파일의 기능을 main.py에서 손쉽게 불러와 재사용할 수 있습니다.

---

4. 🔍 import 사용법 : 3가지 호출 방식 장단점 비교

모듈을 불러오는 구문은 여러 가지가 있는데, 상황에 맞는 선택 기준을 아는 것이 중요합니다.

호출 방식코드 예시장점 (선택 기준)단점 및 주의점

import 모듈	import math<br>print(math.sqrt(16))	• 코드에서 어떤 모듈의 기능을 쓰는지 출처가 명확함<br>• 이름 충돌을 예방할 수 있음	• 함수를 쓸 때마다 앞에 모듈 이름을 계속 붙여야 해서 코드가 길어짐
from 모듈 import 이름	from math import sqrt<br>print(sqrt(16))	• 특정 기능만 바로 호출 가능<br>• 코드가 간결해짐	• 다른 파일에 동명의 함수가 있다면 출처 혼선 및 덮어쓰기 위험이 있음
별칭 지정 (as)	import datetime as dt<br>now = dt.datetime.now()	• 긴 모듈 이름을 짧게 줄여 편의성을 높임<br>• 실무에서 널리 쓰이는 형태 (예: import pandas as pd)	• 과도하게 개별적인 별칭을 임의로 만들면 타인이 코드를 이해하기 어려워짐

⚠️ 주의! from 모듈 import * 처럼 와일드카드를 사용하여 모듈 내 모든 함수를 한꺼번에 부르는 방식은 편해 보이지만, 어떤 모듈에서 가져온 기능인지 출처를 흐려 이름 충돌을 유발하므로 실무에서는 사용을 권장하지 않습니다.

---

5. 🚨 입문자가 가장 많이 겪는 import 3대 에러 & 예방법

파이썬 파일 분리를 시작하면 높은 확률로 막히는 세 가지 포인트가 있습니다. 미리 알아두면 불필요한 삽질 시간을 획기적으로 줄일 수 있습니다! 🚀

① ModuleNotFoundError (모듈을 찾을 수 없대요!)

• 원인: 파이썬 실행 경로상에서 해당 모듈 파일의 위치를 찾지 못했기 때문입니다.
• 해결법: 가져다 쓰려는 모듈 파일과 실행 파일(main.py)이 반드시 같은 폴더에 들어 있는지 확인해 주세요. 모듈 탐색 시 파이썬은 실행 중인 파일의 디렉토리를 가장 우선하여 찾기 때문에 폴더 위치 일치가 아주 중요합니다.

② AttributeError: module '...' has no attribute '...' (분명 있는 함수인데 없다고 나와요!)

• 원인: 직접 만든 파이썬 파일의 이름이 내장 모듈의 이름과 겹치는 경우 발생합니다.
• 사례: 난수 연습을 하겠다고 내가 만든 파이썬 파일명을 random.py로 짓고 실행하면, 파이썬은 내장 라이브러리인 random 대신 내가 만든 빈 파일을 먼저 읽어 들입니다. 결과적으로 내장 함수가 전부 덮어씌워져 에러를 뿜게 됩니다.
• 해결법: 파일명을 지을 때 random.py, math.py, json.py 같은 표준 라이브러리 이름과 겹치지 않게 주의해 주세요.

③ import만 했는데 파일 안의 코드가 지맘대로 실행돼요!

• 원인: 파이썬 모듈을 import하는 순간, 해당 파일의 최상위에 있는 코드들은 즉시 실행되기 때문입니다.
• 해결법: 모듈 안에는 함수나 클래스 정의만 남겨두고, 테스트나 실행 목적의 코드는 반드시 시작점 제어 코드 안으로 넣어 관리해 주셔야 합니다.

# module_ex.py
def my_func():
    print("기능 실행")

# 모듈 단독 실행 시에만 동작하고, import 시에는 실행을 차단함
if __name__ == "__main__":
    print("모듈 직접 테스트 실행!")
    my_func()

---

6. 🏁 에필로그 : 프로젝트 구조화로 나아가는 첫걸음

모듈과 import를 다룰 줄 알게 되었다면, 이제 여러분의 파이썬 코드는 단순한 단일 스크립트 연습 수준을 넘어 서로 유기적으로 협력하는 실제 프로젝트 구조로 확장되기 시작한 것입니다.

함수로 기능을 쪼개던 사고방식을 파일 단위로 한 단계 넓혀 보세요. 훨씬 더 견고하고 구조적인 설계를 구현할 수 있습니다.