`io` — 스트림 작업을 위한 핵심 도구¶

소스 코드: Lib/io.py

개요¶

io 모듈은 다양한 유형의 I/O를 처리하기 위한 파이썬의 주요 장치를 제공합니다. I/O에는 세 가지 주요 유형이 있습니다: 텍스트(text) I/O, 바이너리(binary) I/O 및 원시(raw) I/O. 이들은 일반적인 범주이며 다양한 배경 저장소를 각각에 사용할 수 있습니다. 이러한 범주 중 하나에 속하는 구상 객체는 파일 객체 입니다. 다른 일반적인 용어로는 스트림(stream) 과 파일류 객체(file-like object) 가 있습니다.

범주와 상관없이, 각 구상 스트림 객체에는 다양한 기능이 있습니다: 읽기 전용, 쓰기 전용 또는 읽고-쓰기일 수 있습니다. 또한 임의의 무작위 액세스(임의의 위치로 전방이나 후방 탐색)를 허용하거나 순차적 액세스(예를 들어 소켓이나 파이프의 경우)만 허용할 수 있습니다.

모든 스트림은 그것에 제공하는 데이터형에 주의를 기울입니다. 예를 들어 str 객체를 바이너리 스트림의 write() 메서드에 제공하면 TypeError가 발생합니다. 텍스트 스트림의 write() 메서드에 bytes 객체를 제공해도 마찬가지입니다.

버전 3.3에서 변경: IOError가 이제는 OSError의 별칭이라서, IOError를 발생시켰던 연산은 이제 OSError를 발생시킵니다.

텍스트 I/O¶

텍스트 I/O는 str 객체를 기대하고 생성합니다. 이는 배경 저장소가 네이티브 하게 바이트열로 구성되었을 때마다 (가령 파일의 경우), 플랫폼별 줄 넘김 문자의 선택적 변환뿐만 아니라 데이터의 인코딩과 디코딩이 투명하게 이루어짐을 의미합니다.

텍스트 스트림을 만드는 가장 쉬운 방법은 open()을 사용하는 것이고, 선택적으로 인코딩을 지정합니다:

f = open("myfile.txt", "r", encoding="utf-8")

인 메모리 텍스트 스트림도 StringIO 객체로 제공됩니다:

f = io.StringIO("some initial text data")

참고

비차단 스트림을 사용할 때, 텍스트 I/O 객체에서 읽기 작업은 스트림이 즉시 작업을 수행할 수 없는 경우 :exc:`BlockingIOError`를 발생시킬 수 있다는 점에 유의하십시오.

텍스트 스트림 API는 TextIOBase의 설명서에 자세히 설명되어 있습니다.

바이너리 I/O¶

바이너리 I/O(버퍼링 된(buffered) I/O라고도 합니다)는 바이트열류 객체를 기대하고 bytes 객체를 생성합니다. 인코딩, 디코딩 또는 줄 넘김 변환이 수행되지 않습니다. 이 범주의 스트림은 모든 종류의 텍스트가 아닌 데이터에 사용할 수 있으며, 텍스트 데이터 처리를 수동으로 제어해야 할 때도 사용할 수 있습니다.

바이너리 스트림을 만드는 가장 쉬운 방법은 모드 문자열에 'b'를 제공하여 open()을 사용하는 것입니다:

f = open("myfile.jpg", "rb")

인 메모리 바이너리 스트림도 BytesIO 객체로 제공됩니다:

f = io.BytesIO(b"some initial binary data: \x00\x01")

바이너리 스트림 API는 BufferedIOBase 설명서에 자세히 설명되어 있습니다.

다른 라이브러리 모듈은 텍스트나 바이너리 스트림을 만드는 다른 방법을 제공할 수 있습니다. 예를 들어 socket.socket.makefile()을 참조하십시오.

원시 I/O¶

원시 I/O(버퍼링 되지 않은(unbuffered) I/O라고도 합니다)는 일반적으로 바이너리와 텍스트 스트림을 위한 저수준 빌딩 블록으로 사용됩니다; 사용자 코드에서 원시 스트림을 직접 조작하는 것은 거의 유용하지 않습니다. 그런데도, 버퍼링을 비활성화해서 바이너리 모드로 파일을 열어 원시 스트림을 만들 수 있습니다:

f = open("myfile.jpg", "rb", buffering=0)

원시 스트림 API는 RawIOBase 설명서에 자세히 설명되어 있습니다.

경고

원시 I/O는 저수준 인터페이스이며, 메서드는 일반적으로 반환 값을 확인하고 작업이 완료되도록 명시적으로 재시도해야 합니다. 예를 들어, :meth:`~RawIOBase.write`는 쓰여진 바이트 수를 반환하는데, 이는 제공된 바이트 수보다 적을 수 있는 부분적 쓰기입니다. :ref:`binary-io`와 :ref:`text-io`와 같은 고수준 I/O 객체는 재시도 동작을 구현합니다.

텍스트 인코딩¶

TextIOWrapper`와 :func:`open`의 기본 인코딩은 로케일별입니다 (:func:`locale.getencoding).

그러나 대부분의 Unix 플랫폼이 기본적으로 UTF-8 로케일을 사용하기 때문에(예: JSON, TOML, Markdown 등과 같이 UTF-8로 인코딩된 텍스트 파일을 열 때), 개발자들은 인코딩을 지정하는 것을 잊어버리는 경우가 많습니다. 이는 로케일 인코딩이 대부분의 Windows 사용자에게 UTF-8이 아니기 때문에 버그를 유발합니다. 예를 들어:

# 파일에 비 ASCII 문자가 있을 때 윈도우에서 작동하지 않을 수 있습니다.
with open("README.md") as f:
    long_description = f.read()

따라서, 텍스트 파일을 열 때는 인코딩을 명시적으로 지정하는 것이 강력히 권장됩니다. UTF-8을 사용하려면 `encoding=”utf-8”`을 전달하세요. 현재 로케일 인코딩을 사용하려면 Python 3.10부터 `encoding=”locale”`이 지원됩니다.

Python UTF-8 Mode: Python UTF-8 모드를 사용하여 기본 인코딩을 로케일별 인코딩에서 UTF-8로 변경할 수 있습니다.
PEP 686: Python 3.15부터 :ref:`utf8-mode`가 기본값이 됩니다.

선택적 인코딩 경고¶

Added in version 3.10: 더 자세한 정보는 :pep:`597`을 참조하십시오.

기본 로케일 인코딩이 사용되는 위치를 찾으려면, -X warn_default_encoding 명령줄 옵션을 활성화하거나 PYTHONWARNDEFAULTENCODING 환경 변수를 설정할 수 있습니다. 이 변수는 기본 인코딩이 사용될 때 :exc:`EncodingWarning`을 방출합니다.

