`site` — 사이트별 설정 훅

이 모듈은 초기화 중에 자동으로 임포트돼요. 자동 임포트는 인터프리터의 -S 옵션으로 막을 수 있어요.

보통 이 모듈을 임포트하면 사이트별 경로를 모듈 검색 경로에 덧붙이고, help()를 포함한 callable을 내장 네임스페이스에 추가해요. 하지만 Python 시작 옵션 -S는 이를 막고, 모듈 검색 경로의 자동 수정이나 builtins 추가 없이 이 모듈을 안전하게 임포트할 수 있어요. 평소의 사이트별 추가를 명시적으로 촉발하려면 main() 함수를 호출하세요.

버전 3.3 변경: 이 모듈을 임포트하면 -S를 쓸 때도 경로 조작을 촉발하곤 했음.
버전 3.5 변경: "site-python" 디렉터리 지원이 제거됨.
버전 3.13 변경: Unix에서 자유 스레딩 Python 설치를 lib/python3.13t/ 같은 버전별 디렉터리 이름의 "t" 접미사로 식별함.
버전 3.14 변경: site는 더 이상 Virtual Environments에서 sys.prefix와 sys.exec_prefix를 갱신하지 않음. 이제는 경로 초기화 중에 처리됨. 결과적으로 Virtual Environments 아래에서 sys.prefix와 sys.exec_prefix는 더 이상 site 초기화에 의존하지 않으며 -S의 영향을 받지 않음.

이 모듈은 머리(head)와 꼬리(tail) 부분으로 최대 네 개의 디렉터리를 만드는 것으로 시작해요. 머리 부분에는 sys.prefix와 sys.exec_prefix를 사용하고, 빈 머리는 건너뛰어요. 꼬리 부분에는 빈 문자열을 사용하고 이어 lib/site-packages(Windows) 또는 lib/python*X.Y[t]*/site-packages(Unix와 macOS)를 사용해요. (선택 접미사 "t"는 자유 스레딩 빌드(free-threaded build)를 나타내며, sys.abiflags 상수에 "t"가 있으면 추가돼요.) 각각의 구별되는 머리-꼬리 조합에 대해 기존 디렉터리를 가리키는지 확인하고, 그렇다면 sys.path에 추가하고 새로 추가된 경로의 설정 파일도 검사해요.

가상 환경에서 실행할 때는 sys.prefix의 pyvenv.cfg 파일에서 사이트별 설정을 확인해요. include-system-site-packages 키가 존재하고(대소문자 무시) true로 설정돼 있으면 시스템 수준 접두사에서 site-packages를 검색하고, 아니면 검색하지 않아요.

경로 설정 파일은 이름이 *name*.pth 형식이고 위 네 디렉터리 중 하나에 존재하는 파일이에요. 그 내용은 sys.path에 추가할 추가 항목(한 줄에 하나)이에요. 존재하지 않는 항목은 결코 sys.path에 추가되지 않고, 항목이 파일이 아니라 디렉터리를 가리키는지에 대한 검사는 이뤄지지 않아요. 어떤 항목도 sys.path에 두 번 이상 추가되지 않아요. 빈 줄과 #로 시작하는 줄은 건너뛰어요. import로 시작하는 줄(공백 또는 탭이 뒤따르는)은 실행돼요.

참고

.pth 파일의 실행 가능한 줄은 특정 모듈이 실제로 사용될지 여부와 무관하게 매 Python 시작마다 실행돼요. 따라서 그 영향은 최소로 유지해야 해요. 실행 가능한 줄의 주된 의도는 해당 모듈(들)을 임포트 가능하게 만드는 것이에요(서드파티 임포트 훅 로드, PATH 조정 등). 다른 초기화는 실제 임포트 시점에 해야 해요. 코드 덩어리를 한 줄로 제한하는 것은 여기에 더 복잡한 것을 넣지 못하게 하려는 의도적인 조치예요.

버전 3.13 변경: .pth 파일은 이제 먼저 UTF-8로, 실패하면 로케일 인코딩으로 디코딩됨.

예를 들어 sys.prefix와 sys.exec_prefix가 /usr/local로 설정돼 있다고 가정해 보세요. 그러면 Python X.Y 라이브러리는 /usr/local/lib/python*X.Y*에 설치돼요. 여기에 foo, bar, spam 세 개의 하위 하위 디렉터리와 foo.pth, bar.pth 두 개의 경로 설정 파일이 있는 하위 디렉터리 /usr/local/lib/python*X.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은 생략된다는 점에 주의하세요.

출처: Python 표준 라이브러리

본문

`sitecustomize`

이 경로 조작 후 sitecustomize라는 이름의 모듈을 임포트하려고 시도하는데, 이는 임의의 사이트별 사용자 지정을 수행할 수 있어요. 보통 시스템 관리자가 site-packages 디렉터리에 만드는 모듈이에요. 이 임포트가 ImportError나 그 하위 클래스 예외로 실패하고, 예외의 name 속성이 'sitecustomize'와 같으면 조용히 무시돼요. Windows의 pythonw.exe처럼(기본적으로 IDLE을 시작할 때 쓰는 것) 출력 스트림 없이 Python을 시작하면 sitecustomize의 출력 시도는 무시돼요. 다른 예외는 프로세스의 조용하고 아마도 수수께끼 같은 실패를 일으켜요.

`usercustomize`

