파이썬 프로그래밍 (5) - 프로젝트 구조 & 템플릿 분석

이영락·2024년 8월 1일

개발자 기본기

목록 보기

5/53

파이썬 프로젝트 구조 & 템플릿 분석

🏖️ 1. 프로젝트의 전체 구조

\root                        # 프로젝트의 최상위 디렉터리
    ├── .gitignore           # Git에 포함시키지 않을 파일 및 폴더를 정의
    ├── README.md            # 프로젝트 설명, 설치 방법, 사용법 등을 기록
    ├── LICENSE              # 프로젝트의 라이선스 정보
    ├── requirements.txt     # 프로젝트 실행에 필요한 패키지 목록
    ├── setup.py             # 프로젝트의 빌드, 배포를 위한 설정 파일
    ├── test_requirements.txt # 테스트에 필요한 패키지 목록
    ├── 패키지명              # 주요 소스 코드가 위치한 디렉터리
    │   ├── __init__.py      # 디렉터리가 파이썬 패키지임을 알리는 파일
    │   ├── 패키지명.py      # 주요 기능을 정의하는 메인 코드
    │   ├── info.py          # 패키지 이름과 버전을 정의하는 파일
    │   ├── 부가기능.py      # 부가적인 기능을 정의하는 소스 코드
    │   └── resources        # 설정 파일 등 리소스가 위치한 디렉터리
    │       ├── __init__.py  # 디렉터리가 파이썬 패키지임을 알리는 파일
    │       └── config.yml   # 프로그램 실행에 필요한 설정 파일
    └── tests                # 테스트 코드가 위치한 디렉터리
        ├── __init__.py      # 디렉터리가 파이썬 패키지임을 알리는 파일
        ├── test_부가기능.py  # 부가기능을 테스트하는 코드
        └── resources        # 테스트에 필요한 설정 파일이 위치한 디렉터리
            ├── __init__.py  # 디렉터리가 파이썬 패키지임을 알리는 파일
            └── config.yml   # 테스트에 필요한 설정 파일

🏖️ 2. 최상위 폴더 (`root`)의 구성 요소

`.gitignore`:

역할: Git에 커밋할 때 포함시키지 않을 파일과 폴더를 지정합니다. 예를 들어, 빌드 중 생성된 파일, IDE 설정 파일, 테스트 캐시 등을 제외할 수 있습니다.

예시:

/.pytest_cache/
/__pycache__/
*.pyc
*.egg
/dist/
/build/
/.idea/
*.DS_Store

.gitignore 파일에는 주로 버전 관리에서 제외하고 싶은 파일이나 디렉토리를 명시합니다.
프로젝트의 종류와 사용되는 언어에 따라 .gitignore 파일에 포함될 내용은 달라질 수 있지만, 일반적으로 포함되는 항목들은 다음과 같습니다.

운영체제별 파일

macOS: .DS_Store

Windows: Thumbs.db, desktop.ini

Linux: ~로 끝나는 임시 파일

IDE 및 텍스트 에디터 관련 파일

Visual Studio Code: .vscode/

JetBrains: .idea/

Sublime Text: .sublime-project, .sublime-workspace

빌드 파일 및 컴파일된 아티팩트

Python: __pycache__/, *.pyc, *.pyo

Java: *.class

C/C++: *.out, *.o, *.a, *.so

Node.js: node_modules/

환경 설정 파일

.env: 환경 변수 파일

.env.local, .env.*.local: 로컬 환경 설정

로그 파일

*.log

디펜던시 디렉토리

Python: venv/, .venv/

Node.js: node_modules/

배포 관련 파일

dist/, build/

임시 파일 및 백업 파일

*.tmp, *.swp, *.bak

예시 `.gitignore` 파일

1) Node.js 프로젝트를 예시로 한 .gitignore 파일

# Node.js 관련
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# 환경 변수 파일
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# 디렉토리별 빌드 결과물
dist/
build/

# 운영체제 파일
.DS_Store
Thumbs.db

# IDE 설정 파일
.vscode/
.idea/

# 로그 파일
*.log

# 임시 파일
*.tmp
*.swp
*.bak

2) 파이썬 프로젝트용 .gitignore 파일 예시

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
#  사용 시, PyInstaller가 빌드 아티팩트를 저장하는 디렉토리
#  아래 경로들은 사용자 설정에 따라 다를 수 있음
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
.hypothesis/

