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

DefPixel/DataAccessObject/Implements/PostgreSQL/Adapters/Array.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+from typing import Sequence
+
+from psycopg.types.array import ListDumper
+
+__all__ = (
+	'ArrayDumper',
+)
+
+
+class ArrayDumper(ListDumper):
+	"""Dump tuples as PostgreSQL arrays in the same way as lists."""
+
+	def dump(self, o: Sequence):
+		return super().dump(list(o))

DefPixel/DataAccessObject/Implements/PostgreSQL/Adapters/JavaScriptObjectNotation.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+
+from collections.abc import (
+	Mapping,
+	Set,
+)
+from dataclasses import (
+	fields,
+	is_dataclass,
+)
+from datetime import (
+	date,
+	datetime,
+	time,
+	timedelta,
+)
+from decimal import Decimal
+from json import dumps
+from typing import Any
+from uuid import UUID
+
+from psycopg.adapt import Dumper
+
+__all__ = (
+	'encode',
+	'JavaScriptObjectNotationDumper',
+	'DataclassDumper',
+)
+
+
+def encode(o: Any) -> Any:
+	"""Convert values that the standard JSON encoder cannot serialize."""
+	if is_dataclass(o) and not isinstance(o, type):
+		return {member.name: getattr(o, member.name) for member in fields(o)}
+	if isinstance(o, (datetime, date, time)):
+		return o.isoformat()
+	if isinstance(o, timedelta):
+		return o.total_seconds()
+	if isinstance(o, (Decimal, UUID)):
+		return str(o)
+	if isinstance(o, Set):
+		return list(o)
+	if isinstance(o, Mapping):
+		return dict(o)
+	if isinstance(o, tuple):
+		return list(o)
+	if isinstance(o, (bytes, bytearray, memoryview)):
+		raise TypeError('Binary values cannot be encoded as JSON')
+	raise TypeError('{} cannot be encoded as JSON'.format(o.__class__.__name__))
+
+
+def serialize(o: Any) -> bytes:
+	return dumps(
+		o,
+		default=encode,
+		ensure_ascii=False,
+		allow_nan=False,
+	).encode('utf-8')
+
+
+class JavaScriptObjectNotationDumper(Dumper):
+	"""Dump mappings as JSON text and let PostgreSQL infer json or jsonb from the context."""
+
+	def dump(self, o: Any) -> bytes:
+		return serialize(o)
+
+
+class DataclassDumper(Dumper):
+	"""Dump dataclass instances as JSON objects; reject other unadaptable objects."""
+
+	def dump(self, o: Any) -> bytes:
+		if not is_dataclass(o) or isinstance(o, type):
+			raise TypeError('cannot adapt type {!r}'.format(o.__class__.__name__))
+		return serialize(o)

DefPixel/DataAccessObject/Implements/PostgreSQL/Adapters/__init__.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+
+from typing import (
+	Mapping as TypingMapping,
+	Optional,
+)
+
+from psycopg.adapt import (
+	AdaptersMap,
+	Dumper,
+	Loader,
+)
+
+from .Array import ArrayDumper
+from .JavaScriptObjectNotation import (
+	DataclassDumper,
+	JavaScriptObjectNotationDumper,
+)
+
+__all__ = (
+	'ArrayDumper',
+	'DataclassDumper',
+	'JavaScriptObjectNotationDumper',
+	'DUMPERS',
+	'register',
+)
+
+DUMPERS = {
+	dict: JavaScriptObjectNotationDumper,
+	tuple: ArrayDumper,
+	object: DataclassDumper,
+}
+
+
+def register(
+	adapters: AdaptersMap,
+	dumpers: Optional[TypingMapping] = None,
+	loaders: Optional[TypingMapping] = None,
+) -> AdaptersMap:
+	"""Register DefPixel defaults first, then user dumpers and loaders that may override them."""
+	for cls, dumper in DUMPERS.items():
+		adapters.register_dumper(cls, dumper)
+	for cls, dumper in (dumpers or {}).items():
+		if not isinstance(dumper, type) or not issubclass(dumper, Dumper):
+			raise TypeError('Dumpers must be psycopg Dumper classes')
+		adapters.register_dumper(cls, dumper)
+	for oid, loader in (loaders or {}).items():
+		if not isinstance(loader, type) or not issubclass(loader, Loader):
+			raise TypeError('Loaders must be psycopg Loader classes')
+		adapters.register_loader(oid, loader)
+	return adapters

