"pkgutil" --- Package extension utility
***************************************

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

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

이 모듈은 임포트 시스템, 특히 패키지 지원을 위한 유틸리티를 제공합니다
.

class pkgutil.ModuleInfo(module_finder, name, ispkg)

   모듈 정보에 대한 간략한 요약을 담고 있는 네임드 튜플.

   버전 3.6에 추가.

pkgutil.extend_path(path, name)

   패키지를 구성하는 모듈의 검색 경로를 확장합니다. 의도된 사용법은 패
   키지의 "__init__.py"에 다음 코드를 삽입하는 것입니다:

      from pkgutil import extend_path
      __path__ = extend_path(__path__, __name__)

   This will add to the package's "__path__" all subdirectories of
   directories on "sys.path" named after the package.  This is useful
   if one wants to distribute different parts of a single logical
   package as multiple directories.

   It also looks for "*.pkg" files beginning where "*" matches the
   *name* argument.  This feature is similar to "*.pth" files (see the
   "site" module for more information), except that it doesn't
   special-case lines starting with "import".  A "*.pkg" file is
   trusted at face value: apart from checking for duplicates, all
   entries found in a "*.pkg" file are added to the path, regardless
   of whether they exist on the filesystem.  (This is a feature.)

   입력 경로가 리스트가 아니면 (프로즌 패키지의 경우처럼) 변경되지 않
   은 상태로 반환됩니다. 입력 경로는 수정되지 않습니다; 확장한 사본이
   반환됩니다. 항목은 사본의 끝에 추가되기만 합니다.

   "sys.path"기 시퀀스라고 가정합니다. 존재하는 디렉터리를 참조하는 문
   자열이 아닌 "sys.path" 항목은 무시됩니다. 파일명으로 사용될 때 에러
   를 일으키는 "sys.path"의 유니코드 항목은 이 함수가 예외를 발생시키
   도록 할 수 있습니다 ("os.path.isdir()" 동작과 일치합니다).

class pkgutil.ImpImporter(dirname=None)

   **PEP 302** Finder that wraps Python's "classic" import algorithm.

   If *dirname* is a string, a **PEP 302** finder is created that
   searches that directory.  If *dirname* is "None", a **PEP 302**
   finder is created that searches the current "sys.path", plus any
   modules that are frozen or built-in.

   Note that "ImpImporter" does not currently support being used by
   placement on "sys.meta_path".

   버전 3.3부터 폐지: This emulation is no longer needed, as the
   standard import mechanism is now fully **PEP 302** compliant and
   available in "importlib".

class pkgutil.ImpLoader(fullname, file, filename, etc)

   *Loader* that wraps Python's "classic" import algorithm.

   버전 3.3부터 폐지: This emulation is no longer needed, as the
   standard import mechanism is now fully **PEP 302** compliant and
   available in "importlib".

pkgutil.find_loader(fullname)

   주어진 *fullname*에 대한 모듈 *로더*를 가져옵니다.

   This is a backwards compatibility wrapper around
   "importlib.util.find_spec()" that converts most failures to
   "ImportError" and only returns the loader rather than the full
   "ModuleSpec".

   버전 3.3에서 변경: 패키지 내부 **PEP 302** 임포트 에뮬레이션에 의존
   하는 대신, "importlib"에 직접 기반하도록 갱신되었습니다.

   버전 3.4에서 변경: **PEP 451**에 기반하도록 갱신되었습니다

pkgutil.get_importer(path_item)

   주어진 *path_item*에 대한 *파인더*를 가져옵니다.

   반환된 파인더는 경로 훅 때문에 새로 만들어지면
   "sys.path_importer_cache"에 캐시 됩니다.

   "sys.path_hooks"의 재검색이 필요하면, 캐시(또는 그 일부)를 수동으로
   지울 수 있습니다.

   버전 3.3에서 변경: 패키지 내부 **PEP 302** 임포트 에뮬레이션에 의존
   하는 대신, "importlib"에 직접 기반하도록 갱신되었습니다.