open() 또는 TextIOWrapper`를 사용하고 `encoding=None`을 매개변수로 전달하는 API를 제공하는 경우, 호출자는 `encoding`을 전달하지 않으면 :exc:`EncodingWarning`을 방출하도록 :func:`text_encoding`을 사용할 수 있습니다. 하지만, 새로운 API의 경우 기본적으로 UTF-8(즉, `encoding="utf-8")을 사용하는 것을 고려해 주십시오.

고수준 모듈 인터페이스¶

io.DEFAULT_BUFFER_SIZE¶: 모듈의 버퍼링 된 I/O 클래스에서 사용하는 기본 버퍼 크기를 포함하는 int. open()은 가능하면 파일의 blksize(os.stat()으로 얻은)를 사용합니다.

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)¶

이것은 내장 open() 함수의 별칭입니다.

이 함수는 인자 path, mode 및 flags로 감사 이벤트 open을 발생시킵니다. mode와 flags 인자는 원래 호출에서 수정되었거나 유추되었을 수 있습니다.

io.open_code(path)¶

제공된 파일을 'rb' 모드로 엽니다. 이 함수는 내용을 실행 코드로 취급하려고 할 때 사용해야 합니다.

path는 str이고 절대 경로여야 합니다.

이 함수의 동작은 PyFile_SetOpenCodeHook() 에 대한 이전 호출로 재정의될 수 있습니다. 하지만, path가 str이고 절대 경로임을 가정할 때, open_code(path)는 항상 open(path, 'rb')와 같게 동작해야 합니다. 동작의 재정의는 파일의 추가 유효성 검사나 사전 처리를 위한 것입니다.

Added in version 3.8.

io.text_encoding(encoding, stacklevel=2, /)¶

이 함수는 open() 또는 TextIOWrapper`를 사용하고 `encoding=None 매개변수를 갖는 호출자를 위한 헬퍼 함수입니다.

이 함수는 None`이 아니면 *encoding*을 반환합니다. 그렇지 않으면 :ref:`UTF-8 Mode <utf8-mode>`에 따라 `”locale” 또는 `”utf-8”`을 반환합니다.

이 함수는 sys.flags.warn_default_encoding 가 True이고 encoding 이 None 인 경우 EncodingWarning 을 방출합니다. stacklevel 은 경고가 방출되는 위치를 지정합니다. 예를 들어:

def read_text(path, encoding=None):
    encoding = io.text_encoding(encoding)  # stacklevel=2
    with open(path, encoding) as f:
        return f.read()

이 예시에서는 read_text() 호출자에 대해 :class:`EncodingWarning`이 방출됩니다.

더 자세한 내용은 :ref:`io-text-encoding`을 참조하십시오.

Added in version 3.10.

버전 3.11에서 변경: text_encoding() 은 UTF-8 모드가 활성화되었고 encoding 이 None 일 때 “utf-8”을 반환합니다.

exception io.BlockingIOError¶: 이것은 내장 BlockingIOError 예외에 대한 호환 별칭입니다.

exception io.UnsupportedOperation¶: 지원되지 않는 연산이 스트림에서 호출될 때 발생하는 OSError와 ValueError를 상속하는 예외.

sys: 표준 IO 스트림을 포함합니다: sys.stdin, sys.stdout 및 sys.stderr.

클래스 위계¶

I/O 스트림의 구현은 클래스의 위계(hierarchy)로 구성됩니다. 먼저 다양한 범주의 스트림을 지정하는 데 사용되는 추상 베이스 클래스(ABC)가 있고, 그다음으로 표준 스트림 구현을 제공하는 구상 클래스가 있습니다.

참고

추상 베이스 클래스는 또한 구상 스트림 클래스의 구현을 돕기 위해 일부 메서드의 기본 구현을 제공합니다. 예를 들어, BufferedIOBase는 최적화되지 않은 readinto()와 readline() 구현을 제공합니다.

I/O 위계의 맨 위에는 추상 베이스 클래스 IOBase가 있습니다. 스트림에 대한 기본 인터페이스를 정의합니다. 그러나 스트림에 대한 읽기와 쓰기가 분리되지 않음에 유의하십시오; 구현은 주어진 연산을 지원하지 않으면 UnsupportedOperation을 발생시킬 수 있습니다.

RawIOBase ABC는 IOBase를 확장합니다. 스크림에 대한 바이트열의 읽기와 쓰기를 처리합니다. FileIO는 RawIOBase를 서브 클래싱하여 기계의 파일 시스템에 있는 파일에 대한 인터페이스를 제공합니다.

BufferedIOBase ABC는 IOBase를 확장합니다. 원시 바이너리 스트림(RawIOBase)에 대한 버퍼링을 다룹니다. 이것의 서브 클래스, BufferedWriter, BufferedReader 및 BufferedRWPair는 각각 쓸 수 있는, 읽을 수 있는, 그리고 읽고 쓸 수 있는 원시 바이너리 스트림을 버퍼링합니다. BufferedRandom은 탐색할 수 있는 (seekable) 스트림에 버퍼 인터페이스를 제공합니다. 또 다른 BufferedIOBase 서브 클래스 BytesIO는 인 메모리 바이트열의 스트림입니다.

TextIOBase ABC는 IOBase를 확장합니다. 이것은 바이트가 텍스트를 나타내는 스트림을 다루고, 문자열과의 인코딩과 디코딩을 처리합니다. TextIOBase를 확장하는 TextIOWrapper는 버퍼링 된 원시 스트림(BufferedIOBase)에 대한 버퍼링 된 텍스트 인터페이스입니다. 마지막으로, StringIO는 텍스트에 대한 인 메모리 스트림입니다.

인자 이름은 명세의 일부가 아니며, open()의 인자는 키워드 인자로만 사용하려는 의도입니다.

다음 표는 io 모듈에서 제공하는 ABC를 요약합니다:

ABC	상속	스텁(stub) 메서드	믹스 인 메서드와 프로퍼티
`IOBase`		`fileno`, `seek` 및 `truncate`	`close`, `closed`, `__enter__`, `__exit__`, `flush`, `isatty`, `__iter__`, `__next__`, `readable`, `readline`, `readlines`, `seekable`, `tell`, `writable` 및 `writelines`
`RawIOBase`	`IOBase`	`readinto`와 `write`	상속된 `IOBase` 메서드, `read` 및 `readall`
`BufferedIOBase`	`IOBase`	`detach`, `read`, `read1` 및 `write`	상속된 `IOBase` 메서드, `readinto` 및 `readinto1`
`TextIOBase`	`IOBase`	`detach`, `read`, `readline` 및 `write`	상속된 `IOBase` 메서드, `encoding`, `errors` 및 `newlines`

I/O 베이스 클래스¶

class io.IOBase¶

모든 I/O 클래스의 추상 베이스 클래스.

이 클래스는 파생 클래스가 선택적으로 재정의할 수 있는 많은 메서드에 대해 빈 추상 구현을 제공합니다; 기본 구현은 읽거나 쓰거나 탐색할 수 없는 파일을 나타냅니다.

