파이썬의 import 시스템

파이썬 코드가 다른 모듈의 코드에 접근하는 방법은 딱 하나인데, 바로 그 모듈을 import 하는 과정을 거치는 거예요. import 문이 import 메커니즘을 불러내는 가장 흔한 방법이지만, 그게 유일한 방법은 아니에요. importlib.import_module()이라든가 내장 함수 __import__() 같은 것도 얼마든지 import 메커니즘을 직접 호출할 수 있거든요.

이 글에서는 파이썬의 import 시스템이 어떻게 동작하는지, 모듈을 찾고(finder), 불러오고(loader), 캐시하고, 필요하면 자체적으로 메커니즘을 확장하는 방법까지 하나씩 살펴볼게요.

출처: Python 언어 레퍼런스

본문

import 문은 실제로 두 가지 작업을 합쳐 놓은 거예요. 먼저 지정한 이름의 모듈을 찾고, 그 다음에는 찾은 결과를 로컬 스코프의 어떤 이름에 바인딩해요. 여기서 '검색' 부분은 적절한 인자와 함께 __import__() 함수를 호출하는 것으로 정의돼요. 그리고 __import__()의 반환값을 이용해 이름 바인딩 작업을 수행하는 거죠. 이름 바인딩의 정확한 동작은 import 문 문서에서 더 자세히 볼 수 있어요.

한편 __import__()를 직접 호출하는 건 모듈 검색과, 찾았을 경우 모듈 생성까지만 수행해요. 부모 패키지를 가져온다거나 sys.modules를 비롯한 여러 캐시를 갱신하는 부수 효과는 발생할 수 있지만, 이름 바인딩 작업은 오직 import 문만 수행한다는 점을 기억해 두세요.

import 문이 실행되면 표준 내장 함수인 __import__()가 호출돼요. 그런데 importlib.import_module()처럼 import 시스템을 호출하는 다른 메커니즘은 __import__()를 우회하고 자기만의 방식으로 import 의미론을 구현하기도 해요.

모듈이 처음 import될 때 파이썬은 그 모듈을 찾고, 찾으면 모듈 객체를 만들어 초기화해요[1]. 만약 이름이 붙은 모듈을 찾을 수 없으면 ModuleNotFoundError가 발생하지요. import 메커니즘이 호출되면 파이썬은 이름이 붙은 모듈을 찾기 위해 다양한 전략을 사용해요. 아래 섹션에서 설명할 각종 훅을 사용하면 이런 전략을 수정하거나 확장할 수도 있어요.

버전 3.3에서 변경: import 시스템이 PEP 302의 2단계를 완전히 구현하도록 업데이트됐어요. 더 이상 암묵적인 import 메커니즘은 없고, 전체 import 시스템이 sys.meta_path를 통해 드러나요. 추가로 네이티브 네임스페이스 패키지 지원(PEP 420)도 구현됐구요.

importlib

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

패키지 (Packages)

파이썬에는 모듈 객체의 타입이 하나뿐이에요. 모듈이 파이썬으로 구현됐든, C로 구현됐든, 그 외 다른 것으로 구현됐든 간에 모든 모듈은 같은 타입이에요. 모듈을 정리하고 이름에 계층 구조를 부여하기 위해 파이썬에는 패키지(package) 개념이 있어요.

패키지는 파일 시스템의 디렉터리, 모듈은 그 안의 파일이라고 생각하면 편해요. 다만 이 비유를 너무 글자 그대로 받아들이지는 마세요. 패키지와 모듈이 반드시 파일 시스템에서 와야 하는 건 아니니까요. 문서에서는 편의를 위해 디렉터리/파일 비유를 계속 쓸게요. 파일 시스템 디렉터리처럼 패키지도 계층적으로 구성되고, 패키지는 일반 모듈뿐 아니라 서브패키지(subpackage)도 담을 수 있어요.

한 가지 꼭 기억해야 할 점은, 모든 패키지는 모듈이지만 모든 모듈이 패키지는 아니다라는 거예요. 다시 말하면 패키지는 모듈의 특별한 한 종류일 뿐이에요. 구체적으로, __path__ 속성을 가진 모듈은 무엇이든 패키지로 간주돼요.

모든 모듈은 이름을 가져요. 서브패키지 이름은 파이썬의 표준 속성 접근 문법처럼 점(.)으로 부모 패키지 이름과 구분돼요. 그래서 email이라는 패키지가 있고, 그 안에 email.mime이라는 서브패키지가 있고, 그 서브패키지 안에 email.mime.text라는 모듈이 있는 식으로 구성할 수 있어요.

