Python

site — 사이트별 구성 훅

소스 코드: Lib/site.py

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

이 모듈을 임포트하면 일반적으로 사이트별 경로를 모듈 검색 경로에 추가하고 콜러블 <site-consts>`를 포함해 :func:`help`를 내장 이름 공간에 추가합니다. 그러나 Python 시작 옵션 :option:-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 환경에서는 자유 스레딩 Python 설치가 버전별 디렉터리 이름에 있는 “t” 접미사로 식별됩니다. 예를 들면 :file:`lib/python3.13t/`와 같습니다.

버전 3.14에서 변경: site`는 :ref:`sys-path-init-virtual-environments`에서 :data:`sys.prefix`와 :data:`sys.exec_prefix`를 업데이트하는 책임이 없습니다. 이는 이제 :ref:`경로 초기화 <sys-path-init> 중에 처리됩니다. 그 결과, 가상 환경 아래에서 sys.prefix`와 :data:`sys.exec_prefix`는 더 이상 :mod:!site` 초기화에 의존하지 않으며, 따라서 :option:`-S`에 의해 영향을 받지 않습니다.

가상 환경 에서 실행하는 경우, sys.prefix 에 있는 pyvenv.cfg 파일이 사이트별 구성을 검사합니다. “include-system-site-packages” 키가 존재하며 true 로 설정되어 있으면(대소문자 구분 없음), 시스템 레벨 접두사에서 site-packages를 검색하며, 그렇지 않으면 검색하지 않습니다. 만약 시스템 레벨 접두사에서 검색하지 않는다면, 사용자 사이트 접두사에서도 암묵적으로 site-packages를 검색하지 않습니다.

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

경로 확장 (.pth 파일)

name.pth 에는 sys.path 에 추가될 추가 항목(한 줄에 하나씩)이 포함됩니다. 존재하지 않는 디렉터리를 이름으로 하는 항목은 sys.path 에 절대 추가되지 않으며, 해당 항목이 파일이 아닌 디렉터리를 참조하는지 확인하지 않습니다. 어떤 항목도 sys.path 에 한 번 이상 추가되지 않습니다. 빈 줄과 # 로 시작하는 줄은 건너뜁니다.

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

버전 3.13에서 변경: .pth 파일은 이제 먼저 UTF-8로 디코딩되고, 실패할 경우 :term:`로케일 인코딩 <locale encoding>`를 통해 디코딩됩니다.

버전 3.15에서 변경: .pth 파일의 import 줄은 이제 사용되지 않습니다. 사용 중단 기간 동안에는 이러한 줄이 여전히 실행되지만(아래 경우 제외), -v 플래그를 지정했을 때만 진단 메시지가 발생합니다.

name.pth 안의 import 줄은 일치하는 name.start 파일이 존재하는 경우 조용히 무시됩니다.

개별 줄에서의 오류가 더 이상 파일의 나머지 처리를 중단시키지 않습니다. 각각의 오류는 보고되고 나머지 줄은 처리가 계속됩니다.

버전 3.15에서 폐지되었고, 버전 3.20에서 제거됩니다: utf-8-sig 을 제외한 어떤 인코딩으로도 name.pth 파일을 디코딩하는 것은 Python 3.15에서 사용 중단되며, 로케일 인코딩을 통한 디코딩 지원은 Python 3.20에서 제거될 예정입니다.

name.pth 파일의 import 줄은 사용 중단되었으며 Python 3.18 및 3.19에서는 조용히 무시될 것입니다. Python 3.20에서는 name.pth 파일의 import 줄에 대해 경고가 발생할 것입니다.

시작 진입점 파일 (.start 파일)

Added in version 3.15.

시작 진입점 파일은 이름이 name.start 형태이고 위에서 설명한 site-packages 디렉터리 중 하나에 존재하는 파일입니다. 각 파일은 pkg.mod:callable 구문을 사용하여 인터프리터 시작 시 호출될 진입점을 지정하며, 이는 :func:`pkgutil.resolve_name`에 의해 이해됩니다.

#`로 시작하지 않는 각 빈 줄에는 `pkg.mod:callable 형태의 진입점 참조가 포함되어야 합니다. 콜론과 callable 부분이 필수입니다. 각 callable은 인자 없이 호출되며, 반환 값은 무시됩니다.

.start 파일은 모든 .pth 경로 확장이 :data:`sys.path`에 적용된 후 처리되어, 시작 코드가 실행되기 전에 경로가 사용 가능한지 확인합니다.

.pth 파일의 sys.path 확장과 달리, 중복된 진입점은 제거되지 않습니다 — 진입점이 한 번 이상 나타나면, 한 번 이상 호출됩니다.

진입점의 해결 또는 호출 중에 예외가 발생하면, 트레이스백이 :data:`sys.stderr`에 출력되고 나머지 진입점으로 처리가 계속됩니다.

.start 파일은 UTF-8로 인코딩해야 합니다.

:pep:`829`가 이 기능들의 원래 사양을 정의했습니다.

참고

name.start 파일이 동일한 기본 이름을 가진 name.pth 파일과 함께 존재하면, .pth 파일의 모든 import 라인은 .start 파일의 진입점보다 무시됩니다.

참고

실행 라인 ( name.pth 파일 및 .start 파일 진입점의 import 라인)은 특정 모듈이 실제로 사용될지 여부와 관계없이 항상 Python 시작 시 실행됩니다 ( -S`가 주어지지 않아 ``site.py` 모듈을 완전히 비활성화하는 경우 제외).

참고

name.start 파일은 strict=True``를 사용하여 :func:`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 패키지 시작 코드

