5. import 시스템

5. import 시스템 (The import system)

한 모듈의 Python 코드는 import 과정을 통해 다른 모듈의 코드에 접근할 수 있어요. import 문이 import 메커니즘을 호출하는 가장 흔한 방법이지만, 유일한 방법은 아니에요. importlib.import_module() 같은 함수와 내장 __import__()도 import 메커니즘을 호출하는 데 사용될 수 있어요.

출처: 5. The import system

본문

import 문은 두 가지 연산을 결합해요. 이름이 지정된 모듈을 검색하고, 그 검색 결과를 지역 스코프의 이름에 바인딩해요. import 문의 검색 연산은 적절한 인자로 __import__() 함수를 호출하는 것으로 정의돼요. __import__()의 반환 값은 import 문의 이름 바인딩 연산을 수행하는 데 사용돼요. 그 이름 바인딩 연산의 정확한 세부 사항은 import 문을 참고하세요.

__import__()를 직접 호출하면 모듈 검색만 수행하고, 찾으면 모듈 생성 연산을 수행해요. 부모 패키지 import와 다양한 캐시( sys.modules 포함) 갱신 같은 특정 부수 효과가 발생할 수 있지만, 이름 바인딩 연산을 수행하는 것은 import 문뿐이에요.

import 문이 실행되면 표준 내장 __import__() 함수가 호출돼요. import 시스템을 호출하는 다른 메커니즘(예: importlib.import_module())은 __import__()를 거치지 않고 import 의미론을 구현하기 위해 자신만의 해법을 선택할 수 있어요.

모듈이 처음 import될 때, Python은 모듈을 검색하고 찾으면 모듈 객체 [1]를 만들어 초기화해요. 이름이 지정된 모듈을 찾을 수 없으면 ModuleNotFoundError가 발생해요. Python은 import 메커니즘이 호출될 때 이름이 지정된 모듈을 검색하기 위해 다양한 전략을 구현해요. 이 전략들은 아래 섹션에서 설명하는 다양한 훅(hook)을 사용해 수정하고 확장할 수 있어요.

버전 3.3에서 변경: import 시스템이 PEP 302의 두 번째 단계를 완전히 구현하도록 업데이트되었어요. 더 이상 암시적 import 메커니즘은 없어요 - 전체 import 시스템이 sys.meta_path를 통해 노출돼요. 또한 네이티브 네임스페이스 패키지 지원이 구현되었어요 (PEP 420 참조).

5.1. importlib

importlib 모듈은 import 시스템과 상호작용하기 위한 풍부한 API를 제공해요. 예를 들어 importlib.import_module()은 import 메커니즘을 호출하기 위한 내장 __import__()보다 권장되는 더 단순한 API를 제공해요. 추가 세부 사항은 importlib 라이브러리 문서를 참고하세요.

5.2. 패키지 (Packages)

Python에는 단 한 가지 타입의 모듈 객체가 있고, 모듈이 Python, C, 또는 다른 것으로 구현되었는지와 관계없이 모든 모듈이 이 타입이에요. 모듈을 구성하고 명명 계층을 제공하기 위해 Python에는 패키지라는 개념이 있어요.

패키지를 파일 시스템의 디렉토리로, 모듈을 디렉토리 안의 파일로 생각할 수 있어요. 하지만 패키지와 모듈이 파일 시스템에서 유래할 필요는 없으므로 이 비유를 지나치게 문자 그대로 받아들이지는 마세요. 이 문서의 목적을 위해 우리는 이 편리한 디렉토리-파일 비유를 사용할 거예요. 파일 시스템 디렉토리처럼 패키지는 계층적으로 구성되고, 패키지는 일반 모듈뿐만 아니라 하위 패키지도 포함할 수 있어요.

모든 패키지는 모듈이지만 모든 모듈이 패키지는 아니라는 점을 명심하는 게 중요해요. 달리 말하면 패키지는 특별한 종류의 모듈일 뿐이에요. 구체적으로, __path__ 속성을 포함하는 모든 모듈은 패키지로 간주돼요.

모든 모듈에는 이름이 있어요. 하위 패키지 이름은 Python의 표준 속성 접근 문법과 유사하게 점(dot)으로 부모 패키지 이름과 구분돼요. 따라서 email이라는 패키지가 있고, 그 안에 email.mime이라는 하위 패키지, 그리고 그 하위 패키지 안에 email.mime.text라는 모듈이 있을 수 있어요.

5.2.1. 일반 패키지 (Regular packages)

Python은 일반 패키지와 네임스페이스 패키지, 두 가지 타입의 패키지를 정의해요. 일반 패키지는 Python 3.2 및 그 이전에 존재했던 전통적인 패키지예요. 일반 패키지는 보통 __init__.py 파일을 포함하는 디렉토리로 구현돼요. 일반 패키지가 import되면 이 __init__.py 파일이 암시적으로 실행되고, 그 파일이 정의하는 객체들이 패키지의 네임스페이스에 있는 이름에 바인딩돼요. __init__.py 파일은 다른 모듈이 포함할 수 있는 것과 동일한 Python 코드를 포함할 수 있고, Python은 import될 때 모듈에 몇 가지 추가 속성을 더할 거예요.

예를 들어 다음 파일 시스템 구조는 세 개의 하위 패키지를 가진 최상위 parent 패키지를 정의해요:

parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py

parent.one을 import하면 parent/__init__.py와 parent/one/__init__.py가 암시적으로 실행돼요. 이후의 parent.two 또는 parent.three import는 각각 parent/two/__init__.py와 parent/three/__init__.py를 실행해요.

일반 패키지 안에서 __init__.py 파일을 포함하지 않는 하위 디렉토리는 그 부모에 뿌리를 둔 암시적 네임스페이스 패키지(a "namespace subpackage")로 취급돼요. 근거가 되는 명세는 PEP 420을 참고하세요.

