DefEssential 0.1.8__25-py3-none-any.whl

DefEssential/IO/Writers/StreamWriter.py

@@ -0,0 +1,57 @@
+from typing import (
+	Mapping,
+	Optional,
+)
+
+from ...Response import Response
+from ..ResponseWriter import ResponseWriter
+
+__all__ = (
+	'StreamWriter',
+)
+
+
+class StreamWriter:
+	"""Start a response and write bytes directly to the stream."""
+
+	chunked = False
+
+	def __init__(
+		self,
+		writer: ResponseWriter,
+	):
+		self.writer = writer
+		return
+
+	def begin(
+		self,
+		headers: Optional[Mapping[str, str]] = None,
+		format: Optional[str] = None,
+		charset: Optional[str] = None,
+		status: int = 200,
+	) -> None:
+		self.writer.begin(
+			Response(
+				status=status,
+				headers=headers,
+				format=format,
+				charset=charset,
+			),
+			chunked=self.chunked,
+		)
+		return
+
+	def write(
+		self,
+		data: bytes,
+	) -> None:
+		self.writer.write(data)
+		return
+
+	def flush(self) -> None:
+		self.writer.flush()
+		return
+
+	def end(self) -> None:
+		self.writer.end()
+		return

DefEssential/IO/Writers/__init__.py

@@ -0,0 +1,11 @@
+from .ChunkedStreamWriter import ChunkedStreamWriter
+from .ServerSentEvents import ServerSentEvents
+from .ServerSentEventsWriter import ServerSentEventsWriter
+from .StreamWriter import StreamWriter
+
+__all__ = (
+	'ChunkedStreamWriter',
+	'ServerSentEvents',
+	'ServerSentEventsWriter',
+	'StreamWriter',
+)

DefEssential/IO/__init__.py

@@ -0,0 +1,7 @@
+from .RequestReader import RequestReader
+from .ResponseWriter import ResponseWriter
+
+__all__ = (
+	'RequestReader',
+	'ResponseWriter',
+)

DefEssential/Request.py

@@ -0,0 +1,110 @@
+from email.message import Message
+from io import BytesIO
+from re import fullmatch
+from typing import (
+	Any,
+	Mapping,
+	Optional,
+)
+from urllib.parse import (
+	parse_qs,
+	urlsplit,
+)
+from uuid import uuid4
+
+from .IO.RequestReader import RequestReader
+from .IO.ResponseWriter import ResponseWriter
+from .Error import ClientError
+
+__all__ = (
+	'Request',
+)
+
+
+class Request:
+	"""Represent an HTTP request independently of server environment dictionaries."""
+
+	def __init__(
+		self,
+		address: str,
+		port: int,
+		method: str,
+		uri: str,
+		parameters: Optional[Mapping[str, str]] = None,
+		headers: Optional[Mapping[str, str]] = None,
+		reader: Optional[RequestReader] = None,
+		writer: Optional[ResponseWriter] = None,
+	):
+		self.id = uuid4().hex
+		self.address = address
+		self.port = port
+		self.method = method
+		self.uri = uri
+		parsed = urlsplit(uri)
+		self.path = parsed.path
+		self.querystring = parsed.query
+		self.params = dict(parameters) if parameters is not None else {}
+		self.args = {
+			key: values[0] if len(values) == 1 else values
+			for key, values in parse_qs(
+				parsed.query,
+				keep_blank_values=True,
+			).items()
+		}
+		self.props = Message()
+		for key, value in headers.items() if headers is not None else ():
+			self.props[key] = value
+		self.reader = reader if reader is not None else RequestReader(BytesIO())
+		self.response_writer = writer
+		self.body: Any = None
+		self.session: Any = None
+		return
+
+	@property
+	def writer(self) -> ResponseWriter:
+		"""Return the response writer provided by the execution layer."""
+		if self.response_writer is None:
+			raise RuntimeError('No response writer is attached to this request')
+		return self.response_writer
+
+	def header(
+		self,
+		key: str,
+		value: Optional[str] = None,
+	) -> Optional[str]:
+		if value is not None:
+			del self.props[key]
+			self.props[key] = value
+			return None
+		return self.props.get(key)
+
+	def headers(self) -> list:
+		return list(self.props.items())
+
+	@property
+	def parameters(self) -> dict:
+		return self.params
+
+	@property
+	def qs(self) -> dict:
+		return self.args
+
+	@property
+	def size(self) -> Optional[int]:
+		value = self.header('Content-Length')
+		return int(value) if value is not None else None
+
+	@property
+	def format(self) -> Optional[str]:
+		value = self.header('Content-Type')
+		if value is None:
+			return None
+		format = value.split(';', 1)[0].strip().lower()
+		token = r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+"
+		if fullmatch(token + '/' + token, format) is None:
+			raise ClientError('Invalid Content-Type')
+		return format
+
+	@property
+	def charset(self) -> Optional[str]:
+		return self.props.get_content_charset()

