DefEssential 0.1.7__21-py3-none-any.whl

DefEssential/Descriptor/Value.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+
+from collections.abc import Mapping
+
+from enum import Enum
+from typing import (
+	Any,
+	Iterator,
+	KeysView,
+	ItemsView,
+	ValuesView,
+	Optional,
+	Dict,
+	Union,
+	Iterable,
+	Tuple,
+)
+from abc import (
+	ABCMeta,
+	ABC,
+)
+
+__all__ = (
+	'Type',
+	'Value',
+	'Condition',
+	'Schema',
+	'OneOf',
+	'AllOf',
+	'TypeMapper',
+	'TypeEncoder',
+)
+
+
+class Descriptor(Mapping[str, Any]):
+	def __init__(
+		self,
+		**kwargs: Any,
+	) -> None:
+		self.__properties__: Dict[str, Any] = kwargs
+		return
+
+	def __getitem__(
+		self,
+		key: str,
+	) -> Any:
+		return self.__properties__.__getitem__(key)
+	
+	def __setitem__(
+		self,
+		key: str,
+		value: Any,
+	) -> None:
+		return self.__properties__.__setitem__(key, value)
+	
+	def __delitem__(
+		self,
+		key: str,
+	) -> None:
+		return self.__properties__.__delitem__(key)
+	
+	def __iter__(self) -> Iterator[str]:
+		return self.__properties__.__iter__()
+	
+	def __len__(self) -> int:
+		return self.__properties__.__len__()
+	
+	def __contains__(
+		self,
+		key: object,
+	) -> bool:
+		return self.__properties__.__contains__(key)
+	
+	def keys(self) -> KeysView[str]:
+		return self.__properties__.keys()
+	
+	def items(self) -> ItemsView[str, Any]:
+		return self.__properties__.items()
+	
+	def values(self) -> ValuesView[Any]:
+		return self.__properties__.values()
+	
+	def __eq__(
+		self,
+		other: object,
+	) -> bool:
+		return self.__properties__.__eq__(other)
+	
+	def __ne__(
+		self,
+		value: object,
+	) -> bool:
+		return self.__properties__.__ne__(value)
+	
+	def get(
+		self,
+		key: str,
+		default: Any = None,
+	) -> Any:
+		return self.__properties__.get(key, default)
+
+
+class Type(str, Enum):
+	Boolean = 'boolean'
+	Integer = 'integer'
+	Number = 'number'
+	String = 'string'
+	Array = 'array'
+	Object = 'object'
+
+
+class Value(Descriptor):
+	def __init__(
+		self, 
+		type: Type,
+		description: Optional[str] = None,
+		format: Optional[str] = None,
+		min: Any = None,
+		max: Any = None,
+		default: Any = None,
+		enum: Optional[Iterable[Any]] = None,
+		required: bool = True,
+	) -> None:
+		super().__init__(type=type)
+		if description: self['description'] = description
+		if format: self['format'] = format
+		if min is not None: self['minimum'] = min
+		if max is not None: self['maximum'] = max
+		if not required: self['default'] = default
+		if enum: self['enum'] = enum
+		self.required = required
+		return
+
+
+class Condition(ABC):
+	def __init__(
+		self,
+		*args: Union[Descriptor, 'Condition', 'Schema'],
+	) -> None:
+		self.args = args
+		return
+
+
+class Schema(object):
+	"""Wrap a Descriptor node, condition, or JSON Schema mapping with a name."""
+
+	def __init__(
+		self,
+		name: str,
+		format: Optional[Union[Mapping[str, Any], Condition, 'Schema']] = None,
+	) -> None:
+		self.name = name
+		self.format = format
+		return
+
+
+class OneOf(Condition):
+	def __init__(
+		self,
+		*args: Union[Descriptor, Condition, Schema],
+		discriminator: Optional[str] = None,
+		required: bool = True,
+	) -> None:
+		super().__init__(*args)
+		self.discriminator = discriminator
+		self.required = required
+		return
+
+
+class AllOf(Condition): pass
+
+
+class TypeMapper(metaclass=ABCMeta):
+	"""Convert a user-defined type to a Value subclass and constructor arguments."""
+
+	def __call__(
+		self,
+		o: type,
+	) -> Tuple[type[Value], Dict[str, Any]]:
+		raise NotImplementedError('{} must be implemented __call__'.format(self.__class__.__name__))
+
+
+class TypeEncoder(metaclass=ABCMeta):
+	def __call__(
+		self,
+		o: Any,
+	) -> Any:
+		raise NotImplementedError('{} must be implemented __call__'.format(self.__class__.__name__))

