[Pro Django] Tutorial_1: 프로젝트 셋업, Poetry

Saemi An·2025년 5월 6일

개인프로젝트_고도화

목록 보기
7/19
post-thumbnail

해당 포스팅은 유투버 Bucky의 『Pro Django Tutorial』 1강의 내용을 바탕으로 작성 했습니다.
동영상 바로가기
동영상 속 깃헙 바로가기

🕹️ 프로젝트 시작

🎮 프로젝트 이름 설정

django-admin startproejct project
mv project Core

'project'라는 이름으로 장고 프로젝트를 생성한 뒤,
실제 사용할 프로젝트 이름으로 디렉토리 이름을 변경해 준다.

이를 통해 로컬 환경에서는 개발자가 이해하는 프로젝트 이름을 사용하고
동시에 모든 conf 파일들 에서는 'project'라는 직관적인 이름을 사용할 수 있다.

🎮 .gitignore 작성

괜히 git 연결 테스트 한다고 .gitignore 없이 푸시 한번 했다가
쓸데없는 폴더가 올라가서 지운다고 고생하기 전에
프로젝트 생성 직후에 생성해주는 것이 옳다.

다음은 장고 프로젝트에 적용하는 스탠다드 .gitignore 리스트 이다.

펼쳐서 확인 
# Backup files
*.bak

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

# Django
*.log
*.pot
*.pyc
/staticfiles
__pycache__
db.sqlite3
media

# Environments
.venv
/.env
/local
ENV/
env.bak/
env/
venv
venv.bak/
venv/

# IDEs
.DS_Store
.idea
.vscode

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

# mypy
.mypy_cache

# pyenv
.python-version

# pytest
.pytest_cache

# Python
*$py.class
*.py[cod]

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

🎮 README.rst 생성

.rst(reStrunctered Text) 형식으로 리드미 파일을 생성한다.

  • rst는 문서 작성시 마크업 언어로 문서를 꾸밀 수 있도록 도와주는 라이브러리이다.
  • (옵션) 참고로 VSCode에서 reStructuredText by LeXtudio 익스텐션을 설치하면 실시간 미리보기가 가능하다.
  • rst 문법 참고

아직 프로젝트 시작 단계이니 생성만 해두고 내용은 나중에 작성하도록 한다.

🕹️ Poetry

0단계: Poetry란?
"Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution."
+) 말만 들으면 모르겠다. 활용 가치는 차차 알아가 보자.

1단계: 설치

  • 설치 페이지 바로가기
  • 환경변수 등록
    • 어느 경로에서든 poetry라고 입력하면 실행될 수 있도록해준다. 즉, 환경변수란 '운영체제가 프로그램을 실행하거나 설정을 읽을 때 참고하는 전역변수' 이다.
    • vi ~/.bashrc 명령어를 통해 편집기를 켜고 export 환경변수명=환경변수값 형태로 입력해 준다. 즉, export PATH="/Users/사용자이름/.local/bin:$PATH"을 입력해 준다.
      • 환경변수명 | PATH (실행 가능한 파일들을 찾는 디렉토리 목록)
      • 환경변수값 | 로컬머신에서 Poetry가 설치된 경로
      • $PATH | 기존 PATH 변수의 값 (즉, 기존 경로들)을 유지하자는 의미
  • 변경사항 적용 source ~/.bashrc
  • poetry --version을 통해 버전 확인

1.5단계: 환경변수 설정 오류 해결

  • 터미널을 껏다가 켜니 poetry 환경변수가 먹지 않았다. 이유를 찾아보니 macOS는 로그인 쉘만 실행되므로 bashrc는 자동 실행되지 않는다는 이유였다..
  • 로그인 쉘 터미널인 bash_profile에 다시 poetry 환경변수를 설정해 줬다. 나는 nano가 편하니 이번에는 nano ~/.bash_profile 그리고 기존에 있던 아나콘다 설정 하위에 동일한 환경변수를 적고 source ~/.bash_profile로 변경사항 적용. 이제 어디에서 새로운 터미널을 열어도 poetry --version을 확인할 수 있다!

2단계: poetry init
poetry init을 명령한 후 모든 디폴트 설정을 적용한다.
단, License는 MIT로, define dependencies 질문에는 모두 no를 적용.
이후 pyproject.toml 파일이 생성된다.

License=MIT란?
Poetry를 자유롭게 사용할 수 있다는 의미. 개인 및 상업적인 용도로 Poetry를 사용할 수 있으며, 수정 및 배포도 자유로움.

toml 파일이란? 프로젝트의 requirements와 dependencies를 관리하는 파일이다. (스프링 .yml 파일과 비슷해 보인다.)
"This file contains build system requirements and information, which are used by pip to build the package."

3단계: poetry add 필요한 패키지들 및 가상환경 활성화
poetry add Django psycopg2

