Add Reference Symbols.

James William Pye · James William Pye · commit dacce4fefda5 · 2010-02-27T05:03:33.000-07:00
Implements a means to generate the SQL of a symbol using SQL [on the server].
diff --git a/postgresql/documentation/changes.txt b/postgresql/documentation/changes.txt
@@ -31,3 +31,6 @@ Changes
    connections, whereas the db.wait() method is modified for single targets.
  * Implement an ALock class for managing advisory locks using the
    threading.Lock APIs. [Feedback from Valentine Gogichashvili]
+ * Implement reference symbols. Allow libraries to define symbols that
+   are used to create queries that inherit the original symbol's type and
+   execution method. ``db.prepare(db.prepare(...).first())``
diff --git a/postgresql/documentation/lib.txt b/postgresql/documentation/lib.txt
@@ -336,6 +336,36 @@ effect it will have when invoked:
   ... FROM STDIN``, the iterable must produce COPY lines.
 
 
+Reference Symbols
+=================
+
+Reference Symbols provide a way to construct a Bound Symbol using the Symbol's
+query. When invoked, A Reference Symbol's query is executed in order to produce
+an SQL statement to be used as a Bound Symbol. In ILF files, a reference is
+identified by its symbol name being prefixed with an ampersand::
+
+	[&refsym::first]
+	SELECT 'SELECT 1::int4'::text
+
+Then executed::
+
+	>>> # Runs the 'refsym' SQL, and creates a Bound Symbol using the results.
+	>>> sym = lib.refsym()
+	>>> assert sym() == 1
+
+The Reference Symbol's type and execution method are inherited by the created
+Bound Symbol. With one exception, ``const`` reference symbols are
+special in that they immediately resolved into the target Bound Symbol.
+
+A Reference Symbol's source query *must* produce rows of text columns. Multiple
+columns and multiple rows may be produced by the query, but they must be
+character types as the results are promptly joined together with whitespace so
+that the target statement may be prepared.
+
+Reference Symbols are most likely to be used in dynamic DDL and DML situations,
+or, somewhat more specifically, any query whose definition depends on a
+generated column list.
+
 Distributing and Usage
 ======================
 
@@ -347,7 +377,7 @@ connection is made using the category.
 For mere Python extensions, however, ``distutils`` has a feature that can
 aid in ILF distribution. The ``package_data`` setup keyword can be used to
 include ILF files alongside the Python modules that make up a project. See
-http://docs.python.org/3.0/distutils/setupscript.html#installing-package-data
+http://docs.python.org/3.1/distutils/setupscript.html#installing-package-data
 for more detailed information on the keyword parameter.
 
 The recommended way to manage libraries for extending projects is to
@@ -476,6 +506,10 @@ The following terms are used throughout this chapter:
   An interface to an individual Symbol ready for execution against the subject
   database.
 
+ Bound Reference
+  An interface to an individual Reference Symbol that will produce a Bound
+  Symbol when executed.
+
  ILF
   INI-style Library Format. "lib{NAME}.sql" files.
 
@@ -493,6 +527,9 @@ The following terms are used throughout this chapter:
   An named database operation provided by a Library. Usually, an SQL statement
   with Annotations.
 
+ Reference Symbol
+  A Symbol whose SQL statement *produces* the source for a Bound Symbol.
+
  Category
   An object supporting a classification for connectors that provides database
   initialization facilities for produced connections. For query libraries,
diff --git a/postgresql/lib/__init__.py b/postgresql/lib/__init__.py
@@ -1,29 +1,27 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .lib - query libraries; manage SQL outside of Python.
 ##
 """
 PostgreSQL query libraries.
 
 The purpose of query libraries is provide a means to manage a mapping of symbols
-to database operations. These operations can be simple statements, procedures,
-or something more complex.
+to database operations or objects. These operations can be simple statements,
+procedures, or something more complex.
 
 Libraries are intended to allow the programmer to isolate and manage SQL outside
 of a system's code-flow. It provides a means to construct the basic Python
 interfaces to a PostgreSQL-based application.
 """
 import io
 import os.path
-import operator
-get0 = operator.itemgetter(0)
 from types import ModuleType
 from abc import abstractmethod, abstractproperty
 from ..python.element import Element, ElementSet
 from .. import api as pg_api
 from .. import sys as pg_sys
 from .. import exceptions as pg_exc
 from ..python.itertools import find
