Python

site — 사이트별 구성 훅

소스 코드: Lib/site.py

이 모듈은 초기화 중에 자동으로 임포트 됩니다. 인터프리터의 -S 옵션을 사용하여 자동 임포트를 억제할 수 있습니다.

이 모듈을 임포트하면 보통 사이트별 경로가 모듈 검색 경로에 추가되고, help() 를 포함한 callables 가 내장 네임스페이스에 추가됩니다. 그러나 파이썬 시작 옵션 -S 는 이를 차단하며, 이 경우 모듈 검색 경로의 자동 수정이나 내장 기능의 추가 없이 이 모듈을 안전하게 임포트할 수 있습니다. 일반적인 사이트별 추가를 명시적으로 실행하려면 main() 함수를 호출하십시오.

버전 3.3에서 변경: -S를 사용하는 경우에도 모듈을 임포트 하면 경로 조작을 트리거 했습니다.

헤드와 테일 부분에서 최대 4개의 디렉터리를 구성하며 시작합니다. 헤드 부분에는 sys.prefix 와 sys.exec_prefix 가 사용됩니다; 빈 헤드는 건너뜁니다. 테일 부분에는 빈 문자열을 사용하고 이후 lib/site-packages (Windows) 또는 lib/pythonX.Y[t]/site-packages (Unix 및 macOS)를 사용합니다. (선택적 접미사 “t”는 자유 스레딩 빌드를 나타내며, "t" 가 sys.abiflags 상수 안에 있을 경우 추가됩니다.) 각각의 고유한 헤드-테일 조합에 대해, 기존 디렉터리를 참조하는지 확인하고, 그렇다면 이를 sys.path 에 추가하고 새로 추가된 경로에서 구성 파일을 검사합니다.

버전 3.5에서 변경: “site-python” 디렉터리에 대한 지원이 제거되었습니다.

버전 3.13에서 변경: Unix 환경에서, Free threading 파이썬 설치는 lib/python3.13t/ 와 같이 버전별 디렉터리 이름에 포함된 “t” 접미사를 통해 식별됩니다.

버전 3.14에서 변경: site is no longer responsible for updating sys.prefix and sys.exec_prefix on 가상 환경. This is now done during the path initialization. As a result, under 가상 환경, sys.prefix and sys.exec_prefix no longer depend on the site initialization, and are therefore unaffected by -S.

virtual environment 에서 실행될 때, sys.prefix 에 있는 pyvenv.cfg 파일에서 사이트 관련 설정을 확인합니다. include-system-site-packages 키가 존재하고 대소문자 구분 없이 true 로 설정되어 있으면 시스템 수준의 접두사에서 site-packages를 검색하며, 그렇지 않으면 검색하지 않습니다. 시스템 수준의 접두사를 검색하지 않는 경우 사용자 사이트(user site) 접두사도 암시적으로 제외됩니다.

site 모듈은 경로 구성을 위한 name.pth 형식의 두 가지 시작 구성 파일과, 첫 줄 이전 코드 실행을 위한 name.start 형식의 파일을 인식합니다. 두 파일 모두 위에서 언급된 네 개의 디렉터리 중 하나에 존재할 수 있습니다. 각 디렉터리 내에서 이 파일들은 파일 이름별로 알파벳 순으로 정렬된 후, 정렬된 순서로 파싱됩니다.

경로 확장(.pth 파일)

name.pth 은 sys.path 에 추가할 항목(한 줄에 하나씩)을 포함합니다. 존재하지 않는 디렉터리를 지칭하는 항목은 sys.path 에 추가되지 않으며, 해당 항목이 파일이 아닌 디렉터리인지 확인하는 절차는 거치지 않습니다. 동일한 항목이 sys.path 에 중복으로 추가되지 않습니다. 빈 줄과 # 으로 시작하는 줄은 건너뜁니다.

하위 호환성을 위해, 공백이나 탭이 뒤따르는 import 로 시작하는 줄은 exec() 를 통해 실행됩니다.

버전 3.13에서 변경: .pth 파일은 먼저 UTF-8로 디코딩하며, 실패할 경우에만 locale encoding 으로 디코딩합니다.