그 다음 ENABLE_USER_SITE가 참이면 usercustomize라는 모듈을 임포트하려고 시도하는데, 이는 임의의 사용자별 사용자 지정을 수행할 수 있어요. 이 파일은 -s로 비활성화되지 않는 한 sys.path의 일부인 사용자 site-packages 디렉터리(아래 참고)에 만들도록 의도돼요. 이 임포트가 ImportError나 그 하위 클래스 예외로 실패하고 예외의 name 속성이 'usercustomize'와 같으면 조용히 무시돼요.

일부 비Unix 시스템에서는 sys.prefix와 sys.exec_prefix가 비어 있고 경로 조작이 건너뛰어지지만, sitecustomize와 usercustomize의 임포트는 여전히 시도된다는 점에 주의하세요.

Readline 설정 (Readline configuration)

readline을 지원하는 시스템에서 Python이 -S 옵션 없이 인터랙티브 모드로 시작되면 이 모듈은 rlcompleter 모듈도 임포트하고 설정해요. 기본 동작은 탭 완성을 켜고 ~/.python_history를 히스토리 저장 파일로 쓰는 거예요. 비활성화하려면 sitecustomize나 usercustomize 모듈 또는 PYTHONSTARTUP 파일에서 sys.__interactivehook__ 속성을 삭제(또는 재정의)하세요. 버전 3.4 변경: rlcompleter와 히스토리의 활성화가 자동이 됨.

모듈 내용 (Module contents)

site.PREFIXES

site-packages 디렉터리의 접두사 목록이에요.

site.ENABLE_USER_SITE

사용자 site-packages 디렉터리의 상태를 보여주는 플래그예요. True는 활성화되어 sys.path에 추가됐다는 뜻이고, False는 사용자 요청(-s 또는 PYTHONNOUSERSITE로)에 의해 비활성화됐다는 뜻이며, None은 보안상 이유(사용자나 그룹 ID와 유효 ID의 불일치) 또는 관리자에 의해 비활성화됐다는 뜻이에요.

site.USER_SITE

실행 중인 Python의 사용자 site-packages 경로예요. getusersitepackages()가 아직 호출되지 않았다면 None일 수 있어요. 기본값은 Unix와 비프레임워크 macOS 빌드에서 ~/.local/lib/python*X.Y*[t]/site-packages, macOS 프레임워크 빌드에서 ~/Library/Python/*X.Y*/lib/python/site-packages, Windows에서 *%APPDATA%*\Python\Python*XY*\site-packages예요. 선택 "t"는 자유 스레딩 빌드를 나타내요. 이 디렉터리는 사이트 디렉터리여서 그 안의 .pth 파일이 처리돼요.

site.USER_BASE

사용자 site-packages의 기본 디렉터리 경로예요. getuserbase()가 아직 호출되지 않았다면 None일 수 있어요. 기본값은 Unix와 macOS 비프레임워크 빌드에서 ~/.local, macOS 프레임워크 빌드에서 ~/Library/Python/*X.Y*, Windows에서 *%APPDATA%*\Python이에요. 이 값은 사용자 설치 스킴의 스크립트, 데이터 파일, Python 모듈 등의 설치 디렉터리를 계산하는 데 써요. PYTHONUSERBASE도 참고하세요.

site.main()

모든 표준 사이트별 디렉터리를 모듈 검색 경로에 추가해요. 이 함수는 Python 인터프리터가 -S 플래그로 시작되지 않는 한 이 모듈이 임포트될 때 자동으로 호출돼요. 버전 3.3 변경: 이 함수는 무조건 호출되곤 했음.

site.addsitedir(*sitedir*, *known_paths=None*)

sys.path에 디렉터리를 추가하고 그 .pth 파일을 처리해요. 보통 sitecustomize나 usercustomize에서 사용돼요(위 참고).

site.getsitepackages(*prefixes=None*)

모든 전역 site-packages 디렉터리를 포함하는 목록을 반환해요. prefixes(또는 prefixes가 None이면 PREFIXES)에 주어진 각 디렉터리에 대해 시스템 환경에 따라 site-packages 하위 디렉터리를 계산하고, 존재 여부를 확인하지 않은 전체 경로 목록을 반환해요. 버전 3.2에서 추가, 버전 3.3 변경: 선택 prefixes 매개변수 추가.

site.getuserbase()

사용자 기본 디렉터리 USER_BASE의 경로를 반환해요. 아직 초기화되지 않았다면 PYTHONUSERBASE를 존중하며 설정해요. 버전 3.2에서 추가.

site.getusersitepackages()

사용자별 site-packages 디렉터리 USER_SITE의 경로를 반환해요. 아직 초기화되지 않았다면 USER_BASE를 존중하며 설정해요. 사용자별 site-packages가 sys.path에 추가됐는지 결정하려면 ENABLE_USER_SITE를 써야 해요. 버전 3.2에서 추가.

명령줄 인터페이스 (Command-line interface)

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 디렉터리 경로를 인쇄해요.

두 옵션 모두 주어지면 사용자 base와 user site(항상 이 순서로)가 os.pathsep로 구분되어 인쇄돼요. 어떤 옵션이든 주어지면 스크립트는 사용자 site-packages 디렉터리가 활성화되어 있으면 0, 사용자가 비활성화했으면 1, 보안상 이유나 관리자에 의해 비활성화됐으면 2, 오류가 있으면 2보다 큰 값으로 종료해요.

더 알아보기

PEP 370 – Per user site-packages directory
sys.path 모듈 검색 경로의 초기화 – sys.path의 초기화.

`site` — 사이트별 설정 훅