5.2.2. 네임스페이스 패키지 (Namespace packages)

네임스페이스 패키지는 다양한 부분(portion)의 복합체이며, 각 부분은 부모 패키지에 하위 패키지를 기여해요. 부분들은 파일 시스템의 서로 다른 위치에 있을 수 있어요. 부분들은 zip 파일, 네트워크, 또는 Python이 import 중에 검색하는 다른 어디에든 있을 수 있어요. 네임스페이스 패키지는 파일 시스템의 객체와 직접 일치할 수도 있고 그렇지 않을 수도 있어요. 구체적인 표현이 없는 가상 모듈일 수도 있어요.

네임스페이스 패키지는 __path__ 속성에 일반 리스트를 사용하지 않아요. 대신 사용자 정의 반복 가능(iterable) 타입을 사용하는데, 이 타입은 부모 패키지의 경로(최상위 패키지의 경우 sys.path)가 변경되면 다음 import 시도에서 패키지 부분을 새로 검색할 거예요.

네임스페이스 패키지에는 parent/__init__.py 파일이 없어요. 사실 import 검색 중에 여러 parent 디렉토리가 발견될 수 있고, 각 디렉토리는 서로 다른 부분이 제공해요. 따라서 parent/one이 parent/two와 물리적으로 나란히 있지 않을 수 있어요. 이 경우 Python은 최상위 parent 패키지나 그 하위 패키지 중 하나가 import될 때마다 최상위 parent 패키지용 네임스페이스 패키지를 만들 거예요.

네임스페이스 패키지는 일반 패키지 안에 중첩될 수도 있어요. import 시스템이 일반 패키지의 __path__를 검색할 때 __init__.py 파일을 포함하지 않는 하위 디렉토리를 만나면, 그 하위 디렉토리는 바깥 일반 패키지의 네임스페이스 하위 패키지에 기여하는 부분이 돼요.

네임스페이스 패키지 명세도 PEP 420을 참고하세요.

5.3. 검색 (Searching)

검색을 시작하려면 Python은 import되는 모듈(또는 패키지, 하지만 이 논의의 목적상 그 차이는 무의미해요)의 완전히 정규화된 이름이 필요해요. 이 이름은 import 문의 다양한 인자나 importlib.import_module() 또는 __import__() 함수의 매개변수에서 나올 수 있어요.

이 이름은 import 검색의 다양한 단계에서 사용되며, foo.bar.baz 같은 하위 모듈의 점으로 구분된 경로일 수도 있어요. 이 경우 Python은 먼저 foo를 import하려 하고, 다음 foo.bar, 마지막으로 foo.bar.baz를 import해요. 중간 import 중 하나라도 실패하면 ModuleNotFoundError가 발생해요.

5.3.1. 모듈 캐시 (The module cache)

import 검색 중 가장 먼저 확인하는 곳은 sys.modules예요. 이 매핑은 중간 경로를 포함해 이전에 import된 모든 모듈의 캐시 역할을 해요. 그래서 foo.bar.baz가 이전에 import되었다면, sys.modules에는 foo, foo.bar, foo.bar.baz에 대한 항목이 있을 거예요. 각 키는 해당 모듈 객체를 값으로 가져요.

import 중에 모듈 이름이 sys.modules에서 조회되고, 있으면 관련 값이 import를 충족시키는 모듈이고 그 과정이 완료돼요. 그러나 값이 None이면 ModuleNotFoundError가 발생해요. 모듈 이름이 없으면 Python은 모듈 검색을 계속해요.

sys.modules는 쓰기 가능해요. 키를 삭제해도 관련 모듈이 파괴되지 않을 수 있어요 (다른 모듈이 그것에 대한 참조를 보유할 수 있으므로), 하지만 이름이 지정된 모듈의 캐시 항목을 무효화해서, Python이 다음 import에서 그 모듈을 새로 검색하게 해요. 키에 None을 할당할 수도 있는데, 그러면 다음 import가 ModuleNotFoundError를 발생시키게 해요.

하지만 주의하세요. 모듈 객체에 참조를 유지한 채 sys.modules의 캐시 항목을 무효화하고 이름이 지정된 모듈을 다시 import하면, 두 모듈 객체는 동일하지 않을 거예요. 대조적으로 importlib.reload()는 같은 모듈 객체를 재사용하고, 모듈의 코드를 다시 실행하여 모듈 내용을 다시 초기화할 뿐이에요.

5.3.2. 파인더와 로더 (Finders and loaders)

이름이 지정된 모듈이 sys.modules에서 발견되지 않으면, Python의 import 프로토콜이 호출되어 모듈을 찾고 로드해요. 이 프로토콜은 파인더(finder)와 로더(loader)라는 두 개의 개념적 객체로 구성돼요. 파인더의 임무는 자신이 알고 있는 전략을 사용해 이름이 지정된 모듈을 찾을 수 있는지 여부를 결정하는 것이에요. 두 인터페이스를 모두 구현하는 객체를 importer라고 해요. 요청된 모듈을 로드할 수 있다고 판단하면 자신을 반환해요.

Python에는 여러 기본 파인더와 importer가 포함돼 있어요. 첫 번째는 내장 모듈을 찾는 방법을 알고, 두 번째는 프리즈된(frozen) 모듈을 찾는 방법을 알아요. 세 번째 기본 파인더는 import 경로에서 모듈을 검색해요. import 경로는 파일 시스템 경로나 zip 파일을 가리킬 수 있는 위치들의 목록이에요. URL로 식별되는 자원 같은 검색 가능한 어떤 자원을 검색하도록 확장될 수도 있어요.

import 메커니즘은 확장 가능하므로, 모듈 검색의 범위와 영역을 확장하기 위해 새 파인더를 추가할 수 있어요.

