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

DefPixel/DataAccessObject/Implements/PostgreSQL/Mapping.py

@@ -0,0 +1,359 @@
+# -*- coding: utf-8 -*-
+
+from copy import (
+	copy,
+	deepcopy,
+)
+from dataclasses import (
+	MISSING,
+	field,
+	fields,
+	is_dataclass,
+)
+from types import MemberDescriptorType
+from typing import (
+	Any,
+	Callable,
+	Dict,
+	NamedTuple,
+	Optional,
+	Sequence as TypingSequence,
+	Type as PythonType,
+	TypeVar,
+)
+
+from .Compiler import (
+	Compilable,
+	identifier,
+	qualified,
+)
+from .Constraint import Constraint
+from .Index import Index
+from .Schema import Schema
+from .Sequence import Sequence
+from .Type import Type
+
+__all__ = (
+	'column',
+	'table',
+	'view',
+)
+
+METADATA = 'postgresql'
+MAPPING = '__postgresql__'
+T = TypeVar('T')
+
+
+class Statement(NamedTuple):
+	"""Satisfy the single-execution contract while preserving query and argument unpacking."""
+
+	query: str
+	args: Any = ()
+
+
+class ColumnAccess:
+	"""Expose a column on class access and a standard field value on instance access."""
+
+	def __init__(
+		self,
+		name: str,
+		spec: Type,
+		original: Any,
+		default: Any,
+	):
+		self.name = name
+		self.spec = spec
+		self.original = original
+		self.default = default
+		return
+
+	def __get__(
+		self,
+		instance,
+		owner=None,
+	):
+		if instance is None:
+			return self.spec
+		if self.original is not None:
+			return self.original.__get__(instance, owner)
+		if self.name in instance.__dict__:
+			return instance.__dict__[self.name]
+		if self.default is not MISSING:
+			return self.default
+		raise AttributeError(self.name)
+
+	def __set__(
+		self,
+		instance,
+		value,
+	):
+		if self.original is not None:
+			self.original.__set__(instance, value)
+		else:
+			instance.__dict__[self.name] = value
+		return
+
+	def __delete__(self, instance):
+		if self.original is not None:
+			self.original.__delete__(instance)
+		else:
+			try:
+				del instance.__dict__[self.name]
+			except KeyError:
+				raise AttributeError(self.name) from None
+		return
+
+
+class Mapping:
+	"""Explicit mapping between a dataclass and PostgreSQL storage."""
+
+	def __init__(
+		self,
+		model: PythonType,
+		name: str,
+		kind: str,
+		schema: Optional[str],
+		columns: Dict[str, Type],
+		sequences: TypingSequence[Sequence],
+		constraints: TypingSequence[Constraint],
+		indexes: TypingSequence[Index],
+		executor=None,
+		description=None,
+	):
+		self.model = model
+		self.name = name
+		self.kind = kind
+		self.schema = schema
+		self.columns = columns
+		self.sequences = sequences
+		self.constraints = constraints
+		self.indexes = indexes
+		self.executor = executor
+		self.description = description
+		return
+
+	@property
+	def target(self) -> str:
+		return qualified(self.name, self.schema)
+
+	def key(self, name: str) -> str:
+		"""Resolve a field name or column key to the column key."""
+		if name in self.columns:
+			return self.columns[name].key
+		if name in {spec.key for spec in self.columns.values()}:
+			return name
+		raise ValueError('Column is not mapped: {}'.format(name))
+
+	def values(self, values):
+		unknown = set(values) - self.columns.keys()
+		if unknown:
+			raise ValueError('Unmapped fields: {}'.format(', '.join(sorted(unknown))))
+		return {
+			self.columns[name].key: (self.columns[name], self.columns[name].encode(value))
+			for name, value in values.items()
+		}
+
+	def restore(self, row):
+		members = {member.name: member for member in fields(self.model)}
+		values = {}
+		deferred = {}
+		by_column = {spec.key: name for name, spec in self.columns.items()}
+		for key, value in row.items():
+			if key not in by_column:
+				raise ValueError('Result column is not mapped to the model: {}'.format(key))
+			name = by_column[key]
+			value = self.columns[name].validate(value)
+			if members[name].init:
+				values[name] = value
+			else:
+				deferred[name] = value
+		for name, member in members.items():
+			if (
+				member.init and name not in values
+				and member.default is MISSING and member.default_factory is MISSING
+			):
+				raise ValueError('Missing field required for object restoration: {}'.format(name))
+		instance = self.model(**values)
+		for name, value in deferred.items():
+			object.__setattr__(instance, name, value)
+		return instance
+
+
+def column(
+	spec: Type,
+	*,
+	validator=None,
+	description: Optional[str] = None,
+) -> Any:
+	"""Attach a PostgreSQL specification and its default to a standard Field."""
+	if not isinstance(spec, Type):
+		raise TypeError('column requires a PostgreSQL Type specification')
+	spec = copy(spec)
+	if validator is not None:
+		spec.validator = validator
+	metadata = {
+		METADATA: spec,
+		'description': description,
+	}
+	default = spec.coldef
+	if isinstance(default, Compilable):
+		# Server-side defaults are computed by PostgreSQL; the dataclass value stays empty.
+		return field(default=None, metadata=metadata)
+	if isinstance(default, (list, dict, set)):
+		return field(default_factory=lambda: deepcopy(default), metadata=metadata)
+	return field(default=default, metadata=metadata)
+
+
+def inspect_model(
+	model: PythonType,
+	kind: Optional[str] = None,
+) -> Mapping:
+	if not isinstance(model, type) or not is_dataclass(model):
+		raise TypeError('ORM models must be dataclass classes')
+	mapping = vars(model).get(MAPPING)
+	if not isinstance(mapping, Mapping) or mapping.model is not model:
+		raise ValueError('{} has no PostgreSQL @table or @view mapping'.format(model.__name__))
+	if kind is not None and mapping.kind != kind:
+		raise ValueError('A {} operation cannot use a {} mapping'.format(kind, mapping.kind))
+	return mapping
+
+
+def items(value, kind, name: str) -> tuple:
+	if value is None:
+		return ()
+	if isinstance(value, kind):
+		return (value,)
+	value = tuple(value)
+	for item in value:
+		if not isinstance(item, kind):
+			raise TypeError('{} must contain {} objects'.format(name, kind.__name__))
+	return value
+
+
+def mapped(
+	model: PythonType[T],
+	name,
+	kind,
+	schema,
+	sequences,
+	constraints,
+	indexes,
+	executor,
+	description,
+) -> PythonType[T]:
+	if not isinstance(model, type) or not is_dataclass(model):
+		raise TypeError('@{} must be applied after @dataclass'.format(kind))
+	if MAPPING in vars(model):
+		raise ValueError('The model already has a PostgreSQL mapping')
+	name = model.__name__ if name is None else name
+	identifier(name)
+	if isinstance(schema, Schema):
+		schema = schema.name
+	if schema is not None:
+		identifier(schema)
+	sequences = items(sequences, Sequence, 'sequences')
+	for sequence in sequences:
+		if sequence.schema is not None and sequence.schema != schema:
+			raise ValueError('Sequence {} already belongs to schema {}'.format(sequence.name, sequence.schema))
+		sequence.schema = schema
+	columns = {}
+	accessors = {}
+	keys = set()
+	for member in fields(model):
+		if member.name == MAPPING:
+			raise ValueError('The reserved mapping attribute cannot be used as a field name')
+		if METADATA not in member.metadata:
+			continue
+		spec = copy(member.metadata[METADATA])
+		spec.key = member.name if spec.key is None else spec.key
+		identifier(spec.key)
+		if spec.key in keys:
+			raise ValueError('Duplicate column: {}'.format(spec.key))
+		keys.add(spec.key)
+		spec.model = name
+		spec.schema = schema
+		columns[member.name] = spec
+		original = None
+		for base in model.__mro__:
+			attribute = vars(base).get(member.name)
+			if isinstance(attribute, ColumnAccess):
+				original = attribute.original
+				break
+			if isinstance(attribute, MemberDescriptorType):
+				original = attribute
+				break
+		accessors[member.name] = ColumnAccess(
+			member.name,
+			spec,
+			original,
+			member.default,
+		)
+	if not columns:
+		raise ValueError('No fields are declared with column()')
+	mapping = Mapping(
+		model,
+		name,
+		kind,
+		schema,
+		columns,
+		sequences,
+		items(constraints, Constraint, 'constraints'),
+		items(indexes, Index, 'indexes'),
+		executor,
+		description,
+	)
+	setattr(model, MAPPING, mapping)
+	for key, accessor in accessors.items():
+		setattr(model, key, accessor)
+	return model
+
+
+def table(
+	name=None,
+	*,
+	schema=None,
+	sequences=None,
+	constraints=None,
+	indexes=None,
+	description=None,
+) -> Callable[[PythonType[T]], PythonType[T]]:
+	"""Map a processed dataclass to a table and return the same class."""
+	def decorate(model: PythonType[T]) -> PythonType[T]:
+		return mapped(
+			model,
+			name,
+			'table',
+			schema,
+			sequences,
+			constraints,
+			indexes,
+			None,
+			description,
+		)
+	return decorate
+
+
+def view(
+	*,
+	executor,
+	name=None,
+	schema=None,
+	description=None,
+) -> Callable[[PythonType[T]], PythonType[T]]:
+	"""Map a processed dataclass to a view defined by a query Executor."""
+	def decorate(model: PythonType[T]) -> PythonType[T]:
+		from DefPixel.DataAccessObject.Properties.Database import Executor
+		if not isinstance(executor, Executor) or not isinstance(executor, Compilable):
+			raise TypeError('View definitions require a PostgreSQL query Executor')
+		return mapped(
+			model,
+			name,
+			'view',
+			schema,
+			None,
+			None,
+			None,
+			executor,
+			description,
+		)
+	return decorate

