birchrest.http package

Submodules

birchrest.http.request module

class birchrest.http.request.Request(method: str, path: str, version: str, headers: Dict[str, str], body: str | None, client_address: str, client_port: int | None = None)[source]

Bases: object

Represents an HTTP request, capturing the HTTP method, path, version, headers, body, and other relevant data.

This class is responsible for parsing raw HTTP request data and extracting useful information such as headers, query parameters, path parameters, and the request body. It also generates a unique correlation ID for tracking the request across systems.

Attributes:: method (str): The HTTP method (e.g., GET, POST). path (str): The requested URL path. version (str): The HTTP version used in the request (e.g., HTTP/1.1). headers (Dict[str, str]): Dictionary of HTTP headers. body (Optional[str]): The request body, if any, parsed as JSON if applicable. client_address (str): The IP address of the client making the request. params (Dict[str, str]): URL path parameters (set during route matching). correlation_id (str): A unique ID assigned to the request for tracking. user (Optional[Any]): Placeholder for authenticated user data. queries (Dict[str, str]): Query parameters parsed from the URL. clean_path (str): The URL path without query parameters. received (datetime): Timestamp of when the request was created.

get_header(header_name: str) → str | None[source]

Get a specific header by name, case-insensitive.

Parameters:: header_name – The name of the header to retrieve
Returns:: The header value, or None if not found

static parse(raw_data: str, client_address: str, client_port: int | None = None) → Request[source]

Static method to create a Request object from raw HTTP request data.

Parameters:

raw_data – The raw HTTP request as a string
client_address – The address of the client making the request

Returns:

A Request object

birchrest.http.response module

class birchrest.http.response.Response(correlation_id: str = '')[source]

Bases: object

Represents an HTTP response, providing methods to set status codes, headers, and the response body. It also supports sending JSON-encoded data and generating the final raw HTTP response as a string.

Attributes:: _status_code (int): The HTTP status code of the response. _headers (Dict[str, str]): A dictionary containing the response headers. _body (str): The response body. _is_sent (bool): A flag to indicate if the response has already been sent. correlation_id (str): A unique correlation ID for tracking the request-response cycle.

end() → str[source]

Finalize the response and return it as a raw HTTP response string.

Returns:: The complete HTTP response as a string

send(data: Any = {}) → Response[source]

Set the response body to a JSON-encoded string and set Content-Type to application/json.

Parameters:: data – A dictionary to be JSON-encoded
Returns:: self to allow for chaining

set_header(name: str, value: str) → Response[source]

Set an HTTP header.

Parameters:

name – The name of the header
value – The value of the header

Returns:

self to allow chaining

status(code: int) → Response[source]

Set the HTTP status code.

Parameters:: code – The HTTP status code
Returns:: self to allow for chaining

birchrest.http.server module

class birchrest.http.server.Server(request_handler: Callable[[Request], Awaitable[Response]], host: str = '127.0.0.1', port: int = 5000, backlog: int = 5)[source]

Bases: object

A simple socket-based HTTP server that handles incoming client connections and processes HTTP requests.

The server accepts incoming TCP connections, reads and parses HTTP requests, passes them to a request handler, and sends back the corresponding HTTP response.

Attributes:: host (str): The server’s hostname or IP address. Defaults to ‘127.0.0.1’. port (int): The port the server listens on. Defaults to 5000. backlog (int): The maximum number of queued connections. Defaults to 5. server_socket (Optional[socket.socket]): The server’s main socket. request_handler (Callable[[Request], Response]): A function that processes

the incoming HTTP request and returns a response.

async shutdown() → None[source]: Gracefully shuts down the server by closing the server socket and stopping the server loop.

async start() → None[source]: Starts the server and begins listening for incoming connections asynchronously.

birchrest.http.status module

class birchrest.http.status.HttpStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

ACCEPTED = 202

BAD_GATEWAY = 502

BAD_REQUEST = 400

CONFLICT = 409

CONTINUE = 100

CREATED = 201

EARLY_HINTS = 103

EXPECTATION_FAILED = 417

FORBIDDEN = 403

FOUND = 302

GATEWAY_TIMEOUT = 504

