Objetos bytes

Estas funciones lanzan TypeError cuando se espera un parámetro de bytes y se llama con un parámetro que no es bytes.

type PyBytesObject

Este subtipo de PyObject representa un objeto bytes de Python.

PyTypeObject PyBytes_Type
Part of the Stable ABI.

Esta instancia de PyTypeObject representa el tipo bytes de Python; es el mismo objeto que bytes en la capa de Python.

int PyBytes_Check(PyObject *o)

Retorna verdadero si el objeto o es un objeto bytes o una instancia de un subtipo del tipo bytes. Esta función siempre finaliza con éxito.

int PyBytes_CheckExact(PyObject *o)

Retorna verdadero si el objeto o es un objeto bytes, pero no una instancia de un subtipo del tipo bytes. Esta función siempre finaliza con éxito.

PyObject *PyBytes_FromString(const char *v)
Return value: New reference. Part of the Stable ABI.

Retorna un nuevo objeto bytes con una copia de la cadena de caracteres v como valor en caso de éxito y NULL en caso de error. El parámetro v no debe ser NULL; no se comprobará.

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
Return value: New reference. Part of the Stable ABI.

Retorna un nuevo objeto bytes con una copia de la cadena de caracteres v como valor y longitud len en caso de éxito y NULL en caso de error. Si v es NULL, el contenido del objeto bytes no se inicializa.

Obsoleto desde la versión 3.15: PyBytes_FromStringAndSize(NULL, len) is soft deprecated, use the PyBytesWriter API instead.

PyObject *PyBytes_FromFormat(const char *format, ...)
Return value: New reference. Part of the Stable ABI.

Toma una cadena de caracteres format del estilo C printf() y un número variable de argumentos, calcula el tamaño del objeto bytes Python resultante y retorna un objeto bytes con los valores formateados. Los argumentos variables deben ser tipos C y deben corresponder exactamente a los caracteres de formato en la cadena de caracteres format. Se permiten los siguientes caracteres de formato:

Caracteres de formato

Tipo

Comentario

%%

n/a

El carácter literal %.

%c

int

Un solo byte, representado como un C int.

%d

int

Equivalente a printf("%d"). [1]

%u

unsigned int

Equivalente a printf("%u"). [1]

%ld

long

Equivalente a printf("%ld"). [1]

%lu

unsigned long

Equivalente a printf("%lu"). [1]

%zd

Py_ssize_t

Equivalente a printf("%zd"). [1]

%zu

size_t

Equivalente a printf("%zu"). [1]

%i

int

Equivalente a printf("%i"). [1]

%x

int

Equivalente a printf("%x"). [1]

%s

const char*

Un arreglo de caracteres C terminados en nulo.

%p

const void*

La representación hexadecimal de un puntero en C. Principalmente equivalente a printf("%p") excepto que se garantiza que comience con el literal 0x, independientemente de lo que produzca el printf de la plataforma.

Un carácter de formato no reconocido hace que todo el resto de la cadena de caracteres de formato se copie como está en el objeto de resultado y se descartan los argumentos adicionales.

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)
Return value: New reference. Part of the Stable ABI.

Idéntica a PyBytes_FromFormat() excepto que toma exactamente dos argumentos.

PyObject *PyBytes_FromObject(PyObject *o)
Return value: New reference. Part of the Stable ABI.

Retorna la representación en bytes del objeto o que implementa el protocolo de búfer.

Py_ssize_t PyBytes_Size(PyObject *o)
Part of the Stable ABI.

Retorna la longitud de los bytes en el objeto bytes o.

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

Forma macro de PyBytes_Size() pero sin verificación de errores.

char *PyBytes_AsString(PyObject *o)
Part of the Stable ABI.

Retorna un puntero al contenido de o. El puntero se refiere al búfer interno de o, que consiste en len(o) + 1 bytes. El último byte en el búfer siempre es nulo, independientemente de si hay otros bytes nulos. Los datos no deben modificarse de ninguna manera, a menos que el objeto se haya creado usando PyBytes_FromStringAndSize(NULL, size). No debe ser desasignado. Si o no es un objeto de bytes en absoluto, PyBytes_AsString() retorna NULL y lanza un TypeError.

char *PyBytes_AS_STRING(PyObject *string)

Forma macro de PyBytes_AsString() pero sin verificación de errores.

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
Part of the Stable ABI.

Return the null-terminated contents of the object obj through the output variables buffer and length. Returns 0 on success.

Si length es NULL, el objeto bytes no puede contener bytes nulos incrustados; en caso contrario, la función retorna -1 y se lanza un ValueError.