DefPixel/DataAccessObject/Implements/PostgreSQL/Orders.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+
+from typing import Optional
+
+from .Column import Column
+from .Compiler import (
+	Compilable,
+	Compiler,
+)
+from .Expr import Expr
+
+__all__ = (
+	'Ascend',
+	'Descend',
+	'Random',
+)
+
+NULLS = ('FIRST', 'LAST')
+
+
+class Order(Expr):
+	direction = ''
+
+	def __init__(
+		self,
+		col,
+		null: Optional[str] = 'LAST',
+	):
+		if isinstance(col, str):
+			col = Column(col)
+		if not isinstance(col, Compilable):
+			raise TypeError('Orders require a column name or SQL expression')
+		if null is not None:
+			if not isinstance(null, str) or null.upper() not in NULLS:
+				raise ValueError('null must be FIRST, LAST, or None')
+			null = null.upper()
+		self.col = col
+		self.null = null
+		return
+
+	def compile(self, compiler: Compiler) -> str:
+		return '{} {}{}'.format(
+			compiler.compile(self.col),
+			self.direction,
+			' NULLS {}'.format(self.null) if self.null else '',
+		)
+
+
+class Ascend(Order):
+	direction = 'ASC'
+
+
+class Descend(Order):
+	direction = 'DESC'
+
+
+class Random(Expr):
+	def compile(self, compiler: Compiler) -> str:
+		return 'RANDOM()'

