2020.03.02

포에트리를 사용한 파이썬 프로젝트 관리 방법

Serdar Yegulalp | InfoWorld
“할 수 있는 확실한 방법이 있어야 하며, 그것이 단 하나만 있으면 더 좋다.”
 
ⓒ Getty Images Bank 

팀 피터스의 파이썬 선(Zen of Python)에 나온 말이지만 파이썬이 항상 이 원칙을 따르는 것은 아니다. 파이썬이 이 이상에 부합하지 않는 영역 가운데 하나는 바로 프로젝트 관리(project management)다. 파이썬 프로젝트를 관리하기 위한 툴과 방법론은 오랫동안 뒤죽박죽이었다. 그러나 지금 떠오르는 포에트리(Poetry)가 사실상의 표준이 될 가능성이 있다.

포에트리는 고(Go)와 러스트(Rust)가 오래 전부터 누려온 올인원 프로젝트 관리 툴을 파이썬에 제공한다. 포에트리는 프로젝트에서 특정 패키지 버전에 대한 결정적(deterministic) 종속성을 가질 수 있도록 하므로 여러 곳에서 일관적인 빌드가 가능하다. 또한 포에트리를 사용하면 프로젝트와 라이브러리를 더 쉽게 빌드, 패키징해서 파이파이(PyPI)에 게시해 다른 사람과 공유할 수 있다.

이번 기사에서는 파이썬 개발 프로젝트에 포에트리를 사용하는 방법, 즉 포에트리를 설정하는 방법과 포에트리를 사용해 프로젝트 종속성과 가상 환경을 구성하는 방법, 그리고 포에트리의 독특한 작동 방식에서 비롯되는 몇 가지 함정을 피해가는 방법을 알아본다.


파이썬에서 포에트리 설정하기

포에트리는 설정부터 다른 파이썬 종속성 및 프로젝트 관리 툴과는 다르다. 포에트리는 pip 대신 맞춤형 설치 프로그램을 사용한다. 설치 프로그램은 사용자 프로필 디렉터리에 포에트리 앱을 추가해서 현재는 물론 앞으로 시스템에 설치할 모든 파이썬에서 포에트리를 사용할 수 있도록 한다.

pip install poetry를 사용해 특정 파이썬 설치본에 포에트리를 설치할 수 있지만 이 방법은 1) 다른 시스템 파일과의 충돌 가능성이 있고 2) 다양한 버전의 파이썬과 여러 가상 환경에서 일관적으로 포에트리를 사용하기가 어렵게 되므로 추천하지 않는다.


포에트리로 관리하는 파이썬 프로젝트 만들기

포에트리를 설치했으면 poetry new <project_name>을 입력해 포에트리로 관리하는 프로젝트 디렉터리를 만들 수 있다. 이 명령은 <project_name>이라는 하위 디렉터리를 생성해 프로젝트에 필요한 파일을 배치한다.

포에트리 프로젝트를 위한 파일 중에는 다음과 같은 요소가 포함된다.
  • pyproject.toml: 프로젝트의 정의 파일. 포에트리는 이 정의 파일을 자동으로 관리한다. 숙련된 사용자라면 직접 이 파일을 편집할 수도 있지만 대부분의 경우 그럴 필요가 없다.
  • README.rst: 파이썬 문서에 사용되는 ReStructuredText 파일 형식의 빈 README 파일(문서에 .rst 형식을 사용해야 한다는 규칙은 없다. 단순한 경우에는 마크다운(Markdown)을 사용해도 된다).
  • tests: 단위 테스트에 필요한 파일이 포함된 하위 디렉터리. 새 프로젝트에 대한 테스트를 작성하는 습관을 들여야 한다. 
  • 마지막으로, 프로젝트 이름으로 된 하위 디렉터리가 있다. 프로젝트의 코드는 이 디렉터리에 들어간다.


포에트리에서 파이썬 가상 환경 관리하기

새 포에트리 프로젝트에서 사람들이 가장 먼저 원하는 것은 보통 파이썬 가상 환경이다. 포에트리는 독자적인 방법으로 가상 환경을 다룬다. 프로젝트 디렉터리 내에 가상 환경을 두는 대신, 포에트리는 운영체제에 따라 다음과 같은 중앙화된 캐시 디렉터리에 둔다.
 
  • 유닉스: ~/.cache/pypoetry/virtualenvs
  • 맥OS: ~/Library/Caches/pypoetry/virtualenvs
  • 윈도우: C:\Users\<username>\AppData\Local\pypoetry\Cache\virtualenvs or %LOCALAPPDATA%\pypoetry\Cache\virtualenvs