DefEssential/Descriptor/__init__.py

@@ -0,0 +1,172 @@
+from collections.abc import (
+	Mapping,
+	Sequence,
+)
+from dataclasses import is_dataclass
+from json import (
+	dumps,
+	loads,
+)
+from typing import (
+	Any,
+	Optional,
+	Type,
+)
+
+from .Value import (
+	Value,
+	Condition,
+	Schema,
+	OneOf,
+	AllOf,
+	TypeMapper,
+	TypeEncoder,
+)
+from .Types import (
+	Boolean,
+	IntegerFormat,
+	Integer,
+	NumberFormat,
+	Number,
+	StringFormat,
+	String,
+	Binary,
+	BinaryBase64Encoded,
+	Array,
+	Object,
+	Properties,
+)
+from .DataObject import (
+	DataObjectToSchema,
+	DataObjectToObject,
+)
+
+__all__ = (
+	'Value',
+	'Condition',
+	'Schema',
+	'OneOf',
+	'AllOf',
+	'TypeMapper',
+	'TypeEncoder',
+	'Boolean',
+	'IntegerFormat',
+	'Integer',
+	'NumberFormat',
+	'Number',
+	'StringFormat',
+	'String',
+	'Binary',
+	'BinaryBase64Encoded',
+	'Array',
+	'Object',
+	'Properties',
+	'ToSchema',
+	'DumpSchema',
+	'ToObject',
+)
+
+
+def schema_value(
+	value: Any,
+) -> Any:
+	if isinstance(
+		value,
+		Schema,
+	):
+		return schema_value(value.format)
+	if isinstance(
+		value,
+		Condition,
+	):
+		if isinstance(
+			value,
+			OneOf,
+		):
+			key = 'oneOf'
+		elif isinstance(
+			value,
+			AllOf,
+		):
+			key = 'allOf'
+		else:
+			raise TypeError('Unsupported schema condition: ' + type(value).__name__)
+		return {key: [schema_value(arg) for arg in value.args]}
+	if isinstance(
+		value,
+		Mapping,
+	):
+		return {
+			key: schema_value(item) for key, item in value.items()
+		}
+	if isinstance(
+		value,
+		Sequence,
+	) and not isinstance(
+		value,
+		(
+			str,
+			bytes,
+			bytearray,
+		),
+	):
+		return [schema_value(item) for item in value]
+	if value is None or isinstance(
+		value,
+		(
+			str,
+			int,
+			float,
+			bool,
+		),
+	):
+		return value
+	raise TypeError('Unsupported schema value: ' + type(value).__name__)
+
+
+def DumpSchema(
+	o: Schema,
+) -> dict:
+	if not isinstance(
+		o,
+		Schema,
+	):
+		raise TypeError('A Schema is required')
+	result = schema_value(o)
+	if not isinstance(
+		result,
+		dict,
+	):
+		raise TypeError('A schema must describe an object, value or condition')
+	return loads(dumps(
+		result,
+		allow_nan=False,
+	))
+
+
+def ToSchema(
+	o: Type[object],
+	description: Optional[str] = None,
+	typedef: Optional[TypeMapper] = None,
+) -> Schema:
+	if not isinstance(
+		o,
+		type,
+	) or not is_dataclass(o):
+		raise TypeError('A dataclass type is required')
+	return DataObjectToSchema(mapper=typedef)(
+		o,
+		description,
+	)
+
+
+def ToObject(
+	o: object,
+	typeenc: Optional[TypeEncoder] = None,
+) -> dict:
+	if isinstance(
+		o,
+		type,
+	) or not is_dataclass(o):
+		raise TypeError('A dataclass instance is required')
+	return DataObjectToObject(encoder=typeenc)(o)

DefEssential/Error.py

