객체 프로토콜¶

PyObject *Py_GetConstant(unsigned int constant_id)¶

…의 일부 안정 ABI 버전 3.13 이후로.

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 구현 상세: In CPython, all of these constants are immortal.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶

…의 일부 안정 ABI 버전 3.13 이후로.

Similar to Py_GetConstant(), but return a 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() 대신 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 에 출력(dump)합니다. 이 함수는 디버깅 용도로만 사용해야 합니다.

출력물은 메모리 손상 후에도 객체를 최대한 출력하도록 설계되었습니다:

정보는 액세스 시 충돌 가능성이 가장 낮은 필드부터 기록됩니다.
이 함수는 attached thread state 없이 호출할 수 있지만, 데드락을 유발할 수 있으므로 권장되지 않습니다.
현재 인터프리터에 속하지 않는 객체도 출력될 수 있지만, 이는 충돌이나 예기치 않은 동작을 유발할 수 있습니다.
객체 메모리가 해제되었는지 감지하는 휴리스틱을 구현합니다. 이 경우 객체의 내용을 표시하지 않고 메모리 주소만 표시합니다.
출력 형식이 언제든 변경될 수 있습니다.

출력 예시:

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 이후로.
이것은 PyObject_HasAttrWithError() 와 동일하지만, attr_name 이 PyObject* 대신 const char* UTF-8 인코딩 바이트 문자열로 지정됩니다.

Added in version 3.13.

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

참고

이 함수가 __getattr__() 및 __getattribute__() 메서드를 호출할 때 발생하는 예외는 전파되지 않고 대신 sys.unraisablehook() 으로 전달됩니다. 적절한 에러 처리를 위해서는 대신 PyObject_HasAttrWithError(), PyObject_GetOptionalAttr() 또는 PyObject_GetAttr() 을 사용하십시오.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)¶: …의 일부 안정 ABI.
이것은 PyObject_HasAttr() 와 동일하지만, attr_name 이 PyObject* 대신 const char* UTF-8 인코딩 바이트 문자열로 지정됩니다.

참고

__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과 동등합니다.

누락된 어트리뷰트를 실패로 처리하지 않아야 하는 경우, 대신 PyObject_GetOptionalAttr() 을 사용할 수 있습니다.

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

반환값: 새 참조. …의 일부 안정 ABI.

이것은 PyObject_GetAttr() 와 동일하지만, attr_name 이 PyObject* 대신 const char* UTF-8 인코딩 바이트 문자열로 지정됩니다.

누락된 어트리뷰트를 실패로 처리하지 않아야 하는 경우, 대신 PyObject_GetOptionalAttrString() 을 사용할 수 있습니다.

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

…의 일부 안정 ABI 버전 3.13 이후로.

어트리뷰트를 찾을 수 없어도 AttributeError 를 발생시키지 않는 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 이후로.
이것은 PyObject_GetOptionalAttr() 와 동일하지만, attr_name 이 PyObject* 대신 const char* UTF-8 인코딩 바이트 문자열로 지정됩니다.

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()로 대체되었습니다만, 현재 제거할 계획이 없습니다.

이 함수는 예외가 설정된 상태에서 v 가 NULL 인 경우 호출되어서는 안 됩니다. 이러한 상황은 NULL 체크를 누락하여 발생할 수 있으며, 이 경우 어트리뷰트가 삭제될 수 있습니다.

버전 3.15에서 변경: 예외가 설정된 경우 NULL 값과 함께 호출되어서는 안 됩니다.

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

…의 일부 안정 ABI.

이것은 PyObject_SetAttr() 와 동일하지만, attr_name 이 PyObject* 대신 const char* UTF-8 인코딩 바이트 문자열로 지정됩니다.

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

이 함수에 전달되는 서로 다른 어트리뷰트 이름의 수는 적게 유지해야 하며, 일반적으로 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 이후로.

이것은 PyObject_DelAttr() 와 동일하지만, attr_name 이 PyObject* 대신 const char* UTF-8 인코딩 바이트 문자열로 지정됩니다.

이 함수에 전달되는 서로 다른 어트리뷰트 이름의 수는 적게 유지해야 하며, 일반적으로 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 을 반환합니다.

이 함수는 딕셔너리를 위해 메모리를 할당해야 할 수 있으므로, 객체의 어트리뷰트에 접근할 때는 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.
PyObject_RichCompare() 와 유사하게 opid 에 지정된 연산을 사용하여 o1 과 o2 의 값을 비교하되, 에러 시 -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.
이것은 PyObject_DelItem() 과 동일하지만, key 가 PyObject* 대신 const char* UTF-8 인코딩 바이트 문자열로 지정됩니다.

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.
이것은 파이썬의 __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 를 사용하여 생성되어야 합니다. 파이썬은 이를 확인하지 않습니다.

