PEP 405 – Python 가상 환경

Author:: Carl Meyer <carl at oddbird.net>
BDFL-Delegate:: Alyssa Coghlan
Status:: Final
Type:: Standards Track
Topic:: Packaging
Created:: 13-Jun-2011
Python-Version:: 3.3
Post-History:: 24-Oct-2011, 28-Oct-2011, 06-Mar-2012, 24-May-2012
Resolution:: Python-Dev message

Table of Contents

초록
동기
사양
하위 호환성
- sys.prefix의 의미 분리
- 다른 Python 구현에 미치는 영향
참조 구현
Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

초록

이 PEP는 자체 사이트 디렉터리를 가지며 선택적으로 시스템 사이트 디렉터리와 격리할 수 있는 경량 “가상 환경” 메커니즘을 Python에 추가할 것을 제안합니다. 각 가상 환경은 자체 Python 바이너리를 가지며(다양한 Python 버전의 환경을 생성할 수 있음), 사이트 디렉터리에 설치된 Python 패키지의 독립적인 집합을 자체적으로 가질 수 있지만, 기본 설치 Python과 표준 라이브러리를 공유합니다.

동기

Python 가상 환경의 유용성은 기존 서드파티 가상 환경 도구, 특히 Ian Bicking의 virtualenv가 널리 사용되면서 이미 충분히 입증되었습니다. 가상 환경은 의존성 관리 및 격리, 시스템 관리자 권한 없이 Python 패키지를 쉽게 설치하고 사용하는 작업, 여러 Python 버전에 걸친 Python 소프트웨어의 자동화된 테스트 등을 비롯한 다양한 용도로 이미 널리 사용되고 있습니다.

기존 가상 환경 도구는 Python 자체의 동작으로부터 지원을 받지 못하는 문제를 겪고 있습니다. Python 바이너리를 가상 환경에 복사하지 않는 rvirtualenv와 같은 도구는 시스템 사이트 디렉터리로부터의 안정적인 격리를 제공할 수 없습니다. Python 바이너리를 복사하는 Virtualenv는 Python의 site 모듈 상당 부분을 중복 구현하고, 시작할 때마다 복잡한 부트스트랩 절차를 수행하기 위해 끊임없이 변경되는 표준 라이브러리 모듈 집합을 가상 환경에 수동으로 심볼릭 링크하거나 복사해야 합니다. (Python은 sys.prefix를 검색하기 전에 심볼릭 링크된 실행 파일의 실제 대상을 확인하므로, 격리를 제공하려면 Virtualenv가 바이너리를 복사해야 합니다.)

Python의 가상 환경을 위한 유일한 기존 내장 솔루션인 PYTHONHOME 환경 변수는 전체 표준 라이브러리를 모든 환경에 복사하거나 심볼릭 링크할 것을 요구합니다. 전체 표준 라이브러리를 복사하는 것은 경량 솔루션이 아니며, 심볼릭 링크에 대한 플랫폼 간 지원도 여전히 일관되지 않습니다(심볼릭 링크를 지원하는 Windows 플랫폼에서도 심볼릭 링크를 만들려면 관리자 권한이 필요한 경우가 많습니다).

Python에 통합되고 기존 서드파티 도구를 수년간 사용하며 얻은 경험을 활용하는 가상 환경 메커니즘은 유지 관리 부담을 낮추고, 신뢰성을 높이며, 모든 Python 사용자가 더 쉽게 이용할 수 있도록 합니다.

사양

Python 바이너리가 실행되면 접두사(sys.prefix에 저장됨)를 확인하려고 시도하며, 이 접두사는 표준 라이브러리와 기타 주요 파일을 찾는 데 사용되고 site 모듈이 사이트 패키지 디렉터리의 위치를 확인하는 데 사용합니다. 현재 접두사는(PYTHONHOME이 설정되지 않았다고 가정할 때) 표준 라이브러리의 존재를 나타내는 마커 파일(os.py)을 찾으며 파일 시스템 트리를 먼저 상위 방향으로 탐색하여 확인하고, 파일을 찾지 못하면 바이너리에 하드코딩된 빌드 시점 접두사로 대체합니다.