@@ -0,0 +1,66 @@
+from http import HTTPStatus
+from typing import (
+	Mapping,
+	Optional,
+)
+
+__all__ = (
+	'Error',
+	'ClientError',
+	'ServerError',
+)
+
+
+class Error(Exception):
+	"""Represent an error to be returned as an HTTP response."""
+
+	def __init__(
+		self,
+		status: int,
+		reason: str,
+		headers: Optional[Mapping[str, str]] = None,
+	):
+		super().__init__(reason)
+		self.status = status
+		self.message = HTTPStatus(status).phrase
+		self.reason = reason
+		self.headers = dict(headers) if headers is not None else {}
+		return
+
+
+class ClientError(Error):
+	"""Represent an invalid client request."""
+
+	def __init__(
+		self,
+		reason: str,
+		status: int = 400,
+		headers: Optional[Mapping[str, str]] = None,
+	):
+		if not 400 <= status < 500:
+			raise ValueError('ClientError status code must be in the 4xx range')
+		super().__init__(
+			status,
+			reason,
+			headers,
+		)
+		return
+
+
+class ServerError(Error):
+	"""Represent a server-side processing failure."""
+
+	def __init__(
+		self,
+		reason: str,
+		status: int = 500,
+		headers: Optional[Mapping[str, str]] = None,
+	):
+		if not 500 <= status < 600:
+			raise ValueError('ServerError status code must be in the 5xx range')
+		super().__init__(
+			status,
+			reason,
+			headers,
+		)
+		return

DefEssential/Extension.py