IOBase가 서명이 다양하기 때문에 read()나 write()를 선언하지 않더라도, 구현과 클라이언트는 해당 메서드를 인터페이스의 일부로 고려해야 합니다. 또한, 지원하지 않는 연산이 호출될 때 구현은 ValueError(또는 UnsupportedOperation)를 발생시킬 수 있습니다.

파일에서 읽거나 파일에 쓰는 바이너리 데이터에 사용되는 기본형은 bytes입니다. 다른 바이트열류 객체도 메서드 인자로 허용됩니다. 텍스트 I/O 클래스는 str 데이터로 작동합니다.

닫힌 스트림에 대한 모든 메서드(조회조차도) 호출은 정의되어 있지 않습니다. 이 경우 구현은 ValueError를 발생시킬 수 있습니다.

IOBase(및 그 서브 클래스)는 이터레이터 프로토콜을 지원합니다. 즉, 스트림에서 줄을 산출하면서 IOBase 객체를 이터레이트 할 수 있습니다. 스트림이 바이너리 스트림(바이트열을 산출합니다)인지 텍스트 스트림(문자열을 산출합니다)인지에 따라 줄은 약간 다르게 정의됩니다. 아래 readline()을 참조하십시오.

IOBase는 컨텍스트 관리자이기도 해서, with 문을 지원합니다. 이 예에서, file은 with 문의 스위트가 완료된 후에 닫힙니다 — 예외가 발생하더라도:

with open('spam.txt', 'w') as file:
    file.write('Spam and eggs!')

IOBase는 다음 데이터 어트리뷰트와 메서드를 제공합니다:

close()¶

이 스트림을 플러시하고 닫습니다. 파일이 이미 닫혔으면 이 메서드는 효과가 없습니다. 일단 파일이 닫히면, 파일에 대한 모든 연산(예를 들어 읽기나 쓰기)이 ValueError를 발생시킵니다.

편의상, 이 메서드를 두 번 이상 호출할 수 있습니다; 그러나 첫 번째 호출만 효과가 있습니다.

closed¶: 스트림이 닫혔으면 True.

fileno()¶: 존재한다면 스트림의 하부 파일 기술자(정수)를 반환합니다. IO 객체가 파일 기술자를 사용하지 않으면 OSError가 발생합니다.

flush()¶: 해당하면 스트림의 쓰기 버퍼를 플러시합니다. 이것은 읽기 전용과 비 블로킹 스트림에 대해서는 아무것도 하지 않습니다.

isatty()¶: 스트림이 대화형이면 (즉, 터미널/tty 장치에 연결되었으면) True를 반환합니다.

readable()¶: 스트림을 읽을 수 있으면 True를 반환합니다. False이면, read()는 OSError를 발생시킵니다.

readline(size=-1, /)¶

스트림에서 한 줄을 읽고 반환합니다. size가 지정되면, 최대 size 바이트를 읽습니다.

줄 종결자는 바이너리 파일의 경우 항상 b'\n'입니다; 텍스트 파일의 경우, open()에 대한 newline 인자를 사용하여 인식되는 줄 종결자를 선택할 수 있습니다.

readlines(hint=-1, /)¶

스트림에서 줄 리스트를 읽고 반환합니다. hint는 읽을 줄 수를 제어하도록 지정할 수 있습니다: 지금까지 모든 줄의 총 크기(바이트/문자 단위)가 hint를 초과하면 더는 줄을 읽지 않습니다.

0 이하의 hint 값이나 `None`은 힌트가 없는 것으로 간주됩니다.

file.readlines()를 호출하지 않고 for line in file: ...을 사용하여 파일 객체를 이미 이터레이트 할 수 있음에 유의하십시오.

seek(offset, whence=os.SEEK_SET, /)¶

스트림 위치를 whence가 가리키는 위치를 기준으로 상대적으로 해석되는 지정된 바이트 offset으로 변경하고, 새 절대 위치를 반환합니다. whence의 값은 다음과 같습니다:

os.SEEK_SET 또는 0 – 스트림의 시작(기본값); offset은 0이거나 양수여야 합니다
os.SEEK_CUR 또는 1 – 현재 스트림 위치; offset은 음수일 수 있습니다
os.SEEK_END 또는 2 – 스트림의 끝; offset은 일반적으로 음수입니다

Added in version 3.1: SEEK_* 상수.

Added in version 3.3: 일부 운영 체제는 os.SEEK_HOLE이나 os.SEEK_DATA와 같은 추가 값을 지원할 수 있습니다. 파일에 대해 유효한 값은 그것이 텍스트나 바이너리 모드 중 어느 것으로 열렸는지에 따라 달라질 수 있습니다.

seekable()¶: 스트림이 무작위 액세스를 지원하면 True를 반환합니다. False이면, seek(), tell() 및 truncate()가 OSError를 발생시킵니다.

tell()¶: 현재의 스트림 위치를 반환합니다.

truncate(size=None, /)¶: 바이트 단위로 지정된 size로 스트림 크기를 조정합니다 (또는 size가 지정되지 않으면 현재 위치). 현재 스트림 위치는 변경되지 않습니다. 이 크기 조정은 현재 파일 크기를 늘리거나 줄일 수 있습니다. 확장의 경우, 새 파일 영역의 내용은 플랫폼에 따라 다릅니다 (대부분의 시스템에서, 추가 바이트는 0으로 채워집니다). 새 파일 크기가 반환됩니다.

버전 3.5에서 변경: 윈도우는 이제 확장 시 파일을 0으로 채웁니다.

writable()¶: 스트림이 쓰기를 지원하면 True를 반환합니다. False이면, write()와 truncate()는 OSError를 발생시킵니다.

writelines(lines, /)¶: 스트림에 줄 리스트를 씁니다. 줄 구분자는 추가되지 않아서, 제공된 각 줄 끝에 줄 구분자가 있는 것이 일반적입니다.

__del__()¶: 객체 파괴를 준비합니다. IOBase는 인스턴스의 close() 메서드를 호출하는 이 메서드의 기본 구현을 제공합니다.

class io.RawIOBase¶

원시 바이너리 스트림의 베이스 클래스. IOBase를 상속합니다.

원시 바이너리 스트림은 일반적으로 하부 OS 장치나 API에 대한 저수준 액세스를 제공하며, 이것을 고수준 프리미티브로 캡슐화하려고 하지 않습니다 (이 기능은 이 페이지에서 나중에 설명할 버퍼링 된 바이너리 스트림과 텍스트 스트림에서 고수준으로 수행됩니다).

RawIOBase는 IOBase에서 온 것 외에 이 메서드를 제공합니다:

read(size=-1, /)¶

