객체 프로토콜¶

PyObject *Py_GetConstant(unsigned int constant_id)¶

상의 안정 ABI 버전 3.13 이후로.

상수에 대한 :term:`강한 참조(strong reference) <strong reference>`를 가져옵니다.

constant_id 가 유효하지 않으면 예외를 설정하고 NULL 을 반환합니다.

constant_id 는 다음 상수 식별자 중 하나여야 합니다:

상수 식별자	값	반환되는 객체
Py_CONSTANT_NONE¶	`0`	`None`
Py_CONSTANT_FALSE¶	`1`	`False`
Py_CONSTANT_TRUE¶	`2`	`True`
Py_CONSTANT_ELLIPSIS¶	`3`	`Ellipsis`
Py_CONSTANT_NOT_IMPLEMENTED¶	`4`	`NotImplemented`
Py_CONSTANT_ZERO¶	`5`	`0`
Py_CONSTANT_ONE¶	`6`	`1`
Py_CONSTANT_EMPTY_STR¶	`7`	`''`
Py_CONSTANT_EMPTY_BYTES¶	`8`	`b''`
Py_CONSTANT_EMPTY_TUPLE¶	`9`	`()`

숫자 값은 상수 식별자를 사용할 수 없는 프로젝트에 대해서만 제공됩니다.

Added in version 3.13.

CPython에서 이 모든 상수는 :term:`불멸 <immortal>`입니다.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶

상의 안정 ABI 버전 3.13 이후로.

:c:func:`Py_GetConstant`와 유사하지만, :term:`빌린 참조 <borrowed reference>`를 반환합니다.

이 함수는 주로 하위 호환성을 위해 설계되었습니다: 새로운 코드를 위해서는 Py_GetConstant() 사용을 권장합니다.

이 참조는 인터프리터로부터 빌려온 것이며, 인터프리터가 종료될 때까지 유효합니다.

Added in version 3.13.

PyObject *Py_NotImplemented¶: 지정된 형 조합에 대해 연산이 구현되지 않았음을 알리는 데 사용되는 NotImplemented 싱글톤.

Py_RETURN_NOTIMPLEMENTED¶: C 함수 내에서 Py_NotImplemented 반환을 올바르게 처리합니다 (즉, NotImplemented에 대한 새로운 강한 참조를 만들고 반환합니다).

Py_PRINT_RAW¶: 객체를 출력하는 여러 함수(예: PyObject_Print() 및 PyFile_WriteObject())에 사용되는 플래그입니다. 이 플래그가 전달되면, 해당 함수들은 객체의 repr() 대신 :func:`str`을 사용합니다.

int PyObject_Print(PyObject *o, FILE *fp, int flags)¶: 파일 fp에 객체 o를 인쇄합니다. 에러 시 -1을 반환합니다. flags 인자는 특정 인쇄 옵션을 활성화하는 데 사용됩니다. 현재 지원되는 유일한 옵션은 Py_PRINT_RAW입니다; 주어지면, repr() 대신 객체의 str()이 기록됩니다.

void PyObject_Dump(PyObject *op)¶

객체 op 을 stderr 에 출력합니다. 이 기능은 디버깅 목적으로만 사용해야 합니다.

출력은 메모리 손상 후에도 객체를 덤프하려고 시도하는 것을 목적으로 합니다:

정보는 접근 시 충돌할 가능성이 가장 낮은 필드부터 작성됩니다.
This function can be called without an attached thread state, but it’s not recommended to do so: it can cause deadlocks.
현재 인터프리터에 속하지 않은 객체가 덤프될 수 있지만, 이로 인해 충돌이나 의도치 않은 동작이 발생할 수도 있습니다.
객체 메모리가 해제되었는지 감지하는 휴리스틱을 구현하십시오. 이 경우 객체 내용을 표시하지 말고 메모리 주소만 표시하십시오.
출력 형식은 언제든지 변경될 수 있습니다.

출력 예시:

object address  : 0x7f80124702c0
object refcount : 2
object type     : 0x9902e0
object type name: str
object repr     : 'abcdef'

Added in version 3.15.

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)¶: 상의 안정 ABI 버전 3.13 이후로.
o에 attr_name 어트리뷰트가 있으면 1을, 그렇지 않으면 0을 반환합니다. 이것은 파이썬 표현식 hasattr(o, attr_name)과 동등합니다. 실패하면, -1을 반환합니다.

