비전공자 파이썬 모듈 만드는 법, 파일 나눠야 할 때는 언제인가요

비전공자 파이썬 모듈 만드는 법이 궁금해지는 시점은 대체로 비슷합니다. 처음엔 스크립트 파일 하나로 충분했는데, 어느새 300줄, 500줄이 넘어가면서 어디에 어떤 함수가 있는지 스크롤을 몇 번씩 해야 찾게 되는 순간입니다. 결론부터 말씀드리면, 모듈은 거창한 개념이 아니라 “코드를 담은 파이썬 파일을 다른 파일에서 불러다 쓰는 것”이며, 함수 몇 개만 잘 묶어도 바로 시작할 수 있습니다.

비전공자를 위한 코딩 입문 로드맵에서 다뤘듯, 처음 코딩을 배울 때는 파일 하나에 모든 코드를 몰아 쓰는 것이 자연스럽습니다. 하지만 자동화 스크립트를 여러 개 만들다 보면 “지난주에 만든 엑셀 취합 함수를 이번 스크립트에서도 쓰고 싶은데” 하는 상황이 반드시 생깁니다. 이때 필요한 것이 바로 모듈입니다.

모듈이 뭔가요, 그냥 파일 아닌가요

맞습니다. 파이썬에서 모듈은 특별한 것이 아니라 .py 확장자를 가진 파일 자체입니다. 그 파일 안에 정의된 함수나 변수를 다른 파일에서 import 문으로 가져다 쓸 수 있으면, 그 파일이 곧 모듈이 됩니다. 복잡한 설정이나 별도 도구 없이, 파일을 나누고 import 한 줄만 쓰면 됩니다.

예를 들어 엑셀 파일을 정리하는 함수들을 excel_tools.py라는 파일에 모아뒀다고 가정해보겠습니다.

# excel_tools.py

def clean_column_name(name):
    """열 이름의 앞뒤 공백과 특수문자를 제거합니다."""
    return name.strip().replace("\n", "").replace(" ", "")

def merge_sheets(sheet_list):
    """여러 시트 데이터를 하나의 리스트로 합칩니다."""
    result = []
    for sheet in sheet_list:
        result.extend(sheet)
    return result

이제 다른 파일에서 이 함수들을 그대로 가져다 쓸 수 있습니다.

# main.py

from excel_tools import clean_column_name, merge_sheets

raw_name = "  부서명 \n"
print(clean_column_name(raw_name))  # 부서명

sheets = [["A", "B"], ["C", "D"]]
print(merge_sheets(sheets))  # ['A', 'B', 'C', 'D']

main.py와 excel_tools.py가 같은 폴더 안에만 있으면 별도 설치 없이 바로 동작합니다. 이것이 모듈의 전부이며, 나머지는 이 구조를 언제 어떻게 확장할지의 문제입니다.

언제 파일을 나눠야 할까요

파일을 나누는 정확한 줄 수 기준은 없지만, 실무에서 참고할 만한 신호는 세 가지 정도입니다.

첫째, 같은 함수를 두 개 이상의 스크립트에서 복사 붙여넣기 하고 있다면 나눌 시점입니다. 복사한 함수 중 하나를 고쳤는데 다른 파일의 함수는 그대로인 경우, 나중에 왜 결과가 다른지 한참 헤매게 됩니다. 함수를 한 곳에 모아두면 수정도 한 곳에서만 하면 됩니다.

둘째, 파일 하나에 성격이 다른 코드가 섞여 있을 때입니다. 예를 들어 엑셀 파일을 읽는 코드, PDF를 다루는 코드, 이메일을 보내는 코드가 한 파일에 뒤섞여 있다면 각각 excel_tools.py, pdf_tools.py, mail_tools.py처럼 역할별로 나누는 것이 좋습니다. 엑셀 반복 업무를 파이썬으로 자동화하다가 PDF 자동화까지 손을 뻗게 되면 이런 분리가 특히 유용해집니다.

