예외 처리
*********

이 장에서 설명하는 함수를 사용하면 파이썬 예외를 처리하고 발생시킬 수
있습니다. 파이썬 예외 처리의 기본 사항을 이해하는 것이 중요합니다.
POSIX "errno" 변수와 비슷하게 작동합니다: 발생한 마지막 에러에 대한 전
역 표시기(스레드 당)가 있습니다. 대부분 C API 함수는 성공 시 이를 지우
지 않지만, 실패 시 에러의 원인을 나타내도록 설정합니다. 대부분 C API
함수는 에러 표시기도 반환합니다, 일반적으로 포인터를 반환해야 하면
"NULL", 정수를 반환하면 "-1"을 반환합니다 (예외: "PyArg_*()" 함수는 성
공하면 "1"을, 실패하면 "0"을 반환합니다).

구체적으로, 에러 표시기는 세 가지 객체 포인터로 구성됩니다: 예외 형,
예외 값 및 트레이스백 객체. 이러한 포인터들은 설정되지 않으면 "NULL"이
될 수 있습니다 (하지만 일부 조합은 금지되어 있습니다, 예를 들어 예외
형이 "NULL"이면 "NULL"이 아닌 트레이스백을 가질 수 없습니다).

호출한 일부 함수가 실패하여 함수가 실패해야 할 때, 일반적으로 에러 표
시기를 설정하지 않습니다; 호출된 함수가 이미 설정했습니다. 에러를 처리
하고 예외를 지우거나 보유한 모든 리소스(가령 객체 참조나 메모리 할당)
를 정리한 후 반환해야 할 책임이 있습니다; 에러를 처리할 준비가 되지 않
았을 때 정상적으로 계속되지 *않아야* 합니다. 에러로 인해 반환하면, 호
출자에게 에러가 설정되었음을 알리는 것이 중요합니다. 에러를 처리하지
않거나 신중하게 전파하지 않으면, 파이썬/C API에 대한 추가 호출이 의도
한 대로 작동하지 않을 수 있으며 알 수 없는 방식으로 실패할 수 있습니다
.

참고:

  에러 표시기는 "sys.exc_info()"의 결과가 **아닙니다**. 전자는 아직 포
  착되지 않은 (따라서 여전히 전파 중인) 예외에 해당하는 반면, 후자는
  포착된 후 (따라서 전파가 중단된) 예외를 반환합니다.


인쇄와 지우기
=============

void PyErr_Clear()

   에러 표시기를 지웁니다. 에러 표시기가 설정되어 있지 않으면 효과가
   없습니다.

void PyErr_PrintEx(int set_sys_last_vars)

   표준 트레이스백을 "sys.stderr"로 인쇄하고 에러 표시기를 지웁니다.
   에러가 "SystemExit"가 **아닌 한**, 이 경우에는 트레이스백이 인쇄되
   지 않고 파이썬 프로세스는 "SystemExit" 인스턴스에 의해 지정된 에러
   코드로 종료됩니다.

   에러 표시기가 설정된 경우**에만** 이 함수를 호출하십시오. 그렇지 않
   으면 치명적인 에러가 발생합니다!

   *set_sys_last_vars*가 0이 아니면, 변수 "sys.last_type",
   "sys.last_value" 및 "sys.last_traceback" 은 각각 인쇄되는 예외의 형
   , 값 및 트레이스백으로 설정됩니다.

void PyErr_Print()

   "PyErr_PrintEx(1)"의 별칭.

void PyErr_WriteUnraisable(PyObject *obj)

   현재 예외와 *obj* 인자를 사용하여 "sys.unraisablehook()" 을 호출합
   니다.

   이 유틸리티 함수는 예외가 설정되었지만, 인터프리터가 실제로 예외를
   발생시킬 수 없을 때 "sys.stderr"에 경고 메시지를 인쇄합니다. 예를
   들어, "__del__()" 메서드에서 예외가 발생할 때 사용됩니다.

   이 함수는 발생시킬 수 없는 예외가 발생한 문맥을 식별하는 단일 인자
   *obj*로 호출됩니다. 가능하면, *obj*의 repr이 경고 메시지에 인쇄됩니
   다.

   이 함수를 호출할 때 예외를 설정되어 있어야 합니다.


예외 발생시키기
===============

이 함수들은 현재 스레드의 에러 표시기를 설정하는 데 도움이 됩니다. 편
의를 위해, 이러한 함수 중 일부는 항상 "return" 문에서 사용할 "NULL" 포
인터를 반환합니다.

void PyErr_SetString(PyObject *type, const char *message)

   This is the most common way to set the error indicator.  The first
   argument specifies the exception type; it is normally one of the
   standard exceptions, e.g. "PyExc_RuntimeError".  You need not
   increment its reference count. The second argument is an error
   message; it is decoded from "'utf-8'".

void PyErr_SetObject(PyObject *type, PyObject *value)

   이 함수는 "PyErr_SetString()"과 유사하지만, 예외의 "값"에 대해 임의
   의 파이썬 객체를 지정할 수 있습니다.

PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
    *Return value: Always NULL.*

   이 함수는 에러 표시기를 설정하고 "NULL"을 반환합니다. *exception*은
   파이썬 예외 클래스여야 합니다. *format*과 후속 매개 변수는 에러 메
   시지를 포맷하는 데 도움이 됩니다; "PyUnicode_FromFormat()"에서와 같
   은 의미와 값을 갖습니다. *format*은 ASCII 인코딩된 문자열입니다.

PyObject* PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)
    *Return value: Always NULL.*

   "PyErr_Format()"과 같지만, 가변 개수의 인자 대신 "va_list" 인자를
   취합니다.

   버전 3.5에 추가.

void PyErr_SetNone(PyObject *type)

   이것은 "PyErr_SetObject(type, Py_None)"의 줄임 표현입니다.

int PyErr_BadArgument()

   이것은 "PyErr_SetString(PyExc_TypeError, message)"의 줄임 표현입니
   다, 여기서 *message*는 잘못된 인자로 내장 연산이 호출되었음을 나타
   냅니다. 대부분 내부 용입니다.

PyObject* PyErr_NoMemory()
    *Return value: Always NULL.*

   이것은 "PyErr_SetNone(PyExc_MemoryError)"의 줄임 표현입니다; "NULL"
   을 반환해서 객체 할당 함수는 메모리가 부족할 때 "return
   PyErr_NoMemory();" 라고 쓸 수 있습니다.

PyObject* PyErr_SetFromErrno(PyObject *type)
    *Return value: Always NULL.*

   C 라이브러리 함수가 에러를 반환하고 C 변수 "errno"를 설정했을 때 예
   외를 발생시키는 편의 함수입니다. 첫 번째 항목이 정수 "errno" 값이고
   두 번째 항목이 ("strerror()"에서 얻은) 해당 에러 메시지인 튜플 객체
   를 만든 다음, "PyErr_SetObject(type, object)"를 호출합니다. 유닉스
   에서, "errno" 값이 시스템 호출이 중단되었음을 나타내는 "EINTR"이면,
   "PyErr_CheckSignals()"를 호출하고 이것이 에러 표시기를 설정하면, 설
   정된 그대로 둡니다. 이 함수는 항상 "NULL"을 반환해서, 시스템 호출에
   대한 래퍼 함수는 시스템 호출이 에러를 반환할 때 "return
   PyErr_SetFromErrno(type);" 이라고 쓸 수 있습니다.

PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
    *Return value: Always NULL.*

   "PyErr_SetFromErrno()"와 유사하지만, *filenameObject*가 "NULL"이 아
   니면, *type*의 생성자에 세 번째 매개 변수로 전달된다는 추가 동작이
   있습니다. "OSError" 예외의 경우, 예외 인스턴스의 "filename" 어트리
   뷰트를 정의하는 데 사용됩니다.

PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
    *Return value: Always NULL.*

   "PyErr_SetFromErrnoWithFilenameObject()"와 유사하지만, 두 개의 파일
   명을 취하는 함수가 실패할 때 에러를 발생시키기 위해 두 번째 파일명
   객체를 취합니다.

   버전 3.4에 추가.

PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
    *Return value: Always NULL.*

   "PyErr_SetFromErrnoWithFilenameObject()"와 유사하지만, 파일명이 C
   문자열로 제공됩니다. *filename*은 파일 시스템 인코딩
   ("os.fsdecode()")으로 디코딩됩니다.

PyObject* PyErr_SetFromWindowsErr(int ierr)
    *Return value: Always NULL.*

   "WindowsError"를 발생시키는 편의 함수입니다. "0"의 *ierr*로 호출하
   면, "GetLastError()" 호출에서 반환된 에러 코드가 대신 사용됩니다.
   Win32 함수 "FormatMessage()"를 호출하여 *ierr*이나 "GetLastError()"
   가 제공하는 에러 코드의 윈도우 설명을 얻은 다음, 첫 번째 항목이
   *ierr* 값이고 두 번째 항목이 ("FormatMessage()"에서 얻은) 해당 에러
   메시지인 튜플 객체를 생성한 다음,
   "PyErr_SetObject(PyExc_WindowsError, object)"를 호출합니다. 이 함수
   는 항상 "NULL"을 반환합니다.

   가용성: 윈도우.

PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
    *Return value: Always NULL.*

   "PyErr_SetFromWindowsErr()" 와 유사하며, 발생시킬 예외 형을 지정하
   는 추가 매개 변수가 있습니다.

   가용성: 윈도우.

PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
    *Return value: Always NULL.*

   "PyErr_SetFromWindowsErrWithFilenameObject()"와 유사하지만, 파일명
   이 C 문자열로 제공됩니다. *filename*은 파일 시스템 인코딩
   ("os.fsdecode()")으로 디코딩됩니다.

   가용성: 윈도우.

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
    *Return value: Always NULL.*

   "PyErr_SetFromWindowsErrWithFilenameObject()"와 유사하며, 발생시킬
   예외 형을 지정하는 추가 매개 변수가 있습니다.

   가용성: 윈도우.

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
    *Return value: Always NULL.*

   "PyErr_SetExcFromWindowsErrWithFilenameObject()"와 유사하지만, 두
   번째 파일명 객체를 받아들입니다.

   가용성: 윈도우.

   버전 3.4에 추가.

PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
    *Return value: Always NULL.*

   "PyErr_SetFromWindowsErrWithFilename()"와 유사하며, 발생시킬 예외
   형을 지정하는 추가 매개 변수가 있습니다.

   가용성: 윈도우.

PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
    *Return value: Always NULL.*

   "ImportError"를 발생시키는 편의 함수입니다. *msg*는 예외의 메시지
   문자열로 설정됩니다. 둘 다 "NULL"이 될 수 있는, *name*과 *path*는
   각각 "ImportError"의 "name"과 "path" 어트리뷰트로 설정됩니다.

   버전 3.3에 추가.

PyObject* PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)
    *Return value: Always NULL.*

   "PyErr_SetImportError()" 와 매우 비슷하지만, 이 함수는 발생시킬
   "ImportError"의 서브 클래스를 지정할 수 있습니다.

   버전 3.6에 추가.

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)

   현재 예외에 대한 파일(file), 줄(line) 및 오프셋(offset) 정보를 설정
   합니다. 현재 예외가 "SyntaxError"가 아니면, 추가 어트리뷰트를 설정
   하여, 예외 인쇄 하위 시스템이 예외가 "SyntaxError"라고 생각하게 합
   니다.

   버전 3.4에 추가.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)

   "PyErr_SyntaxLocationObject()" 와 비슷하지만, *filename*은 파일 시
   스템 인코딩("os.fsdecode()")에서 디코딩되는 바이트 문자열입니다.

   버전 3.2에 추가.

void PyErr_SyntaxLocation(const char *filename, int lineno)

   Like "PyErr_SyntaxLocationEx()", but the *col_offset* parameter is
   omitted.

void PyErr_BadInternalCall()

   이것은 "PyErr_SetString(PyExc_SystemError, message)"의 줄임 표현입
   니다. 여기서 *message*는 내부 연산(예를 들어 파이썬/C API 함수)이
   잘못된 인자로 호출되었음을 나타냅니다. 대부분 내부 용입니다.


경고 발행하기
=============

이 함수를 사용하여 C 코드에서 경고를 발행하십시오. 파이썬 "warnings"
모듈에서 내보낸 유사한 함수를 미러링합니다. 일반적으로 *sys.stderr*에
경고 메시지를 인쇄합니다; 그러나, 사용자가 경고를 에러로 전환하도록 지
정했을 수도 있으며, 이 경우 예외가 발생합니다. 경고 장치의 문제로 인해
이 함수가 예외를 발생시키는 것도 가능합니다. 예외가 발생하지 않으면 반
환 값은 "0"이고, 예외가 발생하면 "-1"입니다. (경고 메시지가 실제로 인
쇄되는지나 예외의 이유를 확인할 수 없습니다; 이것은 의도적입니다.) 예
외가 발생하면, 호출자는 정상적인 예외 처리를 수행해야 합니다 (예를 들
어, 소유한 참조를 "Py_DECREF()"하고 에러값을 반환합니다).

int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)

   경고 메시지를 발행합니다. *category* 인자는 경고 범주(아래를 참조하
   십시오)나 "NULL"입니다; *message* 인자는 UTF-8로 인코딩된 문자열입
   니다. *stack_level*은 스택 프레임 수를 제공하는 양수입니다; 해당 스
   택 프레임에서 현재 실행 중인 코드 줄에서 경고가 발생합니다.
   *stack_level*이 1이면 "PyErr_WarnEx()"를 호출하는 함수, 2는 그 위의
   함수, 등등.

   경고 범주는 "PyExc_Warning"의 서브 클래스여야 합니다.
   "PyExc_Warning"은 "PyExc_Exception"의 서브 클래스입니다; 기본 경고
   범주는 "PyExc_RuntimeWarning"입니다. 표준 파이썬 경고 범주는 이름이
   표준 경고 범주 에 열거된 전역 변수로 제공됩니다.

   경고 제어에 대한 자세한 내용은, "warnings" 모듈 설명서와 명령 줄 설
   명서에서 "-W" 옵션을 참조하십시오. 경고 제어를 위한 C API는 없습니
   다.

