DefPixel-MariaDB 0.1.6__91-py3-none-any.whl

DefPixel/DataAccessObject/Implements/MariaDB/Column.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+
+from typing import Optional
+
+from .Compiler import (
+	Compiler,
+	identifier,
+	qualified,
+)
+from .Expr import Expr
+
+
+class Column(Expr):
+	"""
+	An explicitly named SQL column with an optional table/alias and database.
+	"""
+	def __init__(
+		self,
+		name: str,
+		*,
+		table: Optional[str] = None,
+		database: Optional[str] = None,
+	) -> None:
+		identifier(name)
+		if table is not None:
+			identifier(table)
+		if database is not None:
+			identifier(database)
+			if table is None:
+				raise ValueError('A qualified database column requires a table')
+		self.name = name
+		self.table = table
+		self.database = database
+		return
+
+	def compile(self, compiler: Compiler) -> str:
+		if self.table is None or not compiler.qualify:
+			return identifier(self.name)
+		return '{}.{}'.format(qualified(self.table, self.database), identifier(self.name))

DefPixel/DataAccessObject/Implements/MariaDB/Compiler.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+
+from abc import (
+	ABC,
+	abstractmethod,
+)
+from decimal import Decimal
+from math import isfinite
+from typing import Optional
+
+
+def identifier(name: str) -> str:
+	"""
+	Quote a MariaDB identifier without changing percent signs in qmark SQL.
+	"""
+	if not isinstance(name, str) or not name or '\x00' in name:
+		raise ValueError('SQL identifiers must be nonempty strings without null characters')
+	return '`{}`'.format(name.replace('`', '``'))
+
+
+def qualified(
+	name: str,
+	database: Optional[str] = None,
+) -> str:
+	if database is None:
+		return identifier(name)
+	return '{}.{}'.format(identifier(database), identifier(name))
+
+
+class Compilable(ABC):
+	"""
+	A MariaDB SQL object compiled using one shared parameter collector.
+	"""
+	@abstractmethod
+	def compile(self, compiler: 'Compiler') -> str:
+		raise NotImplementedError
+
+	def __str__(self) -> str:
+		return self.compile(Compiler())
+
+
+class Compiler:
+	"""
+	Collect qmark parameters, or render SQL-mode-independent DDL literals.
+	"""
+	def __init__(
+		self,
+		literal: bool = False,
+		qualify: bool = True,
+	) -> None:
+		if type(literal) is not bool or type(qualify) is not bool:
+			raise TypeError('Compiler flags must be bool values')
+		self.literal = literal
+		self.qualify = qualify
+		self.args: list[object] = []
+		return
+
+	def bind(self, value: object) -> str:
+		if isinstance(value, Compilable):
+			raise TypeError('Compilable objects must be compiled, not bound')
+		if not self.literal:
+			self.args.append(value)
+			return '?'
+		if value is None:
+			return 'NULL'
+		if isinstance(value, bool):
+			return str(int(value))
+		if isinstance(value, int):
+			return str(value)
+		if isinstance(value, (float, Decimal)):
+			if not (value.is_finite() if isinstance(value, Decimal) else isfinite(value)):
+				raise ValueError('SQL numeric literals must be finite')
+			return str(value)
+		if isinstance(value, bytes):
+			return "X'{}'".format(value.hex())
+		if isinstance(value, str):
+			# Hex text avoids quoting differences under NO_BACKSLASH_ESCAPES.
+			return "CONVERT(X'{}' USING utf8mb4)".format(value.encode('utf8').hex())
+		raise TypeError('Unsupported MariaDB literal type: {}'.format(type(value).__name__))
+
+	def compile(self, value: object) -> str:
+		if isinstance(value, Compilable):
+			return value.compile(self)
+		return self.bind(value)

