바이트열 객체¶

이 함수들은 바이트열 매개 변수가 필요할 때 바이트열이 아닌 매개 변수로 호출하면 TypeError를 발생시킵니다.

type PyBytesObject¶: 이 PyObject의 서브 형은 파이썬 바이트열 객체를 나타냅니다.

PyTypeObject PyBytes_Type¶: …의 일부 안정 ABI.
이 PyTypeObject의 인스턴스는 파이썬 바이트열 형을 나타냅니다; 파이썬 계층의 bytes와 같은 객체입니다.

int PyBytes_Check(PyObject *o)¶: 객체 o가 바이트열 객체이거나 바이트열 형의 서브 형의 인스턴스면 참을 반환합니다. 이 함수는 항상 성공합니다.

int PyBytes_CheckExact(PyObject *o)¶: 객체 o가 바이트열 객체이지만, 바이트열 형의 서브 형의 인스턴스는 아니면 참을 반환합니다. 이 함수는 항상 성공합니다.

PyObject *PyBytes_FromString(const char *v)¶: 반환값: 새 참조. …의 일부 안정 ABI. Thread safety: Atomic.
성공하면 값으로 v 문자열의 복사본을 갖는 새 바이트열 객체를 반환하고, 실패하면 NULL을 반환합니다. 매개 변수 v는 NULL이 아니어야 합니다; 검사하지 않습니다.

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)¶: 반환값: 새 참조. …의 일부 안정 ABI. Thread safety: Atomic.
성공하면 값이 v 문자열의 복사본이고 길이가 len인 새 바이트열 객체를 반환하고, 실패하면 NULL을 반환합니다. v가 NULL이면, 바이트열 객체의 내용은 초기화되지 않습니다.

버전 3.15부터 약하게 폐지 <Soft deprecated>: PyBytes_FromStringAndSize(NULL, len) 대신 PyBytesWriter API를 사용하십시오.

PyObject *PyBytes_FromFormat(const char *format, ...)¶

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

C printf()-스타일 format 문자열과 가변 개수의 인자를 받아서, 결과 파이썬 바이트열 객체의 크기를 계산하고 그 안에 값이 포맷된 바이트열 객체를 반환합니다. 가변 인자는 C 형이어야 하며 format 문자열에 있는 포맷 문자들과 정확히 대응해야 합니다. 허용되는 포맷 문자는 다음과 같습니다:

포맷 문자	형	주석
`%%`	n/a	리터럴 % 문자.
`%c`	int	단일 바이트, C int로 표현됩니다.
`%d`	int	`printf("%d")`와 동등합니다. [1]
`%u`	unsigned int	`printf("%u")`와 동등합니다. [1]
`%ld`	long	`printf("%ld")`와 동등합니다. [1]
`%lu`	unsigned long	`printf("%lu")`와 동등합니다. [1]
`%zd`	`Py_ssize_t`	`printf("%zd")`와 동등합니다. [1]
`%zu`	size_t	`printf("%zu")`와 동등합니다. [1]
`%i`	int	`printf("%i")`와 동등합니다. [1]
`%x`	int	`printf("%x")`와 동등합니다. [1]
`%s`	const char*	널-종료 C 문자 배열.
`%p`	const void*	C 포인터의 16진수 표현. 플랫폼의 `printf`가 어떤 결과를 내는지에 상관없이 리터럴 `0x`로 시작함이 보장된다는 점을 제외하고는 거의 `printf("%p")`와 동등합니다.

인식할 수 없는 포맷 문자는 포맷 문자열의 나머지 부분이 모두 결과 객체에 그대로 복사되게 만들고, 추가 인자는 무시됩니다.

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)¶: 반환값: 새 참조. …의 일부 안정 ABI. Thread safety: Atomic.
정확히 두 개의 인자를 취한다는 것을 제외하고는 PyBytes_FromFormat()과 같습니다.

PyObject *PyBytes_FromObject(PyObject *o)¶: 반환값: 새 참조. …의 일부 안정 ABI. Thread safety: Safe for concurrent use on the same object.
버퍼 프로토콜을 구현하는 객체 o의 바이트열 표현을 반환합니다.

참고

객체가 버퍼 프로토콜을 구현하는 경우, 바이트 객체가 생성되는 동안 버퍼를 변경해서는 안 됩니다.