파인더는 실제로 모듈을 로드하지는 않아요. 이름이 지정된 모듈을 찾을 수 있으면 *모듈 스펙(module spec)*을 반환해요. 모듈 스펙은 모듈의 import 관련 정보를 캡슐화한 것이고, import 메커니즘이 모듈을 로드할 때 사용해요.

다음 섹션들은 파인더와 로더의 프로토콜을 더 자세히 설명하며, 새 것을 만들고 등록하여 import 메커니즘을 확장하는 방법도 다뤄요.

버전 3.4에서 변경: 이전 Python 버전에서 파인더는 로더를 직접 반환했지만, 이제는 로더를 포함하는 모듈 스펙을 반환해요. 로더는 여전히 import 중에 사용되지만 책임은 더 적어요.

5.3.3. Import 훅 (Import hooks)

import 메커니즘은 확장 가능하도록 설계되었고, 이를 위한 기본 메커니즘은 import 훅이에요. import 훅에는 *메타 훅(meta hook)*과 *import 경로 훅(import path hook)*이라는 두 가지 타입이 있어요.

메타 훅은 sys.modules 캐시 조회 외에 다른 import 처리가 발생하기 전에, import 처리의 시작 시점에 호출돼요. 이는 메타 훅이 sys.path 처리, 프리즈된 모듈, 심지어 내장 모듈까지 재정의할 수 있게 해줘요. 메타 훅은 아래에 설명하는 대로 sys.meta_path에 새 파인더 객체를 추가함으로써 등록돼요.

import 경로 훅은 sys.path(또는 package.__path__) 처리의 일부로, 관련 경로 항목을 만나는 시점에 호출돼요. import 경로 훅은 아래에 설명하는 대로 sys.path_hooks에 새 callable을 추가함으로써 등록돼요.

5.3.4. 메타 경로 (The meta path)

이름이 지정된 모듈이 sys.modules에서 발견되지 않으면, Python은 다음으로 메타 경로 파인더 객체들의 목록을 포함하는 sys.meta_path를 검색해요. 이 파인더들은 이름이 지정된 모듈을 다루는 방법을 아는지 보기 위해 순서대로 질의돼요. 메타 경로 파인더는 find_spec()이라는 메서드를 구현해야 하는데, 이 메서드는 세 가지 인자를 받아요: 이름, import 경로, (선택적으로) 대상 모듈. 메타 경로 파인더는 이름이 지정된 모듈을 다룰 수 있는지 여부를 결정하기 위해 어떤 전략이든 사용할 수 있어요.

메타 경로 파인더가 이름이 지정된 모듈을 다루는 방법을 알면 스펙 객체를 반환해요. 다룰 수 없으면 None을 반환해요. sys.meta_path 처리가 스펙을 반환하지 않고 목록 끝에 도달하면 ModuleNotFoundError가 발생해요. 발생한 다른 예외는 그대로 전파되며 import 과정을 중단해요.

메타 경로 파인더의 find_spec() 메서드는 두 개 또는 세 개의 인자로 호출돼요. 첫 번째는 import되는 모듈의 완전히 정규화된 이름, 예를 들어 foo.bar.baz예요. 두 번째 인자는 모듈 검색에 사용할 경로 항목들이에요. 최상위 모듈의 경우 두 번째 인자는 None이지만, 하위 모듈이나 하위 패키지의 경우 두 번째 인자는 부모 패키지의 __path__ 속성 값이에요. 적절한 __path__ 속성에 접근할 수 없으면 ModuleNotFoundError가 발생해요. 세 번째 인자는 나중에 로드의 대상이 될 기존 모듈 객체예요. import 시스템은 리로드 중에만 대상 모듈을 전달해요.

메타 경로는 단일 import 요청에 대해 여러 번 순회될 수 있어요. 예를 들어 관련 모듈 중 아무것도 아직 캐시되지 않았다고 가정하면, foo.bar.baz를 import하면 먼저 각 메타 경로 파인더(mpf)에 대해 mpf.find_spec("foo", None, None)을 호출하는 최상위 import를 수행해요. foo가 import된 후에는 두 번째로 메타 경로를 순회해 mpf.find_spec("foo.bar", foo.__path__, None)을 호출함으로써 foo.bar가 import돼요. foo.bar가 import되면 마지막 순회가 mpf.find_spec("foo.bar.baz", foo.bar.__path__, None)을 호출해요.

일부 메타 경로 파인더는 최상위 import만 지원해요. 이런 importer는 두 번째 인자로 None이 아닌 것이 전달되면 항상 None을 반환해요.

Python의 기본 sys.meta_path에는 세 개의 메타 경로 파인더가 있어요. 하나는 내장 모듈을 import하는 방법을 알고, 하나는 프리즈된 모듈을 import하는 방법을 알며, 하나는 import 경로(즉, 경로 기반 파인더)에서 모듈을 import하는 방법을 알아요.

버전 3.4에서 변경: 메타 경로 파인더의 find_spec() 메서드가 이제 비추천(deprecated)된 find_module()을 대체했어요. 계속 변경 없이 동작하지만, import 메커니즘은 파인더가 find_spec()을 구현하지 않는 경우에만 그것을 시도할 거예요.

버전 3.10에서 변경: import 시스템이 find_module()을 사용하면 이제 ImportWarning이 발생해요.

버전 3.12에서 변경: find_module()이 제거되었어요. 대신 find_spec()을 사용하세요.

5.4. 로드 (Loading)

모듈 스펙이 발견되면, import 메커니즘은 모듈을 로드할 때 그것(과 그것이 포함한 로더)을 사용해요. 다음은 import의 로드 부분에서 일어나는 일의 근사치예요:

module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
    # It is assumed 'exec_module' will also be defined on the loader.
    module = spec.loader.create_module(spec)