포에트리식 방법의 장점은 필요할 때 여러 프로젝트에 걸쳐 가상 환경을 공유할 수 있다는 것이다. 다만 이를 위해서는 작업 습관을 바꿔야 한다.

포에트리에서 가상 환경을 설정하려면 프로젝트 디렉터리로 이동해 poetry env use python을 입력한다. 그러면 포에트리가 새 가상 환경을 만들어 캐시 디렉터리에 저장하고 무작위로 생성된 가상 환경 이름을 표시한다(나중에 참고할 수 있도록 이 이름을 따로 기록해 둬야 한다).

부가적인 편의 기능으로, 포에트리는 프로젝트의 pyproject.toml 파일에 나열된 종속성도 설치한다. 다른 곳의 포에트리 프로젝트를 자신의 시스템에 복사해서 설정할 때 정말 유용한 기능이다.

이미 포에트리에서 할당한 가상 환경이 있는 프로젝트 디렉터리에서 poetry env use python을 실행하면 포에트리는 해당 CLI 세션의 컨텍스트에서 그 가상 환경을 활성화한다.

다음 단계는 조금 까다롭다. 포에트리에서 관리하는 가상 환경을 IDE와 함께 작동하도록 하는 부분이다. 예를 들어 비주얼 스튜디오 코드는 프로젝트 디렉터리 내의 가상 환경 존재를 자동으로 탐지하지만 포에트리로 관리되는 가상 환경의 존재를 (아직은) 따로 탐지하지 않는다. 단기적인 해결책은 프로젝트의 settings.json 파일에 포에트리가 가상 환경을 두는 위치를 명시하는 다음과 같은 라인을 추가하는 것이다.

"python.venvPath": "C:\\Users\\username\\AppData\\Local\\pypoetry\\Cache\\virtualenvs"

변경 후 비주얼 스튜디오 코드를 다시 시작해야 한다. 포에트리가 가상 환경을 관리하는 기능을 원하지 않는다면 다음 명령으로 비활성화하면 된다.

poetry config virtualenvs.create false


포에트리에서 파이썬 프로젝트에 종속성 추가하기

포에트리는 프로젝트 실행을 위해 필요한 패키지(프로덕션 종속성), 개발 프로세스 중에만 필요한 패키지(개발 종속성)의 두 가지 프로젝트 종속성을 추적한다. 프로덕션 종속성에는 앱의 기능을 위해 사용하는 모든 서드파티 라이브러리가 포함되며 개발 종속성에는 블랙(black), 마이파이(mypy), 독유틸즈(doctuils)와 같은 코딩 툴이 포함된다.
 
  • 프로젝트에 프로덕션 종속성을 추가하려면 poetry add <dependency_name>을 사용한다.
  • 개발 종속성을 추가하려면 poetry add <dependency_name> -D를 사용한다.

poetry remove <dependency_name>을 사용해 개발 종속성(-D 스위치를 사용해서 추가된 종속성)을 제거할 때도 마찬가지로 -D 스위치를 사용한다. 