Added in version 3.13.

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)¶: 상의 안정 ABI 버전 3.13 이후로.
This is the same as PyObject_HasAttrWithError(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

Added in version 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)¶: 상의 안정 ABI.
o에 attr_name 어트리뷰트가 있으면 1을, 그렇지 않으면 0을 반환합니다. 이 함수는 항상 성공합니다.

참고

이것[는] 해당 함수가 __getattribute__() 메서드를 호출할 때 발생하는 예외가 전파되지 않고, 대신 sys.unraisablehook() 함수에 전달됨에 유의하십시오. 적절한 오류 처리를 위해서는 대신 PyObject_HasAttrWithError(), PyObject_GetOptionalAttr() 또는 :c:func:`PyObject_GetAttr`를 사용하십시오.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)¶: 상의 안정 ABI.
This is the same as PyObject_HasAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

참고

__getattr__()과 __getattribute__() 메서드를 호출할 때나 임시 str 객체를 만드는 중에 발생하는 예외는 조용히 무시됩니다. 적절한 에러 처리를 위해서는, 대신 PyObject_HasAttrStringWithError(), PyObject_GetOptionalAttrString() 또는 PyObject_GetAttrString()을 사용하십시오.

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)¶

반환값: 새 참조. 상의 안정 ABI.

객체 o에서 attr_name이라는 이름의 어트리뷰트를 가져옵니다. 성공하면 어트리뷰트 값을, 실패하면 NULL을 반환합니다. 이것은 파이썬 표현식 o.attr_name과 동등합니다.

누락된 어트리뷰트가 오류로 처리되어서는 안 되는 경우, 대신 :c:func:`PyObject_GetOptionalAttr`를 사용할 수 있습니다.

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)¶

반환값: 새 참조. 상의 안정 ABI.

This is the same as PyObject_GetAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

누락된 어트리뷰트가 오류로 처리되어서는 안 되는 경우, 대신 :c:func:`PyObject_GetOptionalAttrString`을 사용할 수 있습니다.

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶

상의 안정 ABI 버전 3.13 이후로.

어트리뷰트가 발견되지 않았을 때 :exc:`AttributeError`를 발생시키지 않는 :c:func:`PyObject_GetAttr`의 변형입니다.

If the attribute is found, return 1 and set *result to a new strong reference to the attribute. If the attribute is not found, return 0 and set *result to NULL; the AttributeError is silenced. If an error other than AttributeError is raised, return -1 and set *result to NULL.

Added in version 3.13.

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);¶: 상의 안정 ABI 버전 3.13 이후로.
This is the same as PyObject_GetOptionalAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

Added in version 3.13.

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)¶: 반환값: 새 참조. 상의 안정 ABI.
형 객체의 tp_getattro 슬롯에 배치되는 일반 어트리뷰트 게터(getter) 함수. 객체의 (있다면) __dict__에 있는 어트리뷰트뿐만 아니라 객체의 MRO에 있는 클래스의 딕셔너리에 있는 디스크립터를 찾습니다. 디스크립터 구현하기에 요약된 것처럼, 데이터 디스크립터는 인스턴스 어트리뷰트보다 우선하지만, 비 데이터 디스크립터는 그렇지 않습니다. 그렇지 않으면, AttributeError가 발생합니다.

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)¶

상의 안정 ABI.

객체 o에 대해, attr_name이라는 이름의 어트리뷰트 값을 v 값으로 설정합니다. 실패 시 예외를 발생시키고 -1을 반환합니다. 성공하면 0을 반환합니다. 이것은 파이썬 문장 o.attr_name = v와 동등합니다.

v가 NULL이면, 어트리뷰트가 삭제됩니다. 이 동작은 폐지되었고 PyObject_DelAttr()로 대체되었습니다만, 현재 제거할 계획이 없습니다.

함수를 NULL v 와 예외가 설정된 상태로 호출해서는 안 됩니다. 이 경우는 NULL 검사를 잊어버려서 발생할 수 있으며, 어트리뷰트를 삭제하게 됩니다.

버전 3.15에서 변경: 예외가 설정되어 있다면 NULL 값으로 호출해서는 안 됩니다.

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)¶

상의 안정 ABI.

This is the same as PyObject_SetAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

v가 NULL이면, 어트리뷰트가 삭제되지만, 이 기능은 폐지되었고 PyObject_DelAttrString()으로 대체되었습니다.