if module is None:
    module = ModuleType(spec.name)
# The import-related module attributes get set here:
_init_module_attrs(spec, module)

if spec.loader is None:
    # unsupported
    raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
    # namespace package
    sys.modules[spec.name] = module
elif not hasattr(spec.loader, 'exec_module'):
    module = spec.loader.load_module(spec.name)
else:
    sys.modules[spec.name] = module
    try:
        spec.loader.exec_module(module)
    except BaseException:
        try:
            del sys.modules[spec.name]
        except KeyError:
            pass
        raise
return sys.modules[spec.name]

다음 세부 사항에 주의하세요:

주어진 이름의 기존 모듈 객체가 sys.modules에 있으면, import는 이미 그것을 반환했을 거예요.
모듈은 로더가 모듈 코드를 실행하기 전에 sys.modules에 존재할 거예요. 이것은 중요해요. 모듈 코드가 (직접 또는 간접적으로) 자신을 import할 수 있기 때문이에요. 미리 sys.modules에 추가하면 최악의 경우 무한 재귀와 최상의 경우 중복 로드를 방지해요.
로드가 실패하면, 실패한 모듈 - 실패한 모듈만 - 이 sys.modules에서 제거돼요. 이미 sys.modules 캐시에 있는 어떤 모듈과 부수 효과로 성공적으로 로드된 어떤 모듈은 캐시에 남아야 해요. 이는 리로드할 때와 대조되는데, 리로드에서는 실패한 모듈조차 sys.modules에 남겨져요.
모듈이 생성된 후 실행되기 전에, import 메커니즘은 (위 의사 코드 예의 "_init_module_attrs"처럼) import 관련 모듈 속성을 설정해요. 이 내용은 나중 섹션에서 요약해요.
모듈 실행은 모듈의 네임스페이스가 채워지는 로드의 핵심 순간이에요. 실행은 전적으로 로더에게 위임되고, 로더가 무엇을 어떻게 채울지 결정해요.
로드 중에 생성되어 exec_module()에 전달된 모듈이 import 끝에 반환되는 모듈이 아닐 수 있어요 [2].

버전 3.4에서 변경: import 시스템이 로더의 보일러플레이트(boilerplate) 책임을 인수했어요. 이들은 이전에 importlib.abc.Loader.load_module() 메서드가 수행했어요.

5.4.1. 로더 (Loaders)

모듈 로더는 로드의 중요한 기능, 즉 모듈 실행을 제공해요. import 메커니즘은 단일 인자, 즉 실행할 모듈 객체로 importlib.abc.Loader.exec_module() 메서드를 호출해요. exec_module()에서 반환되는 어떤 값도 무시돼요.

로더는 다음 요구 사항을 충족해야 해요:

모듈이 Python 모듈(내장 모듈이나 동적으로 로드된 확장과 대조되는)이면, 로더는 모듈의 코드를 모듈의 전역 네임스페이스(module.__dict__)에서 실행해야 해요.
로더가 모듈을 실행할 수 없으면 ImportError를 발생시켜야 하지만, exec_module() 중에 발생한 다른 예외는 전파될 거예요.

많은 경우 파인더와 로더는 같은 객체일 수 있어요. 그러한 경우 find_spec() 메서드는 로더가 self로 설정된 스펙을 반환하기만 하면 돼요.

모듈 로더는 create_module() 메서드를 구현해 로드 중에 모듈 객체를 만드는 것을 선택할 수 있어요. 그것은 하나의 인자, 모듈 스펙을 받고 로드 중에 사용할 새 모듈 객체를 반환해요. create_module()은 모듈 객체에 어떤 속성도 설정할 필요가 없어요. 이 메서드가 None을 반환하면, import 메커니즘이 새 모듈을 직접 만들 거예요.

버전 3.4에서 추가: 로더의 create_module() 메서드.

버전 3.4에서 변경: load_module() 메서드가 exec_module()과, import 메커니즘이 로드의 모든 보일러플레이트 책임을 인수한 것으로 대체되었어요.

기존 로더와의 호환성을 위해, import 메커니즘은 로더에 load_module() 메서드가 존재하고 exec_module()을 구현하지도 않으면 그것을 사용할 거예요. 그러나 load_module()은 비추천되었고 로더는 대신 exec_module()을 구현해야 해요.

load_module() 메서드는 모듈을 실행하는 것 외에 위에서 설명한 모든 보일러플레이트 로딩 기능을 구현해야 해요. 모든 동일한 제약이 적용되며, 몇 가지 추가 설명이 있어요:

주어진 이름의 기존 모듈 객체가 sys.modules에 있으면, 로더는 그 기존 모듈을 사용해야 해요. (그렇지 않으면 importlib.reload()가 올바르게 작동하지 않을 거예요.) 이름이 지정된 모듈이 sys.modules에 없으면, 로더는 새 모듈 객체를 만들고 sys.modules에 추가해야 해요.
무한 재귀나 중복 로드를 방지하기 위해, 로더가 모듈 코드를 실행하기 전에 모듈이 sys.modules에 존재 해야 해요.
로드가 실패하면, 로더는 sys.modules에 삽입한 모든 모듈을 제거해야 하지만, 오직 실패한 모듈만, 그리고 로더 자신이 명시적으로 모듈을 로드한 경우에만 제거해야 해요.

버전 3.5에서 변경: exec_module()이 정의되었지만 create_module()이 정의되지 않았을 때 DeprecationWarning이 발생해요.

버전 3.6에서 변경: exec_module()이 정의되었지만 create_module()이 정의되지 않았을 때 ImportError가 발생해요.

버전 3.10에서 변경: load_module()을 사용하면 ImportWarning이 발생해요.

5.4.2. 하위 모듈 (Submodules)