pkgutil.get_loader(module_or_name)

   *module_or_name*에 대한 *로더* 객체를 가져옵니다.

   모듈이나 패키지가 일반 임포트 메커니즘을 통해 액세스할 수 있으면,
   그 장치의 관련 부분을 감싸는 래퍼가 반환됩니다. 모듈을 찾거나 임포
   트 할 수 없으면 "None"을 반환합니다. 명명된 모듈이 아직 임포트 되지
   않았다면, 패키지 "__path__"를 구성하기 위해 포함하는 패키지(있다면
   ))를 임포트 합니다.

   버전 3.3에서 변경: 패키지 내부 **PEP 302** 임포트 에뮬레이션에 의존
   하는 대신, "importlib"에 직접 기반하도록 갱신되었습니다.

   버전 3.4에서 변경: **PEP 451**에 기반하도록 갱신되었습니다

pkgutil.iter_importers(fullname='')

   주어진 모듈 이름에 대해 *파인더* 객체를 산출(yield)합니다.

   fullname에 "'.'"이 포함되어 있으면, 파인더는 fullname을 포함하는 패
   키지를 위한 것입니다, 그렇지 않으면, 등록된 모든 최상위 수준 파인더
   입니다 (즉, "sys.meta_path" 와 "sys.path_hooks"에 있는 것들).

   명명된 모듈이 패키지에 있으면, 이 함수를 호출하는 부작용으로 그 패
   키지를 임포트 합니다.

   모듈 이름을 지정하지 않으면, 모든 최상위 수준 파인더가 생성됩니다.

   버전 3.3에서 변경: 패키지 내부 **PEP 302** 임포트 에뮬레이션에 의존
   하는 대신, "importlib"에 직접 기반하도록 갱신되었습니다.

pkgutil.iter_modules(path=None, prefix='')

   *path*의 모든 서브 모듈에 대한 "ModuleInfo"를, 또는 *path*가 "None"
   이면, "sys.path"에 있는 모든 최상위 모듈을 산출(yield)합니다.

   *path*는 "None"이거나 모듈을 찾을 경로의 리스트이어야 합니다.

   *prefix*는 출력 시 모든 모듈 이름 앞에 출력할 문자열입니다.

   참고:

     "iter_modules()" 메서드를 정의하는 *파인더*에서만 작동합니다. 이
     인터페이스는 비표준이므로, 모듈은
     "importlib.machinery.FileFinder"와 "zipimport.zipimporter"에 대한
     구현도 제공합니다.

   버전 3.3에서 변경: 패키지 내부 **PEP 302** 임포트 에뮬레이션에 의존
   하는 대신, "importlib"에 직접 기반하도록 갱신되었습니다.

pkgutil.walk_packages(path=None, prefix='', onerror=None)

   *path*에 재귀적으로 포함된 모든 모듈이나, *path*가 "None"이면 모든
   액세스할 수 있는 모듈에 대한 "ModuleInfo"를 산출(yield)합니다.

   *path*는 "None"이거나 모듈을 찾을 경로의 리스트이어야 합니다.

   *prefix*는 출력 시 모든 모듈 이름 앞에 출력할 문자열입니다.

   서브 모듈 검색을 위한 "__path__" 어트리뷰트에 액세스하기 위해, 이
   함수는 주어진 *path*에 있는 모든 *패키지*(모든 모듈이 *아닙니다*!)
   를 임포트 해야 함에 유의하십시오.

   *onerror*는 패키지 임포트를 시도하는 동안 예외가 발생하면 하나의 인
   자(임포트 하려는 패키지의 이름)로 호출되는 함수입니다. *onerror* 함
   수가 제공되지 않으면, "ImportError"는 잡아서 무시하고, 다른 모든 예
   외는 전파되어 검색이 종료됩니다.

   예제:

      # list all modules python can access
      walk_packages()

      # list all submodules of ctypes
      walk_packages(ctypes.__path__, ctypes.__name__ + '.')

   참고:

     "iter_modules()" 메서드를 정의하는 *파인더*에서만 작동합니다. 이
     인터페이스는 비표준이므로, 모듈은
     "importlib.machinery.FileFinder"와 "zipimport.zipimporter"에 대한
     구현도 제공합니다.

   버전 3.3에서 변경: 패키지 내부 **PEP 302** 임포트 에뮬레이션에 의존
   하는 대신, "importlib"에 직접 기반하도록 갱신되었습니다.