DefPixel/DataAccessObject/Implements/PostgreSQL/Pool.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+
+from threading import Lock
+from typing import (
+	Dict,
+	Optional,
+	Tuple,
+)
+
+from psycopg.rows import dict_row
+from psycopg import Connection
+from psycopg_pool import ConnectionPool
+
+from .Adapters import register
+from .Configuration import Configuration
+
+__all__ = (
+	'Pool',
+)
+
+
+class Pool:
+	"""Process-wide registry of connection pools keyed by Configuration object."""
+
+	# Entries keep their Configuration alive so its id cannot be reused by another object.
+	pools: Dict[int, Tuple[Configuration, ConnectionPool]] = {}
+	borrowed: Dict[Connection, Tuple[Configuration, ConnectionPool]] = {}
+	lock = Lock()
+
+	@classmethod
+	def get(cls, conf: Configuration):
+		"""Acquire a connection from the pool for the configuration, creating the pool on first use."""
+		with cls.lock:
+			entry = cls.pools.get(id(conf))
+			pool = entry[1] if entry is not None else None
+			if pool is None:
+				def configure(connection):
+					register(connection.adapters, conf.dumpers, conf.loaders)
+					return
+				pool = ConnectionPool(
+					kwargs=dict(
+						conf.parameters(),
+						autocommit=conf.autocommit,
+						row_factory=dict_row,
+					),
+					min_size=conf.min,
+					max_size=conf.max,
+					configure=configure,
+					open=True,
+				)
+				cls.pools[id(conf)] = (conf, pool)
+		connection = pool.getconn()
+		with cls.lock:
+			cls.borrowed[connection] = (conf, pool)
+		return connection
+
+	@classmethod
+	def release(
+		cls,
+		conf: Configuration,
+		connection,
+	):
+		"""Return to the originating pool, including after shutdown or recreation."""
+		with cls.lock:
+			entry = cls.borrowed.get(connection)
+			if entry is None or entry[0] is not conf:
+				raise RuntimeError('The connection was not borrowed for the configuration')
+			entry[1].putconn(connection)
+			del cls.borrowed[connection]
+		return
+
+	@classmethod
+	def close(cls, conf: Optional[Configuration] = None):
+		"""Close the pool for one configuration, or every pool when no configuration is given."""
+		with cls.lock:
+			if conf is None:
+				pools = [pool for _, pool in cls.pools.values()]
+				cls.pools.clear()
+			else:
+				entry = cls.pools.pop(id(conf), None)
+				pools = [entry[1]] if entry is not None else []
+		for pool in pools:
+			pool.close()
+		return