foo.submod:initialize

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

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

패키지가 현재 name.pth 파일을 배포하는 경우, 모든 sys.path 확장 라인을 변경하지 않고 유지할 수 있습니다. import 라인만 마이그레이션해야 합니다.

마이그레이션을 하려면, 패키지의 임포트 가능한 모듈 내에 callable을 생성합니다 (인자 없음). 이를 일치하는 name.start 파일에서 pkg.mod:callable 진입점으로 참조합니다. import 라인의 첫 번째 세미콜론 이후의 모든 내용을 callable() 함수로 이동합니다.

패키지가 PEP 829 를 지원하지 않는 구형 Python과 지원하는 최신 Python을 모두 지원해야 하는 경우, name.pth 의 import 라인을 다음 형식을 사용하도록 변경합니다:

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

구형 Python에서는 이 import 라인이 실행되고, 최신 Python에서는 name.start 파일의 진입점보다 이를 무시합니다. 병행 기간이 지난 후에는 .pth 파일의 모든 import 라인을 제거하십시오.

sitecustomize

이러한 경로 조작 후, 임의의 사이트별 사용자 정의를 수행할 수 있는 sitecustomize\ 모듈을 임포트 하려고 시도합니다. 일반적으로 시스템 관리자가 site-packages 디렉터리에 생성합니다. 이 임포트가 ImportError\ 또는 그 서브 클래스 예외로 실패하고, 예외의 name 어트리뷰트가 'sitecustomize'\ 와 같으면, 조용히 무시됩니다. 윈도우에서 pythonw.exe\ (IDLE을 시작하는 데 기본적으로 사용됩니다)처럼, 사용 가능한 출력 스트림 없이 파이썬을 시작하면, sitecustomize\ 의 시도된 출력은 무시됩니다. 다른 모든 예외는 프로세스의 조용하고 아마도 신비로운 실패를 야기합니다.

usercustomize

다음으로, ENABLE_USER_SITE\ 가 참인 경우, 임의의 사용자별 사용자 정의를 수행할 수 있는 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\ 에 추가한 다음, .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`를 명시적으로 구축하고 이에 대해 :meth:`StartupState.addsitedir`를 호출합니다. 이렇게 하면 :file:.pth` 및 .start 처리가 단일 StartupState.process() 호출까지 지연되어, 모든 sys.path 확장이 시작 코드가 실행되기 전에 표시되도록 보장합니다.

버전 3.15에서 변경: .start 파일도 처리합니다. :ref:`site-start-files`를 참조하십시오.

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보다 큰 값.

더 보기

분실물 보관소