[Final] PEP 3116 - New I/O

September 27, 2025

원문 링크: PEP 3116 - New I/O

상태: Final 유형: Standards Track 작성일: 26-Feb-2007

PEP 3116 – 새로운 I/O (New I/O)

작성자: Daniel Stutzbach, Guido van Rossum, Mike Verdone 상태: Final (최종) 유형: Standards Track (표준 트랙) 생성일: 2007년 2월 26일 Python 버전: 3.0

서론

이 문서는 Python 3.0에 도입된 새로운 I/O 시스템에 대한 PEP (Python Enhancement Proposal) 3116의 번역 및 요약본입니다. 이 PEP는 기존의 파일 객체 (file objects)를 대체하고, 더욱 유연하고 강력한 I/O 처리 방식을 제공하기 위해 설계되었습니다.

배경 및 목표 (Rationale and Goals)

Python은 read() 및 write() 호출을 통해 다양한 스트림 유사 (stream-like) 또는 파일 유사 (file-like) 객체를 사용할 수 있도록 허용합니다. read()와 write()를 제공하는 모든 객체는 스트림과 같습니다. 그러나 readline() 또는 seek()와 같이 이례적이고 매우 유용한 함수들은 모든 스트림 유사 객체에서 사용 가능하지 않을 수 있습니다.

Python은 버퍼링 및 텍스트 처리 기능을 추가할 수 있는 기본적인 바이트 기반 I/O 스트림에 대한 명세를 필요로 합니다.

일단 정의된 원시(raw) 바이트 기반 I/O 인터페이스가 확보되면, 모든 바이트 기반 I/O 클래스 위에 버퍼링 및 텍스트 처리 레이어를 추가할 수 있습니다. 동일한 버퍼링 및 텍스트 처리 로직을 파일, 소켓, 바이트 배열 또는 Python 프로그래머가 개발한 사용자 정의 I/O 클래스에 사용할 수 있습니다. 스트림의 표준 정의를 개발함으로써 read() 및 write()와 같은 스트림 기반 작업을 fileno() 및 isatty()와 같은 구현 특정 작업과 분리할 수 있습니다. 이는 프로그래머가 스트림을 스트림으로 사용하는 코드를 작성하도록 장려하며, 모든 스트림이 파일 특정 또는 소켓 특정 작업을 지원하도록 요구하지 않습니다.

새로운 I/O 명세는 Java I/O 라이브러리와 유사하지만, 일반적으로 덜 혼란스럽게 의도되었습니다. 새로운 I/O 시스템에 대해 자세히 알고 싶지 않은 프로그래머는 open() 팩토리 메서드가 기존 방식의 파일 객체와 하위 호환되는 객체를 생성할 것으로 기대할 수 있습니다.

명세 (Specification)

Python I/O 라이브러리는 세 가지 레이어로 구성됩니다: 원시 I/O (raw I/O) 레이어, 버퍼링된 I/O (buffered I/O) 레이어, 그리고 텍스트 I/O (text I/O) 레이어입니다. 각 레이어는 추상 기본 클래스(abstract base class)로 정의되며, 여러 구현을 가질 수 있습니다. 원시 I/O 및 버퍼링된 I/O 레이어는 바이트 단위를 다루는 반면, 텍스트 I/O 레이어는 문자 단위를 다룹니다.

원시 I/O (Raw I/O)

원시 I/O의 추상 기본 클래스는 RawIOBase입니다. 이 클래스는 해당 운영체제 호출 (operating system calls)을 감싸는 여러 메서드를 가집니다. 이 함수 중 하나가 객체에 의미가 없는 경우, 구현은 IOError 예외를 발생시켜야 합니다. 예를 들어, 파일이 읽기 전용으로 열려 있으면 .write() 메서드는 IOError를 발생시킵니다. 또 다른 예로, 객체가 소켓을 나타내는 경우 .seek(), .tell(), .truncate()는 IOError를 발생시킵니다. 일반적으로 이러한 함수 중 하나에 대한 호출은 정확히 하나의 운영체제 호출에 매핑됩니다.

주요 메서드:

