"site" --- 사이트별 구성 훅
***************************

**소스 코드:** Lib/site.py

======================================================================

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

이 모듈을 임포트하면 일반적으로 사이트별 경로를 모듈 검색 경로에 추가
하고 "help()"를 포함한 콜러블들을 내장 이름 공간에 추가합니다. 그러나
시작 옵션 "-S"는 이를 막고 모듈 검색 경로의 자동 수정이나 내장의 추가
없이 이 모듈을 안전하게 임포트할 수 있습니다. 일반적인 사이트별 추가를
명시적으로 트리거 하려면, "main()" 함수를 호출하십시오.

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

It starts by constructing up to four directories from a head and a
tail part. For the head part, it uses "sys.prefix" and
"sys.exec_prefix"; empty heads are skipped.  For the tail part, it
uses the empty string and then "lib/site-packages" (on Windows) or
"lib/python*X.Y[t]*/site-packages" (on Unix and macOS). (The optional
suffix "t" indicates the *free-threaded build*, and is appended if
""t"" is present in the "sys.abiflags" constant.) For each of the
distinct head-tail combinations, it sees if it refers to an existing
directory, and if so, adds it to "sys.path" and also inspects the
newly added path for configuration files.

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

버전 3.13에서 변경: On Unix, *Free threading* Python installations are
identified by the "t" suffix in the version-specific directory name,
such as "lib/python3.13t/".

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

When running under a virtual environment, the "pyvenv.cfg" file in
"sys.prefix" is checked for site-specific configurations. If the
"include-system-site-packages" key exists and is set to "true" (case-
insensitive), the system-level prefixes will be searched for site-
packages, otherwise they won't.

경로 구성 파일은 이름이 "*name*.pth" 인 파일이며, 위에서 언급한 4개의
디렉터리 중 하나에 존재합니다; 내용은 "sys.path"에 추가될 추가 항목(한
줄에 하나씩)입니다. 존재하지 않는 항목은 "sys.path"에 추가되지 않으며,
항목이 파일이 아닌 디렉터리를 참조하는지 확인하지 않습니다. 어떤 항목
도 "sys.path"에 두 번 추가되지 않습니다. 빈 줄과 "#"으로 시작하는 줄은
건너뜁니다. "import"로 시작하는 (공백이나 탭이 뒤따르는) 줄은 실행됩니
다.

참고:

  ".pth" 파일의 실행 줄은 특정 모듈이 실제 사용될지에 관계없이 모든 파
  이썬 시작 시에 실행됩니다. 따라서 영향을 최소화해야 합니다. 실행 줄
  의 주요 목적은 해당 모듈을 임포트 가능하게 만드는 것입니다 (제삼자
  임포트 훅 로드, "PATH" 조정 등). 다른 초기화는 모듈의 실제 임포트에
  서 수행된다고 간주합니다, (임포트 한다면 그리고 임포트 할 때). 코드
  청크를 한 줄로 제한하는 것은 여기에 더 복잡한 것을 넣지 않도록 하려
  는 의도입니다.

버전 3.13에서 변경: The ".pth" files are now decoded by UTF-8 at first
and then by the *locale encoding* if it fails.

예를 들어, "sys.prefix"와 "sys.exec_prefix"가 "/usr/local"로 설정되었
다고 가정하십시오. 그러면 파이썬 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"은 경로 구성 파일에 언급되어 있지 않기 때문
에 생략되었습니다.


"sitecustomize"
===============

After these path manipulations, an attempt is made to import a module
named "sitecustomize", which can perform arbitrary site-specific
customizations. It is typically created by a system administrator in
the site-packages directory.  If this import fails with an
"ImportError" or its subclass exception, and the exception's "name"
attribute equals "'sitecustomize'", it is silently ignored.  If Python
is started without output streams available, as with "pythonw.exe" on
Windows (which is used by default to start IDLE), attempted output
from "sitecustomize" is ignored.  Any other exception causes a silent
and perhaps mysterious failure of the process.


"usercustomize"
===============

After this, an attempt is made to import a module named
"usercustomize", which can perform arbitrary user-specific
customizations, if "ENABLE_USER_SITE" is true.  This file is intended
to be created in the user site-packages directory (see below), which
is part of "sys.path" unless disabled by "-s".  If this import fails
with an "ImportError" or its subclass exception, and the exception's
"name" attribute equals "'usercustomize'", it is silently ignored.

Note that for some non-Unix systems, "sys.prefix" and
"sys.exec_prefix" are empty, and the path manipulations are skipped;
however the import of "sitecustomize" and "usercustomize" is still
attempted.


Readline 구성
=============

On systems that support "readline", this module will also import and
configure the "rlcompleter" module, if Python is started in
interactive mode and without the "-S" option. The default behavior is
to enable tab completion and to use "~/.python_history" as the history
save file.  To disable it, delete (or override) the
"sys.__interactivehook__" attribute in your "sitecustomize" or
"usercustomize" module or your "PYTHONSTARTUP" file.

버전 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/python*X.Y*[t]/site-packages", 맥 OS 프레임워크 빌드
   의 경우 "~/Library/Python/*X.Y*/lib/python/site-packages", 윈도우의
   경우 "*%APPDATA%*\Python\Python*XY*\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.addsitedir(sitedir, known_paths=None)

   sys.path에 디렉터리를 추가하고 ".pth" 파일을 처리합니다. 일반적으로
   "sitecustomize"나 "usercustomize"에서 사용됩니다 (위를 참조하십시오
   ).

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.


Command-line interface
======================

The "site" module also provides a way to get the user directories from
the command line:

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

더 보기:

  * **PEP 370** -- 사용자별 site-packages 디렉터리

  * The initialization of the sys.path module search path -- The
    initialization of "sys.path".