오류 시 예외를 설정하고 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 를 사용하여 생성되어야 합니다. 파이썬은 이를 확인하지 않습니다.

에러 시, 예외를 설정하고 음수 값을 반환합니다.

Added in version 3.12.

void *PyObject_GetItemData(PyObject *o)¶

Py_TPFLAGS_ITEMS_AT_END 을 포함하는 클래스의 항목당 데이터(per-item data) 포인터를 가져옵니다.

에러 시, 예외를 설정하고 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 을 반환하고, 지원되지 않거나 인터프리터에 의해 힌트가 무시된 경우(예: obj 에서 이미 지연된 참조 횟수가 활성화된 경우)에는 0 을 반환합니다. 이 함수는 스레드 안전하며 실패하지 않습니다.

이 함수는 지연된 참조 횟수를 지원하지 않는 GIL 활성화 빌드에서는 아무 작업도 수행하지 않습니다. 또한 obj 가 가비지 컬렉터에 의해 추적되는 객체가 아닌 경우에도 아무 작업도 수행하지 않습니다(참조: gc.is_tracked() 및 PyObject_GC_IsTracked()).

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

Added in version 3.14.

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)¶

이것은 불안정 API. 마이너 릴리스에서 예고 없이 변경될 수 있습니다.

obj 이 고유한 임시 객체인지 확인합니다. obj 가 고유한 임시 객체로 확인되면 1 을, 그렇지 않으면 0 을 반환합니다. 이 함수는 실패하지 않지만, 검사는 보수적으로 수행되므로 obj 가 고유한 임시 객체임에도 불구하고 일부 경우에 0 을 반환할 수 있습니다.

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

아래 예제에서 my_func 는 고유한 임시 객체를 인자로 하여 호출됩니다:

my_func([1, 2, 3])

아래 예제에서 my_func 는 참조 횟수가 1 이더라도 고유한 임시 객체를 인자로 하여 호출되지 않습니다:

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

Py_REFCNT() 함수도 참조하십시오.

Added in version 3.14.

int PyUnstable_IsImmortal(PyObject *obj)¶: 이것은 불안정 API. 마이너 릴리스에서 예고 없이 변경될 수 있습니다.

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

참고

특정 CPython 버전에서 immortal인 객체가 다른 버전에서도 immortal임이 보장되지 않습니다.

Added in version 3.14.

int PyUnstable_TryIncRef(PyObject *obj)¶

이것은 불안정 API. 마이너 릴리스에서 예고 없이 변경될 수 있습니다.

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

obj 에 대해 이전에 PyUnstable_EnableTryIncRef() 가 호출되어야 합니다. 그렇지 않으면 free-threaded build 에서 이 함수가 잘못된 값으로 0 을 반환할 수 있습니다.

이 함수는 다음 C 코드와 논리적으로 동일하지만, free-threaded build 에서는 원자적으로 동작한다는 차이가 있습니다:

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

이 기능은 Python 약한 참조 객체 의 오버헤드 없이 약한 참조를 관리하기 위한 구성 요소로 설계되었습니다.

일반적으로 이 함수를 올바르게 사용하려면 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이 활성화된 빌드에서 이 함수는 Py_REFCNT(op) == 1 과 동일합니다.

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

The caller must hold an attached thread state, despite the fact that this function doesn’t call into the Python interpreter. This function cannot fail.

Added in version 3.14.

int PyUnstable_SetImmortal(PyObject *op)¶

이것은 불안정 API. 마이너 릴리스에서 예고 없이 변경될 수 있습니다.

객체 op 를 immortal 로 표시합니다. 인자는 호출하는 스레드에 의해 독점적으로 참조되어야 합니다. 이 기능은 여러 스레드 간에 공유되는 객체에 대해 free-threaded build 에서 발생하는 참조 횟수 경합을 줄이기 위해 사용됩니다.

이것은 단방향 과정입니다. 객체는 immortal이 될 수만 있고 다시 mortal이 될 수는 없습니다. immortal 객체는 참조 횟수 계산에 참여하지 않으며 가비지 수거되지 않습니다. 객체가 GC 추적 대상인 경우, 추적이 해제됩니다.

이 함수는 op 이 생성된 직후에 이를 생성하는 코드(예: 객체의 tp_new 슬롯)에서 사용되도록 설계되었습니다. 객체가 immortal로 설정되면 1을, 그렇지 않으면 0을 반환합니다. 이 함수는 실패하지 않습니다.

Added in version 3.15.

객체 프로토콜¶

분실물 보관소