GONE = 410

HTTP_VERSION_NOT_SUPPORTED = 505

IM_A_TEAPOT = 418

INSUFFICIENT_STORAGE = 507

INTERNAL_SERVER_ERROR = 500

LENGTH_REQUIRED = 411

LOOP_DETECTED = 508

METHOD_NOT_ALLOWED = 405

MOVED_PERMANENTLY = 301

MULTIPLE_CHOICES = 300

NETWORK_AUTHENTICATION_REQUIRED = 511

NON_AUTHORITATIVE_INFORMATION = 203

NOT_ACCEPTABLE = 406

NOT_EXTENDED = 510

NOT_FOUND = 404

NOT_IMPLEMENTED = 501

NOT_MODIFIED = 304

NO_CONTENT = 204

OK = 200

PARTIAL_CONTENT = 206

PAYLOAD_TOO_LARGE = 413

PAYMENT_REQUIRED = 402

PERMANENT_REDIRECT = 308

PRECONDITION_FAILED = 412

PRECONDITION_REQUIRED = 428

PROCESSING = 102

PROXY_AUTHENTICATION_REQUIRED = 407

RANGE_NOT_SATISFIABLE = 416

REQUEST_HEADER_FIELDS_TOO_LARGE = 431

REQUEST_TIMEOUT = 408

RESET_CONTENT = 205

SEE_OTHER = 303

SERVICE_UNAVAILABLE = 503

SWITCHING_PROTOCOLS = 101

TEMPORARY_REDIRECT = 307

TOO_EARLY = 425

TOO_MANY_REQUESTS = 429

UNAUTHORIZED = 401

UNPROCESSABLE_ENTITY = 422

UNSUPPORTED_MEDIA_TYPE = 415

UPGRADE_REQUIRED = 426

URI_TOO_LONG = 414

VARIANT_ALSO_NEGOTIATES = 506

classmethod description(status_code: int) → str[source]: Returns a default description for a given status code.

Module contents

This module provides the core HTTP components for the BirchRest framework.

Components: - Request: Represents an incoming HTTP request, including headers, query parameters, body, and more. - Response: Represents an outgoing HTTP response, used to send data back to the client. - HttpStatus: A collection of HTTP status codes for setting response statuses. - Server: A simple HTTP server that handles incoming requests, processes them, and sends back responses.

Exported components: - Request - Response - HttpStatus - Server

class birchrest.http.HttpStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

ACCEPTED = 202

BAD_GATEWAY = 502

BAD_REQUEST = 400

CONFLICT = 409

CONTINUE = 100

CREATED = 201

EARLY_HINTS = 103

EXPECTATION_FAILED = 417

FORBIDDEN = 403

FOUND = 302

GATEWAY_TIMEOUT = 504

GONE = 410

HTTP_VERSION_NOT_SUPPORTED = 505

IM_A_TEAPOT = 418

INSUFFICIENT_STORAGE = 507

INTERNAL_SERVER_ERROR = 500

LENGTH_REQUIRED = 411

LOOP_DETECTED = 508

METHOD_NOT_ALLOWED = 405

MOVED_PERMANENTLY = 301

MULTIPLE_CHOICES = 300

NETWORK_AUTHENTICATION_REQUIRED = 511

NON_AUTHORITATIVE_INFORMATION = 203

NOT_ACCEPTABLE = 406

NOT_EXTENDED = 510

NOT_FOUND = 404

NOT_IMPLEMENTED = 501

NOT_MODIFIED = 304

NO_CONTENT = 204

OK = 200

PARTIAL_CONTENT = 206

PAYLOAD_TOO_LARGE = 413

PAYMENT_REQUIRED = 402

PERMANENT_REDIRECT = 308

PRECONDITION_FAILED = 412

PRECONDITION_REQUIRED = 428

PROCESSING = 102

PROXY_AUTHENTICATION_REQUIRED = 407

RANGE_NOT_SATISFIABLE = 416

REQUEST_HEADER_FIELDS_TOO_LARGE = 431

REQUEST_TIMEOUT = 408

RESET_CONTENT = 205

SEE_OTHER = 303

SERVICE_UNAVAILABLE = 503