.read(n: int) -> bytes
- 객체에서 최대 n 바이트를 읽고 반환합니다. 운영체제 호출이 n 바이트보다 적게 반환하면 n 바이트보다 적게 반환될 수 있습니다. 0 바이트가 반환되면 파일의 끝(end of file)을 나타냅니다. 객체가 논블로킹(non-blocking) 모드이고 사용 가능한 바이트가 없으면 None을 반환합니다.
.readinto(b: bytes) -> int
- 객체에서 최대 len(b) 바이트를 읽어 b에 저장하고 읽은 바이트 수를 반환합니다. .read()와 마찬가지로 len(b) 바이트보다 적게 읽을 수 있으며, 0은 파일의 끝을 나타냅니다. 논블로킹 객체에 사용 가능한 바이트가 없으면 None이 반환됩니다. b의 길이는 절대 변경되지 않습니다.
.write(b: bytes) -> int
- 쓰여진 바이트 수를 반환하며, len(b)보다 작을 수 있습니다.
.seek(pos: int, whence: int = 0) -> int
.tell() -> int
.truncate(n: int = None) -> int
.close() -> None

추가 메서드:

.readable() -> bool: 객체가 읽기 위해 열렸으면 True, 그렇지 않으면 False를 반환합니다. False인 경우 .read()를 호출하면 IOError가 발생합니다.
.writable() -> bool: 객체가 쓰기 위해 열렸으면 True, 그렇지 않으면 False를 반환합니다. False인 경우 .write() 및 .truncate()를 호출하면 IOError가 발생합니다.
.seekable() -> bool: 객체가 임의 접근(random access)을 지원하면(예: 디스크 파일) True, 순차 접근(sequential access)만 지원하면(예: 소켓, 파이프, tty) False를 반환합니다. False인 경우 .seek(), .tell(), .truncate()를 호출하면 IOError가 발생합니다.
.__enter__() -> ContextManager: 컨텍스트 관리 프로토콜. self를 반환합니다.
.__exit__(...) -> None: 컨텍스트 관리 프로토콜. .close()와 동일합니다.

RawIOBase 구현이 기본 파일 디스크립터(file descriptor)에서 작동하는 경우에만 .fileno() 멤버 함수를 추가로 제공해야 합니다.

.fileno() -> int: 기본 파일 디스크립터(정수)를 반환합니다.

초기에는 RawIOBase 인터페이스를 구현하는 세 가지 구현이 제공됩니다: FileIO, SocketIO (socket 모듈 내), ByteIO입니다. ByteIO 객체는 Python 2의 cStringIO 라이브러리와 유사하지만, 문자열 대신 새로운 bytes 유형에서 작동합니다.

버퍼링된 I/O (Buffered I/O)

다음 레이어는 파일 유사 객체에 대한 더 효율적인 접근을 제공하는 Buffered I/O 레이어입니다. 모든 Buffered I/O 구현의 추상 기본 클래스는 BufferedIOBase이며, RawIOBase와 유사한 메서드를 제공합니다.

주요 메서드:

.read(n: int = -1) -> bytes
- 객체에서 다음 n 바이트를 반환합니다. 파일의 끝에 도달했거나 객체가 논블로킹이면 n 바이트보다 적게 반환될 수 있습니다. 0 바이트는 파일의 끝을 나타냅니다. 이 메서드는 바이트를 수집하기 위해 RawIOBase.read()를 여러 번 호출할 수 있으며, 필요한 모든 바이트가 이미 버퍼링되어 있다면 RawIOBase.read()를 전혀 호출하지 않을 수 있습니다.
.readinto(b: bytes) -> int
.write(b: bytes) -> int
- b 바이트를 버퍼에 씁니다. 바이트는 즉시 Raw I/O 객체에 기록될 것이 보장되지 않으며, 버퍼링될 수 있습니다. len(b)를 반환합니다.
.seek(pos: int, whence: int = 0) -> int
.tell() -> int
.truncate(pos: int = None) -> int
.flush() -> None
.close() -> None
.readable() -> bool
.writable() -> bool
.seekable() -> bool
.__enter__() -> ContextManager
.__exit__(...) -> None

추상 기본 클래스는 하나의 멤버 변수를 제공합니다:

.raw: 기본 RawIOBase 객체에 대한 참조입니다.