셋째, 파일을 열었을 때 원하는 함수를 찾기까지 스크롤이 오래 걸린다면 이미 나눴어야 할 시점을 지난 것입니다. 파일 상단에 목차처럼 함수 목록을 적어두고 찾아야 한다면, 그 자체가 분리 신호입니다.

파이썬 모듈, 언제 파일을 나눠야 할까

폴더 구조는 어떻게 잡아야 하나요

모듈이 늘어나면 폴더 구조도 함께 정리하는 것이 좋습니다. 흔히 쓰는 방식은 아래와 같습니다.

project/
├── main.py
├── excel_tools.py
├── pdf_tools.py
└── mail_tools.py

여기서 더 나아가 관련 모듈을 하나의 폴더로 묶고 싶다면 패키지라는 개념을 씁니다. 폴더 안에 __init__.py라는 빈 파일 하나만 넣어두면, 그 폴더를 하나의 패키지로 인식해 폴더째로 import할 수 있습니다.

project/
├── main.py
└── tools/
    ├── __init__.py
    ├── excel_tools.py
    └── pdf_tools.py

# main.py
from tools.excel_tools import clean_column_name
from tools.pdf_tools import merge_pdf_files

처음부터 이렇게 복잡한 구조를 만들 필요는 없습니다. 함수가 10개를 넘어가고, 폴더 하나로 관리할 만큼 자동화 스크립트가 여러 개 쌓였을 때 고려해도 늦지 않습니다.

자주 실수하는 부분

모듈을 처음 만들 때 자주 걸리는 문제는 크게 두 가지입니다.

하나는 파일 이름이 파이썬 표준 라이브러리 이름과 겹치는 경우입니다. 예를 들어 random.py라는 이름으로 파일을 만들면, 원래 파이썬에 내장된 random 모듈 대신 내가 만든 빈 파일을 불러오게 되어 이상한 에러가 납니다. 이런 에러를 만났을 때는 에러 메시지를 읽는 법을 참고해 어떤 모듈이 어디서 충돌하는지부터 확인하는 것이 순서입니다.

다른 하나는 순환 참조입니다. a.py가 b.py를 import하는데 b.py도 다시 a.py를 import하면 파이썬이 어느 것을 먼저 불러와야 할지 알 수 없어 오류가 납니다. 이럴 때는 두 파일이 공통으로 쓰는 함수를 별도의 common.py로 따로 빼는 방식으로 해결합니다.

모듈을 만들면 뭐가 좋아지나요

가장 큰 이점은 유지보수입니다. 함수 하나를 고쳤을 때 그 함수를 쓰는 모든 스크립트에 자동으로 반영되므로, 여러 파일을 돌아다니며 같은 수정을 반복할 필요가 없습니다. 또한 자동화 스크립트를 여러 개 운영하는 회사라면 자동화 로그 작성과 마찬가지로, 모듈 구조 자체가 “이 기능은 어디에 있다”는 최소한의 문서 역할을 해줍니다. 함수 이름과 파일명만 잘 지어도 나중에 코드를 다시 볼 때, 혹은 다른 담당자가 이어받을 때 훨씬 수월해집니다.

파이썬 함수 자체를 어떻게 만들고 왜 필요한지가 아직 낯설다면, 파이썬 함수 입문을 먼저 보시는 것을 권합니다. 함수를 잘 만들 수 있어야 모듈로 나누는 것도 의미가 있기 때문입니다.

정리하면

모듈은 새로운 문법이 아니라 이미 알고 있는 함수를 정리하는 습관에 가깝습니다. 처음에는 파일 하나로 시작해도 괜찮지만, 복사 붙여넣기가 반복되거나 파일이 지나치게 길어진다면 그때 나누기 시작해도 늦지 않습니다. 픽셀앤코드는 이런 실무형 자동화 스크립트 설계와 코드 정리 방법을 사무직 실무자 눈높이에 맞춰 교육하고 있으며, 이미 만들어둔 자동화 코드를 팀 전체가 유지보수할 수 있는 구조로 다듬는 작업도 함께 지원하고 있습니다.