DefEssential/RequestRunner.py

@@ -0,0 +1,261 @@
+from abc import (
+	ABC,
+	ABCMeta,
+	abstractmethod,
+)
+from dataclasses import dataclass
+from re import fullmatch
+from typing import (
+	Mapping,
+	Optional,
+	Sequence,
+	Type,
+	TypeVar,
+	Union,
+)
+
+from .Body import Body
+from .Request import Request
+from .Response import Response
+from .ResponseSpecification import ResponseSpecification
+from .Validators import (
+	Auth,
+	Headers,
+	Origin,
+	Parameters,
+	QueryString,
+)
+
+__all__ = (
+	'RequestRunnerRequest',
+	'RequestRunnerRequestResponse',
+	'RequestRunnerRequestError',
+	'RequestProperties',
+	'RequestRunner',
+)
+
+
+class RequestRunnerRequest(ABC):
+	"""Transform a prepared request immediately before the handler runs."""
+
+	@abstractmethod
+	def __call__(
+		self,
+		request: Request,
+	) -> Request:
+		raise NotImplementedError
+
+
+class RequestRunnerRequestResponse(ABC):
+	"""Transform a returned response or a direct-output response before transmission."""
+
+	@abstractmethod
+	def __call__(
+		self,
+		request: Request,
+		response: Response,
+	) -> Response:
+		raise NotImplementedError
+
+
+class RequestRunnerRequestError(ABC):
+	"""Observe execution errors from validation through response processing."""
+
+	@abstractmethod
+	def __call__(
+		self,
+		request: Request,
+		error: Exception,
+	) -> None:
+		raise NotImplementedError
+
+
+Hook = TypeVar('Hook')
+
+
+def request_runner_hooks(
+	value: Union[Hook, Sequence[Hook], None],
+	contract: Type[Hook],
+	name: str,
+) -> tuple[Hook, ...]:
+	if value is None:
+		return ()
+	if isinstance(value, contract):
+		return (value,)
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+		result = tuple(value)
+		if all(isinstance(hook, contract) for hook in result):
+			return result
+	raise TypeError(name + ' must be a ' + contract.__name__ + ' instance or a sequence of them')
+
+
+def require_contract(
+	value: object,
+	contract: Type,
+	name: str,
+	*,
+	multiple: bool = False,
+) -> None:
+	if value is None:
+		return
+	values = (value,) if isinstance(value, contract) else value
+	if multiple:
+		if not isinstance(values, Sequence) or isinstance(values, (str, bytes)):
+			raise TypeError(name + ' must contain ' + contract.__name__ + ' instances')
+		if any(not isinstance(item, contract) for item in values):
+			raise TypeError(name + ' must contain ' + contract.__name__ + ' instances')
+		return
+	if not isinstance(value, contract):
+		raise TypeError(name + ' must be a ' + contract.__name__ + ' instance')
+	return
+
+
+class RequestRunnerMeta(ABCMeta):
+	def __new__(
+		cls,
+		class_name,
+		bases,
+		namespace,
+		**kwargs,
+	):
+		if 'name' in kwargs:
+			if 'request_runner_name' in kwargs:
+				raise TypeError('Specify only one request runner name')
+			kwargs['request_runner_name'] = kwargs.pop('name')
+		return super().__new__(
+			cls,
+			class_name,
+			bases,
+			namespace,
+			**kwargs,
+		)
+
+
+@dataclass(frozen=True)
+class RequestProperties:
+	"""Store request handler settings for registration with an application."""
+
+	method: Optional[str]
+	url: Optional[str]
+	origin: Union[Origin, Sequence[Origin], None]
+	auth: Optional[Auth]
+	parameters: Optional[Parameters]
+	qs: Optional[QueryString]
+	headers: Optional[Headers]
+	body: Optional[Body]
+	response: Union[
+		ResponseSpecification,
+		Mapping[str, Union[str, Mapping[str, object]]],
+		Sequence[ResponseSpecification],
+		None,
+	]
+	summary: Optional[str]
+	description: Optional[str]
+	tags: Union[str, Sequence[str], None]
+	on_request: tuple[RequestRunnerRequest, ...]
+	on_request_response: tuple[RequestRunnerRequestResponse, ...]
+	on_request_error: tuple[RequestRunnerRequestError, ...]
+	name: Optional[str] = None
+
+
+class RequestRunner(
+	ABC,
+	metaclass=RequestRunnerMeta,
+):
+	"""Configure a handler through class declarations and instantiate it per request."""
+
+	properties: RequestProperties
+
+	def __init_subclass__(
+		cls,
+		*,
+		method: Optional[str] = None,
+		url: Optional[str] = None,
+		request_runner_name: Optional[str] = None,
+		origin: Union[Origin, Sequence[Origin], None] = None,
+		auth: Optional[Auth] = None,
+		parameters: Optional[Parameters] = None,
+		qs: Optional[QueryString] = None,
+		headers: Optional[Headers] = None,
+		body: Optional[Body] = None,
+		response: Union[
+			ResponseSpecification,
+			Mapping[str, Union[str, Mapping[str, object]]],
+			Sequence[ResponseSpecification],
+			None,
+		] = None,
+		summary: Optional[str] = None,
+		description: Optional[str] = None,
+		tags: Union[str, Sequence[str], None] = None,
+		on_request: Union[
+			RequestRunnerRequest,
+			Sequence[RequestRunnerRequest],
+			None,
+		] = None,
+		on_request_response: Union[
+			RequestRunnerRequestResponse,
+			Sequence[RequestRunnerRequestResponse],
+			None,
+		] = None,
+		on_request_error: Union[
+			RequestRunnerRequestError,
+			Sequence[RequestRunnerRequestError],
+			None,
+		] = None,
+	):
+		super().__init_subclass__()
+		if request_runner_name is not None and (
+			not isinstance(request_runner_name, str) or not request_runner_name.strip()
+		):
+			raise ValueError('name must be a non-empty string')
+		if (method is None) != (url is None):
+			raise TypeError('method and url must be specified together')
+		if method is not None and fullmatch(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+", method) is None:
+			raise ValueError('Invalid HTTP method token')
+		if url is not None and (not url.startswith('/') or '?' in url or '#' in url):
+			raise ValueError('url must be a path starting with /')
+		require_contract(origin, Origin, 'origin', multiple=True)
+		require_contract(auth, Auth, 'auth')
+		require_contract(parameters, Parameters, 'parameters')
+		require_contract(qs, QueryString, 'qs')
+		require_contract(headers, Headers, 'headers')
+		require_contract(body, Body, 'body')
+		cls.properties = RequestProperties(
+			method=method,
+			url=url,
+			name=request_runner_name,
+			origin=origin,
+			auth=auth,
+			parameters=parameters,
+			qs=qs,
+			headers=headers,
+			body=body,
+			response=response,
+			summary=summary,
+			description=description,
+			tags=tags,
+			on_request=request_runner_hooks(
+				on_request,
+				RequestRunnerRequest,
+				'on_request',
+			),
+			on_request_response=request_runner_hooks(
+				on_request_response,
+				RequestRunnerRequestResponse,
+				'on_request_response',
+			),
+			on_request_error=request_runner_hooks(
+				on_request_error,
+				RequestRunnerRequestError,
+				'on_request_error',
+			),
+		)
+		return
+
+	@abstractmethod
+	def run(
+		self,
+		request: Request,
+	) -> Optional[Response]:
+		"""Return a Response, or write through request.writer and return None."""
+		raise NotImplementedError

DefEssential/Response.py

@@ -0,0 +1,89 @@
+from email.message import Message
+from http import HTTPStatus
+from logging import getLogger
+from typing import (
+	Iterable,
+	Mapping,
+	Optional,
+	Union,
+)
+
+__all__ = (
+	'Response',
+)
+
+logger = getLogger('DefEssential.RequestRunner')
+
+
+def close_bodies(
+	*bodies: object,
+	preserve_error: bool = False,
+) -> None:
+	"""Close every repeated body once without letting cleanup errors hide the original failure."""
+	closed: list[object] = []
+	error: Optional[Exception] = None
+	for body in bodies:
+		if any(body is previous for previous in closed):
+			continue
+		closed.append(body)
+		try:
+			close = getattr(body, 'close', None)
+			if close is not None:
+				close()
+		except Exception as caught:
+			if preserve_error or error is not None:
+				logger.exception('Response body cleanup failed')
+			else:
+				error = caught
+	if error is not None:
+		raise error
+	return
+
+
+class Response:
+	"""Represent an HTTP response with a byte body or sequential output."""
+
+	def __init__(
+		self,
+		status: int = 200,
+		message: Optional[str] = None,
+		headers: Optional[Mapping[str, str]] = None,
+		body: Union[bytes, Iterable[bytes]] = b'',
+		format: Optional[str] = None,
+		charset: Optional[str] = None,
+	):
+		self.status = status
+		self.message = HTTPStatus(status).phrase if message is None else message
+		self.props = Message()
+		for key, value in headers.items() if headers is not None else ():
+			self.header(
+				key,
+				value,
+			)
+		if format is not None:
+			self.header(
+				'Content-Type',
+				format + ('; charset=' + charset if charset is not None else ''),
+			)
+		self.body = body
+		return
+
+	def header(
+		self,
+		key: str,
+		value: Optional[str] = None,
+	) -> Optional[str]:
+		if value is None:
+			return self.props.get(key)
+		if '\r' in key or '\n' in key or '\r' in value or '\n' in value:
+			raise ValueError('Response headers must not contain line breaks')
+		del self.props[key]
+		self.props[key] = value
+		return None
+
+	def headers(self) -> list:
+		return list(self.props.items())
+
+	def close(self) -> None:
+		close_bodies(self.body)
+		return

DefEssential/ResponseSpecification.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from typing import (
+	Mapping,
+	Optional,
+	Sequence,
+	Union,
+)
+
+from .Content import Content
+
+__all__ = (
+	'ResponseSpecification',
+)
+
+
+@dataclass(frozen=True)
+class ResponseSpecification:
+	"""Declare an OpenAPI response independently of the actual Response."""
+
+	status: int
+	description: str
+	content: Union[Content, Sequence[Content], None] = None
+	headers: Optional[Mapping[str, object]] = None

DefEssential/Responses/ResponseFile.py

@@ -0,0 +1,108 @@
+from mimetypes import guess_type
+from pathlib import Path
+from typing import (
+	Iterator,
+	Optional,
+)
+
+from ..Error import ClientError
+from ..Response import Response
+
+__all__ = (
+	'FileBody',
+	'ResponseFile',
+)
+
+
+def file_error(error: OSError) -> ClientError:
+	if isinstance(
+		error,
+		(
+			FileNotFoundError,
+			NotADirectoryError,
+			IsADirectoryError,
+		),
+	):
+		return ClientError(
+			'File not found',
+			status=404,
+		)
+	if isinstance(error, PermissionError):
+		return ClientError(
+			'File access denied',
+			status=403,
+		)
+	raise error
+
+
+class FileBody:
+	"""Read an open file in fixed-size chunks and close it when the response ends."""
+
+	def __init__(
+		self,
+		file,
+	):
+		self.file = file
+		self.closed = False
+		return
+
+	def __iter__(self) -> Iterator[bytes]:
+		try:
+			while True:
+				data = self.file.read(65536)
+				if not data:
+					break
+				yield data
+		finally:
+			self.close()
+		return
+
+	def close(self) -> None:
+		if not self.closed:
+			self.closed = True
+			self.file.close()
+		return
+
+
+class ResponseFile(Response):
+	"""Stream a local file or an open FileSystemObject file as a response."""
+
+	def __init__(
+		self,
+		file,
+		format: Optional[str] = None,
+		encoding: Optional[str] = None,
+	):
+		if isinstance(
+			file,
+			(
+				str,
+				Path,
+			),
+		):
+			path = Path(file)
+			try:
+				file = path.open('rb')
+			except (
+				FileNotFoundError,
+				NotADirectoryError,
+				IsADirectoryError,
+				PermissionError,
+			) as error:
+				raise file_error(error) from error
+			mime, compression = guess_type(str(path))
+			if format is None:
+				format = mime
+			if encoding is None:
+				encoding = compression
+		body = FileBody(file)
+		try:
+			super().__init__(
+				body=body,
+				format=format if format is not None else 'application/octet-stream',
+				headers={'Content-Encoding': encoding} if encoding is not None else None,
+			)
+		except Exception:
+			body.close()
+			raise
+		return