int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)

   Issue a warning message with explicit control over all warning
   attributes.  This is a straightforward wrapper around the Python
   function "warnings.warn_explicit()"; see there for more
   information.  The *module* and *registry* arguments may be set to
   "NULL" to get the default effect described there.

   버전 3.4에 추가.

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

   *message*와 *module*이 UTF-8 인코딩된 문자열이고, *filename*은 파일
   시스템 인코딩("os.fsdecode()")으로 디코딩된다는 점을 제외하면
   "PyErr_WarnExplicitObject()" 와 유사합니다.

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)

   "PyErr_WarnEx()"와 유사한 함수지만, "PyUnicode_FromFormat()"을 사용
   하여 경고 메시지를 포맷합니다. *format*은 ASCII 인코딩된 문자열입니
   다.

   버전 3.2에 추가.

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)

   "PyErr_WarnFormat()"과 유사한 함수지만, *category*는
   "ResourceWarning"이고 *source*를 "warnings.WarningMessage()"로 전달
   합니다.

   버전 3.6에 추가.


에러 표시기 조회하기
====================

PyObject* PyErr_Occurred()
    *Return value: Borrowed reference.*

   에러 표시기가 설정되었는지 테스트합니다. 설정되었으면, 예외
   *type*("PyErr_Set*()" 함수나 "PyErr_Restore()"에 대한 마지막 호출의
   첫 번째 인자)을 반환합니다. 설정되지 않았으면, "NULL"을 반환합니다.
   여러분이 반환 값에 대한 참조를 소유하지 않아서, "Py_DECREF()" 할 필
   요가 없습니다.

   호출자는 GIL을 보유해야 합니다.

   참고:

     반환 값을 특정 예외와 비교하지 마십시오; 대신
     "PyErr_ExceptionMatches()"를 사용하십시오, 아래를 참조하십시오. (
     클래스 예외의 경우 예외가 클래스 대신 인스턴스이거나, 예상하는 예
     외의 서브 클래스일 수 있어서 비교는 실패하기 쉽습니다.)

int PyErr_ExceptionMatches(PyObject *exc)

   "PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)"와 동등합니다.
   예외가 실제로 설정되었을 때만 호출해야 합니다; 예외가 발생하지 않았
   으면 메모리 액세스 위반이 발생합니다.

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

   *given* 예외가 *exc*의 예외 형과 일치하면 참을 반환합니다. *exc*가
   클래스 객체이면, *given*이 서브 클래스의 인스턴스일 때도 참을 반환
   합니다. *exc*가 튜플이면, 튜플에 있는 모든 예외 형(그리고 서브 튜플
   도 재귀적으로)을 일치를 위해 검색합니다.

void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

   주소가 전달된 세 개의 변수로 에러 표시기를 꺼냅니다. 에러 표시기가
   설정되지 않았으면, 세 변수를 모두 "NULL"로 설정합니다. 설정되었으면
   , 지워지고 꺼낸 각 객체에 대한 참조를 여러분이 소유합니다. 값과 트
   레이스백 객체는 형 객체가 그렇지 않을 때도 "NULL"일 수 있습니다.

   참고:

     이 함수는 일반적으로 예외를 포착해야 하는 코드나 에러 표시기를 일
     시적으로 저장하고 복원해야 하는 코드에서만 사용됩니다. 예를 들어:

        {
           PyObject *type, *value, *traceback;
           PyErr_Fetch(&type, &value, &traceback);

           /* ... code that might produce other errors ... */

           PyErr_Restore(type, value, traceback);
        }

void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

   세 객체로 에러 표시기를 설정합니다. 에러 표시기가 이미 설정되어 있
   으면, 먼저 지워집니다. 객체가 "NULL"이면, 에러 표시기가 지워집니다.
   "NULL" type과 함께 "NULL"이 아닌 value나 traceback 을 전달하지 마십
   시오. 예외 형은 클래스여야 합니다. 잘못된 예외 형이나 값을 전달하지
   마십시오. (이러한 규칙을 위반하면 나중에 미묘한 문제가 발생합니다.)
   이 호출은 각 객체에 대한 참조를 제거합니다: 호출 전에 각 객체에 대
   한 참조를 소유해야 하며 호출 후에는 더는 이러한 참조를 소유하지 않
   습니다. (이것을 이해할 수 없다면, 이 함수를 사용하지 마십시오. 경고
   했습니다.)

   참고:

     이 함수는 일반적으로 에러 표시기를 일시적으로 저장하고 복원해야
     하는 코드에서만 사용됩니다. 현재 에러 표시기를 저장하려면
     "PyErr_Fetch()"를 사용하십시오.

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)

   특정 상황에서, 아래의 "PyErr_Fetch()"가 반환하는 값은 "비 정규화"되
   었을 수 있습니다. 즉, "*exc"는 클래스 객체이지만 "*val"은 같은 클래
   스의 인스턴스가 아닙니다. 이 함수는 이 경우 클래스를 인스턴스 화하
   는 데 사용할 수 있습니다. 값이 이미 정규화되어 있으면, 아무 일도 일
   어나지 않습니다. 지연된 정규화는 성능 향상을 위해 구현됩니다.

   참고:

     이 함수 예외 값에 "__traceback__" 어트리뷰트를 묵시적으로 설정하
     지 *않습니다*. 트레이스백을 적절하게 설정해야 하면, 다음과 같은
     추가 스니펫이 필요합니다:

        if (tb != NULL) {
          PyException_SetTraceback(val, tb);
        }

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

   "sys.exc_info()"로 알려진 것과 같은, 예외 정보를 꺼냅니다. 이것은
   새로 발생한 예외가 아니라, *이미 포착된* 예외를 가리킵니다. 세 객체
   에 대한 새 참조를 반환합니다. 이 중 어느 것이든 "NULL"일 수 있습니
   다. 예외 정보 상태를 수정하지 않습니다.

   참고:

     이 함수는 일반적으로 예외를 처리하려는 코드에서 사용되지 않습니다
     . 오히려, 코드가 예외 상태를 임시로 저장하고 복원해야 할 때 사용
     할 수 있습니다. 예외 상태를 복원하거나 지우려면
     "PyErr_SetExcInfo()"를 사용하십시오.

   버전 3.3에 추가.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)

   "sys.exc_info()"로 알려진 것과 같은, 예외 정보를 설정합니다. 이것은
   새로 발생한 예외가 아니라, *이미 포착된* 예외를 가리킵니다. 이 함수
   는 인자의 참조를 훔칩니다. 예외 상태를 지우려면, 세 인자 모두에
   "NULL"을 전달하십시오. 세 인자에 대한 일반적인 규칙은,
   "PyErr_Restore()"를 참조하십시오.

   참고:

     이 함수는 일반적으로 예외를 처리하려는 코드에서 사용되지 않습니다
     . 오히려, 코드가 예외 상태를 임시로 저장하고 복원해야 할 때 사용
     할 수 있습니다. 예외 상태를 읽으려면 "PyErr_GetExcInfo()"를 사용
     하십시오.

   버전 3.3에 추가.


