Pyjo.Message - HTTP message base class

from Pyjo.Message import Message

class MyMessage(Message):
    def cookies(self, *cookies): ...
    def extract_start_line(self, buffer): ...
    def get_start_line_chunk(self, offset): ...
    @property
    def start_line_size(self): ...

# Or import the module, as in Google Python Style Guide

import Pyjo.Message

class MyMessage(Pyjo.Message.object):
    def cookies(self, *cookies): ...
    def extract_start_line(self, buffer): ...
    def get_start_line_chunk(self, offset): ...
    @property
    def start_line_size(self): ...

Pyjo.Message is an abstract base class for HTTP message containers, based on RFC 7230, RFC 7231 and RFC 2388, like Pyjo.Message.Request and Pyjo.Message.Response.

Events

Pyjo.Message inherits all events from Pyjo.EventEmitter and can emit the following new ones.

finish

msg.on('finish', lambda msg: ...)

Emitted after message building or parsing is finished.

before = time.time()
msg.on('finish', lambda msg: msg.headers.header('X-Parser-Time', int(time.time() - before)))

progress

msg.on('progress', lambda msg, *args: ...)

Emitted when message building or parsing makes progress.

# Building
msg.on('progress', lambda msg, state, offset: print(f'Building "{state}" at offset {offset}'))

# Parsing
@msg.on('progress')
def progress(msg):
    if not (length := int(msg.headers.content_length or 0)):
        return
    size = msg.content.progress
    print('Progress:', 100 if size == length else int(size / (length / 100)), '%')

See also

Pyjoyment, https://mojolicious.org.

Ported from Mojo::Message of Mojolicious 9.52.

class Pyjo.Message.Error[source]

An error of a message, with the status code of a response for a 4xx or 5xx response.

class Pyjo.Message.Pyjo_Message(*, content: Pyjo_Content | None = None, default_charset: str | None = 'UTF-8', max_line_size: int | None = None, max_message_size: int | None = None, version: str = '1.1')[source]

Pyjo.Message inherits all methods from Pyjo.EventEmitter and implements the following new ones.

__init__(*, content: Pyjo_Content | None = None, default_charset: str | None = 'UTF-8', max_line_size: int | None = None, max_message_size: int | None = None, version: str = '1.1') → None[source]
msg = Pyjo.Message.Request.new()
msg = Pyjo.Message.Response.new(content=Pyjo.Content.MultiPart.new())

Construct a new message object.

property body: bytes[source]
data = msg.body
msg.body = b'Hello!'

Slurp or replace content.

property body_params: Pyjo_Parameters[source]
params = msg.body_params

POST parameters extracted from application/x-www-form-urlencoded or multipart/form-data message body, usually a Pyjo.Parameters object. Note that this method caches all data, so it should not be called before the entire message body has been received. Parts of the message body need to be loaded into memory to parse POST parameters, so you have to make sure it is not excessively large. There’s a 16MiB limit for requests and a 2GiB limit for responses by default.

# Get POST parameter names and values
params = msg.body_params.to_dict()
property body_size: int[source]
size = msg.body_size

Content size in bytes.

build_body() → bytes[source]
data = msg.build_body()

Render whole body with get_body_chunk().

build_headers() → bytes[source]
data = msg.build_headers()

Render all headers with get_header_chunk().

build_start_line() → bytes[source]
data = msg.build_start_line()

Render start-line with get_start_line_chunk().

property content: Pyjo_Content[source]
content = msg.content
msg.content = Pyjo.Content.Single.new()

Message content, defaults to a Pyjo.Content.Single object.

cookie(name: str) → Pyjo_Cookie | None[source]
cookie = msg.cookie('foo')

Access message cookies, usually Pyjo.Cookie.Request or Pyjo.Cookie.Response objects. If there are multiple cookies sharing the same name, and you want to access more than just the last one, you can use every_cookie(). Note that this method caches all data, so it should not be called before all headers have been received.

# Get cookie value
print(msg.cookie('foo').value)
cookies() → Sequence[Pyjo_Cookie][source]
cookies(cookie: Pyjo_Cookie | Mapping[str, Any], /, *cookies: Anything) → Self
cookies = msg.cookies()

Access message cookies. Meant to be overloaded in a subclass.

default_charset
charset = msg.default_charset
msg.default_charset = 'UTF-8'

Default charset used by text and to extract data from application/x-www-form-urlencoded or multipart/form-data message body, defaults to UTF-8.

dom() → Pyjo_DOM | None[source]
dom(css: Anything, /) → Pyjo_Collection[Pyjo_DOM] | None
dom = msg.dom()
collection = msg.dom('a[href]')

Retrieve message body and turn it into a Pyjo.DOM object, with its encoding found as the HTML Living Standard sniffs it, a byte order mark, the Pyjo.Content.Pyjo_Content.charset, the encoding of an XML declaration or of a <meta charset>, and default_charset, an optional selector can be used to call the method Pyjo.DOM.Pyjo_DOM.find() on it right away, which then returns a Pyjo.Collection object. Note that this method caches all data, so it should not be called before the entire message body has been received. The whole message body needs to be loaded into memory to parse it, so you have to make sure it is not excessively large. There’s a 16MiB limit for requests and a 2GiB limit for responses by default.