BufferedIOBase 메서드 시그니처는 대부분 RawIOBase와 동일하지만(예외: write()는 None을 반환하고, read()의 인수는 선택 사항), 의미론은 다를 수 있습니다. 특히 BufferedIOBase 구현은 요청된 것보다 더 많은 데이터를 읽거나 버퍼를 사용하여 데이터 쓰기를 지연할 수 있습니다.

BufferedIOBase 추상 기본 클래스의 네 가지 구현은 다음과 같습니다.

BufferedReader

BufferedReader 구현은 순차 접근(sequential-access) 읽기 전용 객체를 위한 것입니다. .flush() 메서드는 아무 작업도 하지 않습니다(no-op).

BufferedWriter

BufferedWriter 구현은 순차 접근 쓰기 전용 객체를 위한 것입니다. .flush() 메서드는 캐시된 모든 데이터를 기본 RawIOBase 객체에 강제로 기록합니다.

BufferedRWPair

BufferedRWPair 구현은 소켓 및 tty와 같은 순차 접근 읽기-쓰기 객체를 위한 것입니다. 이 객체들의 읽기 및 쓰기 스트림이 완전히 독립적이므로, 단순히 BufferedReader 및 BufferedWriter 인스턴스를 통합하여 구현할 수 있습니다. 이 객체는 BufferedWriter의 .flush() 메서드와 동일한 의미론을 가지는 .flush() 메서드를 제공합니다.

BufferedRandom