pkgutil.get_data(package, resource)

   패키지에서 리소스를 가져옵니다.

   이것은 *로더* "get_data" API에 대한 래퍼입니다. *package* 인자는 표
   준 모듈 형식("foo.bar")의 패키지 이름이어야 합니다. *resource* 인자
   는 "/"를 경로 분리자로 사용하는 상대 파일명의 형식이어야 합니다. 상
   위 디렉터리 이름 ".."는 허용되지 않으며, 루트에서 시작하는("/"로 시
   작하는) 이름도 허용되지 않습니다.

   이 함수는 지정된 리소스의 내용인 바이트열을 반환합니다.

   파일시스템에 있는 패키지(이미 임포트 되었습니다)의 경우, 이것은 대
   략 다음과 동등합니다:

      d = os.path.dirname(sys.modules[package].__file__)
      data = open(os.path.join(d, resource), 'rb').read()

   패키지를 찾거나 로드 할 수 없거나, 패키지가 "get_data"를 지원하지
   않는 *로더*를 사용하면, "None"이 반환됩니다. 특히, *이름 공간 패키
   지*를 위한 *로더*는 "get_data"를 지원하지 않습니다.

pkgutil.resolve_name(name)

   이름을 객체로 해석합니다.

   이 기능은 표준 라이브러리의 여러 곳에서 사용됩니다 (bpo-12915를 참
   조하십시오) - 그리고 동등한 기능이 setuptools, Django 및 Pyramid와
   같은 널리 사용되는 제삼자 패키지에도 있습니다.

   *name*은 다음 형식 중 하나의 문자열 일 것으로 기대됩니다, 여기서 W
   는 유효한 파이썬 식별자를 나타내는 줄임 표현이며 점은 이러한 의사
   정규식에서 리터럴 마침표를 나타냅니다:

   * "W(.W)*"

   * "W(.W)*:(W(.W)*)?"

   첫 번째 형식은 이전 버전과의 호환성을 위해서만 사용됩니다. 점으로
   구분된 이름의 일부는 패키지이고, 나머지는 패키지 내의 어딘가에 있는
   객체이며, 다른 객체 안에 중첩되었을 수 있습니다. 패키지가 멈추고 객
   체 계층 구조가 시작되는 위치는 보는 것 만으로는 유추할 수 없습니다,
   이 형식으로는 임포트 시도를 반복해서 수행해야합니다.

   두 번째 형식에서, 호출자는 단일 콜론을 제공하여 구분 지점을 명확하
   게 만듭니다: 콜론 왼쪽의 점으로 구분된 이름은 임포트할 패키지이고,
   오른쪽의 점으로 구분된 이름은 해당 패키지 내의 객체 계층 구조입니다
   . 이 형식에서는 한 번의 임포트만 필요합니다. 콜론으로 끝나면, 모듈
   객체가 반환됩니다.

   이 함수는 객체(모듈일 수 있습니다)를 반환하거나, 다음 예외 중 하나
   를 발생시킵니다:

   "ValueError" -- *name*이 인식되는 형식이 아니면.

   "ImportError" -- 그러지 말아야할 때 임포트가 실패하면.

   "AttributeError" -- 임포트한 패키지 내에서 객체 계층 구조를 탐색하
   여 원하는 객체에 도달하는 도중 실패가 발생할 때.

   버전 3.9에 추가.
