make migrate.schema.ansisql PEP8 clean and add some sphinx docstrings

migrate/changeset/ansisql.py

@@ -1,43 +1,60 @@
 """
-Module :mod:`migrate.changeset.ansisql`
----------------------------------------
-
    Extensions to SQLAlchemy for altering existing tables.
-At the moment, this isn't so much based off of ANSI as much as things that just
+
-happen to work with multiple databases.
+   At the moment, this isn't so much based off of ANSI as much as
+   things that just happen to work with multiple databases.
 """
 import sqlalchemy as sa
 from sqlalchemy.engine.base import Connection, Dialect
 from sqlalchemy.sql.compiler import SchemaGenerator
+from sqlalchemy.schema import ForeignKeyConstraint
 from migrate.changeset import constraint, exceptions
 
 SchemaIterator = sa.engine.SchemaIterator
 
+
 class RawAlterTableVisitor(object):
-    """Common operations for 'alter table' statements"""
+    """Common operations for ``ALTER TABLE`` statements."""
+
     def _to_table(self, param):
+        """Returns the table object for the given param object."""
         if isinstance(param, (sa.Column, sa.Index, sa.schema.Constraint)):
             ret = param.table
         else:
             ret = param
         return ret
+
     def _to_table_name(self, param):
+        """Returns the table name for the given param object."""
         ret = self._to_table(param)
         if isinstance(ret, sa.Table):
             ret = ret.fullname
         return ret
 
     def _do_quote_table_identifier(self, identifier):
+        """Returns a quoted version of the given table identifier."""
         return '"%s"'%identifier
 
     def start_alter_table(self, param):
+        """Returns the start of an ``ALTER TABLE`` SQL-Statement.
+
+        Use the param object to determine the table name and use it
+        for building the SQL statement.
+
+        :param param: object to determine the table from. This may be
+          a :class:`sqlalchemy.Column`, an :class:`sqlalchemy.Index`,
+          a :class:`sqlachemy.schema.Constraint`, a
+          :class:`sqlalchemy.Table` or a table name string
+        """
         table = self._to_table(param)
         table_name = self._to_table_name(table)
-        self.append('\nALTER TABLE %s ' % self._do_quote_table_identifier(table_name))
+        self.append('\nALTER TABLE %s ' % \
+                        self._do_quote_table_identifier(table_name))
         return table
 
     def _pk_constraint(self, table, column, status):
-        """Create a primary key constraint from a table, column
+        """Create a primary key constraint from a table, column.
+
         Status: true if the constraint is being added; false if being dropped
         """
         if isinstance(column, basestring):
@@ -59,12 +76,11 @@ class RawAlterTableVisitor(object):
             ret.name = pk
         return ret
 
+
 class AlterTableVisitor(SchemaIterator, RawAlterTableVisitor):
     """Common operations for 'alter table' statements"""
 
 
-from sqlalchemy.schema import ForeignKeyConstraint
-    
 class ANSIColumnGenerator(AlterTableVisitor, SchemaGenerator):
     """Extends ansisql generator for column creation (alter table add col)"""
     #def __init__(self, *args, **kwargs):
@@ -96,38 +112,44 @@ class ANSIColumnGenerator(AlterTableVisitor,SchemaGenerator):
 #        else:
         self.execute()
 
-
     def visit_table(self, table):
         pass
 
+
 class ANSIColumnDropper(AlterTableVisitor):
-    """Extends ansisql dropper for column dropping (alter table drop col)"""
+    """Extends ANSI SQL dropper for column dropping (``ALTER TABLE
+    DROP COLUMN``)."""
+
     def visit_column(self, column):
         """Drop a column; #33"""
         table = self.start_alter_table(column)
-        self.append(' DROP COLUMN %s'%self._do_quote_column_identifier(column.name))
+        self.append(' DROP COLUMN %s' % \
+                        self._do_quote_column_identifier(column.name))
         self.execute()
         #if column.primary_key:
         #    cons = self._pk_constraint(table,column,False)
         #    cons.create()
 