# Virtual environments
venv/
ENV/
env/
env.bak/
venv.bak/
.venv/
.venv.bak/

# Jupyter Notebook
.ipynb_checkpoints/

# PyCharm
.idea/

# VS Code
.vscode/

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# Local configuration files
*.env
.env.*

# macOS
.DS_Store

# Windows
Thumbs.db
desktop.ini

# Debug and profiler outputs
*.log
*.trace

# Pycharm local history
.idea/

# Environments specific
.envrc
.pdm.toml
.pdm.lock

# Flask/Django stuff:
instance/
.webassets-cache
scrapy.cfg

주요 항목 설명

__pycache__/, *.pyc, *.pyo: 파이썬이 생성하는 캐시 및 컴파일된 바이트코드 파일을 무시.

venv/, .venv/: 파이썬 가상환경 디렉토리를 무시합니다. 이는 프로젝트별 가상환경을 로컬에 저장할 때 유용.

*.log, *.trace: 로그 파일 및 프로파일러 출력 파일을 무시.

dist/, build/: 패키징 과정에서 생성되는 배포 관련 파일들을 무시.

.env: 환경 변수 파일을 무시하여, 민감한 정보가 Git에 포함되지 않도록 함.

.ipynb_checkpoints/: Jupyter Notebook에서 생성하는 체크포인트 파일을 무시.

추가 설명

와일드카드: *는 모든 문자열과 매칭됩니다. 예를 들어, *.log는 확장자가 .log인 모든 파일을 무시합니다.
디렉토리 무시: node_modules/처럼 슬래시(/)로 끝나는 항목은 해당 디렉토리와 그 하위 모든 파일을 무시합니다.
주석: #로 시작하는 줄은 주석으로 처리되어 무시됩니다.
특정 파일 제외: !를 사용하여 특정 파일을 포함할 수 있습니다. 예를 들어, !important.log는 다른 .log 파일들은 무시하지만 important.log는 무시하지 않도록 합니다.

.gitignore 파일은 프로젝트를 관리하는 데 매우 유용하므로, 항상 프로젝트에 맞게 잘 작성하는 것이 좋습니다. GitHub에서는 다양한 템플릿을 제공하므로, 그곳에서 시작하는 것도 좋은 방법입니다.

`README.md`:

역할: 프로젝트의 개요, 설치 방법, 사용 방법 등을 Markdown 형식으로 설명합니다. GitHub 등에서 프로젝트를 소개하는 첫 페이지로 사용됩니다.

내용 예시:

# 프로젝트 이름
### 개요
이 프로젝트는 X를 수행하기 위해 개발되었습니다.

### 설치 방법
$ pip install -r requirements.txt

### 실행 방법
$ python 패키지명.py

### 참고 사항
- 관련 문서: [링크]

`LICENSE`

역할: 프로젝트의 라이선스 정보를 명시합니다. 라이선스 파일은 프로젝트가 어떤 조건하에 사용될 수 있는지를 규정합니다.

LICENSE 파일에 대하여

LICENSE 파일은 오픈소스 프로젝트에서 소프트웨어의 사용, 복제, 배포, 수정에 대한 법적 권리를 명시하는 문서입니다. 이 파일을 통해 프로젝트의 사용자가 어떤 조건 아래에서 소프트웨어를 사용할 수 있는지, 그리고 어떤 권리와 제한이 있는지를 명확하게 알 수 있습니다.

주요 목적

법적 보호: LICENSE 파일은 개발자가 자신의 코드를 보호하고, 사용자가 코드 사용에 있어 허용된 범위를 알도록 도와줍니다.
명확한 사용 권한: 사용자가 프로젝트를 어떻게 사용할 수 있는지, 어떤 경우에 재배포가 가능한지, 그리고 어떤 조건 하에서 수정이 가능한지를 명확하게 규정합니다.
기여자 보호: 오픈소스 프로젝트에 기여하는 모든 사람은 프로젝트의 라이선스 조건에 따라 보호받습니다.

일반적으로 사용되는 라이선스

MIT License

간결하고 매우 자유로운 라이선스.
소프트웨어 사용, 복제, 수정, 병합, 게시, 배포, 서브라이선스, 판매 등이 가능.
저작권 고지와 라이선스 고지를 유지하는 조건만을 요구.

예시:

MIT License