하위 모듈이 어떤 메커니즘으로든(예: importlib API, import 또는 import-from 문, 내장 __import__()) 로드되면, 부모 모듈의 네임스페이스에 하위 모듈 객체에 대한 바인딩이 배치돼요. 예를 들어 패키지 spam에 하위 모듈 foo가 있으면, spam.foo를 import한 후 spam에는 하위 모듈에 바인딩된 foo 속성이 있을 거예요. 다음과 같은 디렉토리 구조가 있다고 가정해 보세요:

spam/
    __init__.py
    foo.py

그리고 spam/__init__.py에 다음 줄이 있다고 해요:

from .foo import Foo

그러면 다음을 실행하면 spam 모듈에 foo와 Foo에 대한 이름 바인딩이 생겨요:

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.Foo
<class 'spam.foo.Foo'>

Python의 친숙한 이름 바인딩 규칙을 고려하면 이는 놀라워 보일 수 있지만, 실제로는 import 시스템의 근본적인 기능이에요. 성립되는 불변식(invariant)은 sys.modules['spam']과 sys.modules['spam.foo']가 있으면(위 import 후에 그럴 거예요), 후자가 전자의 foo 속성으로 나타나야 한다는 것이에요.

5.4.3. 모듈 스펙 (Module specs)

import 메커니즘은 import 중, 특히 로드 전에 각 모듈에 대한 다양한 정보를 사용해요. 대부분의 정보는 모든 모듈에서 공통이에요. 모듈 스펙의 목적은 이 import 관련 정보를 모듈별로 캡슐화하는 것이에요.

import 중에 스펙을 사용하면 import 시스템 구성 요소 간에 상태를 전송할 수 있어요. 예를 들어 모듈 스펙을 만드는 파인더와 그것을 실행하는 로더 사이에서요. 가장 중요하게는, 모듈 스펙이 없는 경우 로더가 지녔던 로드의 보일러플레이트 연산을 import 메커니즘이 수행할 수 있게 해줘요.

모듈의 스펙은 module.__spec__으로 노출돼요. __spec__을 적절히 설정하는 것은 인터프리터 시작 중에 초기화되는 모듈에도 동일하게 적용돼요. 유일한 예외는 __main__인데, 어떤 경우에는 __spec__이 None으로 설정돼요.

모듈 스펙의 내용에 대한 자세한 내용은 ModuleSpec을 참고하세요.

버전 3.4에서 추가.

5.4.4. 모듈의 path 속성 (path attributes on modules)

__path__ 속성은 패키지의 하위 모듈이 발견될 위치를 열거하는 (어쩌면 빈) 문자열 시퀀스여야 해요. 정의상, 모듈에 __path__ 속성이 있으면 그것은 패키지예요.

패키지의 __path__ 속성은 하위 패키지의 import 중에 사용돼요. import 메커니즘 안에서 그것은 sys.path와 매우 유사하게 기능해요. 즉, import 중에 모듈을 검색할 위치들의 목록을 제공해요. 그러나 __path__는 보통 sys.path보다 훨씬 더 제약돼요.

sys.path에 사용되는 것과 동일한 규칙이 패키지의 __path__에도 적용돼요. 패키지의 __path__를 순회할 때 sys.path_hooks(아래에서 설명)가 조회돼요.

패키지의 __init__.py 파일은 패키지의 __path__ 속성을 설정하거나 변경할 수 있고, 이것이 PEP 420 이전에 네임스페이스 패키지를 구현하던 전형적인 방식이었어요. PEP 420의 채택으로 네임스페이스 패키지는 더 이상 __path__ 조작 코드만 포함하는 __init__.py 파일을 제공할 필요가 없어요. import 메커니즘이 네임스페이스 패키지의 __path__를 자동으로 올바르게 설정해요.

5.4.5. 모듈 repr (Module reprs)

기본적으로 모든 모듈은 사용 가능한 repr을 가지지만, 위에서 설정된 속성과 모듈의 스펙에 따라 모듈 객체의 repr을 더 명시적으로 제어할 수 있어요.

모듈에 스펙(__spec__)이 있으면, import 메커니즘은 그것에서 repr을 생성하려 시도해요. 그것이 실패하거나 스펙이 없으면, import 시스템은 모듈에서 사용 가능한 어떤 정보든 사용해 기본 repr을 만들 거예요. repr에 대한 입력으로 module.__name__, module.__file__, module.__loader__를 사용하려 할 것이고, 누락된 정보에 대해서는 기본값을 사용해요.

사용되는 정확한 규칙은 다음과 같아요:

모듈에 __spec__ 속성이 있으면, 스펙의 정보가 repr을 생성하는 데 사용돼요. "name", "loader", "origin", "has_location" 속성이 참고돼요.
모듈에 __file__ 속성이 있으면, 이것이 모듈의 repr의 일부로 사용돼요.
모듈에 __file__이 없지만 None이 아닌 __loader__가 있으면, 로더의 repr이 모듈의 repr의 일부로 사용돼요.
그렇지 않으면, repr에 모듈의 __name__만 사용해요.

버전 3.12에서 변경: Python 3.4부터 비추천되었던 module_repr() 사용이 Python 3.12에서 제거되었고, 모듈의 repr 해석 중에 더 이상 호출되지 않아요.

5.4.6. 캐시된 바이트코드 무효화 (Cached bytecode invalidation)

Python이 .pyc 파일에서 캐시된 바이트코드를 로드하기 전에, 캐시가 소스 .py 파일과 최신 상태인지 확인해요. 기본적으로 Python은 캐시 파일을 쓸 때 소스의 마지막 수정 타임스탬프와 크기를 캐시 파일에 저장함으로써 이 작업을 해요. 런타임에 import 시스템은 캐시 파일의 저장된 메타데이터를 소스의 메타데이터와 대조해 캐시 파일을 검증해요.