poetry add의 작동 방식은 패키지 이름 또는 깃 경로를 지정할 수 있다는 면에서 pip install과 비슷하다(예를 들어 git+https://github.com/developer/project.git#branchname). 비공개 리포지토리를 사용하도록 포에트리를 구성할 수도 있다.

종속성을 확인, 설치하고 나면 포에트리는 프로젝트 디렉터리에 poetry.lock이라는 파일을 생성한다. 이 파일은 모든 다운로드된 종속성의 매니페스트이며 프로젝트의 나머지 부분과 함께 저장해야 한다. 그러면 소스 제어에서 이 프로젝트의 사본을 가져오는 누구나 모든 필수 패키지의 동일한 버전을 받게 된다.

이제 본격적으로 프로젝트를 시작할 준비가 됐다. 이 시점에서 기억해야 할 것은 앞으로 포에트리, 오직 포에트리만 사용해 모든 종속성과 가상 환경을 관리해야 한다는 점이다. editor@itworld.co.kr 


2020.03.02

포에트리를 사용한 파이썬 프로젝트 관리 방법

Serdar Yegulalp | InfoWorld
“할 수 있는 확실한 방법이 있어야 하며, 그것이 단 하나만 있으면 더 좋다.”
 
ⓒ Getty Images Bank 

팀 피터스의 파이썬 선(Zen of Python)에 나온 말이지만 파이썬이 항상 이 원칙을 따르는 것은 아니다. 파이썬이 이 이상에 부합하지 않는 영역 가운데 하나는 바로 프로젝트 관리(project management)다. 파이썬 프로젝트를 관리하기 위한 툴과 방법론은 오랫동안 뒤죽박죽이었다. 그러나 지금 떠오르는 포에트리(Poetry)가 사실상의 표준이 될 가능성이 있다.

포에트리는 고(Go)와 러스트(Rust)가 오래 전부터 누려온 올인원 프로젝트 관리 툴을 파이썬에 제공한다. 포에트리는 프로젝트에서 특정 패키지 버전에 대한 결정적(deterministic) 종속성을 가질 수 있도록 하므로 여러 곳에서 일관적인 빌드가 가능하다. 또한 포에트리를 사용하면 프로젝트와 라이브러리를 더 쉽게 빌드, 패키징해서 파이파이(PyPI)에 게시해 다른 사람과 공유할 수 있다.

이번 기사에서는 파이썬 개발 프로젝트에 포에트리를 사용하는 방법, 즉 포에트리를 설정하는 방법과 포에트리를 사용해 프로젝트 종속성과 가상 환경을 구성하는 방법, 그리고 포에트리의 독특한 작동 방식에서 비롯되는 몇 가지 함정을 피해가는 방법을 알아본다.


파이썬에서 포에트리 설정하기

포에트리는 설정부터 다른 파이썬 종속성 및 프로젝트 관리 툴과는 다르다. 포에트리는 pip 대신 맞춤형 설치 프로그램을 사용한다. 설치 프로그램은 사용자 프로필 디렉터리에 포에트리 앱을 추가해서 현재는 물론 앞으로 시스템에 설치할 모든 파이썬에서 포에트리를 사용할 수 있도록 한다.

pip install poetry를 사용해 특정 파이썬 설치본에 포에트리를 설치할 수 있지만 이 방법은 1) 다른 시스템 파일과의 충돌 가능성이 있고 2) 다양한 버전의 파이썬과 여러 가상 환경에서 일관적으로 포에트리를 사용하기가 어렵게 되므로 추천하지 않는다.


포에트리로 관리하는 파이썬 프로젝트 만들기

포에트리를 설치했으면 poetry new <project_name>을 입력해 포에트리로 관리하는 프로젝트 디렉터리를 만들 수 있다. 이 명령은 <project_name>이라는 하위 디렉터리를 생성해 프로젝트에 필요한 파일을 배치한다.

포에트리 프로젝트를 위한 파일 중에는 다음과 같은 요소가 포함된다.
  • pyproject.toml: 프로젝트의 정의 파일. 포에트리는 이 정의 파일을 자동으로 관리한다. 숙련된 사용자라면 직접 이 파일을 편집할 수도 있지만 대부분의 경우 그럴 필요가 없다.
  • README.rst: 파이썬 문서에 사용되는 ReStructuredText 파일 형식의 빈 README 파일(문서에 .rst 형식을 사용해야 한다는 규칙은 없다. 단순한 경우에는 마크다운(Markdown)을 사용해도 된다).
  • tests: 단위 테스트에 필요한 파일이 포함된 하위 디렉터리. 새 프로젝트에 대한 테스트를 작성하는 습관을 들여야 한다. 
  • 마지막으로, 프로젝트 이름으로 된 하위 디렉터리가 있다. 프로젝트의 코드는 이 디렉터리에 들어간다.


포에트리에서 파이썬 가상 환경 관리하기

새 포에트리 프로젝트에서 사람들이 가장 먼저 원하는 것은 보통 파이썬 가상 환경이다. 포에트리는 독자적인 방법으로 가상 환경을 다룬다. 프로젝트 디렉터리 내에 가상 환경을 두는 대신, 포에트리는 운영체제에 따라 다음과 같은 중앙화된 캐시 디렉터리에 둔다.
 
  • 유닉스: ~/.cache/pypoetry/virtualenvs
  • 맥OS: ~/Library/Caches/pypoetry/virtualenvs
  • 윈도우: C:\Users\<username>\AppData\Local\pypoetry\Cache\virtualenvs or %LOCALAPPDATA%\pypoetry\Cache\virtualenvs