버전 3.15에서 변경: .pth 파일의 import 로 시작하는 줄은 더 이상 권장되지 않습니다(deprecated). 폐지 기간 동안 이러한 줄은 여전히 실행되지만(아래 경우 제외), -v 플래그가 활성화된 경우에만 진단 메시지가 출력됩니다.

name.pth 내의 import 줄은 matching name.start 파일이 존재하는 경우 무시됩니다.

개별 줄에서 발생하는 오류가 나머지 파일 처리를 중단시키지 않습니다. 각 오류는 보고되며, 남은 줄들은 계속 처리됩니다.

버전 3.15부터 사용 지원 중단(deprecated), 버전 3.20에서 제거 예정: name.pth 파일을 utf-8-sig 이외의 인코딩으로 디코딩하는 기능은 Python 3.15에서 폐지되며, 로케일 인코딩으로의 디코딩 지원은 Python 3.20에서 제거됩니다.

name.pth 파일의 import 줄은 폐지되었으며, Python 3.18 및 3.19에서는 무시됩니다. Python 3.20부터는 해당 문구에 대해 경고가 발생합니다.

시작 엔트리 포인트(.start 파일)

Added in version 3.15.

시작 엔트리 포인트 파일은 이름이 name.start 형식이면서 위에서 설명한 site-packages 디렉터리 중 하나에 존재하는 파일입니다. 각 파일은 pkgutil.resolve_name`이 인식하는 ``pkg.mod:callable`() 구문을 사용하여 인터프리터 시작 시 호출될 엔트리 포인트를 지정합니다.

#``으로 시작하지 않는 모든 빈 줄이 아닌 줄은 ``pkg.mod:callable 형식의 엔트리 포인트 참조를 포함해야 합니다. 콜론과 callable 부분은 필수입니다. 각 callable은 인자 없이 호출되며, 반환 값은 버려집니다.

.start 파일은 모든 .pth 경로 확장이 sys.path 에 적용된 후에 처리되며, 이를 통해 시작 코드가 실행되기 전에 경로를 사용할 수 있도록 보장합니다.

.pth 파일의 sys.path 확장과 달리 중복된 엔트리 포인트는 제거되지 않습니다. 즉, 엔트리 포인트가 여러 번 나타나면 그 횟수만큼 호출됩니다.

엔트리 포인트의 분석이나 호출 중에 예외가 발생하면 트레이스백이 sys.stderr 에 출력되고 나머지 엔트리 포인트에 대한 처리가 계속됩니다.

.start 파일은 반드시 UTF-8로 인코딩되어야 합니다.

PEP 829 이 이러한 기능에 대한 원래 명세서를 정의했습니다.

참고

동일한 기본 이름을 가진 name.pth 파일과 함께 name.start 파일이 존재하는 경우, .pth 파일 내의 모든 import 줄은 무시되고 대신 .start 파일의 엔트리 포인트가 사용됩니다.

참고

실행 가능한 줄(name.pth 파일의 import 줄 및 name.start 파일의 엔트리 포인트)은 특정 모듈을 실제로 사용할지 여부와 관계없이 파이썬 시작 시에 항상 실행됩니다(단, -S 가 제공되어 site.py 모듈이 완전히 비활성화된 경우는 제외).

참고

name.start 파일은 strict=True 로 설정된 pkgutil.resolve_name() 을 호출하며, 이 경우 전체 pkg.mod:callable 형식이 필요합니다.

시작 파일 예시

예를 들어, sys.prefix 와 sys.exec_prefix 가 /usr/local 으로 설정되어 있다고 가정해 보겠습니다. 그러면 파이썬 X.Y 라이브러리가 /usr/local/lib/pythonX.Y 에 설치됩니다. 여기에 foo, bar, spam 이라는 세 개의 하위 디렉터리와, foo.pth 및 bar.pth 라는 두 개의 경로 설정 파일이 있는 /usr/local/lib/pythonX.Y/site-packages 디렉터리가 있다고 가정해 보겠습니다. foo.pth 에 다음 내용이 포함되어 있다고 가정합니다:

# foo package configuration

foo
bar
bletch

bar.pth는 다음을 포함한다고 가정하십시오:

# bar package configuration

bar

그러면 다음과 같은 버전 별 디렉터리가 이 순서대로 sys.path에 추가됩니다:

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