이 PEP는 이 검색에 새로운 첫 단계를 추가할 것을 제안합니다. Python 실행 파일과 인접한 위치 또는 그보다 한 디렉터리 위에서 pyvenv.cfg 파일을 찾으면(실행 파일이 심볼릭 링크인 경우 실제 대상을 확인하지 않음), 이 파일에서 key = value형식의 줄을 검색합니다. home 키가 발견되면 이는 Python 바이너리가 가상 환경에 속한다는 의미이며, home 키의 값은 이 가상 환경을 생성하는 데 사용된 Python 실행 파일이 포함된 디렉터리입니다.

이 경우 home 키의 값을 유효한 Python 바이너리 위치로 사용하여 접두사 확인을 정상적으로 계속하며, 이를 통해 기본 설치의 접두사를 찾습니다. sys.base_prefix는 이 값으로 설정되고, sys.prefix는 pyvenv.cfg가 포함된 디렉터리로 설정됩니다.

(pyvenv.cfg를 찾지 못했거나 home 키가 포함되어 있지 않으면 접두사 확인은 정상적으로 계속되며, sys.prefix는 sys.base_prefix와 같아집니다.)

또한 sys.base_exec_prefix를 추가하고 sys.exec_prefix와 관련하여 동일한 방식으로 처리합니다. (sys.exec_prefix는 플랫폼별 파일에 대한 sys.prefix의 대응 항목이며, 기본적으로 sys.prefix와 같은 값을 가집니다.)

site 및 sysconfig 표준 라이브러리 모듈을 수정하여 표준 라이브러리와 헤더 파일은 sys.base_prefix / sys.base_exec_prefix를 기준으로 찾고, 사이트 패키지 디렉터리(sysconfig 용어로는 “purelib” 및 “platlib”)는 여전히 sys.prefix / sys.exec_prefix를 기준으로 찾도록 합니다.

따라서 가장 단순한 형태의 Python 가상 환경은 Python 바이너리의 복사본 또는 심볼릭 링크에 pyvenv.cfg 파일과 사이트 패키지 디렉터리가 함께 있는 것만으로 구성됩니다.

시스템 사이트 패키지로부터의 격리

기본적으로 가상 환경은 시스템 수준의 사이트 패키지 디렉터리와 완전히 격리됩니다.

pyvenv.cfg 파일에 값이 true(대소문자를 구분하지 않음)인 include-system-site-packages 키도 포함되어 있으면, site 모듈은 가상 환경 사이트 디렉터리 뒤에 시스템 사이트 디렉터리도 sys.path에 추가합니다. 따라서 시스템에 설치된 패키지를 계속 임포트할 수 있지만, 같은 이름의 패키지가 가상 환경에 설치되어 있으면 해당 패키지가 우선합니다.

PEP 370 사용자 수준 사이트 패키지는 venv 목적상 시스템 사이트 패키지의 일부로 간주됩니다. 즉, 격리된 venv에서는 사용할 수 없지만 include-system-site-packages = true venv에서는 사용할 수 있습니다.

가상 환경 생성

이 PEP는 가상 환경 생성을 구현하는 새로운 venv 모듈을 표준 라이브러리에 추가할 것도 제안합니다. 이 모듈은 -m 플래그를 사용하여 실행할 수 있습니다.:

python3 -m venv /path/to/new/virtual/environment

pyvenv로 설치된 스크립트도 이를 더 편리하게 만들기 위해 제공됩니다.:

pyvenv /path/to/new/virtual/environment

이 명령을 실행하면 대상 디렉터리가 생성되고(아직 존재하지 않는 모든 상위 디렉터리도 생성됨) 명령이 실행된 Python 설치를 가리키는 home키가 포함된 pyvenv.cfg 파일이 해당 디렉터리에 배치됩니다. 또한 python3 실행 파일의 복사본(또는 심볼릭 링크)과 packaging 표준 라이브러리 모듈의 pysetup3 스크립트를 포함하는 bin/ (Windows에서는 Scripts) 하위 디렉터리가 생성됩니다(PyPI에서 새 가상 환경으로 패키지를 쉽게 설치하기 위한 것입니다). 그리고 (처음에는 비어 있는) lib/pythonX.Y/site-packages (Windows에서는 Lib\site-packages) 하위 디렉터리도 생성됩니다.