Py_ssize_t PyBytes_Size(PyObject *o)¶: …의 일부 안정 ABI. Thread safety: Atomic.
바이트열 객체 o의 길이를 반환합니다.

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)¶: Thread safety: Atomic.
PyBytes_Size()와 유사하지만, 에러 검사가 없습니다.

char *PyBytes_AsString(PyObject *o)¶: …의 일부 안정 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.
o의 내용에 대한 포인터를 반환합니다. 포인터는 len(o) + 1 바이트로 구성된 o의 내부 버퍼를 가리킵니다. 버퍼의 마지막 바이트는 다른 널(null) 바이트가 있는지에 관계없이 항상 널입니다. 객체가 PyBytes_FromStringAndSize(NULL, size)를 사용하여 방금 만들어진 경우가 아니면 데이터를 수정해서는 안 됩니다. 할당을 해제해서는 안 됩니다. o가 바이트열 객체가 아니면, PyBytes_AsString()은 NULL을 반환하고 TypeError를 발생시킵니다.

char *PyBytes_AS_STRING(PyObject *string)¶: Thread safety: Safe to call from multiple threads with external synchronization only.
PyBytes_AsString()와 유사하지만, 에러 검사가 없습니다.

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)¶

…의 일부 안정 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

출력 변수 buffer와 length로 객체 obj의 널-종료 내용을 반환합니다. 성공하면 0을 반환합니다.

length가 NULL이면, 바이트열 객체는 내장된 널 바이트를 포함할 수 없습니다; 만약 그렇다면 함수는 -1을 반환하고 ValueError를 발생시킵니다.

buffer는 obj의 내부 버퍼를 가리키게 되는데, 끝에 추가 널 바이트가 포함됩니다 (length에는 포함되지 않습니다). 객체가 PyBytes_FromStringAndSize(NULL, size)를 사용하여 방금 만들어진 경우가 아니면 데이터를 수정해서는 안 됩니다. 할당을 해제해서는 안 됩니다. obj가 바이트열 객체가 아니면 PyBytes_AsStringAndSize()는 -1을 반환하고 TypeError를 발생시킵니다.

버전 3.5에서 변경: 이전에는, 바이트열 객체에 널 바이트가 포함되어 있으면 TypeError가 발생했습니다.

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)¶: …의 일부 안정 ABI. Thread safety: Safe for concurrent use on the same object.
*bytes 에 newpart 를 추가한 내용으로 새로운 bytes 객체를 생성합니다. 호출자가 새 참조를 소유하게 됩니다. bytes 의 이전 값에 대한 참조는 “stolen “됩니다. 새 객체를 생성할 수 없는 경우에도 bytes 의 기존 참조는 여전히 “stolen”되며, *bytes 값은 NULL 로 설정되고 적절한 예외가 발생합니다.

참고

newpart 가 버퍼 프로토콜을 구현하는 경우, 새 바이트 객체가 생성되는 동안 버퍼를 변경해서는 안 됩니다.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)¶: …의 일부 안정 ABI. Thread safety: Safe for concurrent use on the same object.
bytes에 newpart의 내용을 덧붙인 새 바이트열 객체를 *bytes에 만듭니다. 이 버전은 newpart로의 강한 참조를 해제합니다 (즉 참조 횟수를 감소시킵니다).

참고

newpart 가 버퍼 프로토콜을 구현하는 경우, 새 바이트 객체가 생성되는 동안 버퍼를 변경해서는 안 됩니다.

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)¶

Thread safety: Safe for concurrent use on the same object.

파이썬의 sep.join(iterable)와 유사합니다.

sep은 반드시 파이썬의 bytes 객체이어야 합니다.(PyUnicode_Join()는 NULL 구분자를 허용하고 이를 공백으로 취급하는 반면, PyBytes_Join()는 NULL 구분자를 허용하지 않음에 유의하십시오.)

iterable은 반드시 버퍼 프로토콜을 구현하는 객체를 생성하는 반복 가능한 객체이어야 합니다.

성공 시 새로운 bytes 객체를 반환합니다. 실패 시 예외를 설정하고 NULL을 반환합니다.

Added in version 3.14.

참고