@@ -0,0 +1,191 @@
+from abc import (
+	ABC,
+	abstractmethod,
+)
+from logging import getLogger
+from typing import (
+	Optional,
+	Sequence,
+	Type,
+	TypeVar,
+	TYPE_CHECKING,
+	Union,
+)
+
+from .Request import Request
+from .Response import Response
+
+if TYPE_CHECKING:
+	from .Application import Application
+
+__all__ = (
+	'Extension',
+	'ExtensionStartup',
+	'ExtensionCleanup',
+	'ExtensionRequest',
+	'ExtensionRequestResponse',
+	'ExtensionRequestError',
+)
+
+
+class ExtensionStartup(ABC):
+	"""확장 시작 훅의 호출 계약."""
+
+	@abstractmethod
+	def __call__(self) -> None:
+		raise NotImplementedError
+
+
+class ExtensionCleanup(ABC):
+	"""확장 정리 훅의 호출 계약."""
+
+	@abstractmethod
+	def __call__(self) -> None:
+		raise NotImplementedError
+
+
+class ExtensionRequest(ABC):
+	"""확장 요청 진입 훅의 호출 계약."""
+
+	@abstractmethod
+	def __call__(
+		self,
+		request: Request,
+	) -> Request:
+		raise NotImplementedError
+
+
+class ExtensionRequestResponse(ABC):
+	"""확장 응답 반환 훅의 호출 계약."""
+
+	@abstractmethod
+	def __call__(
+		self,
+		request: Request,
+		response: Optional[Response],
+	) -> Optional[Response]:
+		raise NotImplementedError
+
+
+class ExtensionRequestError(ABC):
+	"""확장 오류 관찰 훅의 호출 계약."""
+
+	@abstractmethod
+	def __call__(
+		self,
+		request: Request,
+		error: Exception,
+	) -> None:
+		raise NotImplementedError
+
+
+Hook = TypeVar('Hook')
+
+
+def extension_hooks(
+	value: object,
+	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')
+
+
+class Extension(ABC):
+	"""인스턴스별 사용자 훅과 시작·요청·정리 계약을 제공한다."""
+
+	logger = getLogger('DefEssential.Extension')
+
+	def __init__(
+		self,
+		*,
+		on_startup: Union[
+			ExtensionStartup,
+			Sequence[ExtensionStartup],
+			None,
+		] = None,
+		on_cleanup: Union[
+			ExtensionCleanup,
+			Sequence[ExtensionCleanup],
+			None,
+		] = None,
+		on_request: Union[
+			ExtensionRequest,
+			Sequence[ExtensionRequest],
+			None,
+		] = None,
+		on_request_response: Union[
+			ExtensionRequestResponse,
+			Sequence[ExtensionRequestResponse],
+			None,
+		] = None,
+		on_request_error: Union[
+			ExtensionRequestError,
+			Sequence[ExtensionRequestError],
+			None,
+		] = None,
+	) -> None:
+		self.startup_hooks = extension_hooks(
+			on_startup,
+			ExtensionStartup,
+			'on_startup',
+		)
+		self.cleanup_hooks = extension_hooks(
+			on_cleanup,
+			ExtensionCleanup,
+			'on_cleanup',
+		)
+		self.request_hooks = extension_hooks(
+			on_request,
+			ExtensionRequest,
+			'on_request',
+		)
+		self.request_response_hooks = extension_hooks(
+			on_request_response,
+			ExtensionRequestResponse,
+			'on_request_response',
+		)
+		self.request_error_hooks = extension_hooks(
+			on_request_error,
+			ExtensionRequestError,
+			'on_request_error',
+		)
+		return
+
+	def __str__(self) -> str:
+		return type(self).__name__
+
+	def startup(
+		self,
+		application: 'Application',
+	) -> None:
+		"""구현체 준비 후 호출하여 사용자 시작 훅을 실행한다."""
+		for index, hook in enumerate(self.startup_hooks):
+			self.logger.debug('Extension startup hook starting: index=%s hook=%s', index, type(hook).__qualname__)
+			if hook() is not None:
+				raise TypeError('ExtensionStartup hooks must return None')
+			self.logger.debug('Extension startup hook completed: index=%s', index)
+		return
+
+	def cleanup(self) -> None:
+		"""사용자 정리 훅을 실행한다. 구현체는 별도로 자원 회수를 보장한다."""
+		for index, hook in enumerate(self.cleanup_hooks):
+			self.logger.debug('Extension cleanup hook starting: index=%s hook=%s', index, type(hook).__qualname__)
+			if hook() is not None:
+				raise TypeError('ExtensionCleanup hooks must return None')
+			self.logger.debug('Extension cleanup hook completed: index=%s', index)
+		return
+
+	@abstractmethod
+	def __call__(
+		self,
+		request: Request,
+	) -> Optional[Response]:
+		raise NotImplementedError

DefEssential/Extensions/File.py

@@ -0,0 +1,95 @@
+from pathlib import Path
+from logging import getLogger
+from typing import (
+	Optional,
+	Sequence,
+	Union,
+)
+
+from ..Application import Application
+from ..Extension import (
+	Extension,
+	ExtensionCleanup,
+	ExtensionRequest,
+	ExtensionRequestError,
+	ExtensionRequestResponse,
+	ExtensionStartup,
+)
+from ..Request import Request
+from ..Responses import ResponseFile
+from .Utils.Routes import (
+	http_routes,
+	validate_path,
+)
+
+__all__ = (
+	'File',
+)
+
+
+class File(Extension):
+	"""고정 HTTP 경로에 파일과 인스턴스별 사용자 훅을 연결한다."""
+
+	logger = getLogger('DefEssential.Extensions.File')
+
+	def __init__(
+		self,
+		path: str,
+		file: Union[
+			str,
+			Path,
+		],
+		*,
+		on_startup: Optional[Union[
+			ExtensionStartup,
+			Sequence[ExtensionStartup],
+		]] = None,
+		on_cleanup: Optional[Union[
+			ExtensionCleanup,
+			Sequence[ExtensionCleanup],
+		]] = None,
+		on_request: Optional[Union[
+			ExtensionRequest,
+			Sequence[ExtensionRequest],
+		]] = None,
+		on_request_response: Optional[Union[
+			ExtensionRequestResponse,
+			Sequence[ExtensionRequestResponse],
+		]] = None,
+		on_request_error: Optional[Union[
+			ExtensionRequestError,
+			Sequence[ExtensionRequestError],
+		]] = None,
+	):
+		super().__init__(
+			on_startup=on_startup,
+			on_cleanup=on_cleanup,
+			on_request=on_request,
+			on_request_response=on_request_response,
+			on_request_error=on_request_error,
+		)
+		validate_path(path)
+		self.path = path
+		self.file = Path(file).resolve()
+		return
+
+	def __str__(self) -> str:
+		return '{}(uri={}, path={})'.format(type(self).__name__, self.path, self.file)
+
+	def startup(
+		self,
+		application: Application,
+	) -> None:
+		for route in http_routes(self, self.path):
+			application.add_extension_route(self, route)
+		super().startup(application)
+		return
+
+	def __call__(
+		self,
+		request: Request,
+	) -> ResponseFile:
+		self.logger.debug('File response preparing: request_id=%s', request.id)
+		response = ResponseFile(self.file)
+		self.logger.debug('File response prepared: request_id=%s', request.id)
+		return response