개요
파이썬 프로젝트를 하면서 패키지로 배포할 일이 발생했는데
프로젝트를 만들고, 의존성을 관리하고, 패키지로 배포하는데 만약 Poetry가 없었다면 상당히 불편했을 것이다
나중에 또 파이썬 프로젝트를 수행해야 할 때, 빠르게 필요한 내용들을 기억해내기 위해 핵심내용들만 글로 정리한다
그리고 이런 프로젝트 관리 프로그램의 개념을 적립해두면, Go언어의 go?나 Rust의 cargo? 또는 Swift의 SPM을 사용할 때도 유용할 것이다
프로젝트 시작과 가상환경
프로젝트 초기화
Poetry를 사용해 새로운 Python 프로젝트를 초기화하려면 다음 명령을 실행한다
poetry init
이 명령을 통해 프로젝트의 메타데이터와 의존성을 관리하는 pyproject.toml 파일을 생성하고, 의존성 관련 정보들을 가지는 poetry.lock 파일도 생성된다
가상환경 생성 및 관리
자동 가상환경 생성
poetry install
다음 명령을 실행하면 pyproject.toml에 존재하는 패키지들 설치와 함께 가상환경이 생성된다
후술하겠지만, poetry add 또한 패키지를 설치하기에 가상환경이 없다면 마찬가지로 생성된다
가상환경 활성화
Poetry의 가상환경에 진입하려면 다음 명령을 사용한다
poetry shell
해당 명령을 실행하면 가상환경이 활성화되며, 가상환경 내에서 명령어를 실행할 수 있다
의존성 설치와 추가(+그룹)
기본 의존성 추가
프로젝트에 필요한 라이브러리를 추가하려면 다음 명령을 실행한다
poetry add <패키지명>
그룹
그룹은 의존성을 논리적으로 분류하는 기능으로, 다음과 같이 기본 의존성과 다른 목적에 따른 의존성들이 존재할 수 있다
- 기본 의존성: 프로젝트 실행에 필요한 라이브러리.
- 개발용 의존성: 테스트, 코드 포맷팅 등 개발 도구.
- 예시코드용 의존성: …
기본 의존성은 설치되고 목적에 맞게 다음 명령어들을 통해 의존성을 설치하면 된다
그룹 포함/제외하여 의존성 설치
기본적으로 poetry install 명령은 기본 의존성만 설치한다
특정 그룹을 포함해 설치하려면 --with 옵션을 사용하면 된다(--without은 제외)
poetry install --with dev,examples
poetry install --without examples
그룹별 의존성 추가
특정 그룹에 의존성을 추가하려면 --group 옵션을 사용한다
poetry add --group <그룹명> <패키지명>의존성 관리
Poetry는 의존성 관리에서 poetry.lock 파일을 사용해 프로젝트의 재현 가능한 환경을 보장한다(이 파일은 의존성의 구체적인 버전과 해시값을 기록)
- 프로젝트의 모든 의존성을 최신 버전으로 업데이트하고 싶을 때 → poetry update
- 특정 의존성만 업데이트하고 싶을 때 → poetry lock
모든 의존성 최신화
poetry update
pyproject.toml에 명시된 버전 범위를 기준으로 최신 버전으로 모든 의존성을 강제 갱신한다
특정 의존성만 업데이트
poetry lock
pyproject.toml의 버전 범위를 기준으로 변경된 의존성만 갱신한다
poetry lock --no-update
poetry.lock 파일이 손상되거나 다시 생성이 필요한 경우, 기존 poetry.lock의 의존성 버전은 유지하면서 정확한 해시값을 재생성한다
빌드와 배포
배포는 빌드 후, 파일을 업로드하는 방식으로 진행된다
빌드
poetry build
해당 명령을 수행하면, 프로젝트를 빌드하고 배포할 수 있는 다음과 같은 두 가지 파일이 dist/ 폴더에 생성된다
Wheel 파일 (.whl)
- 빠르게 설치할 수 있는 바이너리 패키지
- .whl 파일은 Python 설치 도구인 pip를 통해 빠르게 설치
- 플랫폼 독립적이거나 특정 플랫폼용으로 빌드 가능
Source Distribution 파일 (.tar.gz)
- 소스 코드 압축본으로, 빌드에 필요한 모든 파일이 포함
- 소스 코드 그대로 제공되며, 모든 Python 버전과 플랫폼에서 빌드 가능
- 소스에서 직접 빌드할 필요가 있는 환경에서 사용
배포
poetry publish
빌드된 파일 dist/ 폴더 내 파일들을 PyPI 또는 지정된 저장소에 업로드한다
poetry publish --build
빌드와 배포를 동시에 수행할 수 있다
마무리
| 명령어 | 설명 |
| poetry init | 프로젝트 초기화 및 pyproject.toml 생성 |
| poetry shell | 가상환경 활성화 |
| poetry add <패키지명> | 의존성 추가, 제거는 remove |
| poetry add --group <그룹명> <패키지명> | 특정 그룹에 의존성 추가 |
| poetry install | 의존성 설치 |
| poetry install --with <그룹> | 특정 그룹 포함해서 설치 |
| poetry lock | 변경된 요소만 의존성 최신화 |
| poetry update | 프로젝트의 모든 의존성을 최신화 |
| poetry build | 패키지 빌드 |
| poetry publish | 패키지 배포 |
| poetry version <version> | pyproject.toml에 명시된 버전 업데이트 |