El búfer se refiere a un búfer interno de obj, que incluye un byte nulo adicional al final (no está considerado en length). Los datos no deben modificarse de ninguna manera, a menos que el objeto se haya creado usando PyBytes_FromStringAndSize(NULL, size). No debe ser desasignado. Si obj no es un objeto bytes en absoluto, PyBytes_AsStringAndSize() retorna -1 y lanza TypeError.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzaba cuando se encontraban bytes nulos incrustados en el objeto bytes.

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
Part of the Stable ABI.

Crea un nuevo objeto de bytes en *bytes que contiene el contenido de newpart agregado a bytes; la persona que llama poseerá la nueva referencia. La referencia al valor anterior de bytes será robada. Si no se puede crear el nuevo objeto, la referencia anterior a bytes se seguirá descartando y el valor de *bytes se establecerá en NULL; se establecerá la excepción apropiada.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
Part of the Stable ABI.

Create a new bytes object in *bytes containing the contents of newpart appended to bytes. This version releases the strong reference to newpart (i.e. decrements its reference count).

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

Similar to sep.join(iterable) in Python.

sep must be Python bytes object. (Note that PyUnicode_Join() accepts NULL separator and treats it as a space, whereas PyBytes_Join() doesn’t accept NULL separator.)

iterable must be an iterable object yielding objects that implement the buffer protocol.

On success, return a new bytes object. On error, set an exception and return NULL.

Added in version 3.14.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

Resize a bytes object. newsize will be the new length of the bytes object. You can think of it as creating a new bytes object and destroying the old one, only more efficiently. Pass the address of an existing bytes object as an lvalue (it may be written into), and the new size desired. On success, *bytes holds the resized bytes object and 0 is returned; the address in *bytes may differ from its input value. If the reallocation fails, the original bytes object at *bytes is deallocated, *bytes is set to NULL, MemoryError is set, and -1 is returned.

Obsoleto desde la versión 3.15: The function is soft deprecated, use the PyBytesWriter API instead.

PyBytesWriter

The PyBytesWriter API can be used to create a Python bytes object.

Added in version 3.15.0a0 (unreleased).

type PyBytesWriter

A bytes writer instance.

The API is not thread safe: a writer should only be used by a single thread at the same time.

The instance must be destroyed by PyBytesWriter_Finish() on success, or PyBytesWriter_Discard() on error.

Create, Finish, Discard

PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)

Create a PyBytesWriter to write size bytes.

If size is greater than zero, allocate size bytes, and set the writer size to size. The caller is responsible to write size bytes using PyBytesWriter_GetData().

On error, set an exception and return NULL.

size must be positive or zero.

PyObject *PyBytesWriter_Finish(PyBytesWriter *writer)

Finish a PyBytesWriter created by PyBytesWriter_Create().

On success, return a Python bytes object. On error, set an exception and return NULL.

The writer instance is invalid after the call in any case. No API can be called on the writer after PyBytesWriter_Finish().

PyObject *PyBytesWriter_FinishWithSize(PyBytesWriter *writer, Py_ssize_t size)

Similar to PyBytesWriter_Finish(), but resize the writer to size bytes before creating the bytes object.

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

Similar to PyBytesWriter_Finish(), but resize the writer using buf pointer before creating the bytes object.

Set an exception and return NULL if buf pointer is outside the internal buffer bounds.

Function pseudo-code:

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

Discard a PyBytesWriter created by PyBytesWriter_Create().

Do nothing if writer is NULL.

The writer instance is invalid after the call. No API can be called on the writer after PyBytesWriter_Discard().

High-level API

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

Grow the writer internal buffer by size bytes, write size bytes of bytes at the writer end, and add size to the writer size.

If size is equal to -1, call strlen(bytes) to get the string length.

On success, return 0. On error, set an exception and return -1.

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

Similar to PyBytes_FromFormat(), but write the output directly at the writer end. Grow the writer internal buffer on demand. Then add the written size to the writer size.

On success, return 0. On error, set an exception and return -1.

Getters

Py_ssize_t PyBytesWriter_GetSize(PyBytesWriter *writer)

Get the writer size.

void *PyBytesWriter_GetData(PyBytesWriter *writer)

Get the writer data: start of the internal buffer.

The pointer is valid until PyBytesWriter_Finish() or PyBytesWriter_Discard() is called on writer.

Low-level API

int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size)

Resize the writer to size bytes. It can be used to enlarge or to shrink the writer.

Newly allocated bytes are left uninitialized.

On success, return 0. On error, set an exception and return -1.

size must be positive or zero.

int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)

Resize the writer by adding grow bytes to the current writer size.

Newly allocated bytes are left uninitialized.

On success, return 0. On error, set an exception and return -1.

size can be negative to shrink the writer.

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

Similar to PyBytesWriter_Grow(), but update also the buf pointer.

The buf pointer is moved if the internal buffer is moved in memory. The buf relative position within the internal buffer is left unchanged.

On error, set an exception and return NULL.

buf must not be NULL.

Function pseudo-code:

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