함수를 NULL v 와 예외가 설정된 상태로 호출해서는 안 됩니다. 이 경우는 NULL 검사를 잊어버려서 발생할 수 있으며, 어트리뷰트를 삭제하게 됩니다.

함수에 전달되는 다양한 어트리뷰트 이름의 개수는 가능한 한 적게 유지해야 하며, 일반적으로 attr_name 으로 정적으로 할당된 문자열을 사용합니다. 컴파일 시간에 알 수 없는 어트리뷰트 이름의 경우, PyUnicode_FromString() 과 PyObject_SetAttr() 를 직접 호출하는 것이 좋습니다. 더 자세한 내용은 키 객체를 생성하는 데 내부적으로 사용될 수 있는 PyUnicode_InternFromString() 을 참조하십시오.

버전 3.15에서 변경: 예외가 설정되어 있다면 NULL 값으로 호출해서는 안 됩니다.

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)¶: 상의 안정 ABI.
형 객체의 tp_setattro 슬롯에 배치되는 일반 어트리뷰트 세터(setter)와 딜리터(deleter) 함수. 객체의 MRO에 있는 클래스의 딕셔너리에서 데이터 디스크립터를 찾고, 발견되면 인스턴스 딕셔너리에 있는 어트리뷰트를 설정하거나 삭제하는 것보다 우선합니다. 그렇지 않으면, 객체의 (있다면) __dict__에서 어트리뷰트가 설정되거나 삭제됩니다. 성공하면 0이 반환되고, 그렇지 않으면 AttributeError가 발생하고 -1이 반환됩니다.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)¶: 상의 안정 ABI 버전 3.13 이후로.
객체 o에 대해, attr_name이라는 이름의 어트리뷰트를 삭제합니다. 실패 시 -1을 반환합니다. 이것은 파이썬 문장 del o.attr_name과 동등합니다.

int PyObject_DelAttrString(PyObject *o, const char *attr_name)¶

상의 안정 ABI 버전 3.13 이후로.

This is the same as PyObject_DelAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

함수에 전달되는 다양한 어트리뷰트 이름의 개수는 가능한 한 적게 유지해야 하며, 일반적으로 attr_name 으로 정적으로 할당된 문자열을 사용합니다. 컴파일 시간에 알 수 없는 어트리뷰트 이름의 경우, PyUnicode_FromString() 과 PyObject_DelAttr() 를 직접 호출하는 것이 좋습니다. 더 자세한 내용은 조회용 키 객체를 생성하는 데 내부적으로 사용될 수 있는 PyUnicode_InternFromString() 을 참조하십시오.

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)¶

반환값: 새 참조. 상의 안정 ABI 버전 3.10 이후로.

__dict__ 디스크립터의 게터(getter)를 위한 일반적인 구현. 필요하면 딕셔너리를 만듭니다.

이 함수는 또한 객체 o 의 __dict__ 를 가져오는 데 사용될 수 있습니다. 호출할 때 context 에 NULL 을 전달하십시오. 이 함수는 딕셔너리를 위한 메모리를 할당해야 할 수도 있으므로, 객체의 어트리뷰트에 접근할 때는 PyObject_GetAttr() 를 호출하는 것이 더 효율적일 수 있습니다.

실패하는 경우, 예외가 설정된 NULL 을 반환합니다.

Added in version 3.3.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)¶: 상의 안정 ABI 버전 3.7 이후로.
__dict__ 디스크립터의 세터(setter)를 위한 일반적인 구현. 이 구현은 딕셔너리 삭제를 허락하지 않습니다.

Added in version 3.3.

PyObject **_PyObject_GetDictPtr(PyObject *obj)¶

객체 obj 의 __dict__ 포인터를 반환합니다. __dict__ 가 없으면, 예외를 설정하지 않고 NULL 을 반환합니다.

이 함수는 딕셔너리를 위한 메모리를 할당해야 할 수도 있으므로, 객체의 어트리뷰트에 접근할 때는 :c:func:`PyObject_GetAttr`를 호출하는 것이 더 효율적일 수 있습니다.

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)¶: 반환값: 새 참조. 상의 안정 ABI.
opid에 의해 지정된 연산을 사용하여 o1과 o2의 값을 비교합니다. opid는 Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT 또는 Py_GE 중 하나여야 하고 각각 <, <=, ==, !=, > 또는 >=에 해당합니다. 이는 파이썬 표현식 o1 op o2와 동등합니다. 여기서 op는 opid에 해당하는 연산자입니다. 성공 시 비교 값을, 실패 시 NULL을 반환합니다.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)¶: 상의 안정 ABI.
opid 가 지정하는 연산을 사용하여 o1 과 o2 의 값을 비교합니다. 이 연산은 PyObject_RichCompare() 와 유사하지만, 오류 발생 시 -1 을, 결과가 false인 경우 0 을, 그렇지 않은 경우 1 을 반환합니다.