Python은 또한 소스 파일 내용의 해시를 메타데이터 대신 저장하는 "해시 기반" 캐시 파일을 지원해요. 해시 기반의 .pyc 파일에는 checked와 unchecked 두 가지 변형이 있어요. checked 해시 기반 .pyc 파일의 경우, Python은 소스 파일을 해시하고 그 결과 해시를 캐시 파일의 해시와 비교해 캐시 파일을 검증해요. checked 해시 기반 캐시 파일이 유효하지 않다고 판단되면, Python은 그것을 재생성하고 새 checked 해시 기반 캐시 파일을 써요. unchecked 해시 기반 .pyc 파일의 경우, Python은 캐시 파일이 존재하기만 하면 유효하다고 단순히 가정해요. 해시 기반 .pyc 파일 검증 동작은 --check-hash-based-pycs 플래그로 재정의될 수 있어요.

버전 3.7에서 변경: 해시 기반 .pyc 파일이 추가되었어요. 이전에 Python은 바이트코드 캐시의 타임스탬프 기반 무효화만 지원했어요.

5.5. 경로 기반 파인더 (The Path Based Finder)

앞서 언급했듯이 Python에는 여러 기본 메타 경로 파인더가 함께 제공돼요. 그중 하나인 경로 기반 파인더(PathFinder)는 경로 항목들의 목록을 포함하는 import 경로를 검색해요. 각 경로 항목은 모듈을 검색할 위치를 가리켜요.

경로 기반 파인더 자체는 아무것도 import하는 방법을 알지 못해요. 대신 개별 경로 항목을 순회하며, 각 항목을 그 특정 종류의 경로를 다루는 방법을 아는 경로 항목 파인더(path entry finder)와 연관지어요.

기본 경로 항목 파인더 집합은 파일 시스템에서 모듈을 찾기 위한 모든 의미론을 구현하며, Python 소스 코드(.py 파일), Python 바이트코드(.pyc 파일), 공유 라이브러리(예: .so 파일) 같은 특수 파일 타입을 다뤄요. 표준 라이브러리의 zipimport 모듈이 지원하면, 기본 경로 항목 파인더는 (공유 라이브러리를 제외한) 이 모든 파일 타입을 zip 파일에서 로드하는 것도 다뤄요.

경로 항목은 파일 시스템 위치로 제한될 필요가 없어요. URL, 데이터베이스 쿼리, 또는 문자열로 지정할 수 있는 다른 어떤 위치를 가리킬 수도 있어요.

경로 기반 파인더는 검색 가능한 경로 항목 타입을 확장하고 사용자 지정할 수 있도록 추가 훅과 프로토콜을 제공해요. 예를 들어 경로 항목을 네트워크 URL로 지원하고 싶다면, 웹에서 모듈을 찾는 HTTP 의미론을 구현하는 훅을 작성할 수 있어요. 이 훅(callable)은 아래에서 설명하는 프로토콜을 지원하는 경로 항목 파인더를 반환하고, 이는 웹에서 모듈의 로더를 얻는 데 사용돼요.

한마디 경고: 이 섹션과 이전 섹션은 모두 파인더라는 용어를 사용하지만, 메타 경로 파인더와 경로 항목 파인더라는 용어로 구분해요. 이 두 타입의 파인더는 매우 비슷하고, 비슷한 프로토콜을 지원하며, import 과정에서 비슷한 방식으로 기능하지만, 미묘하게 다르다는 점을 명심하는 게 중요해요. 특히 메타 경로 파인더는 sys.meta_path 순회에 따라 import 과정의 시작에서 동작해요.

대조적으로, 경로 항목 파인더는 어떤 의미에서 경로 기반 파인더의 구현 세부 사항이에요. 사실 경로 기반 파인더가 sys.meta_path에서 제거되면, 경로 항목 파인더 의미론은 전혀 호출되지 않을 거예요.

5.5.1. 경로 항목 파인더 (Path entry finders)

경로 기반 파인더는 위치가 문자열 경로 항목으로 지정된 Python 모듈과 패키지를 찾고 로드하는 책임이 있어요. 대부분의 경로 항목은 파일 시스템의 위치를 가리키지만, 이것에 제한될 필요는 없어요.

메타 경로 파인더로서 경로 기반 파인더는 앞서 설명한 find_spec() 프로토콜을 구현하지만, 모듈이 import 경로에서 어떻게 발견되고 로드되는지 사용자 지정하는 데 사용할 수 있는 추가 훅을 노출해요.

경로 기반 파인더는 sys.path, sys.path_hooks, sys.path_importer_cache라는 세 변수를 사용해요. 패키지 객체의 __path__ 속성도 사용돼요. 이것들은 import 메커니즘을 사용자 지정할 수 있는 추가 방법을 제공해요.

sys.path는 모듈과 패키지의 검색 위치를 제공하는 문자열 목록을 포함해요. PYTHONPATH 환경 변수와 다양한 설치 및 구현별 기본값에서 초기화돼요. sys.path의 항목은 파일 시스템의 디렉토리, zip 파일, 그리고 모듈을 검색해야 하는 잠재적으로 다른 "위치"(site 모듈 참조)를 가리킬 수 있어요. 예를 들어 URL이나 데이터베이스 쿼리 같은 것요. sys.path에는 문자열만 있어야 해요. 다른 모든 데이터 타입은 무시돼요.

경로 기반 파인더는 메타 경로 파인더이므로, import 메커니즘은 앞서 설명한 대로 경로 기반 파인더의 find_spec() 메서드를 호출함으로써 import 경로 검색을 시작해요. find_spec()의 path 인자가 주어지면 그것은 순회할 문자열 경로 목록일 거예요 - 보통 그 패키지 안에서의 import를 위한 패키지의 __path__ 속성이에요. path 인자가 None이면 최상위 import를 나타내며 sys.path가 사용돼요.