+
 class ANSISchemaChanger(AlterTableVisitor, SchemaGenerator):
     """Manages changes to existing schema elements.
-    Note that columns are schema elements; "alter table add column" is in
+
-    SchemaGenerator.
+    Note that columns are schema elements; ``ALTER TABLE ADD COLUMN``
+    is in SchemaGenerator.
 
     All items may be renamed. Columns can also have many of their properties -
     type, for example - changed.
 
-    Each function is passed a tuple, containing (object,name); where object 
+    Each function is passed a tuple, containing (object,name); where
-    is a type of object you'd expect for that function (ie. table for
+    object is a type of object you'd expect for that function
-    visit_table) and name is the object's new name. NONE means the name is
+    (ie. table for visit_table) and name is the object's new
-    unchanged.
+    name. NONE means the name is unchanged.
     """
 
     def _do_quote_column_identifier(self, identifier):
-        """override this function to define how identifiers (table and column names) should be written in the sql.
+        """override this function to define how identifiers (table and
-        for instance, in postgres, double quotes should surround the identifier
+        column names) should be written in the SQL.  For instance, in
+        PostgreSQL, double quotes should surround the identifier
         """
         return identifier
 
@@ -147,7 +169,8 @@ class ANSISchemaChanger(AlterTableVisitor,SchemaGenerator):
         if 'nullable' in keys:
             self._run_subvisit(delta, self._visit_column_nullable)
         if 'server_default' in keys:
-            # Skip 'default': only handle server-side defaults, others are managed by the app, not the db.
+            # Skip 'default': only handle server-side defaults, others
+            # are managed by the app, not the db.
             self._run_subvisit(delta, self._visit_column_default)
         #if 'primary_key' in keys:
         #    #self._run_subvisit(delta,self._visit_column_primary_key)
@@ -156,6 +179,7 @@ class ANSISchemaChanger(AlterTableVisitor,SchemaGenerator):
         #    self._visit_column_foreign_key(delta)
         if 'name' in keys:
             self._run_subvisit(delta, self._visit_column_name)
+
     def _run_subvisit(self, delta, func, col_name=None, table_name=None):
         if table_name is None:
             table_name = self._to_table(delta.table)
@@ -178,6 +202,7 @@ class ANSISchemaChanger(AlterTableVisitor,SchemaGenerator):
             column_foreign_key = None
         cons.drop()
         cons.create()
+
     def _visit_column_primary_key(self, delta):
         table = delta.table
         col = getattr(table.c, delta.current_name)
@@ -185,26 +210,31 @@ class ANSISchemaChanger(AlterTableVisitor,SchemaGenerator):
         cons = self._pk_constraint(table, col, pk)
         cons.drop()
         cons.create()
+
     def _visit_column_nullable(self, table_name, col_name, delta):
         nullable = delta['nullable']
         table = self._to_table(delta)
         self.start_alter_table(table_name)
-        self.append("ALTER COLUMN %s "%self._do_quote_column_identifier(col_name))
+        self.append("ALTER COLUMN %s " % \
+                        self._do_quote_column_identifier(col_name))
         if nullable:
             self.append("DROP NOT NULL")
         else:
             self.append("SET NOT NULL")
+
     def _visit_column_default(self, table_name, col_name, delta):
         server_default = delta['server_default']
         # Dummy column: get_col_default_string needs a column for some reason
         dummy = sa.Column(None, None, server_default=server_default)
         default_text = self.get_column_default_string(dummy)
         self.start_alter_table(table_name)
-        self.append("ALTER COLUMN %s "%self._do_quote_column_identifier(col_name))
+        self.append("ALTER COLUMN %s " % \
+                        self._do_quote_column_identifier(col_name))
         if default_text is not None:
             self.append("SET DEFAULT %s"%default_text)
         else:
             self.append("DROP DEFAULT")
+
     def _visit_column_type(self, table_name, col_name, delta):
         type = delta['type']
         if not isinstance(type, sa.types.AbstractType):
@@ -213,11 +243,16 @@ class ANSISchemaChanger(AlterTableVisitor,SchemaGenerator):
         #type_text = type.engine_impl(self.engine).get_col_spec()
         type_text = type.dialect_impl(self.dialect).get_col_spec()
         self.start_alter_table(table_name)
-        self.append("ALTER COLUMN %s TYPE %s"%(self._do_quote_column_identifier(col_name),type_text))
+        self.append("ALTER COLUMN %s TYPE %s" % \
+                        (self._do_quote_column_identifier(col_name),
+                         type_text))
+
     def _visit_column_name(self, table_name, col_name, delta):
         new_name = delta['name']
         self.start_alter_table(table_name)
-        self.append('RENAME COLUMN %s TO %s'%(self._do_quote_column_identifier(col_name), self._do_quote_column_identifier(new_name)))
+        self.append('RENAME COLUMN %s TO %s' % \
+                        (self._do_quote_column_identifier(col_name),
+                         self._do_quote_column_identifier(new_name)))
 
     def visit_index(self, param):
         """Rename an index; #36"""