참고

o1과 o2가 같은 객체이면, PyObject_RichCompareBool() 은 항상 Py_EQ의 경우는 1을, Py_NE의 경우는 0을 반환합니다.

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)¶

상의 안정 ABI.

format_spec 을 사용하여 obj 를 포맷합니다. 이는 파이썬 표현식 format_(obj, format_spec) 과 동일합니다.

format_spec 이 NULL 일 수 있습니다. 이 경우 호출은 format_(obj) 와 같습니다. 성공 시 포맷된 문자열을, 실패 시 NULL 을 반환합니다.

PyObject *PyObject_Repr(PyObject *o)¶

반환값: 새 참조. 상의 안정 ABI.

객체 o의 문자열 표현을 계산합니다. 성공하면 문자열 표현을, 실패하면 NULL을 반환합니다. 이것은 파이썬 표현식 repr(o)와 동등합니다. repr() 내장 함수에 의해 호출됩니다.

인자가 NULL 인 경우, 문자열 '<NULL>' 을 반환합니다.

버전 3.4에서 변경: 이 함수에는 이제 디버그 어서션이 포함되어 있어 활성 예외를 조용히 버리지 않도록 합니다.

PyObject *PyObject_ASCII(PyObject *o)¶

반환값: 새 참조. 상의 안정 ABI.

PyObject_Repr()처럼, 객체 o의 문자열 표현을 계산하지만, \x, \u 또는 \U 이스케이프를 사용하여 PyObject_Repr()이 반환한 문자열에서 비 ASCII 문자를 이스케이프 합니다. 이것은 파이썬 2에서 PyObject_Repr()에 의해 반환된 것과 유사한 문자열을 생성합니다. ascii() 내장 함수에 의해 호출됩니다.

인자가 NULL 인 경우, 문자열 '<NULL>' 을 반환합니다.

PyObject *PyObject_Str(PyObject *o)¶

반환값: 새 참조. 상의 안정 ABI.

객체 o의 문자열 표현을 계산합니다. 성공 시 문자열 표현을, 실패 시 NULL을 반환합니다. 이것은 파이썬 표현식 str(o)와 동등합니다. str() 내장 함수에 의해, 따라서 print() 함수에 의해서도 호출됩니다.

인자가 NULL 인 경우, 문자열 '<NULL>' 을 반환합니다.

버전 3.4에서 변경: 이 함수에는 이제 디버그 어서션이 포함되어 있어 활성 예외를 조용히 버리지 않도록 합니다.

PyObject *PyObject_Bytes(PyObject *o)¶

반환값: 새 참조. 상의 안정 ABI.

객체 o의 바이트열 표현을 계산합니다. 실패하면 NULL을, 성공하면 바이트열 객체를 반환됩니다. 이는 o가 정수가 아닐 때 파이썬 표현식 bytes(o)와 동등합니다. bytes(o)와 달리, o가 정수이면 0으로 초기화된 바이트열 객체 대신 TypeError가 발생합니다.

인자가 NULL 이면, bytes 객체 b'<NULL>' 을 반환합니다.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)¶

상의 안정 ABI.

클래스 derived가 클래스 cls와 동일하거나 cls에서 파생되었으면 1을 반환하고, 그렇지 않으면 0을 반환합니다. 에러가 발생하면 -1을 반환합니다.

cls가 튜플이면, cls의 모든 항목에 대해 검사가 수행됩니다. 적어도 하나의 검사에서 1을 반환하면 결과는 1이 되고, 그렇지 않으면 0이 됩니다.

cls에 __subclasscheck__() 메서드가 있으면, PEP 3119에 설명된 대로 서브 클래스 상태를 판별하기 위해 호출됩니다. 그렇지 않으면, derived가 직접 또는 간접 서브 클래스일 때 cls의 서브 클래스입니다, 즉 cls.__mro__에 포함되어 있습니다.

일반적으로 클래스 객체(즉 type이나 파생 클래스의 인스턴스)만 클래스로 간주합니다. 그러나, 객체는 __bases__ 어트리뷰트(베이스 클래스의 튜플이어야 합니다)를 가짐으로써 이를 재정의할 수 있습니다.

