[PY-004][기초] 함수·모듈·패키지로 Python 코드 나누기 > IT 기술 공유

• 목록

[이번 수업]
코드가 길어지면 한 파일에서 원하는 부분을 찾기 어려워집니다. 반복 작업은 함수로 묶고, 함수들을 모듈 파일에 두며, 관련 모듈은 패키지 폴더로 정리할 수 있습니다.

[선수지식]
PY-001의 실행과 기본 문법, PY-002의 문자열·불리언, PY-003의 리스트·딕셔너리를 알면 좋습니다. 파일과 폴더를 만들고 터미널에서 Python을 실행할 수 있어야 합니다.

[학습목표]
1. 매개변수와 반환값이 있는 함수를 작성한다.
2. Python 파일을 모듈로 가져온다.
3. 패키지 폴더와 `__init__.py`의 역할을 설명한다.
4. import 경로와 실행 위치에서 생기는 오류를 진단한다.

[핵심개념]
함수는 이름을 붙인 재사용 가능한 코드 단위입니다. `def` 뒤에 함수명과 매개변수를 적고, `return`으로 호출한 곳에 결과를 돌려줍니다. 매개변수(parameter)는 함수 정의의 입력 이름이고, 인자(argument)는 실제 호출 때 전달하는 값입니다. 함수가 `return` 없이 끝나면 `None`을 반환합니다.

모듈은 Python 정의와 문장을 담은 `.py` 파일입니다. `text.py`를 import하면 파일 이름 `text`가 모듈 이름이 됩니다.

패키지는 점으로 구분된 모듈 이름을 구성하는 방법입니다. 이 수업에서는 `study_tools` 폴더에 `__init__.py`를 둡니다. `from .text import normalize`의 점은 현재 패키지를 기준으로 가져오라는 상대 import입니다.

함수는 동작을 나누고, 모듈은 파일을 나누며, 패키지는 관련 모듈을 폴더와 이름 공간으로 묶습니다. 너무 작은 함수마다 파일을 만들기보다 함께 바뀌는 기능을 기준으로 나눕니다.

[따라하기]
`py-package-practice` 폴더 안에 `study_tools` 폴더를 만듭니다. Windows PowerShell은 `mkdir study_tools`, macOS·Linux도 `mkdir study_tools`를 사용할 수 있습니다. 다음 세 파일을 작성하세요.

`study_tools/text.py`
```python
def normalize(text: str) -> str:
    """앞뒤와 연속 공백을 정리한 새 문자열을 반환합니다."""
    return ' '.join(text.strip().split())
```

`study_tools/__init__.py`
```python
from .text import normalize

__all__ = ['normalize']
```

`main.py`
```python
from study_tools import normalize

raw = '  Python  package  '
cleaned = normalize(raw)

print(f'원본: [{raw}]')
print(f'정리: [{cleaned}]')

assert cleaned == 'Python package'
```

세 파일의 들여쓰기는 공백 4칸으로 맞춥니다. 프로젝트 최상위 폴더에서 Windows는 `python main.py`, macOS·Linux는 보통 `python3 main.py`를 실행합니다. `python -m main` 또는 `python3 -m main`도 같은 위치에서 실행할 수 있습니다. 예상 결과는 다음과 같습니다.

```text
원본: [  Python  package  ]
정리: [Python package]
```

assert가 조용히 끝나면 함수 반환값도 기대와 같습니다.

[흔한 실수]
- `return` 대신 print만 사용해 결과를 재사용하지 못합니다. 계산과 화면 출력을 나누세요.
- `study_tools.py` 파일과 같은 이름의 `study_tools` 폴더를 함께 만들어 import가 헷갈립니다.
- 프로젝트 바깥이나 다른 폴더에서 main.py를 실행해 ModuleNotFoundError가 납니다. 현재 경로를 확인하세요.
- 표준 라이브러리 이름과 같은 `json.py`, `typing.py` 파일을 만들어 원래 모듈을 가립니다.

[보안 주의]
import는 모듈의 최상위 코드를 실행할 수 있으므로 출처를 모르는 Python 파일이나 패키지를 실행하지 마세요. 비슷하게 철자만 바꾼 패키지를 잘못 설치하지 않도록 공식 이름과 출처를 확인합니다. 사용자 문자열을 모듈 이름으로 만들어 동적 import하거나 `eval`·`exec`로 실행하지 않습니다. API 키와 비밀번호는 모듈 상수로 적지 말고 안전한 설정 방식을 사용하세요. 실습은 로컬의 고정 문자열만 처리합니다.

[직접 해볼 과제]
1. `normalize`에 빈 문자열과 줄바꿈이 포함된 문자열을 전달해 결과를 확인하세요.
2. `study_tools/text.py`에 글자 수를 반환하는 `count_chars` 함수를 추가하고 패키지에서 공개하세요.
3. main.py에 assert 두 개를 더해 두 함수 결과를 검사하세요.

[확인문제]
1. 함수의 매개변수와 호출할 때의 인자는 어떻게 다른가요?
2. 모듈과 패키지는 각각 코드를 어떤 단위로 나누나요?
3. import할 파일의 최상위 코드에 예상 밖의 동작을 두면 왜 위험한가요?

[다음 학습]
번호 우선 순환에 따라 다음 글은 JSTS-004 이벤트 루프와 비동기 처리입니다. PY 다음 수업은 PY-005 가상환경과 pip입니다.

[공식 참고 자료]
- Python 함수 정의: https://docs.python.org/3/tutorial/controlflow.html#defining-functions
- Python 모듈: https://docs.python.org/3/tutorial/modules.html
- Python 패키지: https://docs.python.org/3/tutorial/modules.html#packages
- Python import 시스템: https://docs.python.org/3/reference/import.html