대상 디렉터리가 이미 존재하면 오류가 발생하지만, --clear 옵션이 제공된 경우에는 대상 디렉터리가 삭제되고 가상 환경 생성이 평소와 같이 진행됩니다.

생성된 pyvenv.cfg 파일에는 include-system-site-packages키도 포함되며, pyvenv가 --system-site-packages 옵션으로 실행되면 true로, 기본적으로는 false로 설정됩니다.

pyvenv에 여러 경로를 지정할 수 있으며, 이 경우 지정된 각 경로에 주어진 옵션에 따라 동일한 가상 환경이 생성됩니다.

venv 모듈은 POSIX 및 Windows 시스템을 위한 “셸 활성화 스크립트”도 가상 환경의 bin 또는 Scripts 디렉터리에 배치합니다. 이러한 스크립트는 가상 환경의 bin (또는 Scripts) 디렉터리를 사용자의 셸 PATH 앞에 추가할 뿐입니다. 이는 가상 환경을 사용하는 데 반드시 필요한 것은 아니지만(가상 환경의 Python 바이너리나 스크립트에 대한 명시적 경로를 사용해도 동일하게 이용할 수 있음) 편리합니다.

pysetup및 기타 Python 패키지 관리자가 일반적인 Python 설치에 패키지를 설치하는 것과 동일한 방식으로 가상 환경에 패키지를 설치하도록 하고, 적절한 경우 sys.prefix대신 sys.base_prefix를 사용하는 것 외에는 sysconfig에서 가상 환경을 특별히 처리하지 않도록 하기 위해, 내부 가상 환경 레이아웃은 각 플랫폼에서 Python 설치 자체의 레이아웃을 모방합니다. 따라서 POSIX 시스템에서 일반적인 가상 환경 레이아웃은 다음과 같습니다.:

pyvenv.cfg
bin/python3
bin/python
bin/pysetup3
include/
lib/python3.3/site-packages/

Windows 시스템에서는 다음과 같습니다.:

pyvenv.cfg
Scripts/python.exe
Scripts/python3.dll
Scripts/pysetup3.exe
Scripts/pysetup3-script.py
        ... other DLLs and pyds...
Include/
Lib/site-packages/

가상 환경에 설치된 서드파티 패키지의 Python 모듈은 site-packages 디렉터리에 배치되고, 실행 파일은 bin/ 또는 Scripts에 배치됩니다.

Note

일반적인 Windows 시스템 수준 설치에서는 기본 가상 환경 레이아웃에서와 달리 Python 바이너리 자체가 “Scripts/” 하위 디렉터리 안에 들어가지 않습니다. 이는 사용자가 가상 환경을 효과적으로 “활성화”하기 위해 셸 PATH에 단일 디렉터리만 추가하면 되도록 가상 환경에서 유용합니다.

Note

Windows에서는 컴파일된 표준 라이브러리 모듈의 DLL 및 pyd 파일도 환경에 복사하거나 심볼릭 링크해야 합니다. 시스템 전체에 설치되지 않은 Python 설치에서 가상 환경이 생성된 경우, 가상 환경에서 Python을 실행할 때 Windows가 Python 설치에 있는 해당 파일의 복사본을 찾지 못하기 때문입니다.

Sysconfig 설치 체계 및 사용자 사이트

이 방식은 가상 환경을 위한 새로운 sysconfig 설치 체계를 도입하지 않도록 명시적으로 선택합니다. 대신 sys.prefix를 수정함으로써, 위치를 sys.prefix에 기반하는 기존 설치 체계가 가상 환경에서 그대로 작동하도록 보장합니다. 경로가 sys.prefix에 상대적이지 않은 다른 설치 체계(예를 들어 사용자 사이트 체계)에 대한 설치는 가상 환경의 영향을 전혀 받지 않습니다.

가상 환경에 특화된 sysconfig 체계를 기반으로 Python 가상 환경의 대체 구현을 만드는 것이 가능할 수도 있지만, 해당 구현이 가상 환경 내부에서 작동하는지 여부를 인식해야 하는 코드가 더 많이 필요하므로 견고성이 떨어집니다.

복사본과 심볼릭 링크