iterable 객체들이 버퍼 프로토콜을 구현하는 경우, 새 바이트 객체가 생성되는 동안 버퍼를 변경해서는 안 됩니다.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)¶: Thread safety: Safe to call without external synchronization on distinct objects.
바이트열 객체의 크기를 변경합니다. newsize는 바이트열 객체의 새 길이가 됩니다. 새 바이트열 객체를 생성하고 이전 객체를 파괴한다고 생각할 수 있습니다. 단지 더 효율적으로 수행합니다. 기존 바이트열 객체의 주소를 lvalue(내용을 기록할 수 있습니다)로 전달하고, 원하는 새 크기를 전달합니다. 성공하면, *bytes는 크기가 변경된 바이트열 객체를 갖게 되고 0이 반환됩니다; *bytes의 주소는 입력값과 다를 수 있습니다. 재할당이 실패하면, *bytes에 있는 원래 바이트열 객체는 할당 해제되고, *bytes가 NULL로 설정되고, MemoryError가 설정되며 -1이 반환됩니다.

버전 3.15부터 약하게 폐지 <Soft deprecated>: 대신 PyBytesWriter API를 사용하십시오.

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)¶

…의 일부 안정 ABI. Thread safety: Atomic.

bytes 의 문자열 표현을 가져옵니다. 이 함수는 현재 파이썬에서 bytes.__repr__() 를 구현하는 데 사용됩니다.

이 함수는 타입 체크를 수행하지 않습니다. bytes 를 바이트가 아닌 객체나 NULL 으로 전달하는 것은 정의되지 않은 동작(undefined behavior)입니다.

smartquotes 가 true인 경우, bytes 에 작은따옴표가 포함되어 있으면 문자열 표현 시 큰따옴표를 사용합니다. 예를 들어, 바이트 문자열 'Python' 은 smartquotes 가 true일 때 b"'Python'" 로, false일 때 b'\'Python\'' 으로 표현됩니다.

On success, this function returns a strong reference to a str object containing the representation. On failure, this returns NULL with an exception set.

PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)¶

…의 일부 안정 ABI. Thread safety: Atomic.

백슬래시로 이스케이프된 문자열 s 를 언이스케이프합니다. s 는 NULL 이 아니어야 하며, len 은 s 의 크기여야 합니다.

errors 는 "strict", "replace" 또는 "ignore" 중 하나여야 합니다. errors 가 NULL 인 경우 기본적으로 "strict" 가 사용됩니다.

On success, this function returns a strong reference to a Python bytes object containing the unescaped string. On failure, this function returns NULL with an exception set.

버전 3.9에서 변경: unicode 와 recode_encoding 은 이제 사용되지 않습니다.

PyBytesWriter¶

PyBytesWriter API를 사용하여 파이썬 bytes 객체를 생성할 수 있습니다.

Added in version 3.15.

type PyBytesWriter¶

바이트 기록기(bytes writer) 인스턴스입니다.

이 API는 스레드 안전하지 않습니다: 기록기는 한 번에 하나의 스레드에서만 사용되어야 합니다.

인스턴스는 성공 시 PyBytesWriter_Finish() 에 의해, 오류 시 PyBytesWriter_Discard() 에 의해 파괴되어야 합니다.

생성, 종료, 폐기¶

PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)¶

size 바이트를 쓰기 위한 PyBytesWriter 를 생성합니다.

size 가 0보다 크면 size 바이트를 할당하고 기록기 크기를 size 로 설정합니다. 호출자는 PyBytesWriter_GetData() 를 사용하여 size 바이트를 작성할 책임이 있습니다. 이 함수는 과도하게 할당(overallocate)하지 않습니다.

오류 시 예외를 설정하고 NULL 을 반환합니다.

size 는 양수이거나 0이어야 합니다.

PyObject *PyBytesWriter_Finish(PyBytesWriter *writer)¶

PyBytesWriter_Create() 에 의해 생성된 PyBytesWriter 를 완료합니다.

성공 시 파이썬 bytes 객체를 반환합니다. 오류 시 예외를 설정하고 NULL 을 반환합니다.

어떠한 경우에도 호출 후에는 기록기 인스턴스가 유효하지 않습니다. PyBytesWriter_Finish() 이후에는 기록기에 대한 어떤 API도 호출할 수 없습니다.

PyObject *PyBytesWriter_FinishWithSize(PyBytesWriter *writer, Py_ssize_t size)¶: PyBytesWriter_Finish() 와 유사하지만, bytes 객체를 생성하기 전에 기록기를 size 바이트로 조정합니다.

PyObject *PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)¶

PyBytesWriter_Finish() 와 유사하지만, bytes 객체를 생성하기 전에 buf 포인터를 사용하여 기록기를 조정합니다.

