pkgutil — 패키지 확장 유틸리티

소스 코드: Lib/pkgutil.py

이 모듈은 import 시스템, 특히 패키지 지원을 위한 유틸리티를 제공해요.

출처: Python 표준 라이브러리

본문

class pkgutil.ModuleInfo(module_finder, name, ispkg)

모듈에 대한 간단한 요약을 담는 namedtuple이에요.

버전 3.6에 추가.

pkgutil.extend_path(path, name)

패키지를 구성하는 모듈의 검색 경로를 확장해요. 의도된 사용법은 패키지의 __init__.py에 다음 코드를 넣는 거예요:

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

sys.path의 각 디렉터리에서 패키지 이름과 일치하는 하위 디렉터리가 있으면, 그 하위 디렉터리를 패키지의 __path__에 추가해요. 이는 하나의 논리적 패키지의 서로 다른 부분을 여러 디렉터리로 배포하려 할 때 유용해요.

또한 *가 name 인자와 일치하는 *.pkg 파일을 찾아요. 이 기능은 *.pth 파일(site 모듈 참고)과 비슷하지만, import로 시작하는 줄을 특별 취급하지 않아요. *.pkg 파일은 그대로 신뢰해요. 빈 줄을 건너뛰고 주석을 무시하는 것 외에는 *.pkg 파일에서 찾은 모든 항목이 파일 시스템에 존재하는지 여부와 무관하게 경로에 추가돼요(이것이 기능이에요).

입력 경로가 리스트가 아니면(동결된(frozen) 패키지의 경우처럼) 변경 없이 반환돼요. 입력 경로는 수정되지 않아요. 확장된 복사본이 반환돼요. 항목은 복사본 끝에만 추가돼요.

sys.path가 시퀀스라고 가정해요. 기존 디렉터리를 가리키지 않는 문자열이 아닌 sys.path 항목은 무시돼요. 파일 이름으로 사용할 때 오류를 일으키는 sys.path의 유니코드 항목은 이 함수가 예외를 발생시키게 할 수 있어요(os.path.isdir() 동작과 일치).

pkgutil.get_importer(path_item)

주어진 path_item에 대한 finder를 검색해요.

반환된 finder가 경로 훅에 의해 새로 생성된 것이면 sys.path_importer_cache에 캐시돼요. sys.path_hooks를 다시 스캔해야 하면 캐시(또는 그 일부)를 수동으로 지울 수 있어요.

버전 3.3에서 변경: 패키지 내부의 PEP 302 import 에뮬레이션에 의존하는 대신 importlib에 직접 기반하도록 업데이트됨.

pkgutil.iter_importers(fullname='')

주어진 모듈 이름에 대한 finder 객체를 생성해내요.

fullname이 '.'을 포함하면 finder는 fullname을 담은 패키지에 대한 것이고, 그렇지 않으면 등록된 모든 최상위 finder(sys.meta_path와 sys.path_hooks 양쪽에 있는 것)가 돼요.

이름이 붙은 모듈이 패키지 안에 있으면 이 함수를 호출하는 부작용으로 그 패키지가 임포트돼요. 모듈 이름이 지정되지 않으면 모든 최상위 finder가 생성돼요.

버전 3.3에서 변경: importlib에 직접 기반하도록 업데이트됨.

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

path의 모든 하위 모듈에 대한 ModuleInfo를 생성해내거나, path가 None이면 sys.path의 모든 최상위 모듈에 대한 ModuleInfo를 생성해내요.

path는 None이거나 모듈을 찾을 경로의 리스트여야 해요. prefix는 출력 시 모든 모듈 이름 앞에 붙는 문자열이에요.

버전 3.3에서 변경: importlib에 직접 기반하도록 업데이트됨.

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

path의 모든 모듈에 대한 ModuleInfo를 재귀적으로 생성해내거나, path가 None이면 접근 가능한 모든 모듈에 대한 ModuleInfo를 생성해내요.

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__ + '.')

버전 3.3에서 변경: importlib에 직접 기반하도록 업데이트됨.

pkgutil.get_data(package, resource)

패키지에서 리소스를 가져와요.

이것은 loader get_data API의 wrapper예요. package 인자는 표준 모듈 형식(foo.bar)의 패키지 이름이어야 해요. resource 인자는 /를 경로 구분자로 사용하는 상대 파일 이름 형식이어야 해요.

함수는 지정된 리소스의 내용인 이진 문자열을 돌려줘요.

이 함수는 loader 메서드 get_data()를 사용해 파일 시스템에 설치된 모듈은 물론, zip 파일, 데이터베이스, 그 밖의 곳에 설치된 모듈도 지원해요.

파일 시스템에 있고 이미 임포트된 패키지의 경우, 이것은 대략 다음과 같아요:

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

open() 함수처럼 get_data()는 상위 디렉터리(../)와 절대 경로(예: / 또는 C:/로 시작)를 따라갈 수 있어요. .py와 .pyc 파일이나 예약된 파일 이름을 가진 파일 같은 컴파일/설치 산출물도 열 수 있어요. 비파일 시스템 loader와 호환되려면 이러한 기능 사용을 피하세요.

경고 — 이 함수는 신뢰할 수 있는 입력을 위한 것입니다. resource가 package에 "속하는지"는 검증하지 않아요. 사용자 제공 resource 경로를 사용한다면 검증을 고려하세요. 예를 들어 알려진 확장자를 가진 영숫자 파일 이름을 요구하거나, 알려진 리소스 목록을 설치·확인하세요.

패키지를 찾거나 로드할 수 없거나, loader가 get_data를 지원하지 않으면 None이 반환돼요. 특히 네임스페이스 패키지용 loader는 get_data를 지원하지 않아요.

더 알아보기

importlib.resources 모듈 — 모듈 리소스에 대한 구조화된 접근을 제공.