pkgutil --- 패키지 확장 유틸리티

소스 코드: 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__)

그러면 sys.path에 있는 디렉터리들의 모든 서브 디렉터리 중 패키지의 이름과 일치하는 것들을 패키지의 __path__에 추가합니다. 이것은 하나의 논리적 패키지의 부분들을 여러 디렉터리로 분배하려고 할 때 유용합니다.

flowdas

__path__는 모든 패키지에 생성되는 전역변수입니다. 패키지의 서브 모듈을 임포트할 때 검색할 경로명이 담겨있습니다. __path__에 대한 자세한 설명은 module.__path__를 참조하십시오.

이 코드는 패키지의 __path__를 수정해서 검색할 경로명들을 여러 디렉터리로 확장합니다. 이러한 코드는 PEP 420이 도입되기 전에 이름 공간 패키지를 구현하는 방법이었습니다. 파이썬 3에서는 이런 코드가 필요 없습니다. 파이썬 3에서는 __init__.py 파일이 없으면 이름 공간 패키지가 되고, 이 코드가 하는 일과 비슷한 일이 임포트 시스템에 의해 자동 수행됩니다. 하지만 이 코드는 파이썬 2와 3 모두에서 동작하는 이름 공간 패키지를 제공하기 위해 여전히 사용됩니다. 좀 더 자주 사용되는 코드는 한 줄로 축약한 버전입니다:

__path__ = __import__('pkgutil').extend_path(__path__, __name__)

*name 인자와 일치하는 *.pkg 파일도 찾습니다. 이 기능은 import로 시작하는 줄을 특수하게 다루지 않는다는 점을 제외하면, *.pth 파일과 유사합니다 (자세한 내용은 site 모듈을 참조하십시오). *.pkg 파일을 액면 그대로 신뢰합니다: 중복은 확인하지만, *.pkg 파일에 있는 모든 항목은 파일 시스템에 있는지에 관계없이 경로에 추가됩니다. (이것은 기능입니다.)

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

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

class pkgutil.ImpImporter(dirname=None)

파이썬의 "고전적인" 임포트 알고리즘을 감싸는 PEP 302 파인더.

dirname이 문자열이면, 해당 디렉터리를 검색하는 PEP 302 파인더가 만들어집니다. dirnameNone이면, 현재 sys.path와 프로즌 또는 내장 모듈을 검색하는 PEP 302 파인더가 만들어집니다.

ImpImporter는 현재 sys.meta_path에 넣어서 사용하는 것을 지원하지 않음에 유의하십시오.

버전 3.3부터 폐지: 표준 임포트 메커니즘이 이제 완전히 PEP 302를 준수하고 importlib에서 사용할 수 있으므로, 이 에뮬레이션은 더는 필요하지 않습니다.

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

파이썬의 "고전적인" 임포트 알고리즘을 감싸는 로더.

버전 3.3부터 폐지: 표준 임포트 메커니즘이 이제 완전히 PEP 302를 준수하고 importlib에서 사용할 수 있으므로, 이 에뮬레이션은 더는 필요하지 않습니다.

pkgutil.find_loader(fullname)

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

이것은 importlib.util.find_spec()을 감싸는 하위 호환성 래퍼인데, 대부분의 실패를 ImportError로 변환하고 전체 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를, 또는 pathNone이면, sys.path에 있는 모든 최상위 모듈을 산출(yield)합니다.

pathNone이거나 모듈을 찾을 경로의 리스트이어야 합니다.

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

참고

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

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

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

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

pathNone이거나 모듈을 찾을 경로의 리스트이어야 합니다.

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

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

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

예제:

# 파이썬이 액세스할 수 있는 모든 모듈을 나열합니다
walk_packages()

# ctypes의 모든 서브 모듈을 나열합니다
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

참고

iter_modules() 메서드를 정의하는 파인더에서만 작동합니다. 이 인터페이스는 비표준이므로, 모듈은 importlib.machinery.FileFinderzipimport.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에 추가.