위 명령어를 실행하면 다음 사항들이 실행된다;

  • poetry.lock 파일 생성 (모든 팀원들이 가져가야할 정확한 패키지 및 그 버전이 명시된다.)
  • poetry.toml 파일에 설치한 패키지들이 업데이트 된다.
  • 새로운 가상환경이 생성된다.
  • poetry env info --path poetry가 생성한 가상환경 경로를 확인한다
  • VSCode에서 F1을 눌러 Command Palette를 열고 Python: Select Interpreter를 선택한 후 Enter interpreter path 선택 후 (위에서 찾은 경로)/bin/python을 선택해 준다.
  • 기존 터미널을 끄고 새로운 터미널을 열면 poetry 가상환경을 통해 터미널이 열린것을 확인할 수 있다.

(옵션) 3.5단계: 가상환경 명시적으로 설정하기

poetry 명령어를 실행하면 poetry가 자동으로 가상환경을 인식하고 그 안에서 패키지들을 관리하게 된다.

하지만 차후 poetry가 관리하는 가상환경이 늘어남에 따라 가상환경간의 전환에 오류가 생기는 경우가 있다고 한다.

따라서 개발자가 사용하는 IDE가 가상환경을 정확히 인지하게 하도록 하기 위해 다음과 같은 설정을 해보자;

  • 일단 poetry env remove $(poetry env list --full-path) 명령어를 통해 pyproject.toml에서 가상환경 '연결'을 제거하고 Poetry가 해당 환경을 더 이상 사용하지 않도록 한다.
  • rm -rf /Users/(사용자 이름)/Library/Caches/pypoetry/virtualenvs/core-pAcdJB7s-py3.11 가상환경 폴더를 물리적으로 직접 삭제해준다. (rm -rf 명령어 실행시 휴지통 안 거치고 완전 삭제되니 항상 조심 또 조심..)
  • (옵션) poetry는 가상환경을 계속 쌓아둔다. 따라서 poetry cache clear virtualenvs --all를 통해 Poetry가 캐시로 저장해놓은 모든 가상환경을 날려줄 수도 있다.
  • poetry config virtualenvs.in-project true poetry가 관리하는 가상환경 폴더가 프로젝트 폴더 안에 생성되도록 기존의 전역설정을 바꿔준다.
  • 이후 진행할 프로젝트의 터미널에서 poetry install 명령어를 통해 다시 가상환경을 설치해 준다. 이제 프로젝트 디렉토리 내부에 가상환경 폴더 .venv가 생성되었음을 확인할 수 있다.
  • VSCode 명령 팔레트에서 수동으로 가상환경을 지정한다.
    • .venv가 프로젝트 디렉토리 내부에 생겼다. Poetry는 pyproject.toml로 의존성을 관리하지만, VSCode는 Poetry 자체를 모른다.
    • 더군다나 나의 경의 VSCode 자체에서(.vscode/settings.json에서) python.defaultInterpreterPath가 아나콘다로 만든 다른 가상환경이 설정되어 있다.
    • 따라서 해당 프로젝트가 poetry가 생성 및 관리하는 가상환경을 사용한다는 점을 최초 1회에 한해 수동으로 설정해 줘야 한다.

🎮 Poetry를 통한 개발서버 실행

poetry run python manage.py runserver
Poetry는 프로젝트의 일관성을 유지해준다.
+) 패키지 버전관리 목적 이외에 Poetry를 통해 프로젝트를 실행하는 구체적인 이유???
따라서 모든 명령어의 실행은 Poetry를 통해 이루어져야 한다.

🕹️ (옵션) Makefile 작성

앞으로 모든 실행 명령은 poetry run (명령어) 형태로 내려질 것이다.
또한 개발/운영 설정파일들을 나누다 보면 명령어의 옵션들이 길어질 수 있다.

따라서 명령어를 커스텀해주는 Makefile을 만들어보자
(사실 배우는 단계에서 커스텀한 단축 명령어를 사용하는 것은 옳지 않다고 생각한다. 리눅스 명령어를 귀신같이 사용하려면 손에 익어야 하기 때문에.. 그래도 일단 과정 안에 있으니 배워보자.)

⚠️ 오류: make (커스텀 명령어) 실행 위치
make는 현재 디렉토리의 Makefile을 기준으로 동작한다고 한다.
즉, 터미널에서 반드시 Makefile이 있는 디렉토리로 이동한 상태여야 한다.

🕹️ 프로젝트 Tree 재구성

최상위 디렉토리에 기존 프로젝트명(Core)을 소문자로 한 이름의 디렉토리(core)를 생성한다.
core 디렉토리 하위에 manage.py 와 project 디렉토리를 옮겨준다.

이는 비지니스 로직이 담긴 소스코드를 한 곳에 모아 보관하며,
설정파일 등을 비롯한 기타 폴더 및 파일들과 분리하기 위함이다.

프로트를 실행할 소스코드가 담긴 파일이 옮겨졌음으로 다음과 같은 변경사항을 적용한다;

  • manage.py: main() 함수 안에서 setdefault()를 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "core.project.settings")로 변경
  • settings.py:
    • BASE_DIR = Path(__file__).resolve().parent.parent.parent
    • ROOT_URLCONF = "core.project.urls"
    • WSGI_APPLICATION = "core.project.wsgi.application"