DefPixel/DataAccessObject/Implements/PostgreSQL/Column.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+
+from typing import Optional
+
+from .Compiler import (
+	Compilable,
+	Compiler,
+	identifier,
+	typename,
+)
+
+__all__ = (
+	'Column',
+)
+
+
+class Column(Compilable):
+	"""Unqualified column reference with an optional type cast."""
+
+	def __init__(self, name: str):
+		identifier(name)
+		self.name = name
+		self.typecast: Optional[str] = None
+		return
+
+	def cast(self, type) -> 'Column':
+		self.typecast = typename(type)
+		return self
+
+	def compile(self, compiler: Compiler) -> str:
+		return '{}{}'.format(
+			identifier(self.name),
+			'::{}'.format(self.typecast) if self.typecast else '',
+		)

DefPixel/DataAccessObject/Implements/PostgreSQL/Compiler.py

@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+
+from abc import (
+	ABC,
+	abstractmethod,
+)
+import re
+from typing import (
+	Any,
+	Dict,
+	Optional,
+)
+
+from psycopg import (
+	adapters as default_adapters,
+	sql,
+)
+from psycopg.adapt import AdaptersMap
+
+from .Adapters import register
+
+__all__ = (
+	'Compilable',
+	'Compiler',
+	'identifier',
+	'qualified',
+	'quote',
+	'typename',
+	'valuetype',
+)
+
+
+def quote(name: str) -> str:
+	"""Quote an identifier for use inside a bound text value such as a regclass name."""
+	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 identifier(name: str) -> str:
+	"""Quote an identifier and escape percent signs for parameterized execution."""
+	return quote(name).replace('%', '%%')
+
+
+def qualified(
+	name: str,
+	schema: Optional[str] = None,
+) -> str:
+	if schema is None:
+		return identifier(name)
+	return '{}.{}'.format(identifier(schema), identifier(name))
+
+
+def typename(
+	value,
+	escape: bool = True,
+) -> str:
+	"""Resolve a SQL type declaration from a string, Type class, or Type instance."""
+	from .Type import Type
+	if isinstance(value, str):
+		if not value.strip() or '\x00' in value or ';' in value or '--' in value or '/*' in value:
+			raise ValueError('SQL type names must be nonempty strings without null characters, semicolons, or comments')
+		text = value
+	elif isinstance(value, Type) or (isinstance(value, type) and issubclass(value, Type)):
+		text = value.typestr
+		if not text:
+			raise ValueError('{} has no SQL type'.format(value.__name__ if isinstance(value, type) else type(value).__name__))
+	else:
+		raise TypeError('A SQL type must be a string or a PostgreSQL Type')
+	return text.replace('%', '%%') if escape else text
+
+
+UNBOUNDED = {
+	'CHAR': 'BPCHAR',
+	'CHARACTER': 'BPCHAR',
+	'BIT': 'VARBIT',
+}
+
+
+def valuetype(value) -> str:
+	"""Resolve a cast for bound column values without length or precision modifiers.
+
+	An explicit cast such as ::VARCHAR(10) silently truncates, so values are cast to the
+	unbounded type and PostgreSQL applies its assignment and comparison rules instead.
+	"""
+	text = re.sub(r'\s*\(\s*\d+\s*(?:,\s*-?\d+\s*)?\)', '', typename(value, escape=False))
+	text = re.sub(
+		r'^(CHARACTER|CHAR|BIT)(?=$|\[)',
+		lambda match: UNBOUNDED[match.group(1).upper()],
+		text,
+		flags=re.IGNORECASE,
+	)
+	return text
+
+
+class LiteralContext:
+	"""Adaptation context used to render DDL literals with DefPixel dumpers."""
+
+	def __init__(self):
+		self.adapters = AdaptersMap(default_adapters)
+		self.connection = None
+		register(self.adapters)
+		return
+
+
+class Compilable(ABC):
+	"""Object that renders itself into SQL through a Compiler."""
+
+	@abstractmethod
+	def compile(self, compiler: 'Compiler') -> str:
+		raise NotImplementedError('{} must be implemented compile'.format(self.__class__.__name__))
+
+	def __str__(self) -> str:
+		return self.compile(Compiler())
+
+
+class Compiler:
+	"""Collect bound parameters, or render literals for DDL that cannot take parameters.
+
+	qualify=False renders mapped columns without their table name, as required inside CREATE TABLE and CREATE INDEX.
+	"""
+
+	context = None
+
+	def __init__(
+		self,
+		literal: bool = False,
+		qualify: bool = True,
+	):
+		self.literal = literal
+		self.qualify = qualify
+		self.args: Dict[str, Any] = {}
+		return
+
+	def bind(
+		self,
+		value: Any,
+		cast=None,
+	) -> str:
+		if isinstance(value, Compilable):
+			raise TypeError('Compilable objects must be compiled, not bound')
+		if self.literal:
+			if Compiler.context is None:
+				Compiler.context = LiteralContext()
+			text = sql.Literal(value).as_string(Compiler.context).replace('%', '%%')
+		else:
+			name = 'p{}'.format(len(self.args))
+			self.args[name] = value
+			text = '%({})s'.format(name)
+		if cast is not None:
+			text = '{}::{}'.format(text, typename(cast))
+		return text
+
+	def compile(
+		self,
+		value: Any,
+		cast=None,
+	) -> str:
+		if isinstance(value, Compilable):
+			return value.compile(self)
+		return self.bind(value, cast)