이 PEP의 기법은 일반적으로 복사되거나 심볼릭 링크된 Python 바이너리(및 Windows에서 필요한 기타 DLL) 모두에서 동일하게 잘 작동합니다. 가능한 경우 심볼릭 링크가 바람직합니다. 기반이 되는 Python 설치를 업그레이드할 때 가상 환경에 복사된 Python 실행 파일이 설치된 표준 라이브러리와 동기화되지 않아 수동 업그레이드가 필요할 수 있기 때문입니다.

심볼릭 링크에는 플랫폼 간에 몇 가지 어려움이 있습니다.

모든 Windows 버전이 심볼릭 링크를 지원하는 것은 아니며, 지원하는 버전에서도 심볼릭 링크를 생성하려면 관리자 권한이 필요한 경우가 많습니다.
OS X 프레임워크 빌드의 Python에서는 sys.executable이 실제 Python 바이너리를 실행하는 스텁일 뿐입니다. 이 스텁을 심볼릭 링크하는 것은 작동하지 않으므로 복사해야 합니다. (다행히 스텁은 크기도 작고 Python의 버그 수정 업그레이드로 변경되지 않으므로 복사해도 문제가 되지 않습니다.)

따라서 이 PEP는 Windows 및 OS X 프레임워크 빌드를 제외한 모든 플랫폼에서 바이너리를 심볼릭 링크할 것을 제안합니다. 적절한 권한을 사용할 수 있고 심볼릭 링크를 지원하는 Windows 버전에서는 --symlink 옵션을 사용하여 심볼릭 링크를 강제로 사용할 수 있습니다. (이 옵션은 심볼릭 링크가 절대 작동할 수 없고 장점도 없으므로 OS X 프레임워크 빌드에는 영향을 주지 않습니다.)

Windows에서 --symlink를 사용하지 않는 경우, 기반 Python 설치가 업그레이드되면 venv의 Python 바이너리와 DLL도 업데이트해야 하며, 그렇지 않으면 업그레이드된 표준 라이브러리와 불일치하는 문제가 발생할 수 있음을 의미합니다. pyvenv 스크립트는 기존 venv에서 이 업그레이드를 쉽게 수행할 수 있도록 --upgrade 옵션을 허용합니다.

Include 파일

현재 virtualenv는 다음과 같은 방식으로 include 파일을 처리합니다.

설치된 Python의 include 파일이 ${base_prefix}/include/pythonX.X에 있는 POSIX 시스템에서는 virtualenv가 ${venv}/include/를 생성하고 ${base_prefix}/include/pythonX.X를 ${venv}/include/pythonX.X로 심볼릭 링크합니다. Python의 include 파일이 {{ sys.prefix }}/Include에 있고 심볼릭 링크를 안정적으로 사용할 수 없는 Windows에서는 virtualenv가 {{ sys.prefix }}/Include를 ${venv}/Include로 복사합니다. 이를 통해 virtualenv 내에서 빌드되고 설치된 확장 모듈은 sys.prefix를 기준으로 예상되는 위치에서 필요한 Python 헤더 파일을 항상 찾을 수 있습니다.

확장 모듈이 자체 헤더 파일을 설치하는 경우에는 이 방식이 이상적이지 않습니다. 해당 헤더 파일의 기본 설치 위치가 쓰기 가능하지 않을 수 있는 시스템 디렉터리를 가리키는 심볼릭 링크일 수 있기 때문입니다. 설치 프로그램 중 하나인 pip는 명시적으로 헤더 파일을 비표준 위치인 ${venv}/include/site/pythonX.X/에 설치하여 이 문제를 우회합니다. Python에는 현재 사이트별 include 디렉터리를 위한 표준 추상화가 없기 때문입니다.

이 PEP는 본질적으로 동일한 효과와 동일한 장단점을 갖지만 약간 다른 접근 방식을 제안합니다. include 파일을 venv에 심볼릭 링크하거나 복사하는 대신, 헤더 파일이 항상 prefix가 아니라 base_prefix를 기준으로 검색되도록 sysconfig 스킴을 간단히 수정합니다. (또한 venv 내부에 include/디렉터리를 생성하여 설치 프로그램이 환경 내에 설치되는 include 파일을 저장할 위치를 제공합니다.)

