text: """Provides an abstraction for obtaining database schema information.
  
  Usage Notes:
  
  Here are some general conventions when accessing the low level inspector
  methods such as get_table_names, get_columns, etc.
  
  1. Inspector methods return lists of dicts in most cases for the following
     reasons:
  
     * They're both standard types that can be serialized.
     * Using a dict instead of a tuple allows easy expansion of attributes.
     * Using a list for the outer structure maintains order and is easy to work
       with (e.g. list comprehension [d['name'] for d in cols]).
  
  2. Records that contain a name, such as the column name in a column record
     use the key 'name'. So for most return values, each record will have a
     'name' attribute..
  """
  
  import sqlalchemy
  from sqlalchemy import exc, sql
  from sqlalchemy import util
  from sqlalchemy.types import TypeEngine
  from sqlalchemy import schema as sa_schema
  
  
  @util.decorator
  def cache(fn, self, con, *args, **kw):
      info_cache = kw.get('info_cache', None)
      if info_cache is None:
          return fn(self, con, *args, **kw)
      key = (
              fn.__name__, 
              tuple(a for a in args if isinstance(a, basestring)), 
              tuple((k, v) for k, v in kw.iteritems() if isinstance(v, (basestring, int, float)))
          )
      ret = info_cache.get(key)
      if ret is None:
          ret = fn(self, con, *args, **kw)
          info_cache[key] = ret
      return ret
  
  
  class Inspector(object):
      """Performs database schema inspection.
  
      The Inspector acts as a proxy to the dialects' reflection methods and
      provides higher level functions for accessing database schema information.
      """
  
      def __init__(self, conn):
          """Initialize the instance.
  
          :param conn: a :class:`~sqlalchemy.engine.base.Connectable`
          """
  
          self.conn = conn
          # set the engine
          if hasattr(conn, 'engine'):
              self.engine = conn.engine
          else:
              self.engine = conn
          self.dialect = self.engine.dialect
          self.info_cache = {}
  
      @classmethod
      def from_engine(cls, engine):
          if hasattr(engine.dialect, 'inspector'):
              return engine.dialect.inspector(engine)
          return Inspector(engine)
  
      @property
      def default_schema_name(self):
          return self.dialect.default_schema_name
  
      def get_schema_names(self):
          """Return all schema names.
          """
  
          if hasattr(self.dialect, 'get_schema_names'):
              return self.dialect.get_schema_names(self.conn,
                                                      info_cache=self.info_cache)
          return []
  
      def get_table_names(self, schema=None, order_by=None):
          """Return all table names in `schema`.
  
          :param schema: Optional, retrieve names from a non-default schema.
          :param order_by: Optional, may be the string "foreign_key" to sort
                           the result on foreign key dependencies.
  
          This should probably not return view names or maybe it should return
          them with an indicator t or v.
          """
  
          if hasattr(self.dialect, 'get_table_names'):
              tnames = self.dialect.get_table_names(self.conn,
              schema,
                                                      info_cache=self.info_cache)
          else:
              tnames = self.engine.table_names(schema)
          if order_by == 'foreign_key':
              ordered_tnames = tnames[:]
              # Order based on foreign key dependencies.
              for tname in tnames:
                  table_pos = tnames.index(tname)
                  fkeys = self.get_foreign_keys(tname, schema)
                  for fkey in fkeys:
                      rtable = fkey['referred_table']
                      if rtable in ordered_tnames:
                          ref_pos = ordered_tnames.index(rtable)
                          # Make sure it's lower in the list than anything it
                          # references.
                          if table_pos > ref_pos:
                              ordered_tnames.pop(table_pos) # rtable moves up 1
                              # insert just below rtable
                              ordered_tnames.index(ref_pos, tname)
              tnames = ordered_tnames
          return tnames
  
      def get_table_options(self, table_name, schema=None, **kw):
          if hasattr(self.dialect, 'get_table_options'):
              return self.dialect.get_table_options(self.conn, table_name, schema,
                                                    info_cache=self.info_cache,
                                                    **kw)
          return {}
  
      def get_view_names(self, schema=None):
          """Return all view names in `schema`.
  
          :param schema: Optional, retrieve names from a non-default schema.
          """
  
          return self.dialect.get_view_names(self.conn, schema,
                                                    info_cache=self.info_cache)
  
      def get_view_definition(self, view_name, schema=None):
          """Return definition for `view_name`.
  
          :param schema: Optional, retrieve names from a non-default schema.
          """
  
          return self.dialect.get_view_definition(
              self.conn, view_name, schema, info_cache=self.info_cache)
  
      def get_columns(self, table_name, schema=None, **kw):
          """Return information about columns in `table_name`.
  
          Given a string `table_name` and an optional string `schema`, return
          column information as a list of dicts with these keys:
  
          name
            the column's name
  
          type
            :class:`~sqlalchemy.types.TypeEngine`
  
          nullable
            boolean
  
          default
            the column's default value
  
          attrs
            dict containing optional column attributes
          """
  
          col_defs = self.dialect.get_columns(self.conn, table_name, schema,
                                              info_cache=self.info_cache,
                                              **kw)
          for col_def in col_defs:
              # make this easy and only return instances for coltype
              coltype = col_def['type']
              if not isinstance(coltype, TypeEngine):
                  col_def['type'] = coltype()
          return col_defs
  
      def get_primary_keys(self, table_name, schema=None, **kw):
          """Return information about primary keys in `table_name`.
  
          Given a string `table_name`, and an optional string `schema`, return
          primary key information as a list of column names.
          """
  
          pkeys = self.dialect.get_primary_keys(self.conn, table_name, schema,
                                                info_cache=self.info_cache,
                                                **kw)
  
          return pkeys
  
      def get_foreign_keys(self, table_name, schema=None, **kw):
          """Return information about foreign_keys in `table_name`.
  
          Given a string `table_name`, and an optional string `schema`, return
          foreign key information as a list of dicts with these keys:
  
          constrained_columns
            a list of column names that make up the foreign key
  
          referred_schema
            the name of the referred schema
  
          referred_table
            the name of the referred table
  
          referred_columns
            a list of column names in the referred table that correspond to
            constrained_columns
  
          \**kw
            other options passed to the dialect's get_foreign_keys() method.
  
          """
  
          fk_defs = self.dialect.get_foreign_keys(self.conn, table_name, schema,
                                                  info_cache=self.info_cache,
                                                  **kw)
          return fk_defs
  
      def get_indexes(self, table_name, schema=None, **kw):
          """Return information about indexes in `table_name`.
  
          Given a string `table_name` and an optional string `schema`, return
          index information as a list of dicts with these keys:
  
          name
            the index's name
  
          column_names
            list of column names in order
  
          unique
            boolean
            
          \**kw
            other options passed to the dialect's get_indexes() method.
          """
  
          indexes = self.dialect.get_indexes(self.conn, table_name,
                                                    schema,
                                              info_cache=self.info_cache, **kw)
          return indexes
  
      def reflecttable(self, table, include_columns):
  
          dialect = self.conn.dialect
  
          # MySQL dialect does this.  Applicable with other dialects?
          if hasattr(dialect, '_connection_charset') \
                                          and hasattr(dialect, '_adjust_casing'):
              charset = dialect._connection_charset
              dialect._adjust_casing(table)
  
          # table attributes we might need.
          reflection_options = dict(
              (k, table.kwargs.get(k)) for k in dialect.reflection_options if k in table.kwargs)
  
          schema = table.schema
          table_name = table.name
  
          # apply table options
          tbl_opts = self.get_table_options(table_name, schema, **table.kwargs)
          if tbl_opts:
              table.kwargs.update(tbl_opts)
  
          # table.kwargs will need to be passed to each reflection method.  Make
          # sure keywords are strings.
          tblkw = table.kwargs.copy()
          for (k, v) in tblkw.items():
              del tblkw[k]
              tblkw[str(k)] = v
  
          # Py2K
          if isinstance(schema, str):
              schema = schema.decode(dialect.encoding)
          if isinstance(table_name, str):
              table_name = table_name.decode(dialect.encoding)
          # end Py2K
  
          # columns
          found_table = False
          for col_d in self.get_columns(table_name, schema, **tblkw):
              found_table = True
              name = col_d['name']
              if include_columns and name not in include_columns:
                  continue
  
              coltype = col_d['type']
              col_kw = {
                  'nullable':col_d['nullable'],
              }
              if 'autoincrement' in col_d:
                  col_kw['autoincrement'] = col_d['autoincrement']
              if 'quote' in col_d:
                  col_kw['quote'] = col_d['quote']
                  
              colargs = []
              if col_d.get('default') is not None:
                  # the "default" value is assumed to be a literal SQL expression,
                  # so is wrapped in text() so that no quoting occurs on re-issuance.
                  colargs.append(sa_schema.DefaultClause(sql.text(col_d['default'])))
                  
              if 'sequence' in col_d:
                  # TODO: mssql, maxdb and sybase are using this.
                  seq = col_d['sequence']
                  sequence = sa_schema.Sequence(seq['name'], 1, 1)
                  if 'start' in seq:
                      sequence.start = seq['start']
                  if 'increment' in seq:
                      sequence.increment = seq['increment']
                  colargs.append(sequence)
                  
              col = sa_schema.Column(name, coltype, *colargs, **col_kw)
              table.append_column(col)
  
          if not found_table:
              raise exc.NoSuchTableError(table.name)
  
          # Primary keys
          primary_key_constraint = sa_schema.PrimaryKeyConstraint(*[
              table.c[pk] for pk in self.get_primary_keys(table_name, schema, **tblkw)
              if pk in table.c
          ])
  
          table.append_constraint(primary_key_constraint)
  
          # Foreign keys
          fkeys = self.get_foreign_keys(table_name, schema, **tblkw)
          for fkey_d in fkeys:
              conname = fkey_d['name']
              constrained_columns = fkey_d['constrained_columns']
              referred_schema = fkey_d['referred_schema']
              referred_table = fkey_d['referred_table']
              referred_columns = fkey_d['referred_columns']
              refspec = []
              if referred_schema is not None:
                  sa_schema.Table(referred_table, table.metadata,
                                  autoload=True, schema=referred_schema,
                                  autoload_with=self.conn,
                                  **reflection_options
                                  )
                  for column in referred_columns:
                      refspec.append(".".join(
                          [referred_schema, referred_table, column]))
              else:
                  sa_schema.Table(referred_table, table.metadata, autoload=True,
                                  autoload_with=self.conn,
                                  **reflection_options
                                  )
                  for column in referred_columns:
                      refspec.append(".".join([referred_table, column]))
              table.append_constraint(
                  sa_schema.ForeignKeyConstraint(constrained_columns, refspec,
                                                 conname, link_to_name=True))
          # Indexes 
          indexes = self.get_indexes(table_name, schema)
          for index_d in indexes:
              name = index_d['name']
              columns = index_d['column_names']
              unique = index_d['unique']
              flavor = index_d.get('type', 'unknown type')
              if include_columns and \
                              not set(columns).issubset(include_columns):
                  util.warn(
                      "Omitting %s KEY for (%s), key covers omitted columns." %
                      (flavor, ', '.join(columns)))
                  continue
              sa_schema.Index(name, *[table.columns[c] for c in columns], 
                           **dict(unique=unique))
  