DefPixel/DataAccessObject/Implements/MariaDB/Configuration.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+
+from typing import Optional
+
+from DefPixel.DataAccessObject import Configuration as BaseConfiguration
+
+__all__ = (
+	'Configuration',
+)
+
+
+def text(
+	name: str,
+	value: Optional[str],
+	required: bool,
+) -> Optional[str]:
+	if value is None and not required:
+		return None
+	if not isinstance(value, str) or not value or '\x00' in value:
+		raise ValueError('{} must be a nonempty string without null characters'.format(name))
+	return value
+
+
+def integer(
+	name: str,
+	value: int,
+	minimum: int,
+	maximum: int,
+) -> int:
+	if type(value) is not int:
+		raise TypeError('{} must be an integer'.format(name))
+	if not minimum <= value <= maximum:
+		raise ValueError('{} must be between {} and {}'.format(name, minimum, maximum))
+	return value
+
+
+def flag(
+	name: str,
+	value: bool,
+) -> bool:
+	if type(value) is not bool:
+		raise TypeError('{} must be a bool'.format(name))
+	return value
+
+
+class Configuration(BaseConfiguration):
+	"""
+	MariaDB connection settings and an optional fixed-size native pool.
+	"""
+
+	def __init__(
+		self,
+		host: str,
+		port: int = 3306,
+		database: Optional[str] = None,
+		username: Optional[str] = None,
+		password: Optional[str] = None,
+		autocommit: bool = False,
+		pool: bool = False,
+		pool_size: int = 5,
+		timezone: Optional[str] = None,
+	) -> None:
+		self.host = text('host', host, True)
+		self.port = integer('port', port, 1, 65535)
+		self.database = text('database', database, True)
+		self.username = text('username', username, False)
+		self.password = text('password', password, False)
+		self.autocommit = flag('autocommit', autocommit)
+		self.pool = flag('pool', pool)
+		self.pool_size = integer('pool_size', pool_size, 1, 64)
+		self.timezone = text('timezone', timezone, False)
+		return
+
+	def parameters(self) -> dict[str, object]:
+		result: dict[str, object] = {
+			'host': self.host,
+			'port': self.port,
+			'database': self.database,
+			'autocommit': self.autocommit,
+		}
+		if self.username is not None:
+			result['user'] = self.username
+		if self.password is not None:
+			result['password'] = self.password
+		return result
+
+	def __repr__(self) -> str:
+		return '{}(host={!r}, port={!r}, database={!r}, username={!r}, autocommit={!r}, pool={!r}, pool_size={!r}, timezone={!r})'.format(
+			self.__class__.__name__,
+			self.host,
+			self.port,
+			self.database,
+			self.username,
+			self.autocommit,
+			self.pool,
+			self.pool_size,
+			self.timezone,
+		)

DefPixel/DataAccessObject/Implements/MariaDB/Connection.py

