Refactor InterfaceElement in order to provide "multiple ancestors".

The InterfaceElement ABC has be moved to postgresql.python.element.Element.
"Ancestors" are no more. Rather, they are called factors. As
in, the factors that play a critical role in the definition of this element.

ife_snapshot_text was completely removed in favor of
postgresql.python.element.format_element and the _e_metas methods.
format_element takes care of all the formatting cases for the printing of the
factor tree, and _e_metas provides any additional, non-factor information about
a given element. This makes adding information points *much* easier as
snapshot_text required that the element do all of the formatting.

Message raising is now supported by checking for the "trap_message" attribute
on a transaction's controller and *all* of its primary factors. Like
with-statement's exit, a message will not raised if a True value is returned by
a given "trap_message" callable. If a message is not suffocated, it will
eventually be given to `postgresql.sys.msghook`, which can be overridden by the
user.

Warnings are no longer Python Warnings, just Message sub-classes. Using Python
warnings was pointless.

Connection failures are not longer published on CCC errors. They are now
published on the connection object itself using
postgresql.protocol.client3.ConnectionAttempt objects.
This object is temporary, so it will be undocumented like CCC's
connection_failure attribute. It may not even make it into 0.9.

Author: James William Pye

postgresql/api.py

@@ -55,11 +55,13 @@ def command(argv = sys.argv):
 			connection = connector()
 			connection.connect()
 		except pg_exc.ClientCannotConnectError as err:
-			for (didssl, sc, cf) in err.connection_failures:
-				if isinstance(cf, pg_exc.AuthenticationSpecificationError):
-					sys.stderr.write(os.linesep + cf.message + (os.linesep*2))
+			for att in connection.attempt:
+				exc = att.exception
+				if isinstance(exc, pg_exc.AuthenticationSpecificationError):
+					sys.stderr.write(os.linesep + exc.message + (os.linesep*2))
 					# keep prompting the user
 					need_prompt = True
+					connection = None
 					break
 			else:
 				# no invalid password failures..

postgresql/bin/pg_python.py

@@ -57,17 +57,23 @@ class Cluster(pg_api.Cluster):
 	accommodate for a particular purpose.
 	"""
 	installation = None
+	data_directory = None
 	DEFAULT_CLUSTER_ENCODING = DEFAULT_CLUSTER_ENCODING
 	DEFAULT_CONFIG_FILENAME = DEFAULT_CONFIG_FILENAME
 	DEFAULT_PID_FILENAME = DEFAULT_PID_FILENAME
 	DEFAULT_HBA_FILENAME = DEFAULT_HBA_FILENAME
 
-	ife_ancestor = property(attrgetter('installation'))
-	def ife_snapshot_text(self):
-		return self.data_directory + ' [' + (
-			'running: ' + str(self.pid)
-			if self.running() else 'not running'
-		) + ']'
+	@property
+	def state(self):
+		if self.running():
+			return 'running'
+		return 'not running'
+
+	def _e_metas(self):
+		state = self.state
+		yield (None, '[' + state + ']')
+		if state == 'running':
+			yield ('pid', self.state)
 
 	@property
 	def daemon_path(self):
@@ -169,9 +175,9 @@ def init(self,
 			if initdb is None:
 				e = pg_exc.ClusterInitializationError(
 					"unable to find `initdb` executable for installation: " + \
-					repr(self.installation)
+					repr(self.installation),
+					creator = self
 				)
-				self.ife_descend(e)
 				e.raise_exception()
 
 		# Transform keyword options into command options for the executable.
@@ -231,15 +237,14 @@ def init(self,
 				msg = os.linesep.join([
 					repr(x)[2:-1] for x in r.splitlines()
 				])
-			e = pg_exc.InitDBError(
+			pg_exc.InitDBError(
 				msg,
 				details = {
 					'COMMAND': cmd,
 					'RESULT': rc,
-				}
-			)
-			self.ife_descend(e)
-			e.raise_exception()
+				},
+				creator = self
+			).raise_exception()
 
 	def drop(self):
 		"""
@@ -254,14 +259,13 @@ def drop(self):
 				try:
 					self.wait_until_stopped()
 				except pg_exc.ClusterTimeoutError:
-					w = pg_exc.ClusterWarning(
+					pg_exc.ClusterWarning(
 						'cluster failed to shutdown after kill',
 						details = {
 							'hint' : 'Shared memory may be leaked.'
-						}
-					)
-					self.ife_descend(w)
-					w.emit()
+						},
+						creator = self
+					).raise_message()
 		# Really, using rm -rf would be the best, but use this for portability.
 		for root, dirs, files in os.walk(self.data_directory, topdown = False):
 			for name in files:
@@ -307,9 +311,10 @@ def restart(self, logfile = None, settings = None, timeout = 10):
 			self.stop()
 			self.wait_until_stopped(timeout = timeout)
 		if self.running():
-			e = pg_exc.ClusterError("failed to shutdown cluster")
-			self.ife_descend(e)
-			e.raise_exception()
+			pg_exc.ClusterError(
+				"failed to shutdown cluster",
+				creator = self
+			).raise_exception()
 		self.start(logfile = logfile, settings = settings)
 		self.wait_until_started(timeout = timeout)
 
@@ -420,11 +425,10 @@ def connect(self, **kw):
 		Cluster must be running.
 		"""
 		if not self.running():
-			e = ClusterNotRunningError(
-				"cannot connect if cluster is not running"
-			)
-			self.ife_descend(e)
-			e.raise_exception()
+			ClusterNotRunningError(
+				"cannot connect if cluster is not running",
+				creator = self
+			).raise_exception()
 		return self.connection(**kw).connect()
 
 	def address(self):
@@ -469,7 +473,8 @@ def ready_for_connections(self):
 				sslmode = 'disable',
 			).close()
 		except pg_exc.ClientCannotConnectError as err:
-			for (ssltried, sockc, x) in err.connection_failures:
+			for attempt in err.database.attempt:
+				x = attempt.exception
 				if self.installation.version_info[:2] < (8,1):
 					if isinstance(x, (
 						pg_exc.UndefinedObjectError,
@@ -515,16 +520,14 @@ def wait_until_started(self,
 							details = {
 								'RESULT' : r,
 								'COMMAND' : self.daemon_command,
-							}
-						)
-						self.ife_descend(e)
-						e.raise_exception()
+							},
+							creator = self
+						).raise_exception()
 				else:
-					e = pg_exc.ClusterNotRunningError(
-						"postgresql daemon has not been started"
-					)
-					self.ife_descend(e)
-					return e.raise_exception()
+					pg_exc.ClusterNotRunningError(
+						"postgresql daemon has not been started",
+						creator = self
+					).raise_exception()
 			r = self.ready_for_connections()
 
 			checkpoint = time.time()
@@ -537,9 +540,10 @@ def wait_until_started(self,
 				# condition, rather it's *still* starting up.
 				if r is not None and isinstance(r, pg_exc.ServerNotReadyError):
 					raise r
-				e = pg_exc.ClusterTimeoutError('timeout on startup')
-				self.ife_descend(e)
-				return e.raise_exception(
+				return pg_exc.ClusterTimeoutError(
+					'timeout on startup',
+					creator = self
+				).raise_exception(
 					raise_from = r if r not in (True,False) else None
 				)
 			time.sleep(delay)
@@ -562,9 +566,10 @@ def wait_until_stopped(self,
 			if self.daemon_process is not None:
 				self.last_exit_code = self.daemon_process.poll()
 			if time.time() - start >= timeout:
-				e = pg_exc.ClusterTimeoutError('timeout on shutdown')
-				self.ife_descend(e)
-				e.raise_exception()
+				pg_exc.ClusterTimeoutError(
+					'timeout on shutdown',
+					creator = self,
+				).raise_exception()
 			time.sleep(delay)
 ##
 # vim: ts=3:sw=3:noet:

postgresql/cluster.py

@@ -216,17 +216,14 @@ class ConfigFile(pg_api.Settings):
 	Every action will cause the file to be wholly read, so using `update` to make
 	multiple changes is desirable.
 	"""
-	ife_ancestor = None
-	ife_label = 'CONFIGFILE'
+	_e_factors = ('path',)
+	_e_label = 'CONFIGFILE'
 