DefPixel/DataAccessObject/Implements/PostgreSQL/Configuration.py

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+
+from collections.abc import Mapping
+from typing import (
+	Any,
+	Dict,
+	Mapping as TypingMapping,
+	Optional,
+)
+
+from DefPixel.DataAccessObject import Configuration as BaseConfiguration
+from psycopg.adapt import (
+	Dumper,
+	Loader,
+)
+
+__all__ = (
+	'Configuration',
+)
+
+
+def text(
+	name: str,
+	value: Any,
+	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: Any) -> int:
+	if type(value) is not int:
+		raise TypeError('{} must be an integer'.format(name))
+	return value
+
+
+def flag(name: str, value: Any) -> bool:
+	if type(value) is not bool:
+		raise TypeError('{} must be a bool'.format(name))
+	return value
+
+
+class Configuration(BaseConfiguration):
+	"""Configuration for PostgreSQL connections and optional connection pools."""
+
+	def __init__(
+		self,
+		host: str,
+		port: int = 5432,
+		database: Optional[str] = None,
+		username: Optional[str] = None,
+		password: Optional[str] = None,
+		autocommit: bool = False,
+		pool: bool = False,
+		min: int = 0,
+		max: int = 0,
+		dumpers: Optional[TypingMapping] = None,
+		loaders: Optional[TypingMapping] = None,
+		timezone: Optional[str] = None,
+	):
+		self.host = text('host', host, True)
+		self.database = text('database', database, True)
+		self.port = integer('port', port)
+		if not 1 <= self.port <= 65535:
+			raise ValueError('port must be between 1 and 65535')
+		self.username = text('username', username, False)
+		self.password = text('password', password, False)
+		self.autocommit = flag('autocommit', autocommit)
+		self.pool = flag('pool', pool)
+		self.min = integer('min', min)
+		self.max = integer('max', max)
+		if self.pool and (self.max < 1 or not 0 <= self.min <= self.max):
+			raise ValueError('A connection pool requires 0 <= min <= max and max >= 1')
+		for name, value, base in (('dumpers', dumpers, Dumper), ('loaders', loaders, Loader)):
+			if value is None:
+				continue
+			if not isinstance(value, Mapping):
+				raise TypeError('{} must be a mapping'.format(name))
+			for adapter in value.values():
+				if not isinstance(adapter, type) or not issubclass(adapter, base):
+					raise TypeError('{} must map to psycopg {} classes'.format(name, base.__name__))
+		self.dumpers = dict(dumpers or {})
+		self.loaders = dict(loaders or {})
+		self.timezone = text('timezone', timezone, False)
+		return
+
+	def __repr__(self) -> str:
+		return '{}(host={!r}, port={!r}, database={!r}, username={!r}, autocommit={!r}, pool={!r})'.format(
+			self.__class__.__name__,
+			self.host,
+			self.port,
+			self.database,
+			self.username,
+			self.autocommit,
+			self.pool,
+		)
+
+	def parameters(self) -> Dict[str, Any]:
+		"""Return driver keyword arguments; secrets never pass through a connection string."""
+		kwargs = {
+			'host': self.host,
+			'port': self.port,
+			'dbname': self.database,
+		}
+		if self.username is not None:
+			kwargs['user'] = self.username
+		if self.password is not None:
+			kwargs['password'] = self.password
+		if self.timezone is not None:
+			kwargs['options'] = '-c TimeZone={}'.format(
+				self.timezone.replace('\\', '\\\\').replace(' ', '\\ '),
+			)
+		return kwargs

DefPixel/DataAccessObject/Implements/PostgreSQL/Connection.py