bletch가 존재하지 않기 때문에 생략되었음에 유의하십시오; bar.pth가 알파벳순으로 foo.pth 앞에 오기 때문에 bar 디렉터리가 foo 디렉터리보다 앞에 옵니다; spam은 경로 구성 파일에 언급되어 있지 않기 때문에 생략되었습니다.

또한, 다음과 같은 내용을 포함하는 foo.start 파일이 있다고 가정해 보겠습니다:

# foo package startup code

foo.submod:initialize

이제 위와 같이 sys.path``가 확장된 후, 파이썬이 제어권을 사용자 코드에 넘기기 전에 ``foo.submod 모듈이 임포트되고 해당 모듈의 initialize() 함수가 호출됩니다.

.pth 파일의 import 줄을 .start 파일로 마이그레이션하기

현재 패키지에 name.pth 파일이 포함되어 있는 경우, 모든 sys.path 확장 라인을 그대로 유지할 수 있습니다. 오직 import 라인만 마이그레이션하면 됩니다.

마이그레이션하려면, 패키지 내의 임포트 가능한 모듈 안에 호출 가능한 함수(인자 0개)를 생성하십시오. 이를 일치하는 name.start 파일에 pkg.mod:callable 엔트리 포인트로 참조하십시오. 기존 import 라인의 첫 번째 세미콜론 이후의 모든 내용을 해당 callable() 함수 안으로 옮기십시오.

패키지가 PEP 829 을 지원하지 않는 이전 버전의 파이썬과 지원하는 최신 버전의 파이썬을 모두 지원해야 하는 경우, name.pth 내의 import 라인을 다음 형식으로 변경하십시오:

import pkg.mod; pkg.mod.callable()

이전 파이썬은 이 import 라인들을 실행하고, 최신 파이썬은 이를 무시하고 대신 name.start 파일을 사용합니다. 호환성 유지 기간이 끝난 후에는 .pth 파일에서 모든 import 라인을 제거하십시오.

sitecustomize

이러한 경로 조작 후, 임의의 사이트별 설정을 수행할 수 있는 sitecustomize 모듈을 임포트하려고 시도합니다. 이 모듈은 대개 시스템 관리자가 site-packages 디렉터리에 생성합니다. 만약 이 임포트가 ImportError 또는 그 하위 클래스 예외로 실패하고, 해당 예외의 name 속성이 'sitecustomize' 과 일치하면 조용히 무시됩니다. 윈도우에서 IDLE을 시작할 때 기본으로 사용하는 pythonw.exe 와 같이 출력 스트림이 없는 상태에서 파이썬이 실행되는 경우, sitecustomize 의 출력 시도는 무시됩니다. 그 외의 예외는 프로세스의 조용하고 정체불명의 실패를 초래합니다.

usercustomize

그 후, ENABLE_USER_SITE 이(가) true인 경우 임의의 사용자별 설정을 수행할 수 있는 usercustomize 모듈을 임포트하려고 시도합니다. 이 파일은 사용자 site-packages 디렉터리(아래 참조)에 생성될 것을 의도하며, 이는 -s 로 비활성화되지 않는 한 sys.path 의 일부입니다. 만약 이 임포트가 ImportError 또는 그 하위 클래스 예외로 실패하고, 해당 예외의 name 속성이 'usercustomize' 과 일치하면 조용히 무시됩니다.

유닉스가 아닌 일부 시스템에서는 sys.prefix 와 sys.exec_prefix 가 비어 있어 경로 조작이 생략되지만, sitecustomize 및 usercustomize 의 임포트는 여전히 시도됩니다.

Readline 구성

readline 을 지원하는 시스템에서 파이썬이 대화형 모드 로 실행되고 -S 옵션이 없는 경우, 이 모듈은 rlcompleter 모듈도 임포트하고 구성합니다. 기본 동작은 탭 완성을 활성화하고 ~/.python_history 를 히스토리 저장 파일로 사용하는 것입니다. 이를 비활성화하려면 sitecustomize 또는 usercustomize 모듈이나 PYTHONSTARTUP 파일에서 sys.__interactivehook__ 속성을 삭제(또는 재정의)하십시오.

버전 3.4에서 변경: rlcompleter와 히스토리 활성화가 자동으로 이루어졌습니다.

모듈 내용

site.PREFIXES