@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+
+from itertools import count
+from typing import (
+	Callable,
+	Optional,
+)
+
+from mariadb import (
+	Connection as NativeConnection,
+	connect,
+)
+from mariadb.constants.STATUS import IN_TRANS
+
+from DefPixel.DataAccessObject import Connection as BaseConnection
+from DefPixel.DataAccessObject.Properties.Database import Database
+from .Configuration import Configuration
+from .Context import Context
+from .Cursor import (
+	Cursor,
+	ParameterSet,
+)
+from .Pool import Pool
+from .Session import Session
+
+__all__ = (
+	'Connection',
+)
+
+
+class Connection(
+	BaseConnection,
+	Database,
+):
+	"""
+	Explicit MariaDB lifecycle, buffered results, transactions and native pools.
+	"""
+
+	def __init__(self, conf: Configuration) -> None:
+		if not isinstance(conf, Configuration):
+			raise TypeError('Connection requires a MariaDB Configuration')
+		self.conf = conf
+		self.connection: Optional[NativeConnection] = None
+		self.cursors: set[Cursor] = set()
+		self.savepoints = count()
+		return
+
+	def connect(self) -> None:
+		if self.connection is not None:
+			raise RuntimeError('The MariaDB connection is already open')
+		if self.conf.pool:
+			self.connection = Pool.get(self.conf)
+			return
+		connection: NativeConnection = connect(**self.conf.parameters())
+		try:
+			Pool.configure(connection, self.conf)
+		except BaseException:
+			connection.close()
+			raise
+		self.connection = connection
+		return
+
+	def active(self) -> NativeConnection:
+		if self.connection is None:
+			raise RuntimeError('The MariaDB connection is not open')
+		return self.connection
+
+	def close(self) -> None:
+		if self.connection is None:
+			return
+		connection: NativeConnection = self.connection
+		self.connection = None
+		errors: list[Exception] = []
+		for cursor in tuple(self.cursors):
+			try:
+				cursor.close()
+			except Exception as error:
+				errors.append(error)
+		try:
+			if self.conf.pool:
+				Pool.release(self.conf, connection)
+			else:
+				try:
+					if connection.server_status & IN_TRANS:
+						connection.rollback()
+				finally:
+					connection.close()
+		except Exception as error:
+			errors.append(error)
+		if errors:
+			raise RuntimeError('Failed to close the MariaDB connection or its cursors') from errors[0]
+		return
+
+	def autocommit(self, operation: str) -> NativeConnection:
+		if self.conf.autocommit:
+			raise RuntimeError('{} is not available in autocommit mode; use session() for a transaction'.format(operation))
+		return self.active()
+
+	def begin(self) -> None:
+		connection: NativeConnection = self.autocommit('begin')
+		if connection.server_status & IN_TRANS:
+			raise RuntimeError('A transaction is already in progress')
+		with self.execute('START TRANSACTION'):
+			pass
+		return
+
+	def execute(
+		self,
+		sql: str,
+		*args: object,
+		**kwargs: object,
+	) -> Context:
+		cursor: Cursor = self.cursor()
+		try:
+			return cursor.execute(sql, *args, **kwargs)
+		except BaseException:
+			cursor.close()
+			raise
+
+	def executes(
+		self,
+		sql: str,
+		*args: ParameterSet,
+	) -> Context:
+		cursor: Cursor = self.cursor()
+		try:
+			return cursor.executes(sql, *args)
+		except BaseException:
+			cursor.close()
+			raise
+
+	def cursor(self) -> Cursor:
+		cursor = Cursor(
+			self.active().cursor(dictionary=True, buffered=True),
+			self.cursors.discard,
+		)
+		self.cursors.add(cursor)
+		return cursor
+
+	def run(
+		self,
+		executor: object,
+		filter: Optional[Callable[[dict[str, object]], dict[str, object]]] = None,
+		fetch: Optional[type] = None,
+	) -> Optional[object | list[object]]:
+		"""
+		Execute model SQL/DDL on a dedicated cursor and release it on every outcome.
+		"""
+		cursor: Cursor = self.cursor()
+		try:
+			return cursor.run(
+				executor,
+				filter=filter,
+				fetch=fetch,
+			)
+		finally:
+			cursor.close()
+
+	def session(self) -> Session:
+		connection: NativeConnection = self.active()
+		session = Session(
+			connection,
+			connection.cursor(dictionary=True, buffered=True),
+			lambda: 'defpixel_savepoint_{}'.format(next(self.savepoints)),
+			self.cursors.discard,
+		)
+		self.cursors.add(session)
+		return session
+
+	def commit(self) -> None:
+		self.autocommit('commit').commit()
+		return
+
+	def rollback(self) -> None:
+		self.autocommit('rollback').rollback()
+		return

DefPixel/DataAccessObject/Implements/MariaDB/Constraints/__init__.py

