Python

importlib.resources – 패키지 리소스 읽기, 열기 및 접근

소스 코드: Lib/importlib/resources/__init__.py

Added in version 3.7.

이 모듈은 파이썬의 임포트 시스템을 활용하여 패키지 내에 있는 리소스 에 대한 접근을 제공합니다.

“리소스”는 파이썬에서 모듈 또는 패키지와 관련된 파일 형태의 리소스입니다. 리소스는 패키지에 직접 포함되거나, 해당 패키지 내의 하위 디렉터리에 포함되거나, 패키지 외부에 있는 모듈 옆에 위치할 수 있습니다. 리소스는 텍스트 또는 바이너리일 수 있습니다. 결과적으로, 패키지의 파이썬 모듈 소스(.py), 컴파일 아티팩트(pycache), 및 설치 아티팩트(디렉터리 내의 예약된 파일명 등)는 기술적으로 해당 패키지의 사실상 리소스입니다. 그러나 실제로는, 리소스는 주로 패키지 제작자가 의도적으로 노출한 파이썬 이외의 아티팩트를 의미합니다.

리소스는 바이너리 또는 텍스트 모드로 열거나 읽을 수 있습니다.

리소스는 디렉터리 내의 파일과 유사하지만, 이것은 단지 비유라는 점을 유념해야 합니다. 리소스와 패키지는 파일 시스템에 물리적 파일 및 디렉터리로 존재할 필요가 없습니다. 예를 들어, 패키지와 그 리소스는 zipimport 를 사용하여 zip 파일에서 불러올 수 있습니다.

경고

importlib.resources 는 내장된 open() 함수와 동일한 보안 모델을 따릅니다. 이 모듈의 함수에 신뢰할 수 없는 입력을 전달하는 것은 안전하지 않습니다.

참고

이 모듈의 독립형 역 이식 버전은 importlib.resources 사용 및 pkg_resources에서 importlib.resources로 마이그레이션 에 대한 자세한 정보를 제공합니다.

리소스 읽기를 지원하려는 Loaders 는 importlib.resources.abc.ResourceReader 에 정의된 대로 get_resource_reader(fullname) 메서드를 구현해야 합니다.

class importlib.resources.Anchor

리소스의 앵커를 나타내며, 모듈 객체 또는 문자열 형태의 모듈 이름이 될 수 있습니다. Union[str, ModuleType] 으로 정의됩니다.

importlib.resources.files(anchor: Anchor | None = None)

리소스 컨테이너(디렉터리 형태)와 그 리소스(파일 형태)를 나타내는 Traversable 객체를 반환합니다. Traversable은 다른 컨테이너(서브 디렉터리 형태)를 포함할 수 있습니다.

anchor 는 선택적인 Anchor 입니다. 앵커가 패키지인 경우 리소스는 해당 패키지에서 확인됩니다. 모듈인 경우 리소스는 해당 모듈과 인접한 곳(동일한 패키지 또는 패키지 루트)에서 확인됩니다. 앵커가 생략된 경우 호출자의 모듈이 사용됩니다.

Added in version 3.9.

버전 3.12에서 변경: package 매개변수가 anchor 로 이름이 변경되었습니다. package 는 여전히 허용되지만, 더 이상 권장되지 않습니다(deprecated).

버전 3.15에서 변경: package 매개변수가 완전히 제거되었습니다. 이제 anchor 는 패키지가 아닌 모듈일 수 있으며, 생략할 경우 호출자의 모듈을 기본값으로 사용합니다. Python 3.15부터는 package 가 더 이상 허용되지 않습니다. 이전 버전의 파이썬에서 호환되는 인터페이스를 사용하려면 anchor를 위치 인수로 전달하거나 importlib_resources >= 5.10 을 사용하십시오.

importlib.resources.as_file(traversable)

일반적으로 importlib.resources.files() 에서 제공되는 파일 또는 디렉터리를 나타내는 importlib.resources.abc.Traversable 객체가 주어지면, with 문에서 사용할 컨텍스트 관리자를 반환합니다. 이 컨텍스트 관리자는 pathlib.Path 객체를 제공합니다.

컨텍스트 관리자를 종료하면 예를 들어 zip 파일에서 리소스를 추출할 때 생성된 임시 파일이나 디렉터리가 정리됩니다.

Traversable 메서드(read_text 등)만으로 충분하지 않고 파일 시스템에 있는 실제 파일이나 디렉터리가 필요한 경우 as_file 을 사용하십시오.

Added in version 3.9.

버전 3.12에서 변경: 디렉터리를 나타내는 traversable 에 대한 지원이 추가되었습니다.

기능형 API

간소화되고 하위 호환성이 유지되는 도우미 함수 세트가 제공됩니다. 이를 통해 단일 함수 호출로 일반적인 작업을 수행할 수 있습니다.

다음 모든 함수에 대하여:

  • anchor 는 files() 와 마찬가지로 Anchor 입니다. files 와 달리 생략할 수 없습니다.

  • path_names 는 anchor를 기준으로 한 리소스 경로의 구성 요소입니다. 예를 들어, 이름이 info.txt 인 리소스의 텍스트를 가져오려면 다음과 같이 사용합니다:

    importlib.resources.read_text(my_module, "info.txt")

    Traversable.joinpath 와 마찬가지로, 각 구성 요소는 경로 구분자로 슬래시(/)를 사용해야 합니다. 예를 들어, 다음은 동등합니다:

    importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")

    하위 호환성을 위해 여러 개의 path_names 가 주어지는 경우 텍스트를 읽는 함수는 명시적인 encoding 인수를 필요로 합니다. 예를 들어, info/chapter1.txt 의 텍스트를 가져오려면 다음과 같이 사용합니다:

    importlib.resources.read_text(my_module, "info", "chapter1.txt",
                              encoding='utf-8')