site-packages 디렉터리의 접두사 리스트.

site.ENABLE_USER_SITE

사용자 site-packages 디렉터리의 상태를 나타내는 플래그. True는 활성화되어 sys.path에 추가되었음을 의미합니다. False는 사용자 요청(-s나 PYTHONNOUSERSITE로)에 의해 비활성화되었음을 의미합니다. None은 보안상의 이유(사용자나 그룹 id와 유효(effective) id가 일치하지 않음)로 또는 관리자에 의해 비활성화되었음을 의미합니다.

site.USER_SITE

실행 중인 파이썬의 사용자 site-packages 경로. getusersitepackages()가 아직 호출되지 않았으면 None일 수 있습니다. 기본값은 유닉스와 비 프레임워크 맥 OS 빌드의 경우 ~/.local/lib/pythonX.Y[t]/site-packages, 맥 OS 프레임워크 빌드의 경우 ~/Library/Python/X.Y/lib/python/site-packages, 윈도우의 경우 %APPDATA%\Python\PythonXY\site-packages입니다. 선택적 “t” 는 자유 스레딩 빌드를 나타냅니다. 이 디렉터리는 사이트 디렉터리이며, 이는 그 안에 있는 .pth 파일이 처리됨을 의미합니다.

site.USER_BASE

사용자 site-packages의 베이스 디렉터리에 대한 경로. getuserbase()가 아직 호출되지 않았으면 None일 수 있습니다. 기본값은 유닉스와 맥 OS 비 프레임워크 빌드의 경우 ~/.local, 맥 OS 프레임워크 빌드의 경우 ~/Library/Python/X.Y, 윈도우의 경우 %APPDATA%\Python입니다. 이 값은 사용자 설치 스킴의 스크립트, 데이터 파일, 파이썬 모듈 등의 설치 디렉터리를 계산하는 데 사용됩니다. PYTHONUSERBASE 도 참조하십시오.

site.main()

모든 표준 사이트별 디렉터리를 모듈 검색 경로에 추가합니다. 파이썬 인터프리터가 -S 플래그로 시작되지 않았으면, 이 모듈이 임포트 될 때 이 함수가 자동으로 호출됩니다.

버전 3.3에서 변경: 이 함수는 무조건 호출되었습니다.

site.makepath(*paths)

paths 를 os.path.join() 으로 결합하고, os.path.abspath() 로 결과를 절대 경로로 만들려고 시도한 뒤, 절대 경로와 os.path.normcase() 에 의해 생성된 대소문자 정규화 형식을 포함하는 2-튜플을 반환합니다. 만약 os.path.abspath() 가 OSError 를 발생시키면, 결합된 경로를 그대로 사용하여 대소문자 정규화 단계를 진행합니다.

반환된 튜플의 두 번째 요소는 대소문자를 구분하지 않는 파일 시스템에서 경로를 비교할 때 site 모듈 전반에서 사용되는 형식이며, 이 모듈 내 다양한 API에서 sys.path 항목이 중복되지 않도록 하는 known_paths 집합을 채우는 데 사용됩니다.

class site.StartupState(known_paths=None)

이 클래스의 인스턴스는 하나 이상의 사이트 디렉터리에서 인터프리터 시작 구성 데이터를 수집합니다. 이들은 여러 사이트 디렉터리에 걸친 .pth 및 .start 파일 처리를 일괄로 처리하는 권장된 인터페이스이며, 이를 통해 모든 시작 코드가 실행되기 전에 모든 sys.path 확장이 인식되도록 합니다.

선택적 인수인 known_paths 는 중복된 sys.path 항목을 방지하기 위해 사용되는 대소문자 정규화 경로 집합입니다( makepath() 를 통해 생성 가능). None 인 경우(기본값), 현재 sys.path 로부터 이 집합이 구성됩니다. main() 은 이 클래스의 인스턴스를 암시적으로 사용합니다.

일반적인 사용법:

state = site.StartupState()
for sitedir in site_dirs:
    state.addsitedir(sitedir)
state.process()

Added in version 3.15.

addsitedir(sitedir)

sitedir 에 있는 .pth 및 .start 파일을 읽어 해당 내용의 sys.path 확장, 더 이상 사용되지 않는 .pth import 라인, 그리고 .start 엔트리 포인트를 이 상태에 기록합니다. 기록된 데이터는 process() 가 호출될 때까지 적용되지 않습니다.

