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.** Thread
   safety: Atomic.*

   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.** Thread
   safety: Atomic.*

   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.

   Soft deprecated since version 3.15: Use the "PyBytesWriter" API
   instead of "PyBytes_FromStringAndSize(NULL, len)".

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

   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       | Tipo            | Comentario                       |
   | formato             |                 |                                  |
   |=====================|=================|==================================|
   | "%%"                | *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.

   [1] Para especificadores de enteros *(d, u, ld, lu, zd, zu, i, x)*:
       el indicador de conversión 0 tiene efecto incluso cuando se
       proporciona una precisión.

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

   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.** Thread
   safety: Safe for concurrent use on the same object.*

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

   Nota:

     If the object implements the buffer protocol, then the buffer
     must not be mutated while the bytes object is being created.

Py_ssize_t PyBytes_Size(PyObject *o)
    * Part of the Stable ABI.** Thread safety: Atomic.*

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

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
    * Thread safety: Atomic.*

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

char *PyBytes_AsString(PyObject *o)
    * Part of the Stable ABI.** Thread safety: Safe to call from
   multiple threads with external synchronization only.*

   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)
    * Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   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.** Thread safety: Safe to call from
   multiple threads with external synchronization only.*

   Retorna los contenidos terminados en nulo del objeto *obj* a través
   de las variables de salida *buffer* y *length*. Retorna "0" en caso
   de éxito.

   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.** Thread safety: Safe for concurrent use
   on the same object.*

   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.

   Nota:

     If *newpart* implements the buffer protocol, then the buffer must
     not be mutated while the new bytes object is being created.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
    * Part of the Stable ABI.** Thread safety: Safe for concurrent use
   on the same object.*

   Crea un nuevo objeto de bytes en **bytes* que contenga el contenido
   de *newpart* agregado a *bytes*. Esta versión libera la *strong
   reference* a *newpart* (es decir, disminuye su recuento de
   referencias).

   Nota:

     If *newpart* implements the buffer protocol, then the buffer must
     not be mutated while the new bytes object is being created.

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)
    * Thread safety: Safe for concurrent use on the same object.*

   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.

   Nota:

     If *iterable* objects implement the buffer protocol, then the
     buffers must not be mutated while the new bytes object is being
     created.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
    * Thread safety: Safe to call without external synchronization on
   distinct objects.*

   Redimensiona un objeto bytes. *newsize* será la nueva longitud del
   objeto bytes. Se puede considerar como crear un nuevo objeto bytes
   y destruir el anterior, solo que de forma más eficiente. Pasa la
   dirección de un objeto bytes existente como lvalue (se puede
   escribir en él) y el nuevo tamaño deseado. En caso de éxito,
   **bytes* contiene el objeto bytes redimensionado y se retorna "0";
   la dirección en **bytes* puede diferir de su valor de entrada. Si
   la reasignación falla, el objeto bytes original en **bytes* se
   desasigna, **bytes* se establece en "NULL", se establece
   "MemoryError" y se retorna "-1".

   Soft deprecated since version 3.15: Use the "PyBytesWriter" API
   instead.

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)
    * Part of the Stable ABI.** Thread safety: Atomic.*

   Get the string representation of *bytes*. This function is
   currently used to implement "bytes.__repr__()" in Python.

   This function does not do type checking; it is undefined behavior
   to pass *bytes* as a non-bytes object or "NULL".

   If *smartquotes* is true, the representation will use a double-
   quoted string instead of single-quoted string when single-quotes
   are present in *bytes*. For example, the byte string "'Python'"
   would be represented as "b"'Python'"" when *smartquotes* is true,
   or "b'\'Python\''" when it is false.

   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)
    * Part of the Stable ABI.** Thread safety: Atomic.*

   Unescape a backslash-escaped string *s*. *s* must not be "NULL".
   *len* must be the size of *s*.

   *errors* must be one of ""strict"", ""replace"", or ""ignore"". If
   *errors* is "NULL", then ""strict"" is used by default.

   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.

   Distinto en la versión 3.9: *unicode* and *recode_encoding* are now
   unused.


PyBytesWriter
*************

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

Added in version 3.15.

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()". This function does not
   overallocate.

   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.

   The function cannot fail.

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*.

   The function cannot fail.


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. This function typically overallocates to achieve
   amortized performance when resizing multiple times.

   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. This function typically overallocates to achieve amortized
   performance when resizing multiple times.

   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;