int PyObject_IsInstance(PyObject *inst, PyObject *cls)¶

상의 안정 ABI.

inst가 cls 클래스나 cls의 서브 클래스의 인스턴스이면 1을 반환하고, 그렇지 않으면 0을 반환합니다. 에러가 발생하면 -1을 반환하고 예외를 설정합니다.

cls가 튜플이면, cls의 모든 항목에 대해 검사가 수행됩니다. 적어도 하나의 검사에서 1을 반환하면 결과는 1이 되고, 그렇지 않으면 0이 됩니다.

cls에 __instancecheck__() 메서드가 있으면, PEP 3119에 설명된 대로 서브 클래스 상태를 판별하기 위해 호출됩니다. 그렇지 않으면, inst는 해당 클래스가 cls의 서브 클래스일 때 cls의 인스턴스입니다.

인스턴스 inst는 __class__ 어트리뷰트를 가짐으로써 클래스로 간주하는 것을 재정의할 수 있습니다.

객체 cls는 __bases__ 어트리뷰트(베이스 클래스의 튜플이어야 합니다)를 가짐으로써, 클래스로 간주하는지와 베이스 클래스가 무엇인지를 재정의할 수 있습니다.

Py_hash_t PyObject_Hash(PyObject *o)¶: 상의 안정 ABI.
객체 o의 해시값을 계산하고 반환합니다. 실패하면 -1을 반환합니다. 이것은 파이썬 표현식 hash(o)와 동등합니다.

버전 3.2에서 변경: 반환형은 이제 Py_hash_t입니다. 이것은 Py_ssize_t와 같은 크기의 부호 있는 정수입니다.

Py_hash_t PyObject_HashNotImplemented(PyObject *o)¶: 상의 안정 ABI.
type(o)가 해시 가능하지 않음을 나타내는 TypeError를 설정하고 -1을 반환합니다. 이 함수는 tp_hash 슬롯에 저장될 때 특수한 처방을 받아서, 인터프리터에 형이 해시 가능하지 않음을 명시적으로 알립니다.

int PyObject_IsTrue(PyObject *o)¶: 상의 안정 ABI.
객체 o를 참으로 간주하면 1을, 그렇지 않으면 0을 반환합니다. 이것은 파이썬 표현식 not not o와 동등합니다. 실패하면 -1을 반환합니다.

int PyObject_Not(PyObject *o)¶: 상의 안정 ABI.
객체 o를 참으로 간주하면 0을, 그렇지 않으면 1을 반환합니다. 이것은 파이썬 표현식 not o와 동등합니다. 실패하면 -1을 반환합니다.

PyObject *PyObject_Type(PyObject *o)¶: 반환값: 새 참조. 상의 안정 ABI.
o가 NULL이 아니면, 객체 o의 객체 형에 해당하는 형 객체를 반환합니다. 실패하면 SystemError를 발생시키고 NULL을 반환합니다. 이것은 파이썬 표현식 type(o)와 동등합니다. 이 함수는 반환 값에 대한 새로운 강한 참조를 만듭니다. 새로운 강한 참조가 필요할 때를 제외하고, PyTypeObject* 형의 포인터를 반환하는 Py_TYPE() 함수 대신 이 함수를 사용할 이유가 없습니다.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)¶: 객체 o가 type 형이거나 type의 서브 형이면 0이 아닌 값을 반환하고, 그렇지 않으면 0을 반환합니다. 두 매개 변수 모두 NULL이 아니어야 합니다.

Py_ssize_t PyObject_Size(PyObject *o)¶
Py_ssize_t PyObject_Length(PyObject *o)¶: 상의 안정 ABI.
객체 o의 길이를 반환합니다. 객체 o가 시퀀스와 매핑 프로토콜을 제공하면, 시퀀스 길이가 반환됩니다. 에러가 발생하면 -1이 반환됩니다. 이것은 파이썬 표현식 len(o)와 동등합니다.

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)¶: o 객체의 추정된 길이를 반환합니다. 먼저 실제 길이를 반환하려고 시도한 다음, __length_hint__()를 사용하여 추정값을 반환하고, 마지막으로 기본값을 반환합니다. 에러 시 -1을 반환합니다. 이것은 파이썬 표현식 operator.length_hint(o, defaultvalue)와 동등합니다.

