API Reference

class plugapi.http.AutoName(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Class for creating an enum with the name of the enum as the value

Inherits from:

enum.Enum – The base enum class

Methods:

_generate_next_value_ – Generates the next value

class plugapi.http.ChunkStream(func: Callable[[T], Tuple[T, bytes]], initial_value: T)

Class for creating a chunked stream

Attributes:

func {typing.Callable[[T], typing.Tuple[T, bytes]]} – The function to call to get the next chunk value {T} – The value to pass to the function

class plugapi.http.FileResponse(body: BufferedReader | str = '', attachment: bool = False, includeFilename: bool = True, filename: str | None = None, status: int = 200, headers: dict[str, str] = {})

Class for sending a file to a client

Inherits from:

Response – The base response class

Attributes:

body {io.BufferedReader | str} – The body of the response attachment {bool} – Whether to display the file in the browser (inline) or as an attachment (default: {False (inline)}) includeFilename {bool} – Whether to include the filename in the Content-Disposition header (default: {True}) filename {str | None} – The filename to include in the Content-Disposition header (default: {None})

class plugapi.http.HTMLResponse(body: str = '', status: int = 200, headers: dict[str, str] = {})

Class for creating a HTML response to send to a client

Inherits from:

Response – The base response class

Attributes:

body {str} – The body of the response

class plugapi.http.JSONPResponse(body: Mapping[str, JSONType] | Sequence[JSONType] | str | int | float | bool | None = {}, callback: str = 'callback', status: int = 200, headers: dict[str, str] = {})

Class for creating a JSONP response to send to a client

Inherits from:

Response – The base response class

Attributes:

body {JSONType} – The body of the response callback {str} – The name of the callback function (default: {“callback”})

class plugapi.http.JSONResponse(body: Mapping[str, JSONType] | Sequence[JSONType] | str | int | float | bool | None = {}, status: int = 200, headers: dict[str, str] = {})

Class for creating a JSON response to send to a client

Inherits from:

Response – The base response class

Attributes:

body {JSONType} – The body of the response

class plugapi.http.MultipartEntry(type: str = 'application/octet-stream', data: bytes = b'', file_name: str | None = None)

Class for creating a multipart entry

Attributes:

type {str} – The content type of the entry (default: {“application/octet-stream”}) data {bytes} – The data of the entry

class plugapi.http.RedirectResponse(to: str = '/', status: int = 308, headers: dict[str, str] = {})

Class for creating a redirect response to send to a client

Inherits from:

Response – The base response class

Attributes:

to {str} – The URL to redirect to

class plugapi.http.Request(path: str, method: RequestMethod, headers: dict[str, str], body: bytes | list[str] | dict[str, MultipartEntry] | dict[str, list[str]] | ChunkStream[bytes] | ChunkStream[tuple[bytes, int]], query: dict[str, list[str]], params: dict[str, str], cookie: str | dict[str, str])

Class containing the request data

Attributes:

path {str} – The path of the request method {RequestMethod} – The method of the request headers {dict[str, str]} – The request headers body {str | list[str] | dict[str, MultipartEntry] | dict[str, list[str]] | ChunkStream[bytes] | ChunkStream[tuple[bytes, int]]} – The body of the request (if any) query {dict[str, list[str]]} – The query string at the end of the path params {dict[str, str]} – The parameters in the path cookie {str | dict[str, str]} – The cookie of the request (if any) (dict if parsed by cookie_middleware)

class plugapi.http.RequestBuilder(client: socket, server: Server)

Class for building a request from a client socket Attributes:

client {socket.socket} – The client socket server {Server} – The server instance

build() → Request | None

Builds the request from the client socket Returns:

Request | None – The built request or None if the request is malformed

chunked_stream_func(encoded_request: bytes) → tuple[bytes, bytes]

The function for streaming a body with a Transfer-Encoding: chunked header Arguments:

encoded_request {bytes} – The current state of the stream (encoded_request)

Returns:

tuple[bytes, bytes] – The new state of the stream and the next chunk

content_length_stream_func(data: tuple[bytes, int]) → tuple[tuple[bytes, int], bytes]

The function for streaming a body with a Content-Length header greater than max_length_before_chunked Arguments:

data {tuple[bytes, int]} – The current state of the stream (encoded_request, length)

Returns:

tuple[tuple[bytes, int], bytes] – The new state of the stream and the next chunk

parse_body(encoded_request: bytes, headers: dict[str, str]) → bytes | ChunkStream[tuple[bytes, int]] | ChunkStream[bytes] | None

Parses the body from the raw request Arguments:

encoded_request {bytes} – The raw request from the client headers {dict[str, str]} – The headers of the request

parse_headers(raw_request: bytes) → dict[str, str] | None

Parses the headers from the raw request Arguments:

raw_request {bytes} – The raw request from the client

parse_method_path(raw_request: bytes) → tuple[str, str] | None

Parses the request method and path from the raw request Arguments:

raw_request {bytes} – The raw request from the client

parse_query(path: str) → tuple[str, dict[str, list[str]]]

Parses the query string from the path Arguments:

path {str} – The path of the request

receive_request() → bytes | None

Receives the request headers from the client

class plugapi.http.RequestMethod(*values)

The enum containing HTTP request methods

Inherits from:

AutoName – The base enum class

class plugapi.http.Response

Class for creating a response to send to a client

Attributes:

status {int} – The status code of the response (default: {200}) headers {dict[str, str]} – The headers of the response (default: {})

send(client: socket)

Sends the response to a client

Arguments:

client {socket.socket} – The client to send the response to

to_bytes() → bytes

Converts the response to bytes

Returns:

bytes: The response in bytes

class plugapi.http.Server(port: int, timeout: int = 5, host: str = 'localhost', https: bool = False, certfile: str | None = None, keyfile: str | None = None, should_log_errors: bool = True, max_length_before_chunked: int = 536870912, max_header_size: int = 8192)

Class for creating a HTTP(S) server

Attributes:

host {str} – The host of the server port {int} – The port of the server timeout {int} – The timeout before the server closes the connection socket {socket.socket} – The socket of the server threads {list[Thread]} – The connection threads lock {Lock} – The lock for the threads list handlers {dict[RequestMethod, dict[str, callable]]} – The handlers for the requests https {bool} – Whether the server is using HTTPS certfile {str | None} – The certificate file for HTTPS keyfile {str | None} – The key file for HTTPS middlewares {list[MiddlewareType]} – The middlewares for the requests context {ssl.SSLContext | None} – The SSL context for HTTPS should_log_errors {bool} – Whether the server should log errors to the console max_length_before_chunked {int} – The maximum Content-Length before the body is returned as a ChunkStream max_header_size {int} – The maximum size of the headers in bytes (default: {8192})

add_middlewares(*middlewares: Callable[[Request, list[MiddlewareType], Callable[[Request], Response]], Response])

Adds middlewares to the server

Arguments:

*middlewares {MiddlewareType} – The middlewares to add

find_handler(request_method: str, path: str) → tuple[Callable[[Request], Response], dict[str, str]] | None

Finds the handler for a request Arguments:

request_method {str} – The method of the request path {str} – The path of the request

Returns:

tuple[HandlerType, dict[str, str]] | None – The handler and the parameters in the path (if any)

handler(path: str | None = None, method: RequestMethod | list[RequestMethod] = RequestMethod.GET) → Callable[[Callable[[Request], Response]], Callable[[Request], Response]]

The decorator for the handlers

Arguments:

path {str} – The path of the handler method {RequestMethod | list[RequestMethod]} – The HTTP method the handler can receive (default: {RequestMethod.GET})

Returns:

callable – The decorator

option_handler(path: str) → Callable[[Request], Response]

The handler for OPTIONS requests

Arguments:

path {str} – The path of the handler

Returns:

HandlerType – The handler

run()

Runs the server

class plugapi.http.TextResponse(body: str = '', status: int = 200, headers: dict[str, str] = {})

Class for creating a text response to send to a client

Inherits from:

Response – The base response class

Attributes:

body {str} – The body of the response

plugapi.http.cookie_middleware(req: Request, next: list[Callable[[Request, list[Callable[[Request, list[MiddlewareType], Callable[[Request], Response]], Response]], Callable[[Request], Response]], Response]], handler: Callable[[Request], Response]) → Response

Middleware for parsing cookies

Arguments:

req: {Request} – The request object next {list[MiddlewareType]} – The remaining middlewares handler {HandlerType} – The handler function

Returns:

Response – The response object

plugapi.http.cors_middleware(req: Request, next: list[Callable[[Request, list[Callable[[Request, list[MiddlewareType], Callable[[Request], Response]], Response]], Callable[[Request], Response]], Response]], handler: Callable[[Request], Response]) → Response

Middleware for adding CORS headers

Arguments:

req: {Request} – The request object next {list[MiddlewareType]} – The remaining middlewares handler {HandlerType} – The handler function

Returns:

Response – The response object

plugapi.http.json_middleware(req: Request, next: list[Callable[[Request, list[Callable[[Request, list[MiddlewareType], Callable[[Request], Response]], Response]], Callable[[Request], Response]], Response]], handler: Callable[[Request], Response]) → Response

Middleware for parsing JSON

Arguments:

req: {Request} – The request object next {list[MiddlewareType]} – The remaining middlewares handler {HandlerType} – The handler function

Returns:

Response – The response object

plugapi.http.multipart_middleware(req: Request, next: list[Callable[[Request, list[Callable[[Request, list[MiddlewareType], Callable[[Request], Response]], Response]], Callable[[Request], Response]], Response]], handler: Callable[[Request], Response]) → Response

Middleware for parsing multipart data

Arguments:

req: {Request} – The request object next {list[MiddlewareType]} – The remaining middlewares handler {HandlerType} – The handler function

Returns:

Response – The response object

plugapi.http.parse_multipart(body: bytes, boundary: bytes) → dict[str, MultipartEntry]

Parses a multipart form

Arguments:

body {str} – The body of the request boundary {str} – The boundary of the multipart form

Returns:

dict[str, MultipartEntry] – The parsed multipart form

plugapi.http.url_encoded_middleware(req: Request, next: list[Callable[[Request, list[Callable[[Request, list[MiddlewareType], Callable[[Request], Response]], Response]], Callable[[Request], Response]], Response]], handler: Callable[[Request], Response]) → Response

Middleware for parsing URL encoded data

Arguments:

req: {Request} – The request object next {list[MiddlewareType]} – The remaining middlewares handler {HandlerType} – The handler function

Returns:

Response – The response object