위와 같은 변경사항은 서버를 실행시키는 명령어를 커스텀한 Makefile에도 적용되어야 한다.
기존에는 run-server라는 커스텀 명령어로 poetry run python manage.py runserver를 실행 했었다. 하지만 manage.py의 위치를 변경했기 때문에 -m 옵션을 사용하여 core 디렉렉토리 하위에 있는 manage 모듈을 실행하라는 의미인 -m core.manage로 변경해 준다.

.PHONY: install   # 타겟이 실행될 때 타겟명을 파일로 간주하고 찾게됨 // 파일이 아님을 명시하여 생산성 증대 + 동일한 파일명 있어도 여기서 찾도록
install:
	poetry install

.PHONY: migrate
migrate:
	poetry run python -m core.manage migrate

.PHONY: migrations
migrations:
	poetry run python -m core.manage makemigrations

.PHONY: run-server
run-server:
	poetry run python -m core.manage runserver

.PHONY: superuser
superuser:
	poetry run python -m core.manage createsuperuser

.PHONY: update
update: install migrate ;

이외 커스텀 명령어들이 대거 추가 되었다.
+) .PHONY가 뭘까?

🕹️ settings.py 관리

🎮 django-split-settings 패키지 설치

poetry add django-split-settings PyYAML
Poetry를 통해 패키지를 설치해 준다.

⚠️ 패키지 설치 중 파이썬 버전 오류 해결
django-split-settings(1.3.2) 패키지는 Python 4.0 미만에서만 사용할 수 있다고 한다.

하지만 myproject.toml 파일에 명시된 Python 버전에 상한선 설정이 없어 오류가 났다. 따라서 .toml 파일에서 requires-python = ">=3.11,<4.0"과 같이 상한선을 추가해 주었다.
+) poetry.lock은 pyproject.toml의 설정을 기반으로 Poetry가 자동으로 생성하는 파일이다. lock 파일을 개발자가 직접 수정한 경우 추후 poetry install이나 poetry update 명령 실행시 이것이 다시 덮어써씌이거나, 예기치 않은 충돌/에러가 발생할 수 있으니 유의한다.

이후 poetry lock --update 를 해 주었다. +) 근데 파이썬 버전 상한선이 명시되지 않았다. 왤까?

  • 이유:
  • .lock 파일의 python-versions = ">=3.8"는 직접 지정된 값이 아니라, 모든 의존성 패키지들이 요구하는 Python 범위의 교집합이다. 따라서 pyproject.toml에 명시한 python = ">=3.11,<4.0"과는 다른 개념이라고 한다.
    • Poetry는 pyproject.toml에 명시된 버전 등의 제약조건들을 기반으로 패키지 버전을 찾게 된다. 그리고 그 과정에서 모든 패키지들이 실제로 호환 가능한 범위를 반영해서 .lock 파일을 생성한다.
    • 실제로 설치된 패키지 중 하나라도 python >=3.8만 요구한다면, .lock에는 >=3.8이라고 표시된다는 뜻.
    • 즉, lock은 pyproject.toml과 정렬되는 값이 아니고, 현재 전체 환경이 어떤 Python 버전에서 동작 가능한지를 기록한다.

🎮 project/settings 디렉토리 생성

project/settings 디렉토리 생성.
이후 project/settings/templates 디렉토리를 생성.
이후 project/settings/templates/settings.dev.py 파일 생성.

⚠️ VSCode가 settings.dev.py를 파이썬 파일로 인식하지 못하는 경우
VSCode는 파일 이름에 마침표가 여러 개 있으면, 때때로 확장자를 제대로 인식하지 못한다. 따라서 settings.json 파일을 열어 다음 코드를 추가해 준다.

"files.associations": {
    "*.dev.py": "python"
}

이후 project/settings.py의 이름을 base.py로 변경한 후, project/settings/base.py 처럼 이동한다.

  • settings: 추후에 Dockerfile 등의 설정파일들을 모아둔다.
  • settings.dev.py: 개발자들 각각이 자신의 개발서버에 적용할 설정 파일이다. (예시 - 테스트를 위해 DB를 변경하는 경우, 테스트를 위해 커스텀 로깅 설정을 하는 경우 등이 있을 수 있다. 이때 각각의 개발자들이 변경한 세팅이 깃헙에 푸시되면 원치않는 상황이 발생할 수 있다. 따라서 settings.dev.py는 private project settings를 위해 분리시켜둔 파일이다.)

split-setting 관련하여 내용이 많아 다음 포스팅에서 자세히 다뤄보겠다..!

끝!

profile
Saemi An
하나씩 차근차근 천천히
이전 포스트

[장고] choices 옵션과 동적 필터 활용

다음 포스트

(미완료)[Pro Django] Tutorial_1: django-split-setting

0개의 댓글