일반 패키지 (Regular packages)

파이썬은 패키지를 일반 패키지(regular package)와 네임스페이스 패키지(namespace package)의 두 종류로 정의해요. 일반 패키지는 파이썬 3.2 이하에서 존재하던 전통적인 패키지예요. 보통은 __init__.py 파일을 담은 디렉터리로 구현되지요. 일반 패키지를 import하면 이 __init__.py 파일이 암묵적으로 실행되면서, 그 파일이 정의한 객체가 패키지 네임스페이스의 이름에 바인딩돼요. __init__.py는 다른 어떤 모듈이 담을 수 있는 파이썬 코드와 동일한 코드를 담을 수 있고, import될 때 파이썬이 모듈에 몇 가지 추가 속성을 덧붙이기도 해요.

예를 들어 다음 파일 시스템 구성은 서브패키지 세 개를 가진 최상위 부모 패키지를 정의해요.

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 파일이 없는 하위 디렉터리는, 그 부모를 루트로 하는 암묵적 네임스페이스 패키지('네임스페이스 서브패키지'라고도 해요)로 취급돼요. 근거가 되는 명세는 PEP 420을 참고하면 돼요.

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

네임스페이스 패키지는 여러 부분(portion) 의 합성물이에요. 각 부분이 부모 패키지에 서브패키지 하나씩을 기여하는 구조지요. 부분들은 파일 시스템의 서로 다른 위치에 있을 수 있어요. zip 파일, 네트워크, 아니면 파이썬이 import 중에 검색하는 어디든 있을 수 있구요. 네임스페이스 패키지는 파일 시스템의 객체와 반드시 일대일 대응할 필요는 없어요. 구체적인 표현 없이 존재하는 가상의 모듈일 수도 있거든요.

네임스페이스 패키지는 __path__ 속성에 보통의 리스트를 쓰지 않아요. 대신 커스텀 iterable 타입을 사용하는데, 이 타입은 부모 패키지의 경로(최상위 패키지라면 sys.path)가 바뀌면 그 패키지 안에서 다음 import를 시도할 때 패키지 부분을 새로 검색해요.

네임스페이스 패키지에는 parent/__init__.py 파일이 없어요. 사실 import 검색 중 서로 다른 부분이 제공하는 부모 디렉터리가 여러 개 발견될 수도 있어요. 그래서 실제로 parent/one이 parent/two 옆에 물리적으로 있지 않을 수도 있어요. 이 경우 최상위 parent 패키지 또는 그 서브패키지 중 하나가 import될 때 파이썬이 최상위 부모 패키지용 네임스페이스 패키지를 만들어요.

네임스페이스 패키지는 일반 패키지 안에 중첩될 수도 있어요. import 시스템이 일반 패키지의 __path__를 검색하다가 __init__.py 파일이 없는 하위 디렉터리를 만나면, 그 하위 디렉터리는 바깥 일반 패키지의 네임스페이스 서브패키지에 기여하는 부분이 돼요.

네임스페이스 패키지의 명세는 PEP 420도 참고해 주세요.

검색 (Searching)

검색을 시작하려면 파이썬은 import 대상 모듈(또는 패키지 — 여기 논의에서는 그 차이가 무의미해요)의 완전한 이름(full qualified name) 이 필요해요. 이 이름은 import 문의 여러 인자에서 오거나, importlib.import_module()이나 __import__() 함수의 매개변수에서 올 수 있어요.

이 이름은 import 검색의 여러 단계에서 사용되는데, foo.bar.baz처럼 하위 모듈을 가리키는 점 표기 경로일 수 있어요. 이 경우 파이썬은 먼저 foo를 import하려 하고, 그다음 foo.bar, 마지막으로 foo.bar.baz를 import하려 해요. 중간 어느 import라도 실패하면 ModuleNotFoundError가 발생하죠.