@@ -0,0 +1,111 @@
+# -*- coding: utf-8 -*-
+
+from collections.abc import Sequence
+from typing import Optional
+
+from ..Compiler import (
+	Compilable,
+	identifier,
+)
+
+__all__ = (
+	'Constraint',
+	'PrimaryKey',
+	'Unique',
+	'ForeignKey',
+	'Check',
+)
+
+
+def columns(value: Sequence[str]) -> tuple[str, ...]:
+	if isinstance(value, str) or not isinstance(value, Sequence) or not value:
+		raise ValueError('Constraint columns must be a nonempty sequence of names')
+	for name in value:
+		identifier(name)
+	if len(set(value)) != len(value):
+		raise ValueError('Constraint columns must not repeat')
+	return tuple(value)
+
+
+class Constraint:
+	"""
+	A named MariaDB table constraint.
+	"""
+	def __init__(self, name: str) -> None:
+		identifier(name)
+		self.name = name
+		return
+
+
+class Columns(Constraint):
+	def __init__(
+		self,
+		name: str,
+		cols: Sequence[str],
+	) -> None:
+		super().__init__(name)
+		self.cols = columns(cols)
+		return
+
+
+class PrimaryKey(Columns):
+	pass
+
+
+class Unique(Columns):
+	pass
+
+
+class ForeignKey(Columns):
+	"""
+	Reference a mapped table or an explicit table name using InnoDB actions.
+	"""
+	def __init__(
+		self,
+		name: str,
+		cols: Sequence[str],
+		reference: str | type,
+		reference_cols: Sequence[str],
+		*,
+		on_delete: Optional[str] = None,
+		on_update: Optional[str] = None,
+	) -> None:
+		super().__init__(
+			name,
+			cols,
+		)
+		if isinstance(reference, str):
+			identifier(reference)
+		elif not isinstance(reference, type):
+			raise TypeError('Foreign key reference must be a mapped model or table name')
+		self.reference = reference
+		self.reference_cols = columns(reference_cols)
+		if len(self.cols) != len(self.reference_cols):
+			raise ValueError('Foreign key column counts must match')
+		for value in (
+			on_delete,
+			on_update,
+		):
+			if value is not None and value not in (
+				'RESTRICT',
+				'NO ACTION',
+				'CASCADE',
+				'SET NULL',
+			):
+				raise ValueError('Unsupported InnoDB foreign key action')
+		self.on_delete = on_delete
+		self.on_update = on_update
+		return
+
+
+class Check(Constraint):
+	def __init__(
+		self,
+		name: str,
+		expression: Compilable,
+	) -> None:
+		super().__init__(name)
+		if not isinstance(expression, Compilable):
+			raise TypeError('CHECK requires a MariaDB expression')
+		self.expression = expression
+		return

DefPixel/DataAccessObject/Implements/MariaDB/Context.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+
+from types import TracebackType
+from typing import (
+	Callable,
+	Optional,
+)
+
+from mariadb import Cursor as NativeCursor
+
+from DefPixel.DataAccessObject.Properties.Database import Context as BaseContext
+
+__all__ = (
+	'Context',
+)
+
+
+class Context(BaseContext):
+	"""
+	A buffered dictionary result; row reads advance its owning cursor.
+	"""
+
+	def __init__(
+		self,
+		cursor: NativeCursor,
+		query: Optional[str] = None,
+		close: Optional[Callable[[], None]] = None,
+	) -> None:
+		self.cursor = cursor
+		self.statement = query
+		self.release = close
+		return
+
+	def rows(self) -> list[dict[str, object]]:
+		if self.cursor.description is None:
+			return []
+		return [dict(row) for row in self.cursor.fetchall()]
+
+	def row(self) -> Optional[dict[str, object]]:
+		if self.cursor.description is None:
+			return None
+		row = self.cursor.fetchone()
+		return dict(row) if row is not None else None
+
+	def count(self) -> int:
+		return self.cursor.rowcount
+
+	@property
+	def query(self) -> str:
+		if self.statement is None:
+			raise RuntimeError('The executed query is not available in this context')
+		return self.statement
+
+	def close(self) -> None:
+		if self.release is not None:
+			self.release()
+		return
+
+	def __enter__(self) -> 'Context':
+		return self
+
+	def __exit__(
+		self,
+		exception_type: Optional[type[BaseException]],
+		exception: Optional[BaseException],
+		traceback: Optional[TracebackType],
+	) -> bool:
+		self.close()
+		return False

DefPixel/DataAccessObject/Implements/MariaDB/Cursor.py