DefPixel/DataAccessObject/Implements/PostgreSQL/Schema.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+from typing import Optional
+
+from .Compiler import identifier
+
+__all__ = (
+	'Schema',
+)
+
+
+class Schema:
+	"""PostgreSQL schema declaration usable with Create and Drop."""
+
+	def __init__(
+		self,
+		name: str,
+		username: Optional[str] = None,
+	):
+		identifier(name)
+		if username is not None:
+			identifier(username)
+		self.name = name
+		self.username = username
+		return
+
+	def __str__(self) -> str:
+		return self.name

DefPixel/DataAccessObject/Implements/PostgreSQL/Sequence.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+
+from typing import Optional
+
+from .Compiler import (
+	identifier,
+	typename,
+)
+
+__all__ = (
+	'Sequence',
+)
+
+
+def option(name: str, value, null: bool = False):
+	if value is None and null:
+		return None
+	if type(value) is not int:
+		raise TypeError('Sequence {} must be an int'.format(name))
+	return value
+
+
+class Sequence:
+	"""PostgreSQL sequence declaration; table mappings assign the table schema."""
+
+	def __init__(
+		self,
+		name: str,
+		type=None,
+		increment: int = 1,
+		min: Optional[int] = 1,
+		max: Optional[int] = None,
+		start: Optional[int] = 1,
+		notexists: bool = True,
+	):
+		identifier(name)
+		if type is None:
+			from .Types import BIGINT
+			type = BIGINT
+		self.name = name
+		self.schema: Optional[str] = None
+		self.type = typename(type, escape=False)
+		self.increment = option('increment', increment)
+		if self.increment == 0:
+			raise ValueError('Sequence increment cannot be zero')
+		self.min = option('min', min, True)
+		self.max = option('max', max, True)
+		self.start = option('start', start, True)
+		if not isinstance(notexists, bool):
+			raise TypeError('notexists must be a bool')
+		self.notexists = notexists
+		return
+
+	def __str__(self) -> str:
+		return self.name

DefPixel/DataAccessObject/Implements/PostgreSQL/Session.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable
+
+from psycopg.pq import TransactionStatus
+
+from DefPixel.DataAccessObject.Properties.Database import Session as BaseSession
+from .Compiler import identifier
+from .Cursor import Cursor
+
+__all__ = (
+	'Session',
+)
+
+
+class Session(Cursor, BaseSession):
+	"""Transaction scope: owns a transaction when none is open, otherwise uses a SAVEPOINT."""
+
+	def __init__(
+		self,
+		connection,
+		savepoint: Callable[[], str],
+	):
+		self.connection = connection
+		self.name = savepoint
+		self.savepoint = None
+		self.autocommit = None
+		self.entered = False
+		super().__init__(connection.cursor())
+		return
+
+	def __enter__(self):
+		if self.entered:
+			raise RuntimeError('The session has already been entered')
+		status = self.connection.info.transaction_status
+		if status == TransactionStatus.INERROR:
+			raise RuntimeError('The current transaction is aborted; roll it back before starting a session')
+		if status == TransactionStatus.INTRANS:
+			self.savepoint = identifier(self.name())
+			self.connection.execute('SAVEPOINT {}'.format(self.savepoint))
+		elif status == TransactionStatus.IDLE:
+			if self.connection.autocommit:
+				self.autocommit = True
+				self.connection.autocommit = False
+			try:
+				# An empty statement makes psycopg open the transaction without a server warning.
+				self.connection.execute('')
+			except BaseException:
+				self.restore()
+				raise
+		else:
+			raise RuntimeError('A session cannot start while the connection is {}'.format(status.name))
+		self.entered = True
+		return self
+
+	def __exit__(
+		self,
+		exception_type,
+		exception,
+		traceback,
+	):
+		try:
+			if self.savepoint is not None:
+				if exception_type is not None:
+					self.connection.execute('ROLLBACK TO SAVEPOINT {}'.format(self.savepoint))
+				self.connection.execute('RELEASE SAVEPOINT {}'.format(self.savepoint))
+			elif exception_type is None:
+				self.connection.commit()
+			else:
+				self.connection.rollback()
+		finally:
+			try:
+				self.close()
+			finally:
+				self.restore()
+		return False
+
+	def restore(self):
+		if self.autocommit is not None:
+			if self.connection.info.transaction_status != TransactionStatus.IDLE:
+				self.connection.rollback()
+			self.connection.autocommit = self.autocommit
+			self.autocommit = None
+		return