시그널 처리하기
===============

int PyErr_CheckSignals()

   이 함수는 파이썬의 시그널 처리와 상호 작용합니다. 시그널이 프로세스
   로 전송되었는지 확인하고, 그렇다면, 해당 시그널 처리기를 호출합니다
   . "signal" 모듈이 지원되면, 파이썬으로 작성된 시그널 처리기를 호출
   할 수 있습니다. 모든 경우에, "SIGINT"의 기본 효과는
   "KeyboardInterrupt" 예외를 발생시키는 것입니다. 예외가 발생하면 에
   러 표시기가 설정되고 함수는 "-1"을 반환합니다; 그렇지 않으면 함수는
   "0"을 반환합니다. 에러 표시기는 이전에 설정한 경우 지워지거나 지워
   지지 않을 수 있습니다.

void PyErr_SetInterrupt()

   "SIGINT" 시그널 도착의 효과를 시뮬레이션합니다. 다음에
   "PyErr_CheckSignals()"가 호출되면, "SIGINT"에 대한 파이썬 시그널 처
   리기가 호출됩니다.

   "SIGINT"가 파이썬에서 처리되지 않으면 ("signal.SIG_DFL"이나
   "signal.SIG_IGN"으로 설정되어서), 이 함수는 아무 작업도 수행하지 않
   습니다.

int PySignal_SetWakeupFd(int fd)

   이 유틸리티 함수는 시그널이 수신될 때마다 시그널 번호가 단일 바이트
   로 기록되는 파일 기술자를 지정합니다. *fd*는 비 블로킹이어야 합니다
   . 이전의 파일 기술자를 반환합니다.

   값 "-1"은 기능을 비활성화합니다; 이것이 초기 상태입니다. 이것은 파
   이썬의 "signal.set_wakeup_fd()"와 동등하지만, 에러 검사는 없습니다.
   *fd*는 유효한 파일 기술자여야 합니다. 함수는 메인 스레드에서만 호출
   되어야 합니다.

   버전 3.5에서 변경: 윈도우에서, 함수는 이제 소켓 핸들도 지원합니다.


예외 클래스
===========

PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict)
    *Return value: New reference.*

   이 유틸리티 함수는 새 예외 클래스를 만들고 반환합니다. *name* 인자
   는 새 예외의 이름, "module.classname" 형식의 C 문자열이어야 합니다.
   *base*와 *dict* 인자는 일반적으로 "NULL"입니다. 이렇게 하면
   "Exception"(C에서 "PyExc_Exception"으로 액세스할 수 있습니다)에서
   파생된 클래스 객체가 만들어집니다.

   새 클래스의 "__module__" 어트리뷰트는 *name* 인자의 첫 번째 부분(마
   지막 점까지)으로 설정되고, 클래스 이름은 마지막 부분(마지막 점 뒤)
   으로 설정됩니다. *base* 인자는 대체 베이스 클래스를 지정하는 데 사
   용할 수 있습니다; 하나의 클래스나 클래스의 튜플일 수 있습니다.
   *dict* 인자는 클래스 변수와 메서드의 딕셔너리를 지정하는 데 사용할
   수 있습니다.

PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
    *Return value: New reference.*

   새로운 예외 클래스에 독스트링을 쉽게 부여할 수 있다는 점을 제외하면
   "PyErr_NewException()"과 같습니다: *doc*이 "NULL"이 아니면, 예외 클
   래스에 대한 독스트링으로 사용됩니다.

   버전 3.2에 추가.


예외 객체
=========

PyObject* PyException_GetTraceback(PyObject *ex)
    *Return value: New reference.*

   파이썬에서 "__traceback__"을 통해 액세스 할 수 있는 새로운 참조로
   예외와 관련된 트레이스백을 반환합니다. 관련된 트레이스백이 없으면,
   "NULL"을 반환합니다.

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

   예외와 관련된 트레이스백을 *tb*로 설정합니다. 지우려면 "Py_None"을
   사용하십시오.

PyObject* PyException_GetContext(PyObject *ex)
    *Return value: New reference.*

   파이썬에서 "__context__"를 통해 액세스 할 수 있는 새 참조로 예외와
   연관된 컨텍스트(다른 예외 인스턴스, 이것을 처리하는 도중 *ex*가 발
   생했습니다)를 반환합니다. 연결된 컨텍스트가 없으면 "NULL"을 반환합
   니다.

void PyException_SetContext(PyObject *ex, PyObject *ctx)

   예외와 연관된 컨텍스트를 *ctx*로 설정합니다. 지우려면 "NULL"을 사용
   하십시오. *ctx*가 예외 인스턴스인지 확인하는 형 검사는 없습니다. 이
   것은 *ctx*에 대한 참조를 훔칩니다.

PyObject* PyException_GetCause(PyObject *ex)
    *Return value: New reference.*

   파이썬에서 "__cause__"를 통해 액세스 할 수 있는 새 참조로 예외와 관
   련된 원인(예외 인스턴스나 "None", "raise ... from ..."으로 설정됩니
   다)을 반환합니다.

void PyException_SetCause(PyObject *ex, PyObject *cause)

   예외와 관련된 원인을 *cause*로 설정합니다. 지우려면 "NULL"을 사용하
   십시오. *cause*가 예외 인스턴스나 "None"인지 확인하는 형 검사는 없
   습니다. 이것은 *cause*에 대한 참조를 훔칩니다.

   "__suppress_context__"는 이 함수에 의해 묵시적으로 "True"로 설정됩
   니다.


유니코드 예외 객체
==================

다음 함수는 C에서 유니코드 예외를 만들고 수정하는 데 사용됩니다.

PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
    *Return value: New reference.*

   *encoding*, *object*, *length*, *start*, *end* 및 *reason* 어트리뷰
   트를 사용하여 "UnicodeDecodeError" 객체를 만듭니다. *encoding*과
   *reason*은 UTF-8로 인코딩된 문자열입니다.

PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
    *Return value: New reference.*

   *encoding*, *object*, *length*, *start*, *end* 및 *reason* 어트리뷰
   트를 사용하여 "UnicodeEncodeError" 객체를 만듭니다. *encoding*과
   *reason*은 UTF-8로 인코딩된 문자열입니다.

   버전 3.3부터 폐지: 3.11"Py_UNICODE"는 파이썬 3.3부터 폐지되었습니다
   . "PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)"로
   마이그레이션 하십시오.

PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
    *Return value: New reference.*

   *object*, *length*, *start*, *end* 및 *reason* 어트리뷰트를 사용하
   여 "UnicodeTranslateError" 객체를 만듭니다. *reason*은 UTF-8로 인코
   딩된 문자열입니다.

   버전 3.3부터 폐지: 3.11"Py_UNICODE"는 파이썬 3.3부터 폐지되었습니다
   . "PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...)"
   로 마이그레이션 하십시오.

PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
    *Return value: New reference.*

   주어진 예외 객체의 *encoding* 어트리뷰트를 반환합니다.

PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
    *Return value: New reference.*

   주어진 예외 객체의 *object* 어트리뷰트를 반환합니다.

int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)

   주어진 예외 객체의 *start* 어트리뷰트를 가져와서 **start*에 배치합
   니다. *start*는 "NULL"이 아니어야 합니다. 성공하면 "0"을, 실패하면
   "-1"을 반환합니다.

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)

   주어진 예외 객체의 *start* 어트리뷰트를 *start*로 설정합니다. 성공
   하면 "0"을, 실패하면 "-1"을 반환합니다.

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)

   주어진 예외 객체의 *end* 어트리뷰트를 가져와서 **end*에 배치합니다.
   *end*는 "NULL"이 아니어야 합니다. 성공하면 "0"을, 실패하면 "-1"을
   반환합니다.

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)

   주어진 예외 객체의 *end* 어트리뷰트를 *end*로 설정합니다. 성공하면
   "0"을, 실패하면 "-1"을 반환합니다.

PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
    *Return value: New reference.*

   주어진 예외 객체의 *reason* 어트리뷰트를 반환합니다.

int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)

   주어진 예외 객체의 *reason* 어트리뷰트를 *reason*으로 설정합니다.
   성공하면 "0"을, 실패하면 "-1"을 반환합니다.