distutils/패키징에서, 더 나아가 pyvenv에서 include 파일을 더 잘 처리하는 것은 향후 별도의 PEP가 필요할 수 있는 영역입니다. 현재로서는 virtualenv의 동작이 실무에서 적어도 “충분히 괜찮은” 것으로 입증되었다고 제안합니다.

API

위에서 설명한 상위 수준의 방법은 타사 가상 환경 생성자가 필요에 따라 환경 생성을 사용자 지정할 수 있는 메커니즘을 제공하는 간단한 API를 사용합니다.

venv 모듈에는 인스턴스화할 때 다음 키워드 인자를 허용하는 EnvBuilder 클래스가 포함되어 있습니다.

system_site_packages - 시스템 Python 사이트 패키지를 환경에서 사용할 수 있음을 나타내는 불리언 값입니다. 기본값은 False입니다.
clear - true인 경우 예외를 발생시키는 대신 기존 대상 디렉터리를 삭제하는 불리언 값입니다. 기본값은 False입니다.
symlinks - 복사하는 대신 Python 바이너리(및 필요한 DLL이나 pythonw.exe와 같은 기타 바이너리)를 심볼릭 링크하려고 시도할지 나타내는 불리언 값입니다. 기본값은 False입니다.

인스턴스화된 환경 빌더에는 가상 환경을 포함할 대상 디렉터리의 경로(현재 디렉터리에 대한 절대 경로 또는 상대 경로)를 필수 인자로 받는 create 메서드가 있습니다. create 메서드는 지정된 디렉터리에 환경을 생성하거나 적절한 예외를 발생시킵니다.

venv 모듈은 편의를 위해 모듈 수준의 create 함수도 제공합니다.:

def create(env_dir,
           system_site_packages=False, clear=False, use_symlinks=False):
    builder = EnvBuilder(
        system_site_packages=system_site_packages,
        clear=clear,
        use_symlinks=use_symlinks)
    builder.create(env_dir)

타사 가상 환경 도구의 생성자는 제공된 EnvBuilder 클래스를 자유롭게 베이스 클래스로 사용할 수 있습니다.

EnvBuilder 클래스의 create 메서드는 사용자 지정에 사용할 수 있는 훅을 보여 줍니다.:

def create(self, env_dir):
    """
    Create a virtualized Python environment in a directory.

    :param env_dir: The target directory to create an environment in.

    """
    env_dir = os.path.abspath(env_dir)
    context = self.create_directories(env_dir)
    self.create_configuration(context)
    self.setup_python(context)
    self.post_setup(context)

create_directories, create_configuration, setup_python, post_setup 각 메서드는 재정의할 수 있습니다. 이러한 메서드의 기능은 다음과 같습니다.

create_directories - 환경 디렉터리와 필요한 모든 디렉터리를 생성하고 컨텍스트 객체를 반환합니다. 이는 다른 메서드에서 사용할 속성(예: 경로)을 보관하는 역할만 합니다.
create_configuration - 환경에 pyvenv.cfg 구성 파일을 생성합니다.
setup_python - 환경에 Python 실행 파일의 사본을 생성합니다(Windows에서는 DLL도 생성합니다).
post_setup - 기본적으로 아무 작업도 수행하지 않으며, 가상 환경에 패키지를 사전 설치하거나 스크립트를 설치하도록 서드파티 서브클래스에서 재정의할 수 있는 후크 메서드입니다.

또한 EnvBuilder는 서브클래스의 post_setup에서 호출하여 가상 환경에 사용자 정의 스크립트를 설치하는 데 도움을 주는 유틸리티 메서드를 제공합니다. install_scripts 메서드는 인수로 context 객체(위 참조)와 디렉터리 경로를 받습니다. 디렉터리에는 “common”, “posix”, “nt” 서브디렉터리가 포함되어야 하며, 각 서브디렉터리에는 환경의 bin 디렉터리에 배치할 스크립트가 포함되어야 합니다. “common”의 내용과 os.name에 해당하는 디렉터리의 내용은 자리 표시자를 일부 텍스트 치환한 후 복사됩니다.

__VENV_DIR__는 환경 디렉터리의 절대 경로로 치환됩니다.
__VENV_NAME__은 환경 이름(환경 디렉터리 경로의 마지막 구성 요소)으로 치환됩니다.
__VENV_BIN_NAME__은 bin 디렉터리의 이름(bin 또는 Scripts)으로 치환됩니다.
__VENV_PYTHON__은 환경 실행 파일의 절대 경로로 치환됩니다.