# Perform "find" right away
print(msg.dom('h1, h2, h3').map('text').join("\n"))

# Use everything else Pyjo.DOM has to offer
print(msg.dom().at('title').text)
print(msg.dom().at('body').children().map('tag').uniq().join("\n"))
property error: Error | None[source]
err = msg.error
msg.error = {'message': 'Parser error'}

Get or set message error, a None return value indicates that there is no error. Setting it finishes the message.

# Connection or parser error
msg.error = {'message': 'Connection refused'}

# 4xx/5xx response
msg.error = {'message': 'Internal Server Error', 'code': 500}
cookies = msg.every_cookie('foo')

Similar to cookie(), but returns all message cookies sharing the same name as a list.

# Get first cookie value
print(msg.every_cookie('foo')[0].value)
every_upload(name: str) → list[Pyjo_Upload][source]
uploads = msg.every_upload('foo')

Similar to upload(), but returns all file uploads sharing the same name as a list.

# Get content of first uploaded file
print(msg.every_upload('foo')[0].asset.slurp())
extract_start_line(buffer: bytearray) → bool | None[source]
boolean = msg.extract_start_line(buffer)

Extract start-line from a bytearray, which loses it. Meant to be overloaded in a subclass.

finish() → Self[source]
msg = msg.finish()

Finish message parser/generator.

fix_headers() → Self[source]
msg = msg.fix_headers()

Make sure message has all required headers.

get_body_chunk(offset: int) → bytes | None[source]
data = msg.get_body_chunk(offset)

Get a chunk of body data starting from a specific position. Note that it might not be possible to get the same chunk twice if content was generated dynamically.

get_header_chunk(offset: int) → bytes[source]
data = msg.get_header_chunk(offset)

Get a chunk of header data, starting from a specific position. Note that this method finalizes the message.

get_start_line_chunk(offset: int) → bytes[source]
data = msg.get_start_line_chunk(offset)

Get a chunk of start-line data starting from a specific position. Meant to be overloaded in a subclass.

property header_size: int[source]
size = msg.header_size

Size of headers in bytes. Note that this method finalizes the message.

property headers: Pyjo_Headers[source]
headers = msg.headers

Message headers, usually a Pyjo.Headers object.

# Longer version
headers = msg.content.headers
property is_finished: bool[source]
boolean = msg.is_finished

Check if message parser/generator is finished.

property is_limit_exceeded: bool[source]
boolean = msg.is_limit_exceeded

Check if message has exceeded max_line_size, max_message_size, Pyjo.Content.Pyjo_Content.max_buffer_size or Pyjo.Headers.Pyjo_Headers.max_line_size.

json(pointer: str | None = None) → Any[source]
value = msg.json()
value = msg.json('/foo/bar')

Decode JSON message body directly using Pyjo.JSON if possible, a None return value indicates a bare null or that decoding failed. An optional JSON Pointer can be used to extract a specific value with Pyjo.JSON.Pointer. Note that this method caches all data, so it should not be called before the entire message body has been received. The whole message body needs to be loaded into memory to parse it, so you have to make sure it is not excessively large. There’s a 16MiB limit for requests and a 2GiB limit for responses by default.

# Extract JSON values
print(msg.json()['foo']['bar'][23])
print(msg.json('/foo/bar/23'))
property max_line_size: int[source]
size = msg.max_line_size
msg.max_line_size = 1024

Maximum start-line size in bytes, defaults to the value of the PYJO_MAX_LINE_SIZE environment variable or 65536 (64KiB).

property max_message_size: int[source]
size = msg.max_message_size
msg.max_message_size = 1024

Maximum message size in bytes, defaults to the value of the PYJO_MAX_MESSAGE_SIZE environment variable or 16777216 (16MiB). Setting the value to 0 will allow messages of indefinite size.

parse(chunk: bytes) → Self[source]
msg = msg.parse(b'HTTP/1.1 200 OK...')

Parse message chunk.

save_to(path: Anything) → Self[source]
msg = msg.save_to('/some/path/index.html')

Save message body to a file.

property start_line_size: int[source]
size = msg.start_line_size

Size of the start-line in bytes. Meant to be overloaded in a subclass.

property text: str[source]
string = msg.text

Retrieve body and try to decode it with Pyjo.Content.Pyjo_Content.charset or default_charset. A body that does not decode is a string of the characters 0-255, one for each byte.

to_bytes() → bytes[source]
data = msg.to_bytes()

Render whole message. Note that this method finalizes the message, and that it might not be possible to render the same message twice if content was generated dynamically.

upload(name: str) → Pyjo_Upload | None[source]
upload = msg.upload('foo')

Access multipart/form-data file uploads, usually Pyjo.Upload objects. If there are multiple uploads sharing the same name, and you want to access more than just the last one, you can use every_upload(). Note that this method caches all data, so it should not be called before the entire message body has been received.

# Get content of uploaded file
print(msg.upload('foo').asset.slurp())
uploads() → list[Pyjo_Upload][source]
uploads = msg.uploads()

All multipart/form-data file uploads, usually Pyjo.Upload objects.

# Names of all uploads
for upload in msg.uploads():
    print(upload.name)
version
version = msg.version
msg.version = '1.1'

HTTP version of message, defaults to 1.1.