객체에서 최대 size 바이트를 읽고 반환합니다. 참고로, size*가 지정되지 않았거나 -1이면, EOF까지의 모든 바이트가 반환됩니다. 그렇지 않으면, 하나의 시스템 호출만 수행됩니다. 운영 체제 시스템 호출이 *size 바이트 미만을 반환하는 경우 size 바이트 미만이 반환될 수 있습니다.

시스템 호출이 인터럽트 되어도 단 하나의 시스템 호출만 시도하되, 시그널 핸들러가 예외를 발생시키지 않으면 재시도합니다 (근거는 PEP 475\를 참조하십시오). 이는 운영 체제 호출이 size 바이트 미만을 반환할 경우 size 바이트 미만이 반환될 수 있음을 의미합니다.

0바이트가 반환되고, size가 0이 아니면, 파일의 끝을 나타냅니다. 객체가 비 블로킹 모드이고 사용 가능한 바이트가 없으면 None이 반환됩니다.

기본 구현은 readall()과 readinto()로 위임합니다.

readall()¶

필요한 경우 스트림에 대한 다중 호출을 사용하여, EOF까지 스트림의 모든 바이트를 읽고 반환합니다.

만약 0 바이트가 반환된다면 파일의 끝을 나타냅니다. 객체가 비 블로킹 모드이고 하부의 read() 가 바이트가 사용 가능하지함을 나타내는 None 을 반환하는 경우, None 이 반환됩니다.

readinto(b, /)¶

미리 할당되고, 쓰기 가능한 바이트열류 객체 b\로 바이트를 읽고, 읽은 바이트 수를 반환합니다. 예를 들어, b\는 bytearray\일 수 있습니다.

0 이 반환되고 len(b) 가 0 이 아니면, 이는 파일의 끝을 나타냅니다. 객체가 비 블로킹 모드이고 사용 가능한 바이트가 없으면, None 이 반환됩니다.

write(b, /)¶: 주어진 바이트열류 객체, b를 하부 원시 스트림에 쓰고, 쓴 바이트 수를 반환합니다. 하부 원시 스트림의 특성에 따라, 특히 비 블로킹 모드이면 바이트 단위로 b의 길이보다 짧을 수 있습니다. 원시 스트림이 블록 하지 않도록 설정되었고 단일 바이트를 당장 쓸 수 없으면 None이 반환됩니다. 호출자는 이 메서드가 반환된 후 b를 해제하거나 변경할 수 있어서, 구현은 메서드 호출 중에만 b에 액세스해야 합니다.

경고

이 함수는 모든 바이트가 쓰여지거나 예외가 발생함을 보장하지 않습니다. 호출자는 반환 값을 확인하고, 그 값이 b\의 길이보다 작으면, 모든 미작성 바이트가 전송될 때까지 추가 쓰기 호출로 루프를 구현할 수 있습니다. 바이너리 I/O 및 :ref:`text-io`와 같은 높은 수준의 I/O 객체는 재시도 동작을 구현합니다.

class io.BufferedIOBase¶

어떤 종류의 버퍼링을 지원하는 바이너리 스트림의 베이스 클래스. IOBase를 상속합니다.

RawIOBase`와 주요 차이점은, :meth:`read, readinto(), 그리고 write() 메서드는 요청된 만큼의 입력을 읽으려고 (각각) 시도하거나 제공된 모든 데이터를 방출한다는 것입니다.

게다가, 하부 원시 스트림이 비 블로킹 모드인 경우, 시스템이 블록할 것으로 예상되는 write() 는 BlockingIOError.characters_written 을 포함하여 BlockingIOError 를 발생시키고, read() 는 지금까지 읽은 데이터를 반환하거나 데이터가 사용 가능하지 않으면 None 을 반환합니다.

또한, read() 메서드에는 readinto()로 위임하는 기본 구현이 없습니다.

일반적인 BufferedIOBase 구현은 RawIOBase 구현에서 상속하지 말고, BufferedWriter와 BufferedReader처럼 감싸야 합니다.

BufferedIOBase는 IOBase에서 온 것 외에 다음 데이터 어트리뷰트와 메서드를 제공하거나 재정의합니다:

raw¶: BufferedIOBase 가 다루는 하부 원시 스트림 (RawIOBase 인스턴스). 이것은 BufferedIOBase API의 일부가 아니며 일부 구현에는 없을 수 있습니다.

detach()¶

하부 원시 스트림을 버퍼에서 분리하고 반환합니다.

원시 스트림이 분리된 후에는, 버퍼가 사용할 수 없는 상태가 됩니다.

BytesIO와 같은 일부 버퍼에는 이 메서드가 반환할 단일 원시 스트림 개념이 없습니다. 그들은 UnsupportedOperation을 발생시킵니다.

Added in version 3.1.

read(size=-1, /)¶

최대 size 바이트를 읽고 반환합니다. 인수가 생략되거나, None 이거나, 음수일 경우 가능한 한 많은 양을 읽습니다.

요청한 것보다 적은 바이트가 반환될 수 있습니다. 스트림이 이미 EOF에 도달했다면 빈 bytes 객체가 반환됩니다. 오류가 발생하면 여러 번 읽기가 수행될 수 있고 호출이 재시도될 수 있습니다. 자세한 내용은 :meth:`os.read`와 :pep:`475`를 참조하십시오. size 바이트 미만이 반환되는 것이 EOF가 임박했음을 의미하지는 않습니다.

최대한 많이 읽을 때는 기본 구현은 사용 가능한 경우 raw.readall``을 사용합니다 (이는 :meth:`RawIOBase.readall`을 구현해야 합니다). 그렇지 않으면 read가 ``None, 빈 bytes, 또는 재시도할 수 없는 오류를 반환할 때까지 루프를 돌려 읽습니다. 대부분의 스트림의 경우 이는 EOF까지가 목표지만, 비 블로킹 스트림의 경우 더 많은 데이터가 사용 가능해질 수 있습니다.

참고

하부 원시 스트림이 비 블로킹인 경우, 구현체는 데이터가 사용 가능하지 않으면 BlockingIOError 를 발생시키거나 None 을 반환할 수 있습니다. io 구현체는 None 을 반환합니다.

read1(size=-1, /)¶: 최대 size 바이트를 읽고 반환하며, PEP 475 에 따라 readinto() 를 호출하는데, 이는 EINTR 이 발생할 경우 재시도할 수 있습니다. size 가 -1 이거나 제공되지 않은 경우, 구현체는 size 에 임의의 값을 선택합니다.

참고

하부 원시 스트림이 비 블로킹인 경우, 구현체는 데이터가 사용 가능하지 않으면 BlockingIOError 를 발생시키거나 None 을 반환할 수 있습니다. io 구현체는 None 을 반환합니다.

readinto(b, /)¶

미리 할당되고, 쓰기 가능한 바이트열류 객체 b로 바이트를 읽고 읽은 바이트 수를 반환합니다. 예를 들어, b는 bytearray일 수 있습니다.

read()와 마찬가지로, 하부 원시 스트림이 대화식이 아닌 한, 여러 읽기가 수행될 수 있습니다.