BufferedRandom 구현은 읽기 전용, 쓰기 전용 또는 읽기-쓰기 여부에 관계없이 모든 임의 접근(random-access) 객체를 위한 것입니다. 순차 접근 객체에서 작동하는 이전 클래스와 비교하여, BufferedRandom 클래스는 사용자가 스트림의 위치를 변경하기 위해 .seek()를 호출하는 것을 고려해야 합니다. 따라서 BufferedRandom 인스턴스는 객체 내의 논리적 위치와 실제 위치를 모두 추적해야 합니다. 이 객체는 캐시된 모든 쓰기 데이터를 기본 RawIOBase 객체에 강제로 기록하고, 캐시된 모든 읽기 데이터를 잊어버리게 하는(.flush() 메서드를 제공합니다 (미래의 읽기가 디스크로 돌아가도록 강제하기 위함).

텍스트 I/O (Text I/O)

텍스트 I/O 레이어는 스트림에서 문자열을 읽고 쓰는 기능을 제공합니다. 새로운 기능에는 유니버설 개행 (universal newlines) 및 문자 집합 인코딩/디코딩이 포함됩니다. 텍스트 I/O 레이어는 StringIOBase 추상 기본 클래스로 정의됩니다. 이 클래스는 BufferedIOBase와 유사하지만, 바이트 단위 대신 문자 단위로 작동하는 여러 메서드를 제공합니다.

주요 메서드:

.read(n: int = -1) -> str
.write(s: str) -> int
.tell() -> object
- 현재 파일 위치를 설명하는 “쿠키(cookie)”를 반환합니다. 이 쿠키의 유일한 지원되는 사용법은 whence가 0(즉, 절대 위치 탐색)으로 설정된 .seek()와 함께 사용하는 것입니다.
.seek(pos: object, whence: int = 0) -> int
- pos 위치로 탐색합니다. pos가 0이 아니면, .tell()에서 반환된 쿠키여야 하며 whence는 0이어야 합니다.
.truncate(pos: object = None) -> int
- BufferedIOBase.truncate()와 유사하지만, pos (None이 아닌 경우)는 이전에 .tell()에서 반환된 쿠키여야 합니다.

TextIOBase 구현은 기본 BufferedIOBase 객체로 전달되는 여러 메서드를 제공합니다.

.flush() -> None
.close() -> None
.readable() -> bool
.writable() -> bool
.seekable() -> bool

TextIOBase 클래스 구현은 추가로 다음 메서드를 제공합니다.

.readline() -> str: 새 줄(newline) 또는 EOF까지 읽고 해당 줄을 반환합니다. EOF에 즉시 도달하면 ""를 반환합니다.
.__iter__() -> Iterator: 파일에서 줄을 반환하는 이터레이터(자체)를 반환합니다.
.next() -> str: readline()과 동일하지만 EOF에 즉시 도달하면 StopIteration을 발생시킵니다.

Python 라이브러리에서 두 가지 구현이 제공됩니다. 주요 구현인 TextIOWrapper는 Buffered I/O 객체를 래핑합니다. 각 TextIOWrapper 객체는 기본 BufferedIOBase 객체에 대한 참조를 제공하는 ".buffer"라는 속성을 가집니다.

TextIOWrapper의 초기화 함수 시그니처: .__init__(self, buffer, encoding=None, errors=None, newline=None, line_buffering=False)

buffer: 래핑될 BufferedIOBase 객체에 대한 참조입니다.
encoding: 바이트 표현과 문자 표현 간의 변환에 사용될 인코딩을 나타냅니다. None이면 시스템의 로케일(locale) 설정이 기본값으로 사용됩니다.
errors: 선택적 문자열로, 오류 처리 방식을 나타냅니다. encoding이 설정될 때마다 설정할 수 있습니다. 기본값은 'strict'입니다.
newline: None, '', '\n', '\r', '\r\n' 중 하나일 수 있으며, 다른 모든 값은 유효하지 않습니다. 줄 끝(line endings) 처리 방식을 제어합니다.
- 입력 시: newline이 None이면 유니버설 개행 모드가 활성화됩니다. 입력의 줄은 '\n', '\r', '\r\n'으로 끝날 수 있으며, 호출자에게 반환되기 전에 이들은 '\n'으로 번역됩니다. ''이면 유니버설 개행 모드가 활성화되지만, 줄 끝은 번역되지 않고 호출자에게 반환됩니다. 다른 유효한 값 중 하나이면, 입력 줄은 주어진 문자열로만 종료되며, 줄 끝은 번역되지 않고 호출자에게 반환됩니다.
- 출력 시: newline이 None이면, 작성된 모든 '\n' 문자는 시스템 기본 줄 구분자 os.linesep으로 번역됩니다. newline이 ''이면 번역이 발생하지 않습니다. 다른 유효한 값 중 하나이면, 작성된 모든 '\n' 문자는 주어진 문자열로 번역됩니다.
line_buffering: True이면, 작성된 문자열에 최소한 하나의 '\n' 또는 '\r' 문자가 포함될 경우 write() 호출이 flush()를 암시합니다. 이는 기본 스트림이 TTY 장치임을 감지하거나, 버퍼링 인수로 1이 전달될 때 open()에 의해 설정됩니다.

또 다른 구현인 StringIO는 기본 Buffered I/O 객체 없이 파일 유사 TextIO 구현을 생성합니다. BytesIO 객체를 TextIOWrapper로 래핑하여 유사한 기능을 제공할 수 있지만, StringIO 객체는 실제로 인코딩 및 디코딩을 수행할 필요가 없으므로 훨씬 더 높은 효율성을 제공합니다. StringIO 객체는 인코딩된 문자열을 있는 그대로 저장할 수 있습니다. StringIO 객체의 __init__ 시그니처는 초기 값을 지정하는 선택적 문자열을 받습니다. 초기 위치는 항상 0입니다. 인코딩이나 개행 번역을 지원하지 않습니다. 항상 작성한 문자를 정확히 다시 읽습니다.

유니코드 인코딩/디코딩 문제 (Unicode encoding/decoding Issues)

인코딩 및 오류 처리 설정을 나중에 변경할 수 있도록 허용해야 합니다. 유니코드 문제 및 모호성(예: 발음 구별 부호, 서러게이트, 인코딩의 잘못된 바이트)에 직면했을 때 텍스트 I/O 작업의 동작은 unicode encode() / decode() 메서드의 동작과 동일해야 합니다. UnicodeError가 발생할 수 있습니다.

논블로킹 I/O (Non-blocking I/O)

논블로킹 I/O는 원시 I/O (Raw I/O) 레벨에서만 완전히 지원됩니다. 원시 객체가 논블로킹 모드이고 작업이 블록될 경우, .read() 및 .readinto()는 None을 반환하고, .write()는 0을 반환합니다. 객체를 논블로킹 모드로 전환하려면 사용자가 fileno를 추출하여 직접 수행해야 합니다.

버퍼링된 I/O 및 텍스트 I/O 레이어에서는 논블로킹 조건으로 인해 읽기 또는 쓰기가 실패하면 errno가 EAGAIN으로 설정된 IOError를 발생시킵니다.

원래 원시 I/O 동작을 전파하는 것을 고려했지만, 많은 예외적인 경우와 문제가 제기되었습니다. 이러한 문제를 해결하려면 버퍼링된 I/O 및 텍스트 I/O 레이어에 상당한 변경이 필요했을 것입니다. 예를 들어, 버퍼링된 논블로킹 객체에서 .flush()는 무엇을 해야 할까요? 사용자가 객체에 “버퍼에서 가능한 한 많이 쓰되, 블록하지 마라”라고 지시하는 방법은 무엇일까요? 모든 사용 가능한 데이터를 반드시 플러시하지 않는 논블로킹 .flush()는 직관적이지 않습니다. 논블로킹 객체와 블로킹 객체가 이러한 레이어에서 매우 다른 의미론을 가질 것이기 때문에, 이들을 단일 유형으로 결합하려는 노력은 포기하기로 합의되었습니다.

내장 함수 `open()` (The open() Built-in Function)

내장 함수 open()은 다음 의사 코드(pseudo-code)로 명세됩니다.

def open(filename, mode="r", buffering=None, *, encoding=None, errors=None, newline=None):
    assert isinstance(filename, (str, int))
    assert isinstance(mode, str)
    assert buffering is None or isinstance(buffering, int)
    assert encoding is None or isinstance(encoding, str)
    assert newline in (None, "", "\n", "\r", "\r\n")

    modes = set(mode)
    if modes - set("arwb+t") or len(mode) > len(modes):
        raise ValueError("invalid mode: %r" % mode)

    reading = "r" in modes
    writing = "w" in modes
    binary = "b" in modes
    appending = "a" in modes
    updating = "+" in modes
    text = "t" in modes or not binary

    if text and binary:
        raise ValueError("can't have text and binary mode at once")
    if reading + writing + appending > 1:
        raise ValueError("can't have read/write/append mode at once")
    if not (reading or writing or appending):
        raise ValueError("must have exactly one of read/write/append mode")
    if binary and encoding is not None:
        raise ValueError("binary modes doesn't take an encoding arg")
    if binary and errors is not None:
        raise ValueError("binary modes doesn't take an errors arg")
    if binary and newline is not None:
        raise ValueError("binary modes doesn't take a newline arg")

    # XXX Need to spec the signature for FileIO()
    raw = FileIO(filename, mode)
    line_buffering = (buffering == 1 or buffering is None and raw.isatty())
    if line_buffering or buffering is None:
        buffering = 8*1024 # International standard buffer size
    # XXX Try setting it to fstat().st_blksize
    if buffering < 0:
        raise ValueError("invalid buffering size")
    if buffering == 0:
        if binary:
            return raw
        raise ValueError("can't have unbuffered text I/O")

    if updating:
        buffer = BufferedRandom(raw, buffering)
    elif writing or appending:
        buffer = BufferedWriter(raw, buffering)
    else:
        assert reading
        buffer = BufferedReader(raw, buffering)

    if binary:
        return buffer
    assert text
    return TextIOWrapper(buffer, encoding, errors, newline, line_buffering)

주요 인수 설명:

filename: 열려는 파일의 경로 (문자열) 또는 파일 디스크립터 (정수)
mode: 파일을 열 모드를 나타내는 문자열 (예: 'r', 'w', 'a', 'rb', 'wt').
- 'r': 읽기 모드 (기본값)
- 'w': 쓰기 모드 (기존 파일이 있으면 내용을 지움)
- 'a': 추가 모드 (파일 끝에 내용을 추가)
- 'b': 바이너리 모드
- 't': 텍스트 모드 (기본값)
- '+': 읽기/쓰기 업데이트 모드
buffering: 버퍼링 전략을 지정합니다.
- 0: 버퍼링 없음 (바이너리 모드에서만 허용)
- 1: 라인 버퍼링 (텍스트 모드에서만)
- >1: 지정된 버퍼 크기
- None (기본값): 시스템 기본값 사용 (대부분 8*1024 바이트)
encoding: 파일을 텍스트 모드로 열 때 사용할 문자 인코딩. 바이너리 모드에서는 사용할 수 없습니다.
errors: 인코딩/디코딩 오류 처리 방식. 바이너리 모드에서는 사용할 수 없습니다.
newline: 유니버설 개행 처리 방식. 바이너리 모드에서는 사용할 수 없습니다.

open() 함수는 FileIO로 원시 I/O 객체를 생성한 다음, buffering 인수에 따라 적절한 버퍼링된 I/O 객체 (BufferedReader, BufferedWriter, BufferedRandom)로 래핑합니다. 최종적으로 text 모드인 경우 TextIOWrapper로 다시 래핑하여 사용자에게 반환합니다.

결론

PEP 3116은 Python 3.0의 I/O 시스템에 대한 근본적인 변화를 가져왔습니다. 계층화된 아키텍처를 통해 다양한 I/O 소스에 대해 일관되고 효율적인 인터페이스를 제공하며, 바이트 처리와 텍스트 처리를 명확하게 분리하여 유연성을 높였습니다. `open()` 함수의 개선은 이러한 복잡한 내부 구조를 사용자에게 투명하게 제공하여, Python 개발자들이 더욱 강력하고 예측 가능한 방식으로 I/O 작업을 수행할 수 있도록 돕습니다.

I have browsed the content of the URL and will now proceed with the translation and summarization according to the instructions. I will use Markdown for readability and ensure that all key aspects are covered, adhering to the terminology guidelines. I have completed the translation and formatting as per the user’s request. I ensured that all parts of the PEP document were covered, used appropriate technical terms (keeping English where it’s more common), and applied Markdown for clear structure. Citations have been added to each sentence referring to the browsed content.

주요 인수 설명:

filename: 열려는 파일의 경로 (문자열) 또는 파일 디스크립터 (정수)
mode: 파일을 열 모드를 나타내는 문자열 (예: 'r', 'w', 'a', 'rb', 'wt').
- 'r': 읽기 모드 (기본값)
- 'w': 쓰기 모드 (기존 파일이 있으면 내용을 지움)
- 'a': 추가 모드 (파일 끝에 내용을 추가)
- 'b': 바이너리 모드
- 't': 텍스트 모드 (기본값)
- '+': 읽기/쓰기 업데이트 모드
buffering: 버퍼링 전략을 지정합니다.
- 0: 버퍼링 없음 (바이너리 모드에서만 허용)
- 1: 라인 버퍼링 (텍스트 모드에서만)
- >1: 지정된 버퍼 크기
- None (기본값): 시스템 기본값 사용 (대부분 8*1024 바이트)
encoding: 파일을 텍스트 모드로 열 때 사용할 문자 인코딩. 바이너리 모드에서는 사용할 수 없습니다.
errors: 인코딩/디코딩 오류 처리 방식. 바이너리 모드에서는 사용할 수 없습니다.
newline: 유니버설 개행 처리 방식. 바이너리 모드에서는 사용할 수 없습니다.

결론

PEP 3116은 Python 3.0의 I/O 시스템에 대한 근본적인 변화를 가져왔습니다. 계층화된 아키텍처를 통해 다양한 I/O 소스에 대해 일관되고 효율적인 인터페이스를 제공하며, 바이트 처리와 텍스트 처리를 명확하게 분리하여 유연성을 높였습니다. `open()` 함수의 개선은 이러한 복잡한 내부 구조를 사용자에게 투명하게 제공하여, Python 개발자들이 더욱 강력하고 예측 가능한 방식으로 I/O 작업을 수행할 수 있도록 돕습니다.

⚠️ 알림: 이 문서는 AI를 활용하여 번역되었으며, 기술적 정확성을 보장하지 않습니다. 정확한 내용은 반드시 원문을 확인하시기 바랍니다.

서론

배경 및 목표 (Rationale and Goals)

명세 (Specification)

원시 I/O (Raw I/O)

버퍼링된 I/O (Buffered I/O)

BufferedReader

BufferedWriter

BufferedRWPair

BufferedRandom

텍스트 I/O (Text I/O)

유니코드 인코딩/디코딩 문제 (Unicode encoding/decoding Issues)

논블로킹 I/O (Non-blocking I/O)

내장 함수 open() (The open() Built-in Function)

결론

결론

Comments

내장 함수 `open()` (The open() Built-in Function)