"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")

텍스트 스트림 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" 설명서에 자세히 설명되어 있습니다.


고수준 모듈 인터페이스
======================

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"을 발생시킵니다.

io.open_code(path)

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

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

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

   버전 3.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" 및      | "close", "closed", "__enter__", "__exit__",        |
|                           |                    | "truncate"               | "flush", "isatty", "__iter__", "__next__",         |
|                           |                    |                          | "readable", "readline", "readlines", "seekable",   |
|                           |                    |                          | "tell", "writable" 및 "writelines"                 |
+---------------------------+--------------------+--------------------------+----------------------------------------------------+
| "RawIOBase"               | "IOBase"           | "readinto"와 "write"     | 상속된 "IOBase" 메서드, "read" 및 "readall"        |
+---------------------------+--------------------+--------------------------+----------------------------------------------------+
| "BufferedIOBase"          | "IOBase"           | "detach", "read",        | 상속된 "IOBase" 메서드, "readinto" 및 "readinto1"  |
|                           |                    | "read1" 및 "write"       |                                                    |
+---------------------------+--------------------+--------------------------+----------------------------------------------------+
| "TextIOBase"              | "IOBase"           | "detach", "read",        | 상속된 "IOBase" 메서드, "encoding", "errors" 및    |
|                           |                    | "readline" 및 "write"    | "newlines"                                         |
+---------------------------+--------------------+--------------------------+----------------------------------------------------+


I/O 베이스 클래스
-----------------

class io.IOBase

   The abstract base class for all I/O classes.

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

   "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*를 초과하면 더는 줄을 읽지 않습니다.

      *hint* values of "0" or less, as well as "None", are treated as
      no hint.

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

   seek(offset, whence=SEEK_SET, /)

      스트림 위치를 지정된 바이트 *offset*으로 변경합니다. *offset*은
      *whence*가 가리키는 위치를 기준으로 해석됩니다. *whence*의 기본
      값은 "SEEK_SET"입니다. *whence*의 값은 다음과 같습니다:

      * "SEEK_SET" 또는 "0" -- 스트림의 시작(기본값); *offset*은 0이거
        나 양수여야 합니다

      * "SEEK_CUR" 또는 "1" -- 현재 스트림 위치; *offset*은 음수일 수
        있습니다

      * "SEEK_END" 또는 "2" -- 스트림의 끝; *offset*은 일반적으로 음수
        입니다

      새로운 절대 위치를 반환합니다.

      버전 3.1에 추가: "SEEK_*" 상수.

      버전 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

   Base class for raw binary streams.  It inherits "IOBase".

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

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

   read(size=-1, /)

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

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

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

   readall()

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

   readinto(b, /)

      미리 할당되고, 쓰기 가능한 *바이트열류 객체* *b*로 바이트를 읽고
      읽은 바이트 수를 반환합니다. 예를 들어, *b*는 "bytearray"일 수
      있습니다. 객체가 비 블로킹 모드이고 사용 가능한 바이트가 없으면,
      "None"이 반환됩니다.

   write(b, /)

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

class io.BufferedIOBase

   Base class for binary streams that support some kind of buffering.
   It inherits "IOBase".

   "RawIOBase"와의 주요 차이점은 메서드 "read()", "readinto()" 및
   "write()"는 요청된 만큼 많은 입력을 읽거나 주어진 출력을 모두 소비
   하려고 시도한다는 것입니다, 아마도 하나 이상의 시스템 호출을 하는
   비용을 치르고서라도.

   또한, 하부 원시 스트림이 비 블로킹 모드에 있고 충분한 데이터를 취하
   거나 제공할 수 없으면 이러한 메서드들은 "BlockingIOError"를 발생시
   킬 수 있습니다; "RawIOBase"의 메서드들과는 달리 "None"을 반환하지
   않습니다.

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

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

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

   raw

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

   detach()

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

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

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

      버전 3.1에 추가.

   read(size=-1, /)

      최대 *size* 바이트를 읽고 반환합니다. 인자가 생략되거나, "None"
      이거나 음수이면, EOF에 도달할 때까지 데이터를 읽고 반환합니다.
      스트림이 이미 EOF에 있으면 빈 "bytes" 객체가 반환됩니다.

      인자가 양수이고, 하부 원시 스트림이 대화식이 아니면, 바이트 수를
      충족시키기 위해 여러 원시 읽기가 수행될 수 있습니다 (EOF에 먼저
      도달하지 않는 한). 그러나 대화식 원시 스트림의 경우, 최대 하나의
      원시 읽기가 수행되고 짧은 결과가 EOF가 임박했음을 의미하지는 않
      습니다.

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

   read1(size=-1, /)

      하부 원시 스트림의 "read()" (또는 "readinto()") 메서드를 최대 한
      번만 호출하여, 최대 *size* 바이트를 읽고 반환합니다.
      "BufferedIOBase" 객체 위에 자체 버퍼링을 구현하는 경우 유용할 수
      있습니다.

      *size*가 "-1"(기본값)이면, 임의의 수의 바이트가 반환됩니다 (EOF
      에 도달하지 않았으면 0보다 큽니다).

   readinto(b, /)

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

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

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

   readinto1(b, /)

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

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

      버전 3.5에 추가.

   write(b, /)

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

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

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