하부 원시 스트림이 비 블로킹 모드이고, 현재 사용 가능한 데이터가 없으면 BlockingIOError 가 발생합니다.

readinto1(b, /)¶

하부 원시 스트림의 read() (또는 readinto()) 메서드를 최대 한 번만 호출하여, 미리 할당된 쓰기 가능한 바이트열류 객체 b로 바이트를 읽습니다. 읽은 바이트 수를 반환합니다.

하부 원시 스트림이 비 블로킹 모드이고, 현재 사용 가능한 데이터가 없으면 BlockingIOError 가 발생합니다.

Added in version 3.5.

write(b, /)¶

주어진 바이트열류 객체, b를 쓰고 기록된 바이트 수를 반환합니다 (쓰기에 실패하면 OSError가 발생하기 때문에 항상 바이트 단위로 b 길이와 같습니다). 실제 구현에 따라, 이러한 바이트는 하부 스트림에 쉽게 쓸 수 있거나, 성능과 지연 이유로 버퍼에 보관될 수 있습니다.

비 블로킹 모드에서, 데이터를 원시 스트림에 기록해야 하지만 원시 스트림이 블로킹 없이 모든 데이터를 받아들일 수 없으면, BlockingIOError 가 발생합니다.

호출자는 이 메서드가 반환된 후 b를 해제하거나 변경할 수 있어서, 구현은 메서드 호출 중에만 b에 액세스해야 합니다.

원시 파일 I/O¶

class io.FileIO(name, mode='r', closefd=True, opener=None)¶

바이트 데이터를 포함하는 OS 수준 파일을 나타내는 원시 바이너리 스트림입니다. :class:`RawIOBase`에서 상속받고 낮은 수준의 접근 방식을 구현합니다. 이는 :meth:`~RawIOBase.write`가 모든 바이트가 쓰여질 것을 보장하지 않으며, 하부 파일에 더 많은 바이트가 존재할 수 있음에도 불구하고 :meth:`~RawIOBase.read`가 요청한 것보다 적은 바이트를 읽을 수 있음을 의미합니다. “모두 쓰기” 및 “최소히 읽기” 동작을 얻으려면 :ref:`binary-io`를 사용하십시오.

name은 다음 두 가지 중 하나일 수 있습니다:

열릴 파일의 경로를 나타내는 문자열이나 bytes 객체. 이 경우 closefd는 True(기본값)이어야 합니다. 그렇지 않으면 에러가 발생합니다.
결과 FileIO 객체가 액세스할 기존 OS 수준 파일 기술자의 번호를 나타내는 정수. FileIO 객체가 닫힐 때, closefd가 False로 설정되어 있지 않은 한 이 fd도 닫힙니다.

mode는 읽기(기본값), 쓰기, 배타적 생성 또는 덧붙이기를 위해 'r', 'w', 'x' 또는 'a'일 수 있습니다. 쓰기나 덧붙이기로 열 때 파일이 존재하지 않으면 만들어집니다; 쓰기 위해 열면 파일이 잘립니다. 생성을 위해 열었을 때 파일이 이미 존재하면 FileExistsError 가 발생합니다. 생성하기 위해 파일을 여는 것은 쓰기를 의미하므로, 이 모드는 'w'와 유사한 방식으로 작동합니다. 읽기와 쓰기를 동시에 허락하려면 '+'를 모드에 추가하십시오.

콜러블을 opener로 전달하여 사용자 정의 오프너를 사용할 수 있습니다. 그러면 파일 객체의 하부 파일 기술자는 (name, flags)로 opener를 호출하여 얻습니다. opener는 열린 파일 기술자를 반환해야 합니다 (os.open을 opener로 전달하면 None을 전달하는 것과 유사한 기능이 됩니다).

새로 만들어진 파일은 상속 불가능합니다.

opener 매개 변수 사용에 대한 예는 open() 내장 함수를 참조하십시오.

경고

:class:`FileIO`는 낮은 수준의 I/O 객체이며, :meth:`~RawIOBase.read`와 :meth:`~RawIOBase.write`와 같은 멤버는 “모두 쓰기” 및 “최소히 읽기” 동작을 구현하기 위해 리트라이 루프 내에서 반환 값을 명시적으로 확인해야 합니다. 높은 수준의 I/O 객체인 :ref:`binary-io`와 :ref:`text-io`는 재시도 동작을 구현합니다.

버전 3.3에서 변경: opener 매개 변수가 추가되었습니다. 'x' 모드가 추가되었습니다.

버전 3.4에서 변경: 이제 파일이 상속 불가능합니다.

FileIO는 RawIOBase와 IOBase에서 온 것 외에 다음 데이터 어트리뷰트를 제공합니다:

mode¶: 생성자에 제공된 모드.

name¶: 파일 이름. 생성자에 이름이 지정되지 않으면 파일의 파일 기술자입니다.

버퍼링 된 스트림¶

버퍼링 된 I/O 스트림은 원시 I/O보다 I/O 장치에 대한 더 고수준의 인터페이스를 제공합니다.

class io.BytesIO(initial_bytes=b'')¶

인 메모리 바이트 버퍼를 사용하는 바이너리 스트림. BufferedIOBase를 상속합니다. close() 메서드가 호출될 때 버퍼가 폐기됩니다.

선택적 인자 initial_bytes는 초기 데이터를 포함하는 바이트열류 객체입니다.

메서드는 외부 잠금 없이 :term:`free-threaded builds <free-threaded build>`에서 사용될 수 있습니다.

BytesIO는 BufferedIOBase와 IOBase의 메서드 외에 다음 메서드를 제공하거나 재정의합니다:

getbuffer()¶

복사하지 않고 버퍼의 내용에 대한 읽을 수 있고 쓸 수 있는 뷰를 반환합니다. 또한, 뷰를 변경하면 버퍼의 내용이 투명하게 갱신됩니다:

>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'

참고

뷰가 존재하는 한, BytesIO 객체의 크기를 조정하거나 닫을 수 없습니다.

Added in version 3.2.

getvalue()¶: 버퍼의 전체 내용을 포함하는 bytes를 반환합니다.

read1(size=-1, /)¶: BytesIO에서, 이것은 read()와 같습니다.

버전 3.7에서 변경: size 인자는 이제 선택적입니다.

readinto1(b, /)¶: BytesIO에서, 이것은 readinto()와 같습니다.

Added in version 3.5.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶

읽을 수 있고 탐색할 수 없는(non seekable) RawIOBase 원시 바이너리 스트림에 대한 고수준의 액세스를 제공하는 버퍼링 된 바이너리 스트림. BufferedIOBase를 상속합니다.

이 객체에서 데이터를 읽을 때, 하부 원시 스트림에서 더 많은 양의 데이터가 요청되어, 내부 버퍼에 보관될 수 있습니다. 버퍼링 된 데이터는 후속 읽기에서 직접 반환될 수 있습니다.

