Objetos Bytes¶
Estas funções levantam TypeError quando se espera um parâmetro bytes e são chamados com um parâmetro que não é bytes.
-
PyTypeObject PyBytes_Type¶
- Parte da ABI Estável.
Esta instância de
PyTypeObjectrepresenta o tipo de bytes Python; é o mesmo objeto quebytesna camada de Python.
-
int PyBytes_Check(PyObject *o)¶
Retorna verdadeiro se o objeto o for um objeto bytes ou se for uma instância de um subtipo do tipo bytes. Esta função sempre tem sucesso.
-
int PyBytes_CheckExact(PyObject *o)¶
Retorna verdadeiro se o objeto o for um objeto bytes, mas não uma instância de um subtipo do tipo bytes. Esta função sempre tem sucesso.
-
PyObject *PyBytes_FromString(const char *v)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um novo objeto de bytes com uma cópia da string v como valor em caso de sucesso e
NULLem caso de falha. O parâmetro v não deve serNULLe isso não será verificado.
-
PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um novo objeto de bytes com uma cópia da string v como valor e comprimento len em caso de sucesso e
NULLem caso de falha. Se v forNULL, o conteúdo do objeto bytes não será inicializado.Descontinuado desde a versão 3.15:
PyBytes_FromStringAndSize(NULL, len)is soft deprecated, use thePyBytesWriterAPI instead.
-
PyObject *PyBytes_FromFormat(const char *format, ...)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Leva uma string tipo
printf()do C format e um número variável de argumentos, calcula o tamanho do objeto bytes do Python resultante e retorna um objeto bytes com os valores formatados nela. Os argumentos da variável devem ser tipos C e devem corresponder exatamente aos caracteres de formato na string format. Os seguintes formatos de caracteres são permitidos:Caracteres Formatados
Tipo
Comentário
%%n/d
O caractere literal %.
%cint
Um único byte, representado como um C int.
%dint
Equivalente a
printf("%d"). [1]%uunsigned int
Equivalente a
printf("%u"). [1]%ldlong
Equivalente a
printf("%ld"). [1]%luunsigned long
Equivalente a
printf("%lu"). [1]%zdEquivalente a
printf("%zd"). [1]%zusize_t
Equivalente a
printf("%zu"). [1]%iint
Equivalente a
printf("%i"). [1]%xint
Equivalente a
printf("%x"). [1]%sconst char*
Uma matriz de caracteres C com terminação nula.
%pconst void*
A representação hexadecimal de um ponteiro C. Principalmente equivalente a
printf("%p")exceto que é garantido que comece com o literal0xindependentemente do que oprintfda plataforma ceda.Um caractere de formato não reconhecido faz com que todo o resto da string de formato seja copiado como é para o objeto resultante e todos os argumentos extras sejam descartados.
-
PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Idêntico a
PyBytes_FromFormat()exceto que é preciso exatamente dois argumentos.
-
PyObject *PyBytes_FromObject(PyObject *o)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Retorna a representação de bytes do objeto o que implementa o protocolo de buffer.
-
Py_ssize_t PyBytes_Size(PyObject *o)¶
- Parte da ABI Estável.
Retorna o comprimento dos bytes em objeto bytes o.
-
Py_ssize_t PyBytes_GET_SIZE(PyObject *o)¶
Similar a
PyBytes_Size(), mas sem verificação de erro.
-
char *PyBytes_AsString(PyObject *o)¶
- Parte da ABI Estável.
Retorna um ponteiro para o conteúdo de o. O ponteiro se refere ao buffer interno de o, que consiste em
len(o) + 1bytes. O último byte no buffer é sempre nulo, independentemente de haver outros bytes nulos. Os dados não devem ser modificados de forma alguma, a menos que o objeto tenha sido criado usandoPyBytes_FromStringAndSize(NULL, size). Não deve ser desalocado. Se o não é um objeto de bytes,PyBytes_AsString()retornaNULLe levantaTypeError.
-
char *PyBytes_AS_STRING(PyObject *string)¶
Similar a
PyBytes_AsString(), mas sem verificação de erro.
-
int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)¶
- Parte da ABI Estável.
Retorna os conteúdos terminados nulos do objeto obj através das variáveis de saída buffer e length. Retorna
0em caso de sucesso.Se length for
NULL, o objeto bytes não poderá conter bytes nulos incorporados; se isso acontecer, a função retornará-1e aValueErrorserá levantado.O buffer refere-se a um buffer interno de obj, que inclui um byte nulo adicional no final (não contado em length). Os dados não devem ser modificados de forma alguma, a menos que o objeto tenha sido criado apenas usando
PyBytes_FromStringAndSize(NULL, size). Não deve ser desalinhado. Se obj não é um objeto bytes,PyBytes_AsStringAndSize()retorna-1e levantaTypeError.Alterado na versão 3.5: Anteriormente
TypeErrorera levantado quando os bytes nulos incorporados eram encontrados no objeto bytes.
-
void PyBytes_Concat(PyObject **bytes, PyObject *newpart)¶
- Parte da ABI Estável.
Cria um novo objeto de bytes em *bytes contendo o conteúdo de newpart anexado a bytes; o chamador será o proprietário da nova referência. A referência ao valor antigo de bytes será roubada. Se o novo objeto não puder ser criado, a antiga referência a bytes ainda será descartada e o valor de *bytes será definido como
NULL; a exceção apropriada será definida.
-
void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)¶
- Parte da ABI Estável.
“Crie um novo objeto bytes em *bytes contendo o conteúdo de newpart anexado a bytes. Esta versão libera a strong reference (referência forte) para newpart (ou seja, decrementa a contagem de referências a ele).”
-
PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)¶
Similar a
sep.join(iterable)no Python.sep deve ser um objeto Python
bytes. (Observe quePyUnicode_Join()aceita o separadorNULLe o trata como um espaço, enquantoPyBytes_Join()não aceita o separadorNULL.)iterable deve ser um objeto iterável que produz objetos que implementam o protocolo de buffer.
Em caso de sucesso, retorna um novo objeto
bytes. Em caso de erro, define uma exceção e retornaNULL.Adicionado na versão 3.14.
-
int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)¶
Redimensiona um objeto de bytes. newsize será o novo tamanho do objeto bytes. Você pode pensar nisso como se estivesse criando um novo objeto de bytes e destruindo o antigo, só que de forma mais eficiente. Passe o endereço de um objeto de bytes existente como um lvalue (pode ser gravado) e o novo tamanho desejado. Em caso de sucesso, *bytes mantém o objeto de bytes redimensionados e
0é retornado; o endereço em *bytes pode diferir do seu valor de entrada. Se a realocação falhar, o objeto de bytes originais em *bytes é desalocado, *bytes é definido comoNULL,MemoryErroré definido e-1é retornado.Descontinuado desde a versão 3.15: The function is soft deprecated, use the
PyBytesWriterAPI instead.
PyBytesWriter¶
The PyBytesWriter API can be used to create a Python bytes
object.
Adicionado na versão 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, orPyBytesWriter_Discard()on error.
Create, Finish, Discard¶
-
PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)¶
Create a
PyBytesWriterto 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
PyBytesWritercreated byPyBytesWriter_Create().On success, return a Python
bytesobject. On error, set an exception and returnNULL.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 thebytesobject.
-
PyObject *PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)¶
Similar to
PyBytesWriter_Finish(), but resize the writer using buf pointer before creating thebytesobject.Set an exception and return
NULLif 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
PyBytesWritercreated byPyBytesWriter_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, callstrlen(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()orPyBytesWriter_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. 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;