경로 기반 파인더는 검색 경로의 모든 항목을 반복하고, 각각에 대해 그 경로 항목에 적절한 경로 항목 파인더(PathEntryFinder)를 찾아요. 이는 비용이 많이 드는 연산일 수 있으므로(예: 이 검색에 stat() 호출 오버헤드가 있을 수 있어요), 경로 기반 파인더는 경로 항목을 경로 항목 파인더에 매핑하는 캐시를 유지해요. 이 캐시는 sys.path_importer_cache에 유지돼요 (이름에도 불구하고, 이 캐시는 importer 객체로 제한되는 것이 아니라 실제로 파인더 객체를 저장해요). 이렇게 하면 특정 경로 항목 위치의 경로 항목 파인더에 대한 값비싼 검색을 한 번만 수행하면 돼요. 사용자 코드는 sys.path_importer_cache에서 캐시 항목을 자유롭게 제거해 경로 기반 파인더가 경로 항목 검색을 다시 수행하게 할 수 있어요.

경로 항목이 캐시에 없으면, 경로 기반 파인더는 sys.path_hooks의 모든 callable을 반복해요. 이 목록의 각 경로 항목 훅은 단일 인자, 검색할 경로 항목으로 호출돼요. 이 callable은 경로 항목을 처리할 수 있는 경로 항목 파인더를 반환하거나 ImportError를 발생시킬 수 있어요. ImportError는 경로 기반 파인더가 그 경로 항목에 대한 경로 항목 파인더를 찾을 수 없다는 신호로 사용해요. 그 예외는 무시되고 import 경로 반복이 계속돼요. 훅은 문자열 또는 bytes 객체를 기대해야 해요. bytes 객체의 인코딩은 훅에 달려 있어요(예: 파일 시스템 인코딩, UTF-8, 또는 다른 무엇이든 될 수 있어요), 그리고 훅이 인자를 디코딩할 수 없으면 ImportError를 발생시켜야 해요.

만약 sys.path_hooks 반복이 경로 항목 파인더를 반환하지 않고 끝나면, 경로 기반 파인더의 find_spec() 메서드는 sys.path_importer_cache에 None을 저장하고(이 경로 항목에 대한 파인더가 없다는 뜻), None을 반환해 이 메타 경로 파인더가 모듈을 찾지 못했음을 나타내요.

sys.path_hooks의 경로 항목 훅 callable 중 하나가 경로 항목 파인더를 반환하면, 다음 프로토콜이 파인더에게 모듈 스펙을 요청하는 데 사용되고, 이 스펙은 모듈 로드 시 사용돼요.

빈 문자열로 표시되는 현재 작업 디렉토리는 sys.path의 다른 항목들과 약간 다르게 처리돼요. 첫째, 현재 작업 디렉토리를 결정할 수 없거나 존재하지 않는 것으로 판명되면 sys.path_importer_cache에 값이 저장되지 않아요. 둘째, 현재 작업 디렉토리의 값은 각 모듈 조회마다 새로 조회돼요. 셋째, sys.path_importer_cache에 사용되고 importlib.machinery.PathFinder.find_spec()이 반환하는 경로는 빈 문자열이 아니라 실제 현재 작업 디렉토리일 거예요.

5.5.2. 경로 항목 파인더 프로토콜 (Path entry finder protocol)

모듈과 초기화된 패키지의 import를 지원하고 네임스페이스 패키지에 부분을 기여하기 위해, 경로 항목 파인더는 find_spec() 메서드를 구현해야 해요.

find_spec()은 두 개의 인자를 받아요: import되는 모듈의 완전히 정규화된 이름과 (선택적) 대상 모듈. find_spec()은 모듈에 대해 완전히 채워진 스펙을 반환해요. 이 스펙은 항상 (한 가지 예외를 제외하고) "loader"가 설정되어 있을 거예요.

스펙이 네임스페이스 부분을 나타낸다는 것을 import 메커니즘에 알리기 위해, 경로 항목 파인더는 submodule_search_locations를 그 부분을 포함하는 목록으로 설정해요.

버전 3.4에서 변경: find_spec()이 find_loader()와 find_module()을 대체했어요. 둘 다 이제 비추천되었지만, find_spec()이 정의되지 않으면 사용될 거예요.

오래된 경로 항목 파인더는 find_spec() 대신 이 두 비추천 메서드 중 하나를 구현할 수 있어요. 역방향 호환성을 위해 이 메서드들은 여전히 존중돼요. 그러나 find_spec()이 경로 항목 파인더에 구현되면, 레거시 메서드들은 무시돼요.

find_loader()는 하나의 인자, import되는 모듈의 완전히 정규화된 이름을 받아요. find_loader()는 두 항목 튜플을 반환하는데, 첫 번째 항목은 로더이고 두 번째 항목은 네임스페이스 부분이에요.

import 프로토콜의 다른 구현과의 역방향 호환성을 위해, 많은 경로 항목 파인더는 메타 경로 파인더가 지원하는 것과 동일한, 전통적인 find_module() 메서드도 지원해요. 그러나 경로 항목 파인더의 find_module() 메서드는 path 인자 없이 호출돼요 (경로 훅에 대한 초기 호출에서 적절한 경로 정보를 기록할 것으로 기대돼요).

경로 항목 파인더의 find_module() 메서드는 비추천인데, 경로 항목 파인더가 네임스페이스 패키지에 부분을 기여하는 것을 허용하지 않기 때문이에요. 경로 항목 파인더에 find_loader()와 find_module()이 모두 존재하면, import 시스템은 항상 find_module()보다 find_loader()를 선호해 호출해요.

버전 3.10에서 변경: import 시스템이 find_module()과 find_loader()를 호출하면 ImportWarning이 발생해요.