생성자는 주어진 읽을 수 있는 raw 스트림과 buffer_size에 대해 BufferedReader를 만듭니다. buffer_size를 생략하면, DEFAULT_BUFFER_SIZE가 사용됩니다.

BufferedReader는 BufferedIOBase와 IOBase의 메서드 외에 다음 메서드를 제공하거나 재정의합니다:

peek(size=0, /)¶: 위치(position)를 전진시키지 않고 스트림에서 바이트를 반환합니다. 반환되는 바이트 수는 요청한 것보다 적거나 많을 수 있습니다. 하부 원시 스트림이 비 블로킹이고 작업이 블록될 경우, 빈 바이트를 반환합니다.

read(size=-1, /)¶: :class:`BufferedReader`에서, 이것은 :meth:`io.BufferedIOBase.read`와 같습니다.

read1(size=-1, /)¶: :class:`BufferedReader`에서, 이것은 :meth:`io.BufferedIOBase.read1`와 같습니다.

버전 3.7에서 변경: size 인자는 이제 선택적입니다.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶

쓸 수 있고 탐색할 수 없는(non seekable) RawIOBase 원시 바이너리 스트림에 대한 고수준 액세스를 제공하는 버퍼링 된 바이너리 스트림. BufferedIOBase를 상속합니다.

이 객체에 쓸 때, 데이터는 일반적으로 내부 버퍼에 배치됩니다. 버퍼는 다음과 같은 다양한 조건에서 하부 RawIOBase 객체에 기록됩니다:

계류 중인 모든 데이터에 비해 버퍼가 너무 작아질 때;
flush()가 호출될 때;
seek()이 요청될 때 (BufferedRandom 객체의 경우);
BufferedWriter 객체가 닫히거나 파괴될 때.

생성자는 주어진 쓰기 가능한 raw 스트림에 대해 BufferedWriter를 만듭니다. buffer_size가 제공되지 않으면, 기본값은 DEFAULT_BUFFER_SIZE입니다.

BufferedWriter는 BufferedIOBase와 IOBase의 메서드 외에 다음 메서드를 제공하거나 재정의합니다:

flush()¶: 버퍼에 있는 바이트를 원시 스트림으로 강제 출력합니다. 원시 스트림이 블록되면 BlockingIOError를 발생시켜야 합니다.

write(b, /)¶: 주어진 바이트열류 객체, b 를 쓰고 쓰여진 바이트 수를 반환합니다. 비블로킹 모드에서는 버퍼가 쓸려 나가야 하지만 원시 스트림이 블록될 경우, BlockingIOError.characters_written 가 설정된 BlockingIOError 가 발생합니다.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶

사용 가능한 RawIOBase 원시 바이너리 스트림에 대한 고수준의 액세스를 제공하는, BufferedIOBase 인터페이스를 구현하는 버퍼링된 바이너리 스트림입니다.

생성자는 첫 번째 인자로 주어진 탐색 가능한 원시 스트림에 대한 판독기(reader)와 기록기(writer)를 만듭니다. buffer_size를 생략하면 기본값은 DEFAULT_BUFFER_SIZE입니다.

BufferedRandom은 BufferedReader나 BufferedWriter가 수행 할 수 있는 모든 작업을 수행할 수 있습니다. 또한, seek()과 tell()이 구현되도록 보장됩니다.

class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)¶

하나는 읽을 수 있고, 다른 하나는 쓸 수 있는, 두 개의 탐색할 수 없는 (non seekable) RawIOBase 원시 바이너리 스트림에 대한 고수준 액세스를 제공하는 버퍼링 된 바이너리 스트림. BufferedIOBase를 상속합니다.

reader와 writer는 각각 읽고 쓸 수 있는 RawIOBase 객체입니다. buffer_size가 생략되면 기본값은 DEFAULT_BUFFER_SIZE입니다.

BufferedRWPair는 UnsupportedOperation을 발생시키는 detach()를 제외한 모든 BufferedIOBase 의 메서드를 구현합니다.

경고

BufferedRWPair는 하부 원시 스트림에 대한 동기화된 액세스를 시도하지 않습니다. reader와 writer로 같은 객체를 전달해서는 안 됩니다; 대신 BufferedRandom을 사용하십시오.

텍스트 I/O¶

class io.TextIOBase¶

텍스트 스트림의 베이스 클래스. 이 클래스는 스트림 I/O를 위한 문자와 줄 기반 인터페이스를 제공합니다. IOBase를 상속합니다.

TextIOBase는 IOBase에서 온 것 외에 다음 데이터 어트리뷰트와 메서드를 제공하거나 재정의합니다:

encoding¶: 스트림의 바이트열을 문자열로 디코딩하고, 문자열을 바이트열로 인코딩하는 데 사용되는 인코딩의 이름.

errors¶: 디코더나 인코더의 에러 설정.

newlines¶: 지금까지 번역된 줄 넘김을 나타내는, 문자열, 문자열 튜플 또는 None. 구현과 초기 생성자 플래그에 따라, 사용하지 못할 수 있습니다.

buffer¶: TextIOBase`가 다루는 하부 바이너리 버퍼 ( :class:`BufferedIOBase 또는 RawIOBase 인스턴스). 이것은 TextIOBase API의 일부가 아니며 일부 구현에는 존재하지 않을 수 있습니다.

detach()¶

하부 바이너리 버퍼를 TextIOBase와 분리하여 반환합니다.

하부 버퍼가 분리된 후에는, TextIOBase는 사용할 수 없는 상태가 됩니다.

StringIO와 같은 일부 TextIOBase 구현에는 하부 버퍼 개념이 없을 수 있으며 이 메서드를 호출하면 UnsupportedOperation이 발생합니다.

Added in version 3.1.

read(size=-1, /)¶: 스트림에서 최대 size 문자를 단일 str로 읽고 반환합니다. size가 음수이거나 None이면 EOF까지 읽습니다.

readline(size=-1, /)¶

줄 넘김이나 EOF까지 읽고 단일 str을 반환합니다. 스트림이 이미 EOF에 있으면, 빈 문자열이 반환됩니다.

size가 지정되면, 최대 size 문자를 읽습니다.

seek(offset, whence=SEEK_SET, /)¶

스트림 위치를 지정된 offset으로 변경합니다. 동작은 whence 매개 변수에 따라 다릅니다. whence의 기본값은 SEEK_SET입니다.

SEEK_SET이나 0: 스트림의 시작부터 탐색합니다 (기본값); offset은 TextIOBase.tell()이 반환한 숫자이거나 0이어야 합니다. 다른 offset 값은 정의되지 않은 동작을 생성합니다.
SEEK_CUR이나 1: 현재 위치로 “seek” 합니다; offset은 0이어야 하며, 이는 아무런 일도 하지 않습니다 (다른 모든 값은 지원되지 않습니다).
SEEK_END나 2: 스트림의 끝으로 seek 합니다; offset은 0이어야 합니다 (다른 모든 값은 지원되지 않습니다).