Added in version 3.4.

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)¶: 반환값: 새 참조. 상의 안정 ABI.
객체 key에 해당하는 o의 요소를 반환하거나 실패 시 NULL을 반환합니다. 이것은 파이썬 표현식 o[key]와 동등합니다.

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)¶: 상의 안정 ABI.
객체 key를 값 v에 매핑합니다. 실패 시 예외를 발생시키고 -1을 반환합니다; 성공하면 0을 반환합니다. 이것은 파이썬 문장 o[key] = v와 동등합니다. 이 함수는 v에 대한 참조를 훔치지 않습니다.

int PyObject_DelItem(PyObject *o, PyObject *key)¶: 상의 안정 ABI.
객체 o에서 객체 key에 대한 매핑을 제거합니다. 실패하면 -1을 반환합니다. 이것은 파이썬 문장 del o[key]와 동등합니다.

int PyObject_DelItemString(PyObject *o, const char *key)¶: 상의 안정 ABI.
This is the same as PyObject_DelItem(), but key is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

PyObject *PyObject_Dir(PyObject *o)¶: 반환값: 새 참조. 상의 안정 ABI.
이것은 파이썬 표현식 dir(o)와 동등하며, 객체 인자에 적합한 문자열의 (비어있을 수 있는) 리스트를 반환하거나, 에러가 있으면 NULL을 반환합니다. 인자가 NULL이면, 파이썬 dir()과 비슷하며, 현재 지역(locals)의 이름들을 반환합니다; 이 경우, 실행 프레임이 활성화되어 있지 않으면 NULL이 반환되지만 PyErr_Occurred()는 거짓을 반환합니다.

PyObject *PyObject_GetIter(PyObject *o)¶: 반환값: 새 참조. 상의 안정 ABI.
이것은 파이썬 표현식 iter(o)와 동등합니다. 객체 인자에 대한 새로운 이터레이터를 반환하거나, 객체가 이미 이터레이터이면 객체 자체를 반환합니다. 객체를 이터레이트 할 수 없으면 TypeError를 발생시키고 NULL을 반환합니다.

PyObject *PyObject_SelfIter(PyObject *obj)¶: 반환값: 새 참조. 상의 안정 ABI.
이것은 Python의 __iter__(self): return self 메서드와 동등합니다. iterator 유형에 사용하기 위한 것이며, PyTypeObject.tp_iter 슬롯에서 사용됩니다.

PyObject *PyObject_GetAIter(PyObject *o)¶: 반환값: 새 참조. 상의 안정 ABI 버전 3.10 이후로.
이것은 파이썬 표현식 aiter(o)와 동등합니다. AsyncIterable을 받아서 그 것의 AsyncIterator를 반환합니다. 보통 새 이터레이터이지만, 인자가 AsyncIterator면 그 자신을 반환합니다. 객체를 이터레이트 할 수 없으면 TypeError를 발생시키고 NULL을 반환합니다.

Added in version 3.10.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶

상의 안정 ABI 버전 3.12 이후로.

cls 에 예약된 서브 클래스 전용 데이터에 대한 포인터를 가져옵니다.

객체 o 는 cls 의 인스턴스여야 하며, cls 는 음수 PyType_Spec.basicsize 를 사용하여 생성되어야 합니다. Python은 이를 확인하지 않습니다.

[msgid] On error, set an exception and return NULL.

Added in version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶

상의 안정 ABI 버전 3.12 이후로.

cls 에 예약된 인스턴스 메모리 공간의 크기, 즉 PyObject_GetTypeData() 가 반환하는 메모리 크기를 반환합니다.

이는 -PyType_Spec.basicsize 를 사용하여 요청된 크기보다 클 수 있습니다. 이 더 큰 크기를 사용하는 것은 안전합니다 (예: memset() 과 함께).

타입 cls 는 반드시 음수 PyType_Spec.basicsize 를 사용하여 생성되어야 합니다. Python은 이를 확인하지 않습니다.

오류 발생 시, 예외를 설정하고 음수 값을 반환합니다.

Added in version 3.12.

void *PyObject_GetItemData(PyObject *o)¶

Py_TPFLAGS_ITEMS_AT_END 플래그가 있는 클래스에 대한 항목별 데이터 포인터를 가져옵니다.

오류 발생 시, 예외를 설정하고 NULL 을 반환합니다. o 가 Py_TPFLAGS_ITEMS_AT_END 를 가지고 있지 않은 경우, TypeError 가 발생합니다.