@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+
+from itertools import count
+
+from psycopg import connect
+from psycopg.pq import TransactionStatus
+from psycopg.rows import dict_row
+
+from DefPixel.DataAccessObject import Connection as BaseConnection
+from DefPixel.DataAccessObject.Properties.Database import (
+	Database,
+	Run,
+)
+from .Adapters import register
+from .Configuration import Configuration
+from .Context import Context
+from .Cursor import Cursor
+from .Pool import Pool
+from .Session import Session
+
+__all__ = (
+	'Connection',
+)
+
+
+class Connection(BaseConnection, Database, Run):
+	"""PostgreSQL connection with explicit lifecycle and transaction management."""
+
+	def __init__(self, conf: Configuration):
+		if not isinstance(conf, Configuration):
+			raise TypeError('Connection requires a PostgreSQL Configuration')
+		self.conf = conf
+		self.connection = None
+		self.savepoints = count()
+		return
+
+	def connect(self):
+		if self.connection is not None:
+			raise RuntimeError('The PostgreSQL connection is already open')
+		if self.conf.pool:
+			self.connection = Pool.get(self.conf)
+			return
+		connection = connect(
+			autocommit=self.conf.autocommit,
+			row_factory=dict_row,
+			**self.conf.parameters(),
+		)
+		try:
+			register(connection.adapters, self.conf.dumpers, self.conf.loaders)
+		except BaseException:
+			connection.close()
+			raise
+		self.connection = connection
+		return
+
+	def active(self):
+		if self.connection is None or self.connection.closed:
+			raise RuntimeError('The PostgreSQL connection is not open')
+		return self.connection
+
+	def close(self):
+		"""Close or release the connection; an open transaction is rolled back, never committed."""
+		if self.connection is None:
+			return
+		connection = self.connection
+		self.connection = None
+		try:
+			if not connection.closed and connection.info.transaction_status != TransactionStatus.IDLE:
+				connection.rollback()
+			if not connection.closed and connection.autocommit != self.conf.autocommit:
+				connection.autocommit = self.conf.autocommit
+		finally:
+			if self.conf.pool:
+				Pool.release(self.conf, connection)
+			else:
+				connection.close()
+		return
+
+	def autocommit(self, operation: str):
+		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):
+		connection = self.autocommit('begin')
+		if connection.info.transaction_status != TransactionStatus.IDLE:
+			raise RuntimeError('A transaction is already in progress')
+		# An empty statement makes psycopg open the transaction without a server warning.
+		connection.execute('')
+		return
+
+	def execute(
+		self,
+		sql: str,
+		*args,
+		**kwargs,
+	) -> Context:
+		return self.cursor().execute(sql, *args, **kwargs)
+
+	def executes(
+		self,
+		sql: str,
+		*args,
+	) -> Context:
+		return self.cursor().executes(sql, *args)
+
+	def run(
+		self,
+		executor,
+		filter=None,
+		fetch=None,
+	):
+		cursor = self.cursor()
+		try:
+			return cursor.run(
+				executor,
+				filter=filter,
+				fetch=fetch,
+			)
+		finally:
+			cursor.close()
+
+	def cursor(self) -> Cursor:
+		return Cursor(self.active().cursor())
+
+	def session(self) -> Session:
+		return Session(
+			self.active(),
+			lambda: 'defpixel_savepoint_{}'.format(next(self.savepoints)),
+		)
+
+	def commit(self):
+		self.autocommit('commit').commit()
+		return
+
+	def rollback(self):
+		self.autocommit('rollback').rollback()
+		return

DefPixel/DataAccessObject/Implements/PostgreSQL/Constraint.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+from abc import ABC
+
+from .Compiler import identifier
+
+__all__ = (
+	'Constraint',
+)
+
+
+class Constraint(ABC):
+	"""Named table constraint."""
+
+	def __init__(self, name: str):
+		identifier(name)
+		self.name = name
+		return

DefPixel/DataAccessObject/Implements/PostgreSQL/Constraints/Check.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+
+from ..Compiler import Compilable
+from ..Constraint import Constraint
+
+__all__ = (
+	'Check',
+)
+
+
+class Check(Constraint):
+	"""Named check constraint; values in the expression are rendered as DDL literals."""
+
+	def __init__(
+		self,
+		name: str,
+		expr,
+	):
+		super().__init__(name)
+		if not isinstance(expr, Compilable):
+			raise TypeError('Check requires a SQL expression')
+		self.expr = expr
+		return

DefPixel/DataAccessObject/Implements/PostgreSQL/Constraints/Columns.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+
+from collections.abc import Sequence
+
+from ..Column import Column
+from ..Type import Type
+
+__all__ = (
+	'columns',
+)
+
+
+def columns(values, name: str = 'cols') -> list:
+	"""Normalize constraint columns given as names, Column objects, or column specifications."""
+	if isinstance(values, Sequence) and not isinstance(values, str):
+		values = list(values)
+	else:
+		values = [values]
+	if not values:
+		raise ValueError('{} requires at least one column'.format(name))
+	for value in values:
+		if not isinstance(value, (str, Column, Type)):
+			raise TypeError('{} must contain column names, Column objects, or column specifications'.format(name))
+	return values