addusersitepackages()

활성화되어 있고 존재하는 경우 사용자별 site-packages 디렉터리를 추가합니다. 해당 디렉터리의 시작 데이터는 나중에 process() 에 의해 처리되도록 축적됩니다.

addsitepackages(prefixes=None)

prefixes 로부터 계산되거나, prefixes 가 None 인 경우 전역 PREFIXES 로부터 산출된 전역 site-packages 디렉터리들을 추가합니다. 각 디렉터리의 시작 데이터는 나중에 process() 에 의해 처리되도록 축적됩니다.

process()

축적된 상태를 적용합니다. 먼저 경로 확장 항목을 sys.path`에 추가한 다음, :file:.start` 파일의 엔트리 포인트와 .pth 파일의 import 라인(deprecated)을 실행합니다.

이 메서드는 멱등적이지 않으며 동일한 인스턴스에 대해 여러 번 호출되어서는 안 됩니다. 그렇게 하면 축적된 상태가 중복으로 적용되어 엔트리 포인트와 import 라인이 다시 실행됩니다.

site.addsitedir(sitedir, known_paths=None)

sys.path에 디렉터리를 추가하고 해당 디렉터리에서 발견되는 .pth 및 .start 파일을 파싱합니다. 일반적으로 sitecustomize 또는 usercustomize 에서 사용됩니다(위 참조).

known_paths 인자는 중복된 sys.path 항목을 방지하기 위해 사용되는 선택적 대소문자 정규화 경로 집합입니다. None 인 경우(기본값), 현재 sys.path 를 기반으로 생성됩니다.

여러 사이트 디렉터리에 걸친 일괄 처리를 위해, StartupState 를 명시적으로 구축하고 이에 대한 StartupState.addsitedir() 을 호출하십시오. 이를 통해 .pth 및 .start 처리를 단일 StartupState.process() 호출 시점까지 미루어, 모든 시작 코드가 실행되기 전에 모든 sys.path 확장이 보장되도록 합니다.

버전 3.15에서 변경: .start 파일도 처리합니다. 시작 엔트리 포인트(.start 파일) 를 참조하십시오.

site.getsitepackages()

모든 전역 site-packages 디렉터리를 포함하는 리스트를 반환합니다.

Added in version 3.2.

site.getuserbase()

사용자 베이스 디렉터리 USER_BASE의 경로를 반환합니다. 아직 초기화되지 않았으면, 이 함수는 PYTHONUSERBASE를 따라 설정합니다.

Added in version 3.2.

site.getusersitepackages()

사용자별 site-packages 디렉터리 USER_SITE의 경로를 반환합니다. 아직 초기화되지 않았으면, 이 함수는 USER_BASE를 따라 설정합니다. 사용자별 site-packages가 sys.path에 추가되었는지 확인하려면 ENABLE_USER_SITE를 사용해야 합니다.

Added in version 3.2.

명령 줄 인터페이스

site 모듈은 명령 줄에서 사용자 디렉터리를 가져오는 방법도 제공합니다.

$ python -m site --user-site
/home/user/.local/lib/python3.11/site-packages

인자 없이 호출되면, 표준 출력에 sys.path의 내용을 인쇄한 다음, USER_BASE의 값과 디렉터리가 존재하는지를 인쇄하고, USER_SITE에 대해 같은 것을 인쇄하고, 마지막으로 ENABLE_USER_SITE의 값을 인쇄합니다.

--user-base

사용자 베이스 디렉터리의 경로를 인쇄합니다.

--user-site

사용자 site-packages 디렉터리의 경로를 인쇄합니다.

두 옵션이 모두 제공되면, os.pathsep으로 구분하여, 사용자 베이스와 사용자 사이트를 (항상 이 순서대로) 인쇄합니다.

어떤 옵션이건 제공되면, 스크립트는 다음 값 중 하나로 종료됩니다: 사용자 site-packages 디렉터리가 활성화되었으면 0, 사용자에 의해 비활성화되었으면 1, 보안상의 이유나 관리자에 의해 비활성화되었으면 2, 그리고 에러가 있으면 2보다 큰 값.

더 보기

분실물 보관소