-	def ife_snapshot_text(self):
-		s = (os.linesep+' ').join(
-			k + ' = ' + v for k,v in self.items()
-		)
-		return self._path + (os.linesep+' ' + s if s else '')
+	def _e_metas(self):
+		yield (None, len(self.keys()))
 
 	def __init__(self, path, open = open):
-		self._path = path
+		self.path = path
 		self._open = open
 		self._store = []
 		self._restore = {}
@@ -235,22 +232,22 @@ def __repr__(self):
 		return "%s.%s(%r)" %(
 			type(self).__module__,
 			type(self).__name__,
-			self._path
+			self.path
 		)
 
 	def _save(self, lines : [str]):
-		with self._open(self._path, 'w') as cf:
+		with self._open(self.path, 'w') as cf:
 			for l in lines:
 				cf.write(l)
 
 	def __delitem__(self, k):
-		with self._open(self._path) as cf:
+		with self._open(self.path) as cf:
 			lines = alter_config({k : None}, cf)
 		self._save()
 
 	def __getitem__(self, k):
 		return read_config(
-			self._open(self._path),
+			self._open(self.path),
 			selector = k.__eq__
 		)[k]
 
@@ -282,39 +279,26 @@ def __exit__(self, exc, val, tb):
 		self._restored.clear()
 		return exc is None
 
-	def path():
-		def fget(self):
-			return pg_str.split_ident(self["search_path"])
-		def fset(self, value):
-			self['search_path'] = ','.join([
-				'"%s"' %(x.replace('"', '""'),) for x in value
-			])
-		def fdel(self):
-			self['search_path'] = None
-		doc = 'structured search_path interface'
-		return locals()
-	path = property(**path())
-
 	def get(self, k, alt = None):
 		return read_config(
-			self._open(self._path), selector = k.__eq__
+			self._open(self.path), selector = k.__eq__
 		).get(k, alt)
 
 	def keys(self):
-		return read_config(self._open(self._path)).keys()
+		return read_config(self._open(self.path)).keys()
 
 	def values(self):
-		return read_config(self._open(self._path)).values()
+		return read_config(self._open(self.path)).values()
 
 	def items(self):
-		return read_config(self._open(self._path)).items()
+		return read_config(self._open(self.path)).items()
 
 	def update(self, keyvals):
 		"""
 		Given a dictionary of settings, apply them to the cluster's
 		postgresql.conf.
 		"""
-		with self._open(self._path) as cf:
+		with self._open(self.path) as cf:
 			lines = alter_config(keyvals, cf)
 		self._save(lines)
 
@@ -325,7 +309,7 @@ def getset(self, keys):
 		"""
 		keys = set(keys)
 		cfg = read_config(
-			self._open(self._path),
+			self._open(self.path),
 			selector = keys.__contains__
 		)
 		for x in (keys - set(cfg.keys())):

postgresql/configfile.py

@@ -285,10 +285,9 @@ def close(self):
 		if self.database.closed:
 			err = Error(
 				"connection already closed",
-				source = 'DRIVER',
-			)
-			self.database.ife_descend(err)
-			err.raise_exception()
+				source = 'CLIENT',
+				creator = self.database
+			).raise_exception()
 		self.database.close()
 
 	def cursor(self):
@@ -298,13 +297,12 @@ def commit(self):
 		if self._xact is None:
 			err = InterfaceError(
 				"commit on connection in autocommit mode",
-				source = 'DRIVER',
+				source = 'CLIENT',
 				details = {
 					'hint': 'The "autocommit" property on the connection was set to True.'
-				}
-			)
-			self.database.ife_descend(err)
-			err.raise_exception()
+				},
+				creator = self.database
+			).raise_exception()
 		self._xact.commit()
 		self._xact = self.database.xact()
 		self._xact.start()
@@ -316,10 +314,9 @@ def rollback(self):
 				source = 'DRIVER',
 				details = {
 					'hint': 'The "autocommit" property on the connection was set to True.'
-				}
-			)
-			self.database.ife_descend(err)
-			err.raise_exception()
+				},
+				creator = self.database
+			).raise_exception()
 		self._xact.rollback()
 		self._xact = self.database.xact()
 		self._xact.start()