+from itertools import chain
 
 try:
 	libdir = os.path.abspath(os.path.dirname(__file__))
@@ -83,6 +81,7 @@ def __init__(self,
 		method = None,
 		type = None,
 		parameters = None,
+		reference = False,
 	):
 		self.library = library
 		self.source = source
@@ -94,6 +93,7 @@ def __init__(self,
 		self.method = method
 		self.type = type
 		self.parameters = parameters
+		self.reference = reference
 
 	def __str__(self):
 		"""
@@ -163,15 +163,22 @@ def __init__(self, symbols, preface = None):
 		self._name = None
 		s = self.symbolsd = {}
 		self.preload = set()
-		for name, (typ, exe, doc, query) in symbols:
+		for name, (isref, typ, exe, doc, query) in symbols:
 			if typ and typ not in self.symtypes:
-				raise ValueError("symbol %r has an invalid type: %r" %(name, typ))
+				raise ValueError(
+					"symbol %r has an invalid type: %r" %(name, typ)
+				)
 			if typ == 'preload':
 				self.preload.add(name)
 				typ = None
 			elif typ == 'proc':
 				pass
-			SYM = Symbol(self, query, name = name, method = exe, type = typ)
+			SYM = Symbol(self, query,
+				name = name,
+				method = exe,
+				type = typ,
+				reference = isref
+			)
 			s[name] = SYM
 
 class ILF(SymbolCollection):
@@ -196,27 +203,6 @@ def get_symbol(self, name):
 	def symbols(self):
 		return self.symbolsd.keys()
 
-	def __init__(self, symbols, preface = None):
-		"""
-		Given an iterable of (symtype, symexe, doc, sql) tuples, create an
-		anonymous ILF library.
-		"""
-		self.preface = preface
-		self._address = None
-		self._name = None
-		s = self.symbolsd = {}
-		self.preload = set()
-		for name, (typ, exe, doc, query) in symbols:
-			if typ and typ not in self.symtypes:
-				raise ValueError("symbol %r has an invalid type: %r" %(name, typ))
-			if typ == 'preload':
-				self.preload.add(name)
-				typ = None
-			elif typ == 'proc':
-				pass
-			SYM = Symbol(self, query, name = name, method = exe, type = typ)
-			s[name] = SYM
-
 	@classmethod
 	def from_lines(typ, lines):
 		"""
@@ -247,7 +233,9 @@ def from_lines(typ, lines):
 			# symbol name
 			# symbol type
 			# how to execute symbol
-			name, styp, exe, *_ = (tuple(symdesc.strip().strip('[]').split(':')) + (None, None))
+			name, styp, exe, *_ = (tuple(
+				symdesc.strip().strip('[]').split(':')
+			) + (None, None))
 			doc = ''
 			endofcomment = 0
 			# resolve any symbol references; only one per line.
@@ -266,7 +254,12 @@ def from_lines(typ, lines):
 			query = ''.join(block[endofcomment:])
 			if styp == 'proc':
 				query = query.strip()
-			syms.append((name, (styp, exe, doc, query)))
+			if name.startswith('&'):
+				name = name[1:]
+				isref = True
+			else:
+				isref = False
+			syms.append((name, (isref, styp, exe, doc, query)))
 		return typ(syms, preface = preface)
 
 	@classmethod
@@ -303,9 +296,38 @@ def __init__(self, symbol, database):
 	def __call__(self, *args, **kw):
 		return self.method(*args, **kw)
 
+class BoundReference(object):
+	"""
+	A symbol bound to a database whose results make up the source of a symbol
+	that will be created upon the execution of this symbol.
+
+	A reference to a symbol.
+	"""
+
+	def __init__(self, symbol, database):
+		self.symbol = symbol
+		self.database = database
+		self.method = database.prepare(symbol).chunks
+
+	def __call__(self, *args, **kw):
+		chunks = chain.from_iterable(self.method(*args, **kw))
+		# Join columns with a space, and rows with a newline.
+		src = '\n'.join([' '.join(row) for row in chunks])
+		return BoundSymbol(
+			Symbol(
+				self.symbol.library, src,
+				name = self.symbol.name,
+				method = self.symbol.method,
+				type = self.symbol.type,
+				parameters = self.symbol.parameters,
+				reference = False,
+			),
+			self.database,
+		)
+
 class Binding(object):
 	"""
-	Interface to a library bound to a database(connection).
+	Library bound to a database(connection).
 	"""
 	def __init__(self, database, library):
 		self.__dict__.update({
@@ -328,8 +350,8 @@ def __dir__(self):
 
 	def __getattr__(self, name):
 		"""
-		Return a BoundSymbol against the Binding's database with the symbol named
-		``name`` in the Binding's library.
+		Return a BoundSymbol against the Binding's database with the
+		symbol named ``name`` in the Binding's library.
 		"""
 		d = self.__dict__
 		s = d['__symbol_cache__']
@@ -339,32 +361,43 @@ def __getattr__(self, name):
 		bs = s.get(name)
 		if bs is None:
 			# No symbol cached with that name.
+			# Everything is crammed in here because
+			# we do *not* want methods on this object.
+			# The namespace is primarily reserved for symbols.
 			sym = lib.get_symbol(name)
 			if sym is None:
 				raise AttributeError(
 					"symbol %r does not exist in library %r" %(
 						name, lib.address
 					)
 				)
-			if not isinstance(sym, Symbol):
-				# subjective symbol...
-				sym = sym(db)
-				if not isinstance(sym, Symbol):
-					raise TypeError(
-						"callable symbol, %r, did not produce Symbol instance" %(
-							name,
-						)
-					)
-			if sym.type == 'const':
-				r = BoundSymbol(sym, db)()
-				if sym.method in ('chunks', 'rows', 'column'):
-					# resolve the iterator
-					r = list(r)
-				bs = s[name] = r
-			else:
-				bs = BoundSymbol(sym, db)
+			if sym.reference:
+				# Reference.
+				bs = BoundReference(sym, db)
+				if sym.type == 'const':
+					# Constant Reference means a BoundSymbol.
+					bs = bs()
 				if sym.type != 'transient':
 					s[name] = bs
+			else:
+				if not isinstance(sym, Symbol):
+					# subjective symbol...
+					sym = sym(db)
+					if not isinstance(sym, Symbol):
+						raise TypeError(
+							"callable symbol, %r, did not produce " \
+							"Symbol instance" %(name,)
+						)
+				if sym.type == 'const':
+					r = BoundSymbol(sym, db)()
+					if sym.method in ('chunks', 'rows', 'column'):
+						# resolve the iterator
+						r = list(r)
+					bs = s[name] = r
+				else:
+					bs = BoundSymbol(sym, db)
+					if sym.type != 'transient':
+						s[name] = bs
 		return bs
 
 class Category(pg_api.Category):
diff --git a/postgresql/test/test_lib.py b/postgresql/test/test_lib.py
@@ -53,6 +53,21 @@
 
 [sym_srf_proc:proc]
 test_ilf_srf_proc(int)
+
+[&sym_reference]
+SELECT 'SELECT 1';
+
+[&sym_reference_params]
+SELECT 'SELECT ' || $1::text;
+
+[&sym_reference_first::first]
+SELECT 'SELECT 1::int4';
+
+[&sym_reference_const:const:first]
+SELECT 'SELECT 1::int4';
+
+[&sym_reference_proc:proc]
+SELECT 'test_ilf_proc(int)'::text
 """
 
 class test_lib(pg_unittest.TestCaseWithCluster):
@@ -84,6 +99,13 @@ def _testILF(self, lib):
 		self.failUnlessEqual(b.sym_proc(2,), 2)
 		self.failUnlessEqual(list(b.sym_srf_proc(2,)), [2])
 		self.failUnlessRaises(AttributeError, getattr, b, 'LIES')
+		# reference symbols
+		self.failUnlessEqual(b.sym_reference()(), [(1,)])
+		self.failUnlessEqual(b.sym_reference_params('1::int')(), [(1,)])
+		self.failUnlessEqual(b.sym_reference_params("'foo'::text")(), [('foo',)])
+		self.failUnlessEqual(b.sym_reference_first()(), 1)
+		self.failUnlessEqual(b.sym_reference_const(), 1)
+		self.failUnlessEqual(b.sym_reference_proc()(2,), 2)
 
 	def testILF_from_lines(self):
 		lib = pg_lib.ILF.from_lines([l + '\n' for l in ilf.splitlines()])
