Soup.MessageBody¶

Fields¶

Name	Type	Access	Description
data	`str`	r/w	the data
length	`int`	r/w	length of data

Methods¶

class	`new` ()
	`append` (data)
	`append_buffer` (buffer)
	`complete` ()
	`flatten` ()
	`free` ()
	`get_accumulate` ()
	`get_chunk` (offset)
	`got_chunk` (chunk)
	`set_accumulate` (accumulate)
	`truncate` ()
	`wrote_chunk` (chunk)

Details¶

class Soup.MessageBody¶

A Soup.Message request or response body.

Note that while length always reflects the full length of the message body, data is normally None, and will only be filled in after Soup.MessageBody.flatten() is called. For client-side messages, this automatically happens for the response body after it has been fully read, unless you set the Soup.MessageFlags.OVERWRITE_CHUNKS flags. Likewise, for server-side messages, the request body is automatically filled in after being read.

As an added bonus, when data is filled in, it is always terminated with a ‘\0’ byte (which is not reflected in length).

classmethod new()¶

Returns:: a new Soup.MessageBody.
Return type:: Soup.MessageBody

Creates a new Soup.MessageBody. Soup.Message uses this internally; you will not normally need to call it yourself.

append(data)¶

Parameters:: data (bytes) – data to append

Appends length bytes from data to self.

This function is exactly equivalent to Soup.MessageBody.append() with Soup.MemoryUse.TAKE as second argument; it exists mainly for convenience and simplifying language bindings.

New in version 2.32.

append_buffer(buffer)¶

Parameters:: buffer (Soup.Buffer) – a Soup.Buffer

Appends the data from buffer to self. (Soup.MessageBody uses Soup.Buffers internally, so this is normally a constant-time operation that doesn’t actually require copying the data in buffer.)

complete()¶: Tags self as being complete; Call this when using chunked encoding after you have appended the last chunk.

flatten()¶

Returns:: a Soup.Buffer containing the same data as self. (You must free this buffer if you do not want it.)
Return type:: Soup.Buffer

Fills in self's data field with a buffer containing all of the data in self (plus an additional ‘\0’ byte not counted by self's length field).

free()¶: Frees self. You will not normally need to use this, as Soup.Message frees its associated message bodies automatically.

get_accumulate()¶

Returns:: the accumulate flag for self.
Return type:: bool

Gets the accumulate flag on self; see Soup.MessageBody.set_accumulate() for details.

New in version 2.24.

get_chunk(offset)¶

Parameters:: offset (int) – an offset
Returns:: a Soup.Buffer, or None.
Return type:: Soup.Buffer or None

Gets a Soup.Buffer containing data from self starting at offset. The size of the returned chunk is unspecified. You can iterate through the entire body by first calling Soup.MessageBody.get_chunk() with an offset of 0, and then on each successive call, increment the offset by the length of the previously-returned chunk.

If offset is greater than or equal to the total length of self, then the return value depends on whether or not Soup.MessageBody.complete() has been called or not; if it has, then Soup.MessageBody.get_chunk() will return a 0-length chunk (indicating the end of self). If it has not, then Soup.MessageBody.get_chunk() will return None (indicating that self may still potentially have more data, but that data is not currently available).

got_chunk(chunk)¶

Parameters:: chunk (Soup.Buffer) – a Soup.Buffer received from the network

Handles the Soup.MessageBody part of receiving a chunk of data from the network. Normally this means appending chunk to self, exactly as with Soup.MessageBody.append_buffer(), but if you have set self's accumulate flag to False, then that will not happen.

This is a low-level method which you should not normally need to use.

New in version 2.24.

set_accumulate(accumulate)¶

Parameters:: accumulate (bool) – whether or not to accumulate body chunks in self

Sets or clears the accumulate flag on self. (The default value is True.) If set to False, self's %data field will not be filled in after the body is fully sent/received, and the chunks that make up self may be discarded when they are no longer needed.

In particular, if you set this flag to False on an “incoming” message body (that is, the #SoupMessage:response_body of a client-side message, or #SoupMessage:request_body of a server-side message), this will cause each chunk of the body to be discarded after its corresponding #SoupMessage::got_chunk signal is emitted. (This is equivalent to setting the deprecated Soup.MessageFlags.OVERWRITE_CHUNKS flag on the message.)

If you set this flag to False on the #SoupMessage:response_body of a server-side message, it will cause each chunk of the body to be discarded after its corresponding #SoupMessage::wrote_chunk signal is emitted.

If you set the flag to False on the #SoupMessage:request_body of a client-side message, it will block the accumulation of chunks into self's %data field, but it will not normally cause the chunks to be discarded after being written like in the server-side #SoupMessage:response_body case, because the request body needs to be kept around in case the request needs to be sent a second time due to redirection or authentication. However, if you set the Soup.MessageFlags.CAN_REBUILD flag on the message, then the chunks will be discarded, and you will be responsible for recreating the request body after the Soup.Message ::restarted signal is emitted.

New in version 2.24.

truncate()¶: Deletes all of the data in self.

wrote_chunk(chunk)¶

Parameters:: chunk (Soup.Buffer) – a Soup.Buffer returned from Soup.MessageBody.get_chunk()

Handles the Soup.MessageBody part of writing a chunk of data to the network. Normally this is a no-op, but if you have set self's accumulate flag to False, then this will cause chunk to be discarded to free up memory.

This is a low-level method which you should not need to use, and there are further restrictions on its proper use which are not documented here.

New in version 2.24.