Added in version 3.12.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)¶

obj 의 관리된(managed) 딕셔너리를 순회합니다.

이 함수는 Py_TPFLAGS_MANAGED_DICT 플래그가 설정된 타입의 traverse 함수에서만 호출되어야 합니다.

Added in version 3.13.

void PyObject_ClearManagedDict(PyObject *obj)¶

obj 의 관리된 딕셔너리를 지웁니다.

이 함수는 Py_TPFLAGS_MANAGED_DICT 플래그가 설정된 타입의 clear 함수에서만 호출되어야 합니다.

Added in version 3.13.

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)¶

이것은 불안정 API. 경고 없이 사소 버전에서 변경될 수 있습니다.

런타임에서 지원하는 경우 obj 에 deferred reference counting 을 활성화합니다. free-threaded 빌드에서는 인터프리터가 obj 의 참조 횟수 조정하는 것을 피할 수 있게 하여 멀티스레드 성능을 개선할 수 있습니다. 단점은 obj 가 인터프리터가 더 이상 참조를 가지고 있지 않은 경우에 해제되는 것이 아니라, 트레이싱 가비지 컬렉터에 의해서만 할당 해제된다는 것입니다.

이 함수는 obj 에 deferred reference counting이 활성화되어 있으면 1 을 반환하고, deferred reference counting이 지원되지 않거나 인터프리터에 의해 힌트가 무시된 경우 (예: deferred reference counting이 obj 에 이미 활성화된 경우)에는 0 을 반환합니다. 이 함수는 스레드 안전하며 실패할 수 없습니다.

이 함수는 deferred reference counting을 지원하지 않는 GIL`가 활성화된 빌드에서는 아무것도 하지 않습니다. *obj*가 가비지 컬렉터에서 추적하는 객체가 아니어도 아무것도 하지 않습니다 ( :func:`gc.is_tracked`와 :c:func:`PyObject_GC_IsTracked 참조).

이 함수는 obj 가 생성된 직후, 즉 객체의 tp_new 슬롯과 같이 생성하는 코드에서 사용하도록 의도되었습니다.

Added in version 3.14.

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)¶

이것은 불안정 API. 경고 없이 사소 버전에서 변경될 수 있습니다.

obj 가 고유 임시 객체인지 확인합니다. obj 가 고유 임시 객체로 알려져 있으면 1 을 반환하고, 그렇지 않으면 0 을 반환합니다. 이 함수는 실패할 수 없지만, 검사는 보수적이어서 obj 가 고유 임시 객체이더라도 특정 경우에 0 을 반환할 수 있습니다.

객체가 고유 임시 객체인 경우, 현재 코드가 해당 객체에 대한 유일한 참조를 가지고 있다는 것이 보장됩니다. C 함수 인자의 경우, 참조 횟수가 1 인지 확인하는 대신 이 기능을 사용해야 합니다. Python 3.14부터 해석기는 가능한 경우 borrowing 참조를 사용하여 피연산자 스택에 객체를 로드할 때 일부 참조 횟수 변경을 내부적으로 회피하며, 이는 참조 횟수가 1 인 것만으로는 함수 인자가 고유하게 참조되었다는 것을 보장하지 않음을 의미합니다.

아래 예시에서, my_func 는 고유 임시 객체를 인자로 받습니다.:

my_func([1, 2, 3])

아래 예시에서, refcount가 1 이더라도 my_func 는 고유 임시 객체로 호출되지 않습니다.:

my_list = [1, 2, 3]
my_func(my_list)

또한 함수 :c:func:`Py_REFCNT`도 참조하십시오.

Added in version 3.14.

int PyUnstable_IsImmortal(PyObject *obj)¶: 이것은 불안정 API. 경고 없이 사소 버전에서 변경될 수 있습니다.

이 함수는 obj 가 immortal 이면 0이 아닌 값을 반환하고, 그렇지 않으면 0을 반환합니다. 이 함수는 실패할 수 없습니다.

참고

어떤 CPython 버전에서 불멸인 객체는 다른 버전에서도 불멸이라는 보장이 없습니다.

Added in version 3.14.

int PyUnstable_TryIncRef(PyObject *obj)¶

이것은 불안정 API. 경고 없이 사소 버전에서 변경될 수 있습니다.