importlib.resources.open_binary(anchor, *path_names)

이름이 지정된 리소스를 바이너리 읽기용으로 엽니다.

anchor 와 path_names 에 대한 자세한 내용은 the introduction 를 참조하십시오.

이 함수는 읽기용으로 열린 바이너리 스트림인 BinaryIO 객체를 반환합니다.

이 함수는 대략 다음과 동등합니다:

files(anchor).joinpath(*path_names).open('rb')

버전 3.13에서 변경: 여러 개의 path_names 가 허용됩니다.

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

이름이 지정된 리소스를 텍스트 읽기용으로 엽니다. 기본적으로 내용은 엄격한(strict) UTF-8로 읽힙니다.

anchor 와 path_names 에 대한 자세한 내용은 the introduction 를 참조하십시오. encoding 과 errors 는 내장된 open() 과 동일한 의미를 가집니다.

하위 호환성을 위해 여러 개의 path_names*가 있는 경우 *encoding 인자를 명시적으로 제공해야 합니다. 이 제한은 Python 3.15에서 제거될 예정입니다.

이 함수는 읽기용으로 열린 텍스트 스트림인 TextIO 객체를 반환합니다.

이 함수는 대략 다음과 동등합니다:

files(anchor).joinpath(*path_names).open('r', encoding=encoding)

버전 3.13에서 변경: 여러 개의 path_names 가 허용됩니다. encoding 과 errors 는 키워드 인자로 제공되어야 합니다.

importlib.resources.read_binary(anchor, *path_names)

이름이 지정된 리소스의 내용을 읽어 bytes 로 반환합니다.

anchor 와 path_names 에 대한 자세한 내용은 the introduction 를 참조하십시오.

이 함수는 대략 다음과 동등합니다:

files(anchor).joinpath(*path_names).read_bytes()

버전 3.13에서 변경: 여러 개의 path_names 가 허용됩니다.

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

이름이 지정된 리소스의 내용을 읽어 str 로 반환합니다. 기본적으로 내용은 엄격한(strict) UTF-8로 읽힙니다.

anchor 와 path_names 에 대한 자세한 내용은 the introduction 를 참조하십시오. encoding 과 errors 는 내장된 open() 과 동일한 의미를 가집니다.

하위 호환성을 위해 여러 개의 path_names*가 있는 경우 *encoding 인자를 명시적으로 제공해야 합니다. 이 제한은 Python 3.15에서 제거될 예정입니다.

이 함수는 대략 다음과 동등합니다:

files(anchor).joinpath(*path_names).read_text(encoding=encoding)

버전 3.13에서 변경: 여러 개의 path_names 가 허용됩니다. encoding 과 errors 는 키워드 인자로 제공되어야 합니다.

importlib.resources.path(anchor, *path_names)

resource 에 대한 경로를 실제 파일 시스템 경로로 제공합니다. 이 함수는 with 문에서 사용하기 위한 컨텍스트 관리자를 반환하며, 해당 컨텍스트 관리자는 pathlib.Path 객체를 제공합니다.

컨텍스트 관리자를 종료하면 예를 들어 리소스를 zip 파일에서 추출해야 할 때 생성된 임시 파일이 정리됩니다.

예를 들어, stat() 메서드는 실제 파일 시스템 경로를 필요로 하며, 다음과 같이 사용할 수 있습니다:

with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()

anchor 와 path_names 에 대한 자세한 내용은 the introduction 를 참조하십시오.

이 함수는 대략 다음과 동등합니다:

as_file(files(anchor).joinpath(*path_names))

버전 3.13에서 변경: 여러 개의 path_names 가 허용됩니다.

importlib.resources.is_resource(anchor, *path_names)

이름이 지정된 리소스가 존재하면 True 를, 그렇지 않으면 False 를 반환합니다. 이 함수는 디렉터리를 리소스로 간주하지 않습니다.

anchor 와 path_names 에 대한 자세한 내용은 the introduction 를 참조하십시오.

이 함수는 대략 다음과 동등합니다:

files(anchor).joinpath(*path_names).is_file()

버전 3.13에서 변경: 여러 개의 path_names 가 허용됩니다.

importlib.resources.contents(anchor, *path_names)

패키지 또는 경로 내에 이름이 있는 항목들에 대한 이터러블을 반환합니다. 이터러블은 리소스(예: 파일)와 리소스가 아닌 것(예: 디렉터리)의 이름을 str 로 반환하며, 서브 디렉터리로 재항하지 않습니다.

anchor 와 path_names 에 대한 자세한 내용은 the introduction 를 참조하십시오.

이 함수는 대략 다음과 동등합니다:

for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name

버전 3.11부터 폐지됨: 결과에 대한 더 많은 제어와 풍부한 기능을 제공하는 위에서 언급한 iterdir() 를 사용하는 것을 권장합니다.