새로운 절대 위치를 불투명한 숫자로 반환합니다.

Added in version 3.1: SEEK_* 상수.

tell()¶: 현재 스트림 위치를 불투명한 숫자로 반환합니다. 숫자는 일반적으로 하부 바이너리 저장소의 바이트 수를 나타내지 않습니다.

write(s, /)¶: 문자열 s를 스트림에 쓰고 쓴 문자 수를 반환합니다.

class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)¶

BufferedIOBase 버퍼링 된 바이너리 스트림에 대한 고수준의 액세스를 제공하는 버퍼링 된 텍스트 스트림. TextIOBase를 상속합니다.

encoding 은 스트림이 디코딩되거나 인코딩되는 인코딩의 이름을 제공합니다. UTF-8 Mode 에서는 기본적으로 UTF-8을 사용합니다. 그렇지 않은 경우, locale.getencoding() 을 기본값으로 사용합니다. :encoding=”locale”`을 사용하면 현재 로케일의 인코딩을 명시적으로 지정할 수 있습니다. 더 자세한 내용은 :ref:`io-text-encoding 을 참조하세요.

errors는 인코딩과 디코딩 에러 처리 방법을 지정하는 선택적 문자열입니다. 인코딩 에러가 있을 때 ValueError 예외를 발생시키려면 'strict'를 전달하고 (기본값 None은 같은 효과를 줍니다), 에러를 무시하려면 'ignore'를 전달하십시오. (인코딩 에러를 무시하면 데이터가 손실될 수 있음에 유의하십시오.) 'replace'는 잘못된 데이터가 있는 곳에 대체 마커(가령 '?')가 삽입되도록 합니다. 'backslashreplace'는 잘못된 데이터를 역 슬래시 이스케이프 시퀀스로 대체합니다. 기록할 때, 'xmlcharrefreplace'(적절한 XML 문자 참조로 대체합니다)나 'namereplace'(\N{...} 이스케이프 시퀀스로 대체합니다)를 사용할 수 있습니다. codecs.register_error()로 등록된 다른 에러 처리 이름도 유효합니다.

newline은 줄 끝 처리 방법을 제어합니다. None, '', '\n', '\r' 및 '\r\n' 일 수 있습니다. 다음과 같이 작동합니다:

스트림에서 입력을 읽을 때, newline이 None이면, 유니버설 줄 넘김 모드가 활성화됩니다. 입력의 줄은 '\n', '\r' 또는 '\r\n'으로 끝날 수 있으며, 호출자에게 반환되기 전에 '\n'으로 변환됩니다. newline이 ''이면, 유니버설 줄 넘김 모드가 활성화되지만, 줄 끝은 변환되지 않은 상태로 호출자에게 반환됩니다. newline이 다른 유효한 값이면, 입력 줄은 주어진 문자열로만 끝나고, 줄 끝은 변환되지 않은 상태로 호출자에게 반환됩니다.
스트림에 출력을 기록할 때, newline이 None이면, 기록되는 모든 '\n' 문자는 시스템 기본 줄 구분자 os.linesep으로 변환됩니다. newline이 ''이나 '\n'이면, 변환이 수행되지 않습니다. newline이 다른 유효한 값이면, 기록되는 모든 '\n' 문자는 주어진 문자열로 변환됩니다.

line_buffering이 True이면, write 호출에 줄 넘김 문자나 캐리지 리턴이 포함되어 있으면 flush()가 암시됩니다.

write_through가 True이면, write()에 대한 호출은 버퍼링 되지 않음이 보장됩니다: TextIOWrapper 객체에 기록된 모든 데이터는 즉시 하부 바이너리 buffer로 처리됩니다.

버전 3.3에서 변경: write_through 인자가 추가되었습니다.

버전 3.3에서 변경: 기본 encoding은 이제 locale.getpreferredencoding() 대신 locale.getpreferredencoding(False)입니다. locale.setlocale()을 사용하여 임시 로케일 인코딩을 변경하지 않고, 사용자가 선호하는 인코딩 대신 현재 로케일 인코딩을 사용합니다.

버전 3.10에서 변경: encoding 인수는 이제 “locale” 더미 인코딩 이름을 지원합니다.

참고

하부 원시 스트림이 비블로킹인 경우, 읽기 작업이 즉시 완료될 수 없으면 :exc:`BlockingIOError`가 발생할 수 있습니다.

TextIOWrapper는 TextIOBase와 IOBase에서 온 것 외에 다음 데이터 어트리뷰트와 메서드를 제공합니다:

line_buffering¶: 줄 버퍼링이 활성화되었는지 여부.

write_through¶: 쓰기가 하부 바이너리 버퍼로 즉시 전달되는지 여부.

Added in version 3.7.

reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)¶

encoding, errors, newline, line_buffering 및 write_through에 대한 새로운 설정을 사용하여 이 텍스트 스트림을 재구성합니다.

encoding이 지정되었지만, errors가 지정되지 않았을 때 errors='strict'가 사용되는 것을 제외하고, 지정되지 않은 매개 변수는 현재 설정을 유지합니다.

스트림에서 일부 데이터를 이미 읽었다면 encoding이나 newline을 변경할 수 없습니다. 반면에, 기록 후의 encoding 변경은 가능합니다.

이 메서드는 새 매개 변수를 설정하기 전에 묵시적 스트림 플러시를 수행합니다.

Added in version 3.7.

버전 3.11에서 변경: 이 메서드는 encoding="locale" 옵션을 지원합니다.

seek(cookie, whence=os.SEEK_SET, /)¶

스트림 위치를 설정합니다. 새 스트림 위치를 :class:`int`로 반환합니다.

다음 인자 조합으로 네 가지 연산이 지원됩니다:

seek(0, SEEK_SET): 스트림의 시작으로 되감을 기합니다.
seek(cookie, SEEK_SET): 이전 위치를 복원합니다. cookie 는 tell() 이 반환하는 숫자인 것이 확실해야 합니다.
seek(0, SEEK_END): 스트림의 끝으로 빠르게 건너뜁니다.
seek(0, SEEK_CUR): 현재의 스트림 위치를 변경하지 않습니다.

다른 인자 조합은 모두 유효하지 않으며 예외를 발생시킬 수 있습니다.

tell()¶: Return the stream position as an opaque number. The return value of tell() can be given as input to seek(), to restore a previous stream position.

class io.StringIO(initial_value='', newline='\n')¶

인 메모리 텍스트 버퍼를 사용하는 텍스트 스트림. TextIOBase를 상속합니다.

close() 메서드가 호출될 때 텍스트 버퍼가 폐기됩니다.