SWITCHING_PROTOCOLS = 101

TEMPORARY_REDIRECT = 307

TOO_EARLY = 425

TOO_MANY_REQUESTS = 429

UNAUTHORIZED = 401

UNPROCESSABLE_ENTITY = 422

UNSUPPORTED_MEDIA_TYPE = 415

UPGRADE_REQUIRED = 426

URI_TOO_LONG = 414

VARIANT_ALSO_NEGOTIATES = 506

classmethod description(status_code: int) → str[source]: Returns a default description for a given status code.

class birchrest.http.Request(method: str, path: str, version: str, headers: Dict[str, str], body: str | None, client_address: str, client_port: int | None = None)[source]

Bases: object

Represents an HTTP request, capturing the HTTP method, path, version, headers, body, and other relevant data.

This class is responsible for parsing raw HTTP request data and extracting useful information such as headers, query parameters, path parameters, and the request body. It also generates a unique correlation ID for tracking the request across systems.

Attributes:: method (str): The HTTP method (e.g., GET, POST). path (str): The requested URL path. version (str): The HTTP version used in the request (e.g., HTTP/1.1). headers (Dict[str, str]): Dictionary of HTTP headers. body (Optional[str]): The request body, if any, parsed as JSON if applicable. client_address (str): The IP address of the client making the request. params (Dict[str, str]): URL path parameters (set during route matching). correlation_id (str): A unique ID assigned to the request for tracking. user (Optional[Any]): Placeholder for authenticated user data. queries (Dict[str, str]): Query parameters parsed from the URL. clean_path (str): The URL path without query parameters. received (datetime): Timestamp of when the request was created.

get_header(header_name: str) → str | None[source]

Get a specific header by name, case-insensitive.

Parameters:: header_name – The name of the header to retrieve
Returns:: The header value, or None if not found

static parse(raw_data: str, client_address: str, client_port: int | None = None) → Request[source]

Static method to create a Request object from raw HTTP request data.

Parameters:

raw_data – The raw HTTP request as a string
client_address – The address of the client making the request

Returns:

A Request object

class birchrest.http.Response(correlation_id: str = '')[source]

Bases: object

Represents an HTTP response, providing methods to set status codes, headers, and the response body. It also supports sending JSON-encoded data and generating the final raw HTTP response as a string.

Attributes:: _status_code (int): The HTTP status code of the response. _headers (Dict[str, str]): A dictionary containing the response headers. _body (str): The response body. _is_sent (bool): A flag to indicate if the response has already been sent. correlation_id (str): A unique correlation ID for tracking the request-response cycle.

end() → str[source]

Finalize the response and return it as a raw HTTP response string.

Returns:: The complete HTTP response as a string

send(data: Any = {}) → Response[source]

Set the response body to a JSON-encoded string and set Content-Type to application/json.

Parameters:: data – A dictionary to be JSON-encoded
Returns:: self to allow for chaining

set_header(name: str, value: str) → Response[source]

Set an HTTP header.

Parameters:

name – The name of the header
value – The value of the header

Returns:

self to allow chaining

status(code: int) → Response[source]

Set the HTTP status code.

Parameters:: code – The HTTP status code
Returns:: self to allow for chaining

class birchrest.http.Server(request_handler: Callable[[Request], Awaitable[Response]], host: str = '127.0.0.1', port: int = 5000, backlog: int = 5)[source]

Bases: object

A simple socket-based HTTP server that handles incoming client connections and processes HTTP requests.

The server accepts incoming TCP connections, reads and parses HTTP requests, passes them to a request handler, and sends back the corresponding HTTP response.

Attributes:: host (str): The server’s hostname or IP address. Defaults to ‘127.0.0.1’. port (int): The port the server listens on. Defaults to 5000. backlog (int): The maximum number of queued connections. Defaults to 5. server_socket (Optional[socket.socket]): The server’s main socket. request_handler (Callable[[Request], Response]): A function that processes

the incoming HTTP request and returns a response.

async shutdown() → None[source]: Gracefully shuts down the server by closing the server socket and stopping the server loop.

async start() → None[source]: Starts the server and begins listening for incoming connections asynchronously.