@@ -230,10 +265,11 @@ class ANSISchemaChanger(AlterTableVisitor,SchemaGenerator):
 
 class ANSIConstraintCommon(AlterTableVisitor):
     """
-    Migrate's constraints require a separate creation function from SA's: 
+    Migrate's constraints require a separate creation function from
-    Migrate's constraints are created independently of a table; SA's are
+    SA's: Migrate's constraints are created independently of a table;
-    created at the same time as the table.
+    SA's are created at the same time as the table.
     """
+
     def get_constraint_name(self, cons):
         if cons.name is not None:
             ret = cons.name
@@ -241,7 +277,9 @@ class ANSIConstraintCommon(AlterTableVisitor):
             ret = cons.name = cons.autoname()
         return ret
 
+
 class ANSIConstraintGenerator(ANSIConstraintCommon):
+
     def get_constraint_specification(self, cons, **kwargs):
         if isinstance(cons, constraint.PrimaryKeyConstraint):
             col_names = ','.join([i.name for i in cons.columns])
@@ -263,6 +301,7 @@ class ANSIConstraintGenerator(ANSIConstraintCommon):
         else:
             raise exceptions.InvalidConstraintError(cons)
         return ret
+
     def _visit_constraint(self, constraint):
         table = self.start_alter_table(constraint)
         self.append("ADD ")
@@ -279,7 +318,9 @@ class ANSIConstraintGenerator(ANSIConstraintCommon):
     def visit_migrate_check_constraint(self, *p, **k):
         return self._visit_constraint(*p, **k)
 
+
 class ANSIConstraintDropper(ANSIConstraintCommon):
+
     def _visit_constraint(self, constraint):
         self.start_alter_table(constraint)
         self.append("DROP CONSTRAINT ")
@@ -295,8 +336,10 @@ class ANSIConstraintDropper(ANSIConstraintCommon):
     def visit_migrate_check_constraint(self, *p, **k):
         return self._visit_constraint(*p, **k)
 
+
 class ANSIFKGenerator(AlterTableVisitor, SchemaGenerator):
     """Extends ansisql generator for column creation (alter table add col)"""
+
     def __init__(self, *args, **kwargs):
         self.fk = kwargs.get('fk', None)
         if self.fk:
@@ -315,6 +358,7 @@ class ANSIFKGenerator(AlterTableVisitor,SchemaGenerator):
     def visit_table(self, table):
         pass
 
+
 class ANSIDialect(object):
     columngenerator = ANSIColumnGenerator
     columndropper = ANSIColumnDropper
@@ -324,5 +368,6 @@ class ANSIDialect(object):
     @classmethod
     def visitor(self, name):
         return getattr(self, name)
+
     def reflectconstraints(self, connection, table_name):
         raise NotImplementedError()