참조 구현의 DistributeEnvBuilder 서브클래스는 사용자 정의 후크를 실제로 사용하여 가상 환경에 Distribute를 사전 설치하는 방법을 보여 줍니다. DistributeEnvBuilder가 실제로 Python 코어에 추가될 예정은 아니지만, 이를 통해 테스트 및 탐색 목적에서 참조 구현을 더욱 즉시 유용하게 사용할 수 있습니다.

하위 호환성

`sys.prefix`의 의미 분리

이러한 방식의 가상 환경 도구(사이트 패키지를 격리하면서도 기본 Python의 표준 라이브러리를 계속 사용하고, 이를 가상 환경에 심볼릭 링크로 연결할 필요가 없도록 하는 도구)는 현재 sys.prefix에 함께 담겨 있는 여러 의미 중 두 가지를 분리하자는 제안입니다. 즉, “표준 라이브러리는 어디에 있습니까?”와 “서드파티 모듈을 설치해야 하는 site-packages 위치는 어디입니까?”라는 질문에 대한 답을 분리하는 것입니다.

이러한 분리는 앞의 접두사 또는 뒤의 접두사 중 하나를 위한 새로운 sys 속성을 도입하여 처리할 수 있습니다. 어느 쪽을 선택하든 sys.prefix의 다른 의미를 전제로 작성된 소프트웨어와 하위 호환성 문제가 발생할 가능성이 있습니다. (이러한 소프트웨어는 sys.prefix를 직접 사용하는 대신 site 및 sysconfig 모듈의 API를 사용하여 이러한 질문에 답하는 것이 바람직하며, 이 경우 하위 호환성 문제는 없습니다. 그러나 실제로는 sys.prefix가 때때로 사용됩니다.)

sys.prefix에 대한 documentation은 이를 “플랫폼 독립적인 Python 파일이 설치되는 사이트별 디렉터리 접두사를 제공하는 문자열”로 설명하며, sys.prefix아래에 있는 표준 라이브러리와 헤더 파일을 구체적으로 언급합니다. site-packages는 언급하지 않습니다.

이 문서화된 정의를 유지하려면 sys.prefix가 기본 시스템 설치를 가리키도록 두어야 하며(표준 라이브러리와 헤더 파일이 이곳에 있음), site-packages의 접두사를 가리키도록 sys에 새 값(예: sys.site_prefix)을 도입해야 합니다. 이렇게 하면 sys.prefix의 문서화된 의미는 유지되지만, 서드파티 코드가 site-packages 디렉터리를 찾을 때 sys.site_prefix 또는 적절한 site API 대신 sys.prefix를 사용하면 격리가 깨질 위험이 있습니다.

가장 주목할 만한 사례는 아마도 setuptools와 그 포크인 distribute일 것입니다. 이들은 대부분 distutils 및 sysconfig API를 사용하지만, pth 파일을 유용하게 배치할 수 있는 위치를 사전 점검하기 위해 사이트 디렉터리 목록을 구성할 때 sys.prefix를 직접 사용하기도 합니다.

그 밖에는 Google Code Search를 통해, sys.prefix를 사용하여 site-packages 경로를 구성하는 패키지와 이를 사용하여 예를 들어 표준 라이브러리를 코드 실행 추적에서 제외하는 패키지가 대략 균등하게 섞여 있는 것으로 보입니다.

문서화된 sys.prefix의 정의를 수정해야 하지만, 이 PEP에서는 sys.prefix가 가상 환경(site-packages를 찾을 수 있는 곳)을 가리키도록 하고, 표준 라이브러리와 Python 헤더 파일을 가리키도록 sys.base_prefix를 도입하는 방식을 선호합니다. 이 선택의 근거는 다음과 같습니다.

가상 환경을 더 철저히 격리하는 방향으로 잘못을 감수하는 것이 바람직합니다.
Virtualenv는 이미 sys.prefix를 수정하여 가상 환경을 가리키도록 하며, 실제로 이는 문제가 되지 않았습니다.
setuptools/distribute를 수정할 필요가 없습니다.