obj 가 0이 아닌 경우 참조 횟수를 증가시킵니다. 객체의 참조 횟수가 성공적으로 증가했으면 1 을 반환합니다. 그렇지 않으면 이 함수는 0 을 반환합니다.

PyUnstable_EnableTryIncRef() 는 obj 에 대해 이전에 호출되었어야 하며, 그렇지 않으면 free-threaded build 에서 강제로 0 을 반환할 수 있습니다.

이 함수는 :term:`free-threaded build`에서 원자적으로 동작한다는 점을 제외하고는 다음 C 코드와 논리적으로 동일합니다:

if (Py_REFCNT(op) > 0) {
   Py_INCREF(op);
   return 1;
}
return 0;

이것은 Python :ref:`weak reference object <weakrefobjects>`의 오버헤드 없이 약한 참조를 관리하기 위한 빌딩 블록으로 의도되었습니다.

일반적으로 이 함수의 올바른 사용을 위해서는 obj 의 해제기 (tp_dealloc)의 지원이 필요합니다. 예를 들어, 다음 스케치는 특정 유형에 대해 WeakValueDictionary 처럼 작동하는 “weakmap”을 구현하는 데 적용할 수 있습니다.

PyMutex mutex;

PyObject *
add_entry(weakmap_key_type *key, PyObject *value)
{
    PyUnstable_EnableTryIncRef(value);
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, key, value);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
}

PyObject *
get_value(weakmap_key_type *key)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    PyObject *result = weakmap_find(weakmap, key);
    if (PyUnstable_TryIncRef(result)) {
        // `result`는 사용해도 안전함
        PyMutex_Unlock(&mutex);
        return result;
    }
    // 여기에 도달했다면, `result`는 이미 가비지 수거가 시작되었지만,
    // 아직 weakmap에서 제거되지는 않았습니다.
    PyMutex_Unlock(&mutex);
    return NULL;
}

// weakmap 값에 대한 tp_dealloc 함수
void
value_dealloc(PyObject *value)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, value);

    ...
    PyMutex_Unlock(&mutex);
}

Added in version 3.14.

void PyUnstable_EnableTryIncRef(PyObject *obj)¶: 이것은 불안정 API. 경고 없이 사소 버전에서 변경될 수 있습니다.

obj 에 대한 PyUnstable_TryIncRef() 의 후속 사용을 가능하게 합니다. 호출자는 이 함수를 호출할 때 obj 에 대한 strong reference 를 보유해야 합니다.

Added in version 3.14.

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)¶

이것은 불안정 API. 경고 없이 사소 버전에서 변경될 수 있습니다.

op 이 하나의 참조만 가지고 있는지 판별합니다.

GIL이 활성화된 빌드에서는 이 함수가 :c:expr:`Py_REFCNT(op) == 1`와 동일합니다.

free-threaded build 에서는 이 함수가 op 의 reference count 가 1과 같은지 확인하고, 추가적으로 op 이 이 스레드에 의해서만 사용되는지도 확인합니다. Py_REFCNT(op) == 1 은 free-threaded build에서 스레드 안전하지 않으므로, 이 함수를 사용하는 것이 좋습니다.

이 함수는 Python 인터프리터를 호출하지 않더라도, 호출자가 :term:`attached thread state`를 가지고 있어야 합니다. 이 함수는 실패할 수 없습니다.

Added in version 3.14.

int PyUnstable_SetImmortal(PyObject *op)¶

이것은 불안정 API. 경고 없이 사소 버전에서 변경될 수 있습니다.

객체 op 을 immortal 로 표시합니다. 인수는 호출 스레드에 의해 고유하게 참조되어야 합니다. 이것은 스레드 간에 공유되는 객체의 free-threaded build 에서 참조 횟수 경쟁을 줄이는 데 사용하기 위한 것입니다.

이것은 단방향 프로세스입니다. 객체는 불멸하게만 만들 수 있으며, 다시 유한하게 만들 수는 없습니다. 불멸 객체는 참조 횟수에 참여하지 않으며 절대 가비지 수거되지 않습니다. 객체가 GC 추적 대상인 경우, 추적이 되지 않습니다.

이 함수는 op 이 생성된 직후, 즉 객체의 tp_new 슬롯에서처럼 생성하는 코드가 사용하도록 의도되었습니다. 객체가 불멸하게 만들어졌으면 1을 반환하고, 그렇지 않으면 0을 반환합니다. 이 함수는 실패할 수 없습니다.

Added in version 3.15.

객체 프로토콜¶

분실물 보관소