원시 파일 I/O
-------------

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

   바이트열 데이터를 포함하는 OS 수준 파일을 나타내는 원시 바이너리 스
   트림. "RawIOBase"를 상속합니다.

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

   * 열릴 파일의 경로를 나타내는 문자열이나 "bytes" 객체. 이 경우
     closefd는 "True"(기본값)이어야 합니다. 그렇지 않으면 에러가 발생
     합니다.

   * 결과 "FileIO" 객체가 액세스할 기존 OS 수준 파일 기술자의 번호를
     나타내는 정수. FileIO 객체가 닫힐 때, *closefd*가 "False"로 설정
     되어 있지 않은 한 이 fd도 닫힙니다.

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

   이 클래스의 "read()" (양수 인자로 호출되었을 때), "readinto()" 및
   "write()" 메서드는 하나의 시스템 호출만 수행합니다.

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

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

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

   버전 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*는 초기 데이터를 포함하는 *바이트열류 객
   체*입니다.

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

   getbuffer()

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

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

      참고:

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

      버전 3.2에 추가.

   getvalue()

      버퍼의 전체 내용을 포함하는 "bytes"를 반환합니다.

   read1(size=-1, /)

      "BytesIO"에서, 이것은 "read()"와 같습니다.

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

   readinto1(b, /)

      "BytesIO"에서, 이것은 "readinto()"와 같습니다.

      버전 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, /)

      위치를 전진시키지 않고 스트림에서 바이트열을 반환합니다. 호출을
      충족시키기 위해 원시 스트림에서 최대 하나의 단일 읽기가 수행됩니
      다. 반환된 바이트 수는 요청된 것보다 적거나 많을 수 있습니다.

   read(size=-1, /)

      *size* 바이트를, *size*가 주어지지 않았거나 음수이면, EOF까지 혹
      은 읽기 호출이 비 블로킹 모드에서 블록 되기 전까지 읽고 반환합니
      다.

   read1(size=-1, /)

      원시 스트림에 대한 한 번의 호출로 최대 *size* 바이트를 읽고 반환
      합니다. 적어도 1바이트가 버퍼링 되어 있으면, 버퍼링 된 바이트만
      반환됩니다. 그렇지 않으면, 하나의 원시 스트림 읽기 호출이 수행됩
      니다.

      버전 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" 가 발생합니다.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

   탐색할 수 있는 (seekable) "RawIOBase" 원시 바이너리 스트림에 고수준
   의 액세스를 제공하는 버퍼링 된 바이너리 스트림. "BufferedReader"와
   "BufferedWriter"를 상속합니다.

   생성자는 첫 번째 인자로 주어진 탐색 가능한 원시 스트림에 대한 판독
   기(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

   Base class for text streams.  This class provides a character and
   line based interface to stream I/O.  It inherits "IOBase".

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

   encoding

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

   errors

      디코더나 인코더의 에러 설정.

   newlines

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

   buffer

      "TextIOBase"가 다루는 하부 바이너리 버퍼 ("BufferedIOBase" 인스
      턴스). 이것은 "TextIOBase" API의 일부가 아니며 일부 구현에는 없
      을 수 있습니다.

   detach()

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

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

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

      버전 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이
        어야 합니다 (다른 모든 값은 지원되지 않습니다).

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

      버전 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*은 스트림이 디코딩이나 인코딩될 인코딩의 이름을 제공합니
   다. 기본값은 "locale.getpreferredencoding(False)"입니다.

   *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()"을
   사용하여 임시 로케일 인코딩을 변경하지 않고, 사용자가 선호하는 인코
   딩 대신 현재 로케일 인코딩을 사용합니다.

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

   line_buffering

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

   write_through

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

      버전 3.7에 추가.

   reconfigure(*[, encoding][, errors][, newline][,                      line_buffering][, write_through])

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

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

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

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

      버전 3.7에 추가.

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

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

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

   버퍼의 초깃값은 *initial_value*를 제공하여 설정할 수 있습니다. 줄
   바꿈 변환이 활성화되면, 줄 바꿈은 "write()" 한 것처럼 인코딩됩니다.
   스트림은 버퍼의 시작 부분에 위치합니다.

   출력을 스트림에 쓸 때, *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)

      # Retrieve file contents -- this will be
      # 'First line.\nSecond line.\n'
      contents = output.getvalue()

      # Close object and discard memory buffer --
      # .getvalue() will now raise an exception.
      output.close()

class io.IncrementalNewlineDecoder

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


성능
====

이 섹션에서는 제공된 구상 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보다 상당히 느린데, 문자 코덱을 사용하여 유니코드와 바이너리
데이터 간의 변환이 필요하기 때문입니다. 이것은 큰 로그 파일과 같은 많
은 양의 텍스트 데이터를 처리할 때 드러날 수 있습니다. 또한,
"TextIOWrapper.tell()"과 "TextIOWrapper.seek()"은 사용된 재구성 알고리
즘으로 인해 상당히 느립니다.

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


다중 스레드
-----------

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

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

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


재진입
------

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

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