버퍼의 초깃값은 initial_value를 제공하여 설정할 수 있습니다. 줄 바꿈 변환이 활성화되면, 줄 바꿈은 write() 한 것처럼 인코딩됩니다. 스트림은 버퍼의 시작 부분에 위치하며, 이는 기존 파일을 w+ 모드로 여는 것을 흉내내어 시작부터 즉시 쓰기나 초기 값을 텊어쓰는 쓰기에 준비되도록 합니다. a+ 모드로 파일을 여는 것을 흉내내려면, f.seek(0, io.SEEK_END)을 사용하여 스트림을 버퍼의 끝으로 재위치 시키세요.

출력을 스트림에 쓸 때, newline이 None이면, 모든 플랫폼에서 줄 넘김이 \n로 기록된다는 점을 제외하고는, newline 인자는 TextIOWrapper에서 처럼 작동합니다.

StringIO는 TextIOBase와 IOBase의 메서드 외에 이 메서드를 제공합니다:

getvalue()¶: 버퍼의 전체 내용을 포함하는 str을 반환합니다. 스트림 위치는 변경되지 않지만, 줄 넘김은 read()와 같이 디코딩됩니다.

사용 예:

import io

output = io.StringIO()
output.write('First line.\n')
print('Second line.', file=output)

# 파일 내용을 꺼냅니다 -- 'First line.\nSecond line.\n' 이 됩니다.
contents = output.getvalue()

# 객체를 닫고 메모리 버퍼를 폐기합니다 --
# .getvalue() 는 이제 예외를 발생시킵니다.
output.close()

class io.IncrementalNewlineDecoder¶: 유니버설 줄 넘김 모드의 줄 넘김 디코딩을 하는 도우미 코덱. codecs.IncrementalDecoder를 상속합니다.

정적 타이핑¶

다음 프로토콜들은 간단한 스트림 읽기 또는 쓰기 작업을 위한 함수 및 메서드 인자 주석(annotating)에 사용될 수 있습니다. 이들은 :deco:`typing.runtime_checkable`으로 장식됩니다.

class io.Reader[T]¶

파일 또는 기타 입력 스트림에서 읽기 위한 제네릭 프로토콜입니다. T 는 보통 str 또는 bytes 이지만, 스트림에서 읽을 수 있는 모든 유형이 될 수 있습니다.

Added in version 3.14.

read()¶
read(size, /): 입력 스트림에서 데이터를 읽고 이를 반환합니다. size 가 지정된 경우, 이는 정수형이어야 하며 최대 size 개의 항목(바이트/문자)이 읽힙니다.

예를 들면

def read_it(reader: Reader[str]):
    data = reader.read(11)
    assert isinstance(data, str)

class io.Writer[T]¶

파일 또는 기타 출력 스트림에 쓰기 위한 제네릭 프로토콜입니다. T 는 보통 str 또는 bytes 이지만, 스트림에 쓸 수 있는 모든 유형이 될 수 있습니다.

Added in version 3.14.

write(data, /)¶: data 를 출력 스트림에 쓰고, 쓰여진 항목(바이트/문자)의 수를 반환합니다.

예를 들면

def write_binary(writer: Writer[bytes]):
    writer.write(b"Hello world!\n")

정적 타입 검사에 사용될 수 있는 기타 I/O 관련 프로토콜 및 클래스는 :ref:`typing-io`를 참조하세요.

성능¶

이 섹션에서는 제공된 구상 I/O 구현의 성능에 대해 논합니다.

바이너리 I/O¶

사용자가 단일 바이트를 요청할 때조차 큰 데이터 청크만 읽고 써서, 버퍼링 된 I/O는 운영 체제의 버퍼링 되지 않은 I/O 루틴을 호출하고 실행할 때의 비효율성을 숨깁니다. 이득은 OS 와 수행되는 I/O 종류에 따라 다릅니다. 예를 들어, 리눅스와 같은 일부 최신 OS에서는, 버퍼링 되지 않은 디스크 I/O는 버퍼링 된 I/O만큼 빠를 수 있습니다. 그러나 요점은 버퍼링 된 I/O가 플랫폼과 배경 장치와 관계없이 예측 가능한 성능을 제공한다는 것입니다. 따라서, 바이너리 데이터에는 버퍼링 되지 않은 I/O보다는 버퍼링 된 I/O를 사용하는 것이 거의 항상 바람직합니다.

텍스트 I/O¶

바이너리 저장소(가령 파일)에 대한 텍스트 I/O는 같은 저장소에 대한 바이너리 I/O보다 상당히 느린데, 문자 코덱을 사용하여 유니코드와 바이너리 데이터 간의 변환이 필요하기 때문입니다. 이것은 큰 로그 파일과 같은 많은 양의 텍스트 데이터를 처리할 때 드러날 수 있습니다. 또한, tell()과 seek()은 사용된 재구성 알고리즘으로 인해 상당히 느립니다.

그러나, StringIO는 네이티브 인 메모리 유니코드 컨테이너이며 BytesIO와 비슷한 속도를 나타냅니다.

다중 스레드¶

FileIO 객체는 감싼 운영 체제 호출(가령 유닉스의 read(2))이 스레드 안전하다면 스레드 안전합니다.

바이너리 버퍼링 된 객체(BufferedReader, BufferedWriter, BufferedRandom 및 BufferedRWPair 의 인스턴스)는 록을 사용하여 내부 구조를 보호합니다; 따라서 여러 스레드에서 동시에 호출하는 것이 안전합니다.

TextIOWrapper 객체는 스레드 안전하지 않습니다.

재진입¶

바이너리 버퍼링 된 객체(BufferedReader, BufferedWriter, BufferedRandom 및 BufferedRWPair 의 인스턴스)는 재진입할 수 없습니다. 재진입 호출이 정상적인 상황에서는 발생하지 않지만, signal 처리기에서 I/O를 수행한다면 발생할 수 있습니다. 스레드가 이미 액세스 중인 버퍼링 된 객체에 다시 진입하려고 하면, RuntimeError가 발생합니다. 이것이 다른 스레드가 버퍼링 된 객체에 진입하는 것을 막는 것은 아님에 유의하십시오.

open() 함수는 버퍼링 된 객체를 TextIOWrapper 안에 감싸기 때문에, 위의 내용은 텍스트 파일에도 묵시적으로 확장됩니다. 여기에는 표준 스트림이 포함되므로 내장 print() 함수에도 영향을 줍니다.

io — 스트림 작업을 위한 핵심 도구¶

개요¶

텍스트 I/O¶

바이너리 I/O¶

원시 I/O¶

텍스트 인코딩¶

선택적 인코딩 경고¶

고수준 모듈 인터페이스¶

클래스 위계¶

I/O 베이스 클래스¶

원시 파일 I/O¶

버퍼링 된 스트림¶

텍스트 I/O¶

정적 타이핑¶

성능¶

바이너리 I/O¶

텍스트 I/O¶

다중 스레드¶

재진입¶

분실물 보관소

`io` — 스트림 작업을 위한 핵심 도구¶