buf 포인터가 내부 버퍼 범위를 벗어난 경우 예외를 설정하고 NULL 을 반환합니다.

함수 의사 코드:

Py_ssize_t size = (char*)buf - (char*)PyBytesWriter_GetData(writer);
return PyBytesWriter_FinishWithSize(writer, size);

void PyBytesWriter_Discard(PyBytesWriter *writer)¶

PyBytesWriter_Create() 에 의해 생성된 PyBytesWriter 를 버립니다.

writer 가 NULL 이면 아무 작업도 하지 않습니다.

호출 후에는 기록기 인스턴스가 유효하지 않습니다. PyBytesWriter_Discard() 이후에는 기록기에 대한 어떤 API도 호출할 수 없습니다.

고수준 API¶

int PyBytesWriter_WriteBytes(PyBytesWriter *writer, const void *bytes, Py_ssize_t size)¶

writer 의 내부 버퍼를 size 바이트만큼 확장하고, writer 끝에 bytes 의 size 바이트를 작성하며, writer 크기에 size 를 추가합니다.

size 가 -1 과 같으면 strlen(bytes) 를 호출하여 문자열 길이를 가져옵니다.

성공 시 0 을 반환합니다. 오류 시 예외를 설정하고 -1 을 반환합니다.

int PyBytesWriter_Format(PyBytesWriter *writer, const char *format, ...)¶

PyBytes_FromFormat() 과 유사하지만, 출력을 기록기 끝에 직접 작성합니다. 필요에 따라 기록기의 내부 버퍼를 확장하고, 그 후 작성된 크기를 기록기 크체에 더합니다.

성공 시 0 을 반환합니다. 오류 시 예외를 설정하고 -1 을 반환합니다.

게터(Getters)¶

Py_ssize_t PyBytesWriter_GetSize(PyBytesWriter *writer)¶

기록기 크기를 가져옵니다.

이 함수는 PyBytesWriter_GetData() 에 의해 반환된 포인터를 무효화하지 않습니다.

이 함수는 실패할 수 없습니다.

void *PyBytesWriter_GetData(PyBytesWriter *writer)¶

기록기 데이터를 가져옵니다: 내부 버퍼의 시작 부분.

해당 포인터는 writer 에 대해 PyBytesWriter_GetData() 또는 PyBytesWriter_GetSize() 를 제외한 다른 PyBytesWriter 함수가 호출될 때까지 유효합니다.

이 함수는 실패할 수 없습니다.

저수준 API¶

int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size)¶

기록기를 size 바이트로 조정합니다. 이 함수는 기록기를 확장하거나 축소하는 데 사용될 수 있습니다. 여러 번 크기를 조정할 때 분할 상환(amortized) 성능을 확보하기 위해 일반적으로 과도하게 할당(overallocate)합니다.

새로 할당된 바이트는 초기화되지 않은 상태로 남습니다.

성공 시 0 을 반환합니다. 오류 시 예외를 설정하고 -1 을 반환합니다.

size 는 양수이거나 0이어야 합니다.

int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)¶

현재 기록기 크기에 grow 바이트를 더하여 기록기를 조정합니다. 이 함수는 여러 번 크기를 조정할 때 분할 상량 성능을 확보하기 위해 일반적으로 과도하게 할당합니다.

새로 할당된 바이트는 초기화되지 않은 상태로 남습니다.

성공 시 0 을 반환합니다. 오류 시 예외를 설정하고 -1 을 반환합니다.

size 가 음수이면 기록기를 축소할 수 있습니다.

void *PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)¶

PyBytesWriter_Grow() 와 유사하지만, buf 포인터도 업데이트합니다.

메모리 내에서 내부 버퍼가 이동하면 buf 포인터도 이동합니다. 그러나 내부 버퍼 내에서의 buf 상대 위치는 변하지 않습니다.

오류 시 예외를 설정하고 NULL 을 반환합니다.

buf 은 NULL 이 아니어야 합니다.

함수 의사 코드:

Py_ssize_t pos = (char*)buf - (char*)PyBytesWriter_GetData(writer);
if (PyBytesWriter_Grow(writer, size) < 0) {
    return NULL;
}
return (char*)PyBytesWriter_GetData(writer) + pos;

바이트열 객체¶

PyBytesWriter¶

생성, 종료, 폐기¶

고수준 API¶

게터(Getters)¶

저수준 API¶

분실물 보관소