포에트리식 방법의 장점은 필요할 때 여러 프로젝트에 걸쳐 가상 환경을 공유할 수 있다는 것이다. 다만 이를 위해서는 작업 습관을 바꿔야 한다.

포에트리에서 가상 환경을 설정하려면 프로젝트 디렉터리로 이동해 poetry env use python을 입력한다. 그러면 포에트리가 새 가상 환경을 만들어 캐시 디렉터리에 저장하고 무작위로 생성된 가상 환경 이름을 표시한다(나중에 참고할 수 있도록 이 이름을 따로 기록해 둬야 한다).

부가적인 편의 기능으로, 포에트리는 프로젝트의 pyproject.toml 파일에 나열된 종속성도 설치한다. 다른 곳의 포에트리 프로젝트를 자신의 시스템에 복사해서 설정할 때 정말 유용한 기능이다.

이미 포에트리에서 할당한 가상 환경이 있는 프로젝트 디렉터리에서 poetry env use python을 실행하면 포에트리는 해당 CLI 세션의 컨텍스트에서 그 가상 환경을 활성화한다.

다음 단계는 조금 까다롭다. 포에트리에서 관리하는 가상 환경을 IDE와 함께 작동하도록 하는 부분이다. 예를 들어 비주얼 스튜디오 코드는 프로젝트 디렉터리 내의 가상 환경 존재를 자동으로 탐지하지만 포에트리로 관리되는 가상 환경의 존재를 (아직은) 따로 탐지하지 않는다. 단기적인 해결책은 프로젝트의 settings.json 파일에 포에트리가 가상 환경을 두는 위치를 명시하는 다음과 같은 라인을 추가하는 것이다.

"python.venvPath": "C:\\Users\\username\\AppData\\Local\\pypoetry\\Cache\\virtualenvs"

변경 후 비주얼 스튜디오 코드를 다시 시작해야 한다. 포에트리가 가상 환경을 관리하는 기능을 원하지 않는다면 다음 명령으로 비활성화하면 된다.

poetry config virtualenvs.create false


포에트리에서 파이썬 프로젝트에 종속성 추가하기

포에트리는 프로젝트 실행을 위해 필요한 패키지(프로덕션 종속성), 개발 프로세스 중에만 필요한 패키지(개발 종속성)의 두 가지 프로젝트 종속성을 추적한다. 프로덕션 종속성에는 앱의 기능을 위해 사용하는 모든 서드파티 라이브러리가 포함되며 개발 종속성에는 블랙(black), 마이파이(mypy), 독유틸즈(doctuils)와 같은 코딩 툴이 포함된다.
 
  • 프로젝트에 프로덕션 종속성을 추가하려면 poetry add <dependency_name>을 사용한다.
  • 개발 종속성을 추가하려면 poetry add <dependency_name> -D를 사용한다.

poetry remove <dependency_name>을 사용해 개발 종속성(-D 스위치를 사용해서 추가된 종속성)을 제거할 때도 마찬가지로 -D 스위치를 사용한다. 

poetry add의 작동 방식은 패키지 이름 또는 깃 경로를 지정할 수 있다는 면에서 pip install과 비슷하다(예를 들어 git+https://github.com/developer/project.git#branchname). 비공개 리포지토리를 사용하도록 포에트리를 구성할 수도 있다.

종속성을 확인, 설치하고 나면 포에트리는 프로젝트 디렉터리에 poetry.lock이라는 파일을 생성한다. 이 파일은 모든 다운로드된 종속성의 매니페스트이며 프로젝트의 나머지 부분과 함께 저장해야 한다. 그러면 소스 제어에서 이 프로젝트의 사본을 가져오는 누구나 모든 필수 패키지의 동일한 버전을 받게 된다.

이제 본격적으로 프로젝트를 시작할 준비가 됐다. 이 시점에서 기억해야 할 것은 앞으로 포에트리, 오직 포에트리만 사용해 모든 종속성과 가상 환경을 관리해야 한다는 점이다. editor@itworld.co.kr 


X