버전 3.12에서 변경: find_module()과 find_loader()가 제거되었어요.

5.6. 표준 import 시스템 교체 (Replacing the standard import system)

전체 import 시스템을 교체하는 가장 신뢰할 수 있는 메커니즘은 sys.meta_path의 기본 내용을 삭제하고, 그것들을 완전히 사용자 정의 메타 경로 훅으로 대체하는 것이에요.

import 시스템에 접근하는 다른 API에 영향을 주지 않고 import 문의 동작만 변경하는 것이 허용된다면, 내장 __import__() 함수를 교체하는 것으로 충분할 수 있어요.

메타 경로의 초기에 있는 훅에서 일부 모듈의 import를 선택적으로 방지하려면(표준 import 시스템을 완전히 비활성화하기보다는), None을 반환하는 대신 find_spec()에서 직접 ModuleNotFoundError를 발생시키는 것으로 충분해요. 후자는 메타 경로 검색이 계속되어야 함을 나타내는 반면, 예외를 발생시키는 것은 즉시 종료시켜요.

5.7. 패키지 상대 import (Package Relative Imports)

상대 import는 선행 점(dot)을 사용해요. 단일 선행 점은 현재 패키지에서 시작하는 상대 import를 나타내요. 두 개 이상의 선행 점은 첫 점 이후의 점마다 한 레벨씩, 현재 패키지의 부모에 대한 상대 import를 나타내요. 예를 들어 다음 패키지 구조가 있다고 해요:

package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py

subpackage1/moduleX.py 또는 subpackage1/__init__.py 어느 쪽이든 다음은 유효한 상대 import예요:

from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo

절대 import는 import <> 또는 from <> import <> 문법을 사용할 수 있지만, 상대 import는 두 번째 형태만 사용할 수 있어요. 그 이유는:

import XXX.YYY.ZZZ

는 XXX.YYY.ZZZ를 사용 가능한 표현식으로 노출해야 하지만, .moduleY는 유효한 표현식이 아니기 때문이에요.

5.8. main에 대한 특별 고려 사항 (Special considerations for main)

__main__ 모듈은 Python의 import 시스템에 상대적인 특별한 경우예요. 다른 곳에서 언급했듯이, __main__ 모듈은 sys와 builtins처럼 인터프리터 시작 시 직접 초기화돼요. 그러나 이 둘과 달리 엄밀히 내장 모듈로 자격되지는 않아요. __main__이 초기화되는 방식이 인터프리터가 호출되는 플래그와 다른 옵션에 달려 있기 때문이에요.

5.8.1. main.spec

__main__이 어떻게 초기화되는지에 따라, __main__.__spec__은 적절히 설정되거나 None으로 설정돼요.

Python이 -m 옵션으로 시작되면, __spec__은 해당 모듈 또는 패키지의 모듈 스펙으로 설정돼요. __main__ 모듈이 디렉토리, zip파일, 다른 sys.path 항목의 실행의 일부로 로드될 때도 __spec__이 채워져요.

나머지 경우에 __main__.__spec__은 None으로 설정돼요. __main__을 채우는 데 사용되는 코드가 import 가능한 모듈과 직접 대응하지 않기 때문이에요:

대화형 프롬프트
-c 옵션
stdin에서 실행
소스 또는 바이트코드 파일에서 직접 실행

마지막 경우에는 __main__.__spec__이 항상 None이라는 점에 유의하세요. 파일이 기술적으로 모듈로 직접 import될 수 있더라도 말이에요. __main__에서 유효한 모듈 메타데이터를 원한다면 -m 스위치를 사용하세요.

또한 __main__이 import 가능한 모듈에 해당하고 __main__.__spec__이 그에 따라 설정되더라도, 그것들은 여전히 별개의 모듈로 간주된다는 점에 유의하세요. if __name__ == "__main__": 검사로 보호되는 블록은 모듈이 __main__ 네임스페이스를 채우는 데 사용될 때만 실행되고, 일반 import 중에는 실행되지 않기 때문이에요.

5.9. 참조 (References)

import 메커니즘은 Python 초창기 이후로 상당히 진화했어요. 패키지의 원래 명세는 여전히 읽을 수 있지만, 그 문서가 쓰인 이후 일부 세부 사항은 바뀌었어요.

sys.meta_path의 원래 명세는 PEP 302였고, PEP 420에서 후속 확장이 있었어요.

PEP 420은 Python 3.3용 네임스페이스 패키지를 도입했어요. PEP 420은 또한 find_module()의 대안으로 find_loader() 프로토콜을 도입했어요.

PEP 366은 메인 모듈에서 명시적 상대 import를 위한 __package__ 속성의 추가를 설명해요.

PEP 328은 절대 및 명시적 상대 import를 도입하고, 처음에는 PEP 366이 최종적으로 __package__에 대해 지정할 의미론을 위해 __name__을 제안했어요.

PEP 338은 모듈을 스크립트로 실행하는 것을 정의해요.

PEP 451은 스펙 객체에서 모듈별 import 상태의 캡슐화를 추가해요. 또한 로더의 대부분의 보일러플레이트 책임을 import 메커니즘으로 다시 옮겨요. 이러한 변경은 import 시스템의 여러 API를 비추천하고 파인더와 로더에 새 메서드를 추가하는 것을 허용해요.

각주

[1] types.ModuleType 참조.

[2] importlib 구현은 반환 값을 직접 사용하는 것을 피해요. 대신 sys.modules에서 모듈 이름을 조회해 모듈 객체를 얻어요. 이것의 간접 효과는 import된 모듈이 sys.modules에서 자신을 대체할 수 있다는 것이에요. 이것은 다른 Python 구현에서 작동한다는 보장이 없는 구현별 동작이에요.

5. import 시스템