모듈 캐시 (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가 발생하지요. 모듈 이름이 없으면 파이썬은 모듈을 계속 검색해요.

sys.modules는 쓰기 가능해요. 키를 삭제해도 연결된 모듈이 파괴되는 건 아니지만(다른 모듈이 그 참조를 들고 있을 수 있으니까요), 이름이 붙은 모듈의 캐시 항목을 무효화해서 다음 import 때 파이썬이 그 모듈을 새로 검색하게 만들어요. 키를 None으로 할당할 수도 있는데, 그러면 다음 import에서 그 모듈이 ModuleNotFoundError로 끝나도록 강제돼요.

다만 조심할 게 있어요. 모듈 객체에 참조를 잡아두고, sys.modules의 캐시 항목을 무효화한 다음 그 모듈을 다시 import하면, 두 모듈 객체는 서로 같지 않아요. 반면 importlib.reload()는 같은 모듈 객체를 재사용하면서 모듈 코드를 다시 실행해 내용만 재초기화해요.

파인더와 로더 (Finders and loaders)

이름이 붙은 모듈이 sys.modules에 없으면 파이썬의 import 프로토콜이 호출돼서 모듈을 찾고 불러와요. 이 프로토콜은 파인더(finder) 와 로더(loader) 라는 두 가지 개념적 객체로 구성돼요. 파인더의 임무는 자기가 아는 전략으로 이름 붙은 모듈을 찾을 수 있는지 결정하는 거예요. 이 두 인터페이스를 모두 구현한 객체를 임포터(importer) 라고 하는데, 요청된 모듈을 불러올 수 있다고 판단하면 자기 자신을 반환해요.

파이썬에는 기본 파인더와 임포터가 여럿 포함돼 있어요. 첫 번째는 내장(built-in) 모듈을 찾는 법을 알고, 두 번째는 동결(frozen) 모듈을 찾는 법을 알아요. 세 번째 기본 파인더는 import 경로(import path) 에서 모듈을 검색하지요. import 경로는 파일 시스템 경로나 zip 파일을 가리킬 수 있는 위치의 목록이에요. URL이 식별하는 리소스처럼 찾을 수 있는 어떤 위치로든 확장도 가능해요.

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

파인더는 실제로 모듈을 불러오지는 않아요. 이름 붙은 모듈을 찾으면 모듈 스펙(module spec) 을 반환해요. 스펙은 모듈의 import 관련 정보를 담은 캡슐인데, import 메커니즘이 모듈을 불러올 때 이걸 사용하지요. 다음 섹션들에서 파인더와 로더의 프로토콜을 더 자세히 다루고, import 메커니즘을 확장하기 위해 새로 만들고 등록하는 방법도 설명할게요.

버전 3.4에서 변경: 이전 파이썬 버전에서는 파인더가 로더를 직접 반환했어요. 지금은 로더를 담은 모듈 스펙을 반환하죠. 로더는 import 중에 여전히 사용되지만 책임이 더 줄었어요.

import 훅 (Import hooks)

import 메커니즘은 확장 가능하도록 설계됐는데, 이를 위한 일차적인 수단이 import 훅이에요. import 훅에는 메타 훅(meta hook) 과 import 경로 훅(import path hook) 의 두 종류가 있어요.

메타 훅은 import 처리의 시작, sys.modules 캐시 조회를 제외한 다른 어떤 import 처리가 일어나기 전에 호출돼요. 그래서 메타 훅이 sys.path 처리, 동결 모듈, 심지어 내장 모듈까지 덮어쓸 수 있어요. 메타 훅은 아래에서 설명하듯 sys.meta_path에 새 파인더 객체를 추가해 등록하지요.

import 경로 훅은 sys.path(또는 package.__path__) 처리의 일부로 호출되는데, 관련된 경로 항목을 만나는 지점에서 호출돼요. import 경로 훅은 아래에서 설명하듯 sys.path_hooks에 새 호출 가능 객체(callable)를 추가해 등록해요.

메타 경로 (The meta path)

이름 붙은 모듈이 sys.modules에 없으면 파이썬은 이어서 sys.meta_path를 검색해요. 여기에는 메타 경로 파인더(meta path finder) 객체의 목록이 들어 있어요. 이 파인더들은 이름 붙은 모듈을 다룰 줄 아는지 순서대로 질의받지요. 메타 경로 파인더는 find_spec()이라는 메서드를 구현해야 하는데, 이 메서드는 세 가지 인자를 받아요: 이름(name), import 경로(import path), 그리고 (선택적으로) 대상 모듈(target module). 메타 경로 파인더는 자기가 이름 붙은 모듈을 다룰 수 있는지 어떤 전략으로든 판단할 수 있어요.

메타 경로 파인더가 이름 붙은 모듈을 다룰 줄 알면 스펙 객체를 반환해요. 다룰 수 없으면 None을 반환하지요. sys.meta_path 처리가 목록 끝까지 갔는데도 스펙이 반환되지 않으면 ModuleNotFoundError가 발생해요. 그 외의 다른 예외는 그대로 전파되면서 import 과정을 중단시켜요.

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

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

어떤 메타 경로 파인더는 최상위 import만 지원해요. 이런 임포터는 두 번째 인자로 None이 아닌 다른 게 전달되면 항상 None을 반환해요.

파이썬의 기본 sys.meta_path에는 메타 경로 파인더가 세 개 있어요. 내장 모듈을 import하는 법을 아는 것, 동결 모듈을 import하는 법을 아는 것, 그리고 import 경로에서 모듈을 import하는 법을 아는 것(경로 기반 파인더, path based finder)이지요.

버전 3.4에서 변경: 메타 경로 파인더의 find_spec() 메서드가 현재 사용 중단된 find_module()을 대체했어요. find_module()은 변경 없이 계속 동작하지만, import 메커니즘은 파인더가 find_spec()을 구현하지 않은 경우에만 그것을 시도해요.

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

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

로딩 (Loading)

모듈 스펙이 찾아지면 import 메커니즘은 모듈을 불러올 때 그 스펙(그리고 스펙이 담은 로더)을 사용해요. import 중 로딩 부분에서 일어나는 일을 가까이 근사한 의사 코드는 다음과 같아요.

module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
    # 'exec_module'도 로더에 정의돼 있다고 가정한다.
    module = spec.loader.create_module(spec)
if module is None:
    module = ModuleType(spec.name)
# import 관련 모듈 속성이 여기서 설정된다:
_init_module_attrs(spec, module)

if spec.loader is None:
    # 지원되지 않음
    raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
    # 네임스페이스 패키지
    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 캐시에 있던 모듈이나, 부수 효과로 성공적으로 로딩된 모듈은 캐시에 남아 있어야 해요. 이것은 reload와 대조되는데, reload에서는 실패한 모듈조차 sys.modules에 남겨져요.
모듈이 생성된 뒤, 실행 전에 import 메커니즘은 import 관련 모듈 속성을 설정해요(위 의사 코드의 _init_module_attrs). 이 내용은 뒤의 섹션에서 요약해요.
모듈 실행은 로딩의 핵심 순간인데, 이때 모듈의 네임스페이스가 채워져요. 실행은 전적으로 로더에 위임되고, 무엇을 어떻게 채울지는 로더가 정해요.
로딩 중에 생성되어 exec_module()에 전달된 모듈은 import 끝에서 반환되는 모듈과 다를 수 있어요[2].

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

로더 (Loaders)

모듈 로더는 로딩의 핵심 기능, 즉 모듈 실행을 제공해요. import 메커니즘은 인자 하나(실행할 모듈 객체)로 importlib.abc.Loader.exec_module() 메서드를 호출해요. exec_module()이 반환하는 값은 무시돼요.

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

모듈이 파이썬 모듈이라면(내장 모듈이나 동적으로 불러온 확장이 아니라면), 로더는 모듈의 전역 네임스페이스(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 메커니즘은 로더에 exec_module()이 없고 load_module()이 존재하면 그 메서드를 사용해요. 하지만 load_module()은 사용 중단(deprecated)됐으니 로더는 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이 발생해요.

서브모듈 (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

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

>>> import spam
>>> spam.foo

>>> spam.Foo

이건 파이썬의 익숙한 이름 바인딩 규칙을 생각하면 놀랍게 보일 수도 있는데, 사실 import 시스템의 근본적인 기능 중 하나예요. 성립하는 불변식(invariant)은, (위 import 이후처럼) sys.modules['spam']과 sys.modules['spam.foo']가 있다면 후자가 전자의 foo 속성으로 나타나야 한다는 것이에요.

모듈 스펙 (Module specs)

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

import 중에 스펙을 사용하면 import 시스템 구성 요소들 사이, 예를 들어 모듈 스펙을 만드는 파인더와 그것을 실행하는 로더 사이에서 상태를 전달할 수 있어요. 무엇보다 중요하게, 스펙 덕분에 import 메커니즘이 로딩의 보일러플레이트 작업을 수행할 수 있고, 모듈 스펙이 없던 때에는 그 책임이 로더에 있었어요.

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

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

버전 3.4에서 추가.

모듈의 `path` 속성

__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__를 자동으로 올바르게 설정해 주니까요.

모듈 repr

기본적으로 모든 모듈은 쓸 만한 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에서 변경: 파이썬 3.4부터 사용 중단됐던 module_repr()의 사용이 3.12에서 제거됐고, 모듈 repr을 결정할 때 더 이상 호출되지 않아요.

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

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

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

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

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

앞서 언급했듯 파이썬에는 몇 가지 기본 메타 경로 파인더가 있어요. 그중 하나인 경로 기반 파인더(path based finder, PathFinder) 가 import 경로를 검색해요. import 경로는 경로 항목(path entry)의 목록이고, 각 경로 항목은 모듈을 검색할 위치를 나타내요.

경로 기반 파인더 자체는 아무것도 import하는 법을 알지 못해요. 대신 개별 경로 항목을 순회하면서, 각각을 그런 종류의 경로를 다룰 줄 아는 경로 항목 파인더(path entry finder) 와 연결하지요.

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

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

경로 기반 파인더는 검색 가능한 경로 항목의 유형을 확장하고 커스터마이즈할 수 있도록 추가 훅과 프로토콜을 제공해요. 예를 들어 경로 항목으로 네트워크 URL을 지원하고 싶다면, 웹에서 모듈을 찾도록 HTTP 의미론을 구현하는 훅을 쓸 수 있어요. 이 훅(호출 가능 객체)은 아래에서 설명할 프로토콜을 지원하는 경로 항목 파인더를 반환하고, 그 파인더를 사용해 웹에서 모듈의 로더를 얻는 식이지요.

한마디 경고를 드릴게요. 이 섹션과 이전 섹션은 둘 다 '파인더'라는 용어를 쓰는데, 메타 경로 파인더 와 경로 항목 파인더 라는 용어로 구분해요. 이 두 종류의 파인더는 매우 비슷하고, 비슷한 프로토콜을 지원하며, import 과정에서 비슷하게 동작해요. 하지만 미묘하게 다르다는 점을 꼭 기억하세요. 특히 메타 경로 파인더는 sys.meta_path 순회에 의해 정해져서 import 과정의 시작에서 동작해요. 반면 경로 항목 파인더는 한편으로는 경로 기반 파인더의 구현 세부사항과 같은 것이에요. 실제로 경로 기반 파인더를 sys.meta_path에서 제거하면 경로 항목 파인더의 의미론은 하나도 호출되지 않게 돼요.

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

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

메타 경로 파인더로서 경로 기반 파인더는 앞서 설명한 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의 모든 호출 가능 객체를 반복해요. 이 목록의 각 경로 항목 훅은 인자 하나(검색할 경로 항목)로 호출돼요. 이 호출 가능 객체는 그 경로 항목을 다룰 수 있는 경로 항목 파인더를 반환하거나, ImportError를 발생시킬 수 있어요. ImportError는 경로 기반 파인더가 그 경로 항목에 대한 경로 항목 파인더를 찾을 수 없다는 신호로 사용돼요. 그 예외는 무시되고 import 경로 순회는 계속돼요. 훅은 문자열 또는 bytes 객체를 받을 것으로 기대해야 해요. bytes 객체의 인코딩은 훅의 몫이에요(파일 시스템 인코딩일 수도, UTF-8일 수도, 그 외 다른 것일 수도 있어요). 훅이 인자를 디코딩할 수 없으면 ImportError를 발생시켜야 해요.

sys.path_hooks 순회가 경로 항목 파인더 하나도 반환되지 않은 채 끝나면, 경로 기반 파인더의 find_spec() 메서드는 sys.path_importer_cache에 None을 저장하고(이 경로 항목에 대한 파인더가 없다는 표시), None을 반환해요. 즉 이 메타 경로 파인더가 모듈을 찾지 못했다는 표시지요.

sys.path_hooks의 어느 경로 항목 훅 호출 가능 객체가 경로 항목 파인더를 반환하면, 다음 프로토콜로 파인더에게 모듈 스펙을 요청하고, 그 스펙은 모듈을 불러올 때 사용돼요.

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

경로 항목 파인더 프로토콜

모듈과 초기화된 패키지의 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()는 첫 번째 항목이 로더이고 두 번째 항목이 네임스페이스 부분인 2-튜플을 반환해요.

import 프로토콜의 다른 구현과의 하위 호환을 위해, 많은 경로 항목 파인더가 메타 경로 파인더가 지원하는 것과 똑같은 전통적인 find_module() 메서드도 지원해요. 다만 경로 항목 파인더의 find_module()은 절대 path 인자로 호출되지 않아요(경로 훅을 처음 호출할 때 적절한 경로 정보를 기록할 것으로 기대되거든요).

경로 항목 파인더의 find_module() 메서드는 네임스페이스 패키지에 부분을 기여할 수 없게 하므로 사용 중단됐어요. 경로 항목 파인더에 find_loader()와 find_module()이 둘 다 존재하면, import 시스템은 항상 find_loader()를 find_module()보다 우선해 호출해요.

버전 3.10에서 변경: import 시스템의 find_module()과 find_loader() 호출은 ImportWarning을 발생시켜요.

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

표준 import 시스템 교체하기

전체 import 시스템을 교체하는 가장 확실한 메커니즘은 sys.meta_path의 기본 내용을 삭제하고, 그것을 전부 커스텀 메타 경로 훅으로 대체하는 거예요.

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

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

패키지 상대 import

상대 import(relative import)는 앞에 점(.)을 붙여 사용해요. 점 하나가 앞에 붙으면 현재 패키지에서 시작하는 상대 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는 유효한 표현식이 아니기 때문이에요.

`main`에 대한 특별한 고려사항

__main__ 모듈은 파이썬의 import 시스템에 비추어 특별한 경우예요. 다른 곳에서 언급했듯 __main__ 모듈은 sys나 builtins와 마찬가지로 인터프리터 시작 시 직접 초기화돼요. 다만 그 둘과 달리 내장 모듈로 엄밀히 인정되지는 않아요. __main__이 초기화되는 방식이 인터프리터를 호출할 때의 플래그와 기타 옵션에 달려 있기 때문이에요.

`main.spec`

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

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

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

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

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

또 하나 주의할 점은, __main__이 import 가능한 모듈과 대응하고 __main__.__spec__이 그에 따라 설정되더라도, 그것들은 여전히 서로 구별되는 모듈로 간주된다는 거예요. 그 이유는 if __name__ == "__main__":으로 보호되는 블록이 모듈이 __main__ 네임스페이스를 채우는 데 사용될 때만 실행되고, 정상적인 import 중에는 실행되지 않기 때문이에요.

참고문헌 (References)

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

sys.meta_path의 원래 명세는 PEP 302이고, 이후 PEP 420에서 확장됐어요.
PEP 420은 파이썬 3.3에 네임스페이스 패키지를 도입했어요. PEP 420은 또한 find_module()의 대안으로 find_loader() 프로토콜도 도입했지요.
PEP 366은 메인 모듈에서 명시적 상대 import를 위한 __package__ 속성의 추가를 설명해요.
PEP 328은 절대 import와 명시적 상대 import를 도입했고, 처음에는 PEP 366이 __package__에 대해 최종적으로 명시하게 될 의미론을 위해 __name__을 제안했어요.
PEP 338은 모듈을 스크립트로 실행하는 것을 정의해요.
PEP 451은 스펙 객체에 모듈별 import 상태의 캡슐화를 추가해요. 또한 로더의 대부분의 보일러플레이트 책임을 import 메커니즘에 다시 옮겨 실어요. 이 변경 덕분에 import 시스템의 여러 API를 사용 중단시킬 수 있고, 파인더와 로더에 새 메서드를 추가할 수도 있게 됐어요.

각주

[1] types.ModuleType을 참고하세요.

[2] importlib 구현은 반환값을 직접 사용하지 않아요. 대신 모듈 이름을 sys.modules에서 조회해서 모듈 객체를 얻지요. 이것의 간접적인 효과는, import된 모듈이 sys.modules에서 자기 자신을 대체할 수 있다는 거예요. 이는 구현별 동작이라 다른 파이썬 구현에서 반드시 동작한다고 보장되지는 않아요.

더 알아보기

Python 언어 레퍼런스: import 시스템 — 이 문서의 원문
importlib — import 구현 — import 시스템과 상호작용하는 공식 API
PEP 302 — New Import Hooks — import 훅과 메타 경로의 기반 명세
PEP 420 — Implicit Namespace Packages — 네임스페이스 패키지 명세
PEP 451 — A ModuleSpec Type for the Import System — 모듈 스펙과 로더 재구성

파이썬의 import 시스템