Copyright (c) [YEAR] [AUTHOR]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Apache License 2.0
- 사용자에게 소프트웨어의 사용, 수정, 배포를 허용하며, 특허 사용 권한도 명시.
- 저작권 고지와 라이선스 고지 외에도, 수정된 파일에는 변경 사항을 명시.
- 예시:
```
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
...
```
GNU General Public License (GPL)
- 사용자에게 소프트웨어의 사용, 수정, 배포를 허용하지만, 수정된 소프트웨어도 동일한 GPL 라이선스로 배포되어야 함.
- 예시:
```
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
...
```
BSD License
- MIT 라이선스와 유사하지만, 저작권 고지와 함께 "보증 없음"을 명시하며, 저작자 이름을 사용한 광고를 제한.
- 예시:
```
BSD 3-Clause License

Copyright (c) [YEAR], [ORGANIZATION]
All rights reserved.
...
```

LICENSE 파일 작성 방법

라이선스 선택: 먼저 프로젝트에 적합한 라이선스를 선택. ChooseALicense 같은 웹사이트를 통해 어떤 라이선스가 적합한지 도움을 받을 수 있습니다.
라이선스 템플릿 복사: 선택한 라이선스의 템플릿을 복사하고, 저작권자와 연도를 포함한 정보를 입력.
LICENSE 파일 생성: 프로젝트의 루트 디렉토리에 LICENSE 파일을 생성하고, 복사한 내용을 붙여넣음.

라이선스 선택의 중요성

라이선스는 소프트웨어 프로젝트가 어떻게 사용될 수 있는지를 규정하는 중요한 법적 문서입니다. 올바른 라이선스를 선택하면 프로젝트를 보호할 수 있으며, 사용자와 기여자가 프로젝트의 규칙을 명확히 이해하도록 도와줍니다.

`requirements.txt`

: 프로젝트 실행에 필요한 외부 라이브러리의 목록을 정의합니다.

requirements.txt 파일은 파이썬 프로젝트에서 필요한 패키지(라이브러리)들을 명시하는 텍스트 파일. 이 파일을 사용하면 프로젝트의 의존성을 쉽게 관리할 수 있고, 다른 개발자나 서버에서 동일한 환경을 설정하는 데 도움이 됨.
pip install -r requirements.txt 명령어를 사용해 일괄 설치할 수 있습니다.
내용 예시:
```
numpy==1.21.0
pandas==1.3.0
		```