@@ -0,0 +1,137 @@
+# -*- coding: utf-8 -*-
+
+from collections.abc import (
+	Mapping,
+	Sequence,
+)
+from typing import (
+	Callable,
+	Optional,
+	Union,
+)
+
+from mariadb import Cursor as NativeCursor
+
+from DefPixel.DataAccessObject.Properties.Database import Cursor as BaseCursor
+from .Context import Context
+
+Parameters = Union[tuple[object, ...], dict[str, object]]
+ParameterSet = Union[Sequence[object], Mapping[str, object]]
+
+__all__ = (
+	'Cursor',
+)
+
+
+def parameters(
+	args: tuple[object, ...],
+	kwargs: dict[str, object],
+) -> Optional[Parameters]:
+	if args and kwargs:
+		raise ValueError('Positional and named parameters cannot be used together')
+	if kwargs:
+		return kwargs
+	return args if args else None
+
+
+def batch(args: tuple[ParameterSet, ...]) -> list[Parameters]:
+	if not args:
+		raise ValueError('executes requires at least one parameter set')
+	result: list[Parameters] = []
+	kinds: set[str] = set()
+	for item in args:
+		if isinstance(item, Mapping):
+			if any(not isinstance(key, str) for key in item):
+				raise TypeError('Named parameter keys must be strings')
+			kinds.add('named')
+			result.append(dict(item))
+		elif isinstance(item, Sequence) and not isinstance(item, (str, bytes, bytearray)):
+			kinds.add('positional')
+			result.append(tuple(item))
+		else:
+			raise TypeError('Each parameter set must be a sequence or a mapping')
+	if len(kinds) != 1:
+		raise ValueError('Positional and named parameter sets cannot be mixed')
+	return result
+
+
+class Cursor(BaseCursor):
+	"""
+	A native dictionary cursor with explicit lifetime and parameter validation.
+	"""
+
+	def __init__(
+		self,
+		cursor: NativeCursor,
+		close: Optional[Callable[['Cursor'], None]] = None,
+	) -> None:
+		self.cursor = cursor
+		self.release = close
+		self.closed = False
+		return
+
+	def active(self) -> NativeCursor:
+		if self.closed:
+			raise RuntimeError('The MariaDB cursor is closed')
+		return self.cursor
+
+	def execute(
+		self,
+		sql: str,
+		*args: object,
+		**kwargs: object,
+	) -> Context:
+		if not isinstance(sql, str) or not sql.strip() or '\x00' in sql:
+			raise ValueError('SQL must be a nonempty string without null characters')
+		cursor: NativeCursor = self.active()
+		cursor.execute(sql, parameters(args, kwargs))
+		return Context(cursor, sql, self.close)
+
+	def executes(
+		self,
+		sql: str,
+		*args: ParameterSet,
+	) -> Context:
+		if not isinstance(sql, str) or not sql.strip() or '\x00' in sql:
+			raise ValueError('SQL must be a nonempty string without null characters')
+		cursor: NativeCursor = self.active()
+		cursor.executemany(sql, batch(args))
+		return Context(cursor, sql, self.close)
+
+	def rows(self) -> list[dict[str, object]]:
+		return Context(self.active()).rows()
+
+	def row(self) -> Optional[dict[str, object]]:
+		return Context(self.active()).row()
+
+	def count(self) -> int:
+		return self.active().rowcount
+
+	def run(
+		self,
+		executor: object,
+		filter: Optional[Callable[[dict[str, object]], dict[str, object]]] = None,
+		fetch: Optional[type] = None,
+	) -> Optional[object | list[object]]:
+		"""
+		Execute model SQL/DDL while keeping this cursor owned by the caller.
+		"""
+		from .Run import run
+		self.active()
+		return run(
+			self,
+			executor,
+			filter=filter,
+			fetch=fetch,
+		)
+
+	def close(self) -> None:
+		if self.closed:
+			return
+		self.closed = True
+		try:
+			self.cursor.close()
+		finally:
+			if self.release is not None:
+				self.release(self)
+		return