재귀 제어
=========

이 두 함수는 코어와 확장 모듈 모두에서 C 수준에서 안전한 재귀 호출을
수행하는 방법을 제공합니다. 재귀 코드가 반드시 파이썬 코드를 호출하지
않는 경우 필요합니다 (파이썬 코드는 재귀 깊이를 자동으로 추적합니다).
호출 프로토콜이 재귀 처리를 처리하기 때문에 *tp_call* 구현에도 필요하
지 않습니다.

int Py_EnterRecursiveCall(const char *where)

   재귀적 C 수준 호출이 막 수행되려고 하는 지점을 표시합니다.

   "USE_STACKCHECK"가 정의되었으면, 이 함수는 "PyOS_CheckStack()"을 사
   용하여 OS 스택이 오버플로 되었는지 확인합니다. 이 경우,
   "MemoryError"를 설정하고 0이 아닌 값을 반환합니다.

   그런 다음 함수는 재귀 제한에 도달했는지 확인합니다. 이 경우,
   "RecursionError"가 설정되고 0이 아닌 값이 반환됩니다. 그렇지 않으면
   , 0이 반환됩니다.

   *where*는 재귀 깊이 제한으로 인한 "RecursionError" 메시지에 이어붙
   일 "" in instance check""와 같은 UTF-8 인코딩된 문자열이어야 합니다
   .

   버전 3.9에서 변경: 이 함수는 이제 제한된 API에서도 사용할 수 있습니
   다.

void Py_LeaveRecursiveCall(void)

   "Py_EnterRecursiveCall()" 을 종료합니다. "Py_EnterRecursiveCall()"
   의 각 *성공적인* 호출마다 한 번씩 호출되어야 합니다.

   버전 3.9에서 변경: 이 함수는 이제 제한된 API에서도 사용할 수 있습니
   다.

컨테이너형에 대해 "tp_repr"을 올바르게 구현하려면 특별한 재귀 처리가
필요합니다. 스택을 보호하는 것 외에도, "tp_repr"은 순환을 방지하기 위
해 객체를 추적해야 합니다. 다음 두 함수는 이 기능을 쉽게 만듭니다. 사
실상, 이들은 "reprlib.recursive_repr()"에 대한 C 동등물입니다.

int Py_ReprEnter(PyObject *object)

   순환을 감지하기 위해 "tp_repr" 구현 시작 시 호출됩니다.

   객체가 이미 처리되었으면, 함수는 양의 정수를 반환합니다. 이 경우
   "tp_repr" 구현은 순환을 나타내는 문자열 객체를 반환해야 합니다. 예
   를 들어, "dict" 객체는 "{...}"를 반환하고 "list" 객체는 "[...]"를
   반환합니다.

   재귀 제한에 도달하면 함수는 음의 정수를 반환합니다. 이 경우
   "tp_repr" 구현은 일반적으로 "NULL"을 반환해야 합니다.

   그렇지 않으면, 함수는 0을 반환하고 "tp_repr" 구현은 정상적으로 계속
   될 수 있습니다.

void Py_ReprLeave(PyObject *object)

   "Py_ReprEnter()"를 종료합니다. 0을 반환하는 "Py_ReprEnter()" 호출마
   다 한 번씩 호출해야 합니다.


표준 예외
=========

모든 표준 파이썬 예외는 "PyExc_" 뒤에 파이썬 예외 이름이 오는 이름의
전역 변수로 제공됩니다. "PyObject*" 형입니다; 모두 클래스 객체입니다.
완전성을 위해, 다음은 모든 변수입니다:

+-------------------------------------------+-----------------------------------+------------+
| C 이름                                    | 파이썬 이름                       | 노트       |
|===========================================|===================================|============|
| "PyExc_BaseException"                     | "BaseException"                   | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_Exception"                         | "Exception"                       | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ArithmeticError"                   | "ArithmeticError"                 | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_AssertionError"                    | "AssertionError"                  |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_AttributeError"                    | "AttributeError"                  |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_BlockingIOError"                   | "BlockingIOError"                 |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_BrokenPipeError"                   | "BrokenPipeError"                 |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_BufferError"                       | "BufferError"                     |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ChildProcessError"                 | "ChildProcessError"               |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ConnectionAbortedError"            | "ConnectionAbortedError"          |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ConnectionError"                   | "ConnectionError"                 |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ConnectionRefusedError"            | "ConnectionRefusedError"          |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ConnectionResetError"              | "ConnectionResetError"            |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_EOFError"                          | "EOFError"                        |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_FileExistsError"                   | "FileExistsError"                 |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_FileNotFoundError"                 | "FileNotFoundError"               |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_FloatingPointError"                | "FloatingPointError"              |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_GeneratorExit"                     | "GeneratorExit"                   |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ImportError"                       | "ImportError"                     |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_IndentationError"                  | "IndentationError"                |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_IndexError"                        | "IndexError"                      |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_InterruptedError"                  | "InterruptedError"                |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_IsADirectoryError"                 | "IsADirectoryError"               |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_KeyError"                          | "KeyError"                        |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_KeyboardInterrupt"                 | "KeyboardInterrupt"               |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_LookupError"                       | "LookupError"                     | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_MemoryError"                       | "MemoryError"                     |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ModuleNotFoundError"               | "ModuleNotFoundError"             |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_NameError"                         | "NameError"                       |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_NotADirectoryError"                | "NotADirectoryError"              |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_NotImplementedError"               | "NotImplementedError"             |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_OSError"                           | "OSError"                         | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_OverflowError"                     | "OverflowError"                   |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_PermissionError"                   | "PermissionError"                 |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ProcessLookupError"                | "ProcessLookupError"              |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_RecursionError"                    | "RecursionError"                  |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ReferenceError"                    | "ReferenceError"                  |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_RuntimeError"                      | "RuntimeError"                    |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_StopAsyncIteration"                | "StopAsyncIteration"              |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_StopIteration"                     | "StopIteration"                   |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_SyntaxError"                       | "SyntaxError"                     |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_SystemError"                       | "SystemError"                     |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_SystemExit"                        | "SystemExit"                      |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_TabError"                          | "TabError"                        |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_TimeoutError"                      | "TimeoutError"                    |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_TypeError"                         | "TypeError"                       |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_UnboundLocalError"                 | "UnboundLocalError"               |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_UnicodeDecodeError"                | "UnicodeDecodeError"              |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_UnicodeEncodeError"                | "UnicodeEncodeError"              |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_UnicodeError"                      | "UnicodeError"                    |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_UnicodeTranslateError"             | "UnicodeTranslateError"           |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ValueError"                        | "ValueError"                      |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ZeroDivisionError"                 | "ZeroDivisionError"               |            |
+-------------------------------------------+-----------------------------------+------------+

버전 3.3에 추가: "PyExc_BlockingIOError", "PyExc_BrokenPipeError",
"PyExc_ChildProcessError", "PyExc_ConnectionError",
"PyExc_ConnectionAbortedError", "PyExc_ConnectionRefusedError",
"PyExc_ConnectionResetError", "PyExc_FileExistsError",
"PyExc_FileNotFoundError", "PyExc_InterruptedError",
"PyExc_IsADirectoryError", "PyExc_NotADirectoryError",
"PyExc_PermissionError", "PyExc_ProcessLookupError" 및
"PyExc_TimeoutError"는 **PEP 3151**을 따라 도입되었습니다.

버전 3.5에 추가: "PyExc_StopAsyncIteration" 과 "PyExc_RecursionError".

버전 3.6에 추가: "PyExc_ModuleNotFoundError".

다음은 "PyExc_OSError"에 대한 호환성 별칭입니다:

+---------------------------------------+------------+
| C 이름                                | 노트       |
|=======================================|============|
| "PyExc_EnvironmentError"              |            |
+---------------------------------------+------------+
| "PyExc_IOError"                       |            |
+---------------------------------------+------------+
| "PyExc_WindowsError"                  | [2]        |
+---------------------------------------+------------+

버전 3.3에서 변경: 이러한 별칭은 별도의 예외 형이었습니다.

노트:

[1] 이것은 다른 표준 예외에 대한 베이스 클래스입니다.

[2] 윈도우에서만 정의됩니다; 전 처리기 매크로 "MS_WINDOWS"가 정의되었
    는지 테스트하여 이를 사용하는 코드를 보호하십시오.


표준 경고 범주
==============

모든 표준 파이썬 경고 범주는 "PyExc_" 뒤에 파이썬 예외 이름이 오는 이
름의 전역 변수로 제공됩니다. "PyObject*" 형입니다; 모두 클래스 객체입
니다. 완전성을 위해, 다음은 모든 변수입니다:

+--------------------------------------------+-----------------------------------+------------+
| C 이름                                     | 파이썬 이름                       | 노트       |
|============================================|===================================|============|
| "PyExc_Warning"                            | "Warning"                         | [3]        |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_BytesWarning"                       | "BytesWarning"                    |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_DeprecationWarning"                 | "DeprecationWarning"              |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_FutureWarning"                      | "FutureWarning"                   |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_ImportWarning"                      | "ImportWarning"                   |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_PendingDeprecationWarning"          | "PendingDeprecationWarning"       |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_ResourceWarning"                    | "ResourceWarning"                 |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_RuntimeWarning"                     | "RuntimeWarning"                  |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_SyntaxWarning"                      | "SyntaxWarning"                   |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_UnicodeWarning"                     | "UnicodeWarning"                  |            |
+--------------------------------------------+-----------------------------------+------------+
| "PyExc_UserWarning"                        | "UserWarning"                     |            |
+--------------------------------------------+-----------------------------------+------------+

버전 3.2에 추가: "PyExc_ResourceWarning".

노트:

[3] 이것은 다른 표준 경고 범주의 베이스 클래스입니다.