```

requirements.txt 파일은 각 줄에 하나의 패키지 이름과 그에 해당하는 버전 정보를 적는다. 이 파일을 기반으로, pip 명령어를 사용하여 한 번에 모든 패키지를 설치할 수 있다.

예시: `requirements.txt` 파일 내용

Django==3.2.5
requests==2.25.1
numpy>=1.19.5
pandas

Django==3.2.5: Django 패키지의 3.2.5 버전을 설치합니다.
requests==2.25.1: requests 패키지의 2.25.1 버전을 설치합니다.
numpy>=1.19.5: numpy 패키지의 1.19.5 버전 이상을 설치합니다.
pandas: 특정 버전 없이 pandas 패키지의 최신 버전을 설치합니다.

`requirements.txt` 파일 생성 방법

1. 수동으로 작성하기

프로젝트에서 사용한 패키지와 그 버전을 명확히 알고 있다면, 텍스트 편집기를 사용해 직접 requirements.txt 파일을 작성할 수 있습니다. 각 패키지 이름과 버전을 한 줄씩 적으면 됩니다.

2. pip freeze 명령어를 사용해 자동으로 생성하기

이미 가상환경(virtual environment)을 사용하여 필요한 패키지를 설치했다면, pip freeze 명령어를 사용하여 현재 가상환경에 설치된 모든 패키지 목록을 requirements.txt 파일로 저장할 수 있습니다.
pip freeze > requirements.txt
이 명령어는 현재 가상환경에 설치된 패키지와 버전을 모두 나열하고, 그 목록을 requirements.txt 파일에 저장합니다.

3. pipreqs를 사용하여 필요한 패키지만 포함하기

때때로 pip freeze로 생성된 requirements.txt에는 불필요한 패키지가 포함될 수 있습니다. 이 경우 pipreqs라는 도구를 사용해 프로젝트에서 실제로 사용된 패키지만 추출하여 requirements.txt를 생성할 수 있습니다.

pipreqs 설치:
pip install pipreqs
pipreqs를 사용하여 requirements.txt 생성:
pipreqs /path/to/your/project
위 명령어를 실행하면, 지정된 경로에 있는 프로젝트 소스 코드를 분석해 필요한 패키지만 requirements.txt에 기록합니다.

`requirements.txt` 파일을 사용해 패키지 설치하기

다른 환경(예: 새로운 서버, 다른 개발자의 컴퓨터)에서 동일한 패키지 환경을 설정하려면 다음 명령어를 사용

pip install -r requirements.txt

이 명령어는 requirements.txt 파일에 명시된 모든 패키지를 설치합니다.

`setup.py`

역할: 패키지의 빌드와 배포를 위한 설정을 포함합니다. 이 파일은 프로젝트를 패키지로 배포할 때 중요한 역할을 하며, 패키지 이름, 버전, 필요한 의존성 패키지, 설치 스크립트 등을 정의합니다.

내용 예시:

from setuptools import setup, find_packages

setup(
    name='패키지명',
    version='1.0.0',
    packages=find_packages(),
    install_requires=[
        'numpy',
        'pandas',
    ],
    entry_points={
        'console_scripts': [
            '패키지명=패키지명.main:main'
        ]
    },
)

`test_requirements.txt`**:

역할: 테스트를 수행하는 데 필요한 외부 라이브러리의 목록을 정의합니다. 테스트 시 필요한 추가적인 패키지들을 명시합니다.
내용 예시:
```
pytest==6.2.4
freezegun==1.1.0
```

🏖️ 3. 소스 코드 폴더 (`패키지명`)의 구성 요소

`init.py`

역할: 디렉터리가 파이썬 패키지의 일부임을 알립니다. 파이썬 3.3 이상에서는 없어도 패키지로 인식되지만, 하위 호환성 및 명확성을 위해 유지하는 것이 좋습니다.
내용: 보통 비워 두지만, 필요한 경우 패키지 내에서 임포트할 항목을 명시할 수도 있습니다.

`패키지명.py` (또는 `main.py`)

역할: 프로그램의 주요 기능을 정의하는 메인 소스 코드입니다. 프로그램의 실행 흐름을 관리하고, 다른 모듈을 호출하여 작업을 수행합니다.

내용 예시:

from 부가기능 import some_function

def main():
    some_function()

if __name__ == "__main__":
    main()

`info.py`

역할: 패키지 이름과 버전 정보를 정의하는 파일입니다. 이 정보를 setup.py 등에서 사용하여 패키지 메타데이터를 관리할 수 있습니다.

내용 예시:

__package_name__ = '패키지명'
__version__ = '1.0.0'

`부가기능.py`

역할: 프로그램의 부가적인 기능을 담당하는 소스 코드입니다. 이 파일은 패키지명.py에서 임포트하여 사용됩니다.

내용 예시:

def some_function():
    print("This is a supplementary function.")

`resources`

역할: 프로그램 실행에 필요한 리소스 파일, 예를 들어 설정 파일이나 데이터 파일을 저장합니다. 소스 코드와 리소스를 분리하여 관리합니다.
내용: 보통 설정 파일(.yml, .json 등)을 포함하며, 프로그램이 초기화될 때 이 파일을 읽어 설정을 로드합니다.

4. 테스트 폴더 (`tests`)의 구성 요소

`init.py`**

역할: 테스트 디렉터리가 파이썬 패키지임을 알립니다. 이 파일을 통해 테스트 코드에서 프로젝트의 소스 코드를 임포트할 수 있습니다.

`test_부가기능.py`**

역할: 부가기능을 테스트하는 코드입니다. pytest 등을 사용하여 테스트를 자동화할 수 있습니다.

내용 예시:

import pytest
from 부가기능 import some_function

def test_some_function():
    assert some_function() == "Expected output"

`resources`

역할: 테스트 수행에 필요한 설정 파일이나 데이터를 저장합니다. 실제 실행 환경과 동일한 형태로 작성하여 테스트의 신뢰성을 높입니다.
내용: 테스트에 필요한 설정 파일이나 데이터 파일을 포함합니다.

요약

이와 같은 폴더 구조는 파이썬 프로젝트를 효율적으로 관리하고, 협업과 배포를 용이하게 하며, 코드의 유지보수를 쉽게 하는 데 도움이 됩니다. 각 폴더와 파일의 역할을 명확히 이해하고 활용함으로써 프로젝트를 체계적으로 구성할 수 있습니다. 특히, 규모가 큰 프로젝트나 여러 명이 협업하는 프로젝트에서는 이러한 구조를 따르는 것이 매우 중요함!

참고자료

https://python-guide-kr.readthedocs.io/ko/latest/writing/structure.html

https://velog.io/@redjen/how-to-make-good-python-project

https://www.bearpooh.com/76

이영락

AI Engineer / 의료인공지능

이전 포스트

파이썬 프로그래밍 (4) - 모듈/패키지/프로젝트 구조 분석

다음 포스트

파이썬 프로그래밍 (5) - 프로젝트 구조 & 템플릿 분석

개발자 기본기

파이썬 프로젝트 구조 & 템플릿 분석

🏖️ 1. 프로젝트의 전체 구조

🏖️ 2. 최상위 폴더 (`root`)의 구성 요소

`.gitignore`:

예시 `.gitignore` 파일

주요 항목 설명

추가 설명

`README.md`:

`LICENSE`

LICENSE 파일에 대하여

주요 목적

일반적으로 사용되는 라이선스

LICENSE 파일 작성 방법

라이선스 선택의 중요성

`requirements.txt`

예시: `requirements.txt` 파일 내용

`requirements.txt` 파일 생성 방법

1. 수동으로 작성하기

2. `pip freeze` 명령어를 사용해 자동으로 생성하기

3. `pipreqs`를 사용하여 필요한 패키지만 포함하기

`requirements.txt` 파일을 사용해 패키지 설치하기

`setup.py`

`test_requirements.txt`**:

🏖️ 3. 소스 코드 폴더 (`패키지명`)의 구성 요소

`init.py`

`패키지명.py` (또는 `main.py`)

`info.py`

`부가기능.py`

`resources`

4. 테스트 폴더 (`tests`)의 구성 요소

`init.py`**

`test_부가기능.py`**

`resources`

요약

참고자료

파이썬 프로그래밍 (4) - 모듈/패키지/프로젝트 구조 분석

파이썬 프로그래밍 (6) - 파이썬 클로저 & 데코레이터

0개의 댓글

파이썬 프로그래밍 (5) - 프로젝트 구조 & 템플릿 분석

개발자 기본기

파이썬 프로젝트 구조 & 템플릿 분석

🏖️ 1. 프로젝트의 전체 구조

🏖️ 2. 최상위 폴더 (root)의 구성 요소

.gitignore:

예시 .gitignore 파일

주요 항목 설명

추가 설명

README.md:

LICENSE

LICENSE 파일에 대하여

주요 목적

일반적으로 사용되는 라이선스

LICENSE 파일 작성 방법

라이선스 선택의 중요성

requirements.txt

예시: requirements.txt 파일 내용

requirements.txt 파일 생성 방법

1. 수동으로 작성하기

2. pip freeze 명령어를 사용해 자동으로 생성하기

3. pipreqs를 사용하여 필요한 패키지만 포함하기

requirements.txt 파일을 사용해 패키지 설치하기

setup.py

test_requirements.txt**:

🏖️ 3. 소스 코드 폴더 (패키지명)의 구성 요소

__init__.py

패키지명.py (또는 main.py)

info.py

부가기능.py

resources

4. 테스트 폴더 (tests)의 구성 요소

__init__.py**

test_부가기능.py**

resources

요약

참고자료

파이썬 프로그래밍 (4) - 모듈/패키지/프로젝트 구조 분석

파이썬 프로그래밍 (6) - 파이썬 클로저 & 데코레이터

0개의 댓글

🏖️ 2. 최상위 폴더 (`root`)의 구성 요소

`.gitignore`:

예시 `.gitignore` 파일

`README.md`:

`LICENSE`

`requirements.txt`

예시: `requirements.txt` 파일 내용

`requirements.txt` 파일 생성 방법

2. `pip freeze` 명령어를 사용해 자동으로 생성하기

3. `pipreqs`를 사용하여 필요한 패키지만 포함하기

`requirements.txt` 파일을 사용해 패키지 설치하기

`setup.py`

`test_requirements.txt`**:

🏖️ 3. 소스 코드 폴더 (`패키지명`)의 구성 요소

`init.py`

`패키지명.py` (또는 `main.py`)

`info.py`

`부가기능.py`

`resources`

4. 테스트 폴더 (`tests`)의 구성 요소

`init.py`**

`test_부가기능.py`**

`resources`