From 33aeec5d7ff91bf1850f5175e10dbc6d51012d05 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 4 Dec 2005 20:34:21 +0000 Subject: [PATCH] docstrings, formatting fixes --- doc/build/components/formatting.myt | 4 +-- doc/build/components/pydoc.myt | 1 + doc/build/content/docstrings.myt | 2 +- lib/sqlalchemy/ansisql.py | 2 +- lib/sqlalchemy/mapping/properties.py | 6 ++-- lib/sqlalchemy/schema.py | 6 ++-- lib/sqlalchemy/sql.py | 49 ++++++++++++++-------------- 7 files changed, 36 insertions(+), 34 deletions(-) diff --git a/doc/build/components/formatting.myt b/doc/build/components/formatting.myt index e22a7fd15b..6f92cc8089 100644 --- a/doc/build/components/formatting.myt +++ b/doc/build/components/formatting.myt @@ -190,8 +190,8 @@ <%method formatplain> <%filter> import re - f = re.sub(r'(.+)\n\n',r"

\1

",f, re.S) - f = re.sub(r'\n', r'
\n', f, re.S) + f = re.sub(r'\n[\s\t]*\n[\s\t]*', '

\n

', f, re.S) + f = "

" + f + "

" return f <% m.content() %> diff --git a/doc/build/components/pydoc.myt b/doc/build/components/pydoc.myt index 5cb58628b9..4f0b554e00 100644 --- a/doc/build/components/pydoc.myt +++ b/doc/build/components/pydoc.myt @@ -1,6 +1,7 @@ <%global> import re def format_paragraphs(text): + return text return re.sub(r'([\w ])\n([\w ])', r'\1 \2', text or '', re.S) diff --git a/doc/build/content/docstrings.myt b/doc/build/content/docstrings.myt index 24f6e52c4e..4dd5aa9826 100644 --- a/doc/build/content/docstrings.myt +++ b/doc/build/content/docstrings.myt @@ -12,7 +12,7 @@ <& pydoc.myt:obj_doc, obj=schema &> <& pydoc.myt:obj_doc, obj=engine, classes=[engine.SQLEngine, engine.ResultProxy, engine.RowProxy] &> -<& pydoc.myt:obj_doc, obj=sql &> +<& pydoc.myt:obj_doc, obj=sql, classes=[sql.Compiled, sql.ClauseElement, sql.TableImpl, sql.ColumnImpl] &> <& pydoc.myt:obj_doc, obj=pool, classes=[pool.DBProxy, pool.Pool, pool.QueuePool, pool.SingletonThreadPool] &> <& pydoc.myt:obj_doc, obj=mapping &> <& pydoc.myt:obj_doc, obj=mapping.objectstore, classes=[mapping.objectstore.UnitOfWork] &> diff --git a/lib/sqlalchemy/ansisql.py b/lib/sqlalchemy/ansisql.py index 2a709e3b75..691106a710 100644 --- a/lib/sqlalchemy/ansisql.py +++ b/lib/sqlalchemy/ansisql.py @@ -284,7 +284,7 @@ class ANSICompiler(sql.Compiled): def visit_join(self, join): # TODO: ppl are going to want RIGHT, FULL OUTER and NATURAL joins. righttext = self.get_from_text(join.right) - if join.right.group_parenthesized(): + if join.right._group_parenthesized(): righttext = "(" + righttext + ")" if join.isouter: self.froms[join] = (self.get_from_text(join.left) + " LEFT OUTER JOIN " + righttext + diff --git a/lib/sqlalchemy/mapping/properties.py b/lib/sqlalchemy/mapping/properties.py index fdce0c0e88..5c037f0c55 100644 --- a/lib/sqlalchemy/mapping/properties.py +++ b/lib/sqlalchemy/mapping/properties.py @@ -176,11 +176,11 @@ class PropertyLoader(MapperProperty): crit = [] for fk in secondary.foreign_keys: if fk.references(primary): - crit.append(primary.get_col_by_original(fk.column) == fk.parent) + crit.append(primary._get_col_by_original(fk.column) == fk.parent) self.foreignkey = fk.parent for fk in primary.foreign_keys: if fk.references(secondary): - crit.append(secondary.get_col_by_original(fk.column) == fk.parent) + crit.append(secondary._get_col_by_original(fk.column) == fk.parent) self.foreignkey = fk.parent if len(crit) == 0: raise "Cant find any foreign key relationships between '%s' (%s) and '%s' (%s)" % (primary.name, repr(primary), secondary.name, repr(secondary)) @@ -588,7 +588,7 @@ class EagerLoader(PropertyLoader): statement.order_by(self.eagertarget.rowid_column) if self.order_by is not None: - statement.order_by(*[self.eagertarget.get_col_by_original(c) for c in self.order_by]) + statement.order_by(*[self.eagertarget._get_col_by_original(c) for c in self.order_by]) statement.append_from(statement._outerjoin) statement.append_column(self.eagertarget) diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index bebf38efed..789bb6ed8c 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -87,7 +87,9 @@ class TableSingleton(type): class Table(SchemaItem): - """represents a relational database table.""" + """represents a relational database table. + + Be sure to look at sqlalchemy.sql.TableImpl for additional methods defined on a Table.""" __metaclass__ = TableSingleton def __init__(self, name, engine, *args, **kwargs): @@ -249,7 +251,7 @@ class ForeignKey(SchemaItem): self.column.table is table or # test for an indirect relation via a Selectable - table.get_col_by_original(self.column) is not None + table._get_col_by_original(self.column) is not None ) def _init_column(self): diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py index a5ff50900e..71cbacdac0 100644 --- a/lib/sqlalchemy/sql.py +++ b/lib/sqlalchemy/sql.py @@ -54,6 +54,8 @@ def join(left, right, onclause, **kwargs): def select(columns=None, whereclause = None, from_obj = [], **kwargs): """returns a SELECT clause element. + this can also be called via the table's select() method. + 'columns' is a list of columns and/or selectable items to select columns from 'whereclause' is a text or ClauseElement expression which will form the WHERE clause 'from_obj' is an list of additional "FROM" objects, such as Join objects, which will @@ -64,9 +66,12 @@ def select(columns=None, whereclause = None, from_obj = [], **kwargs): return Select(columns, whereclause = whereclause, from_obj = from_obj, **kwargs) def insert(table, values = None, **kwargs): - """returns an INSERT clause element. + """returns an INSERT clause element. + + This can also be called from a table directly via the table's insert() method. 'table' is the table to be inserted into. + 'values' is a dictionary which specifies the column specifications of the INSERT, and is optional. If left as None, the column specifications are determined from the bind parameters used during the compile phase of the INSERT statement. If the @@ -84,7 +89,9 @@ def insert(table, values = None, **kwargs): return Insert(table, values, **kwargs) def update(table, whereclause = None, values = None, **kwargs): - """returns an UPDATE clause element. + """returns an UPDATE clause element. + + This can also be called from a table directly via the table's update() method. 'table' is the table to be updated. 'whereclause' is a ClauseElement describing the WHERE condition of the UPDATE statement. @@ -107,6 +114,8 @@ def update(table, whereclause = None, values = None, **kwargs): def delete(table, whereclause = None, **kwargs): """returns a DELETE clause element. + This can also be called from a table directly via the table's delete() method. + 'table' is the table to be updated. 'whereclause' is a ClauseElement describing the WHERE condition of the UPDATE statement. """ @@ -253,15 +262,7 @@ class Compiled(ClauseVisitor): return self.execute(*multiparams, **params).fetchone()[0] class ClauseElement(object): - """base class for elements of a programmatically constructed SQL expression. - - includes a list of 'from objects' which collects items to be placed - in the FROM clause of a SQL statement. - - when many ClauseElements are attached together, the from objects and bind - parameters are scooped up into the enclosing-most ClauseElement. - """ - + """base class for elements of a programmatically constructed SQL expression.""" def hash_key(self): """returns a string that uniquely identifies the concept this ClauseElement represents. @@ -287,6 +288,7 @@ class ClauseElement(object): if asfrom: data[self.id] = self def accept_visitor(self, visitor): + """accepts a ClauseVisitor and calls the appropriate visit_xxx method.""" raise NotImplementedError(repr(self)) def copy_container(self): @@ -629,7 +631,7 @@ class Selectable(FromClause): def select(self, whereclauses = None, **params): return select([self], whereclauses, **params) - def get_col_by_original(self, column): + def _get_col_by_original(self, column): """given a column which is a schema.Column object attached to a schema.Table object (i.e. an "original" column), return the Column object from this Selectable which corresponds to that original Column, or None if this Selectable @@ -644,7 +646,7 @@ class Selectable(FromClause): def alias(self, name): return Alias(self, name) - def group_parenthesized(self): + def _group_parenthesized(self): """indicates if this Selectable requires parenthesis when grouped into a compound statement""" return True @@ -668,12 +670,12 @@ class Join(Selectable): primary_key = property (lambda self: [c for c in self.left.columns if c.primary_key] + [c for c in self.right.columns if c.primary_key]) - def group_parenthesized(self): + def _group_parenthesized(self): """indicates if this Selectable requires parenthesis when grouped into a compound statement""" return True - def get_col_by_original(self, column): + def _get_col_by_original(self, column): for c in self.columns: if c.original is column: return c @@ -730,7 +732,7 @@ class Alias(Selectable): def hash_key(self): return "Alias(%s, %s)" % (repr(self.selectable.hash_key()), repr(self.name)) - def get_col_by_original(self, column): + def _get_col_by_original(self, column): return self.columns.get(column.key, None) def accept_visitor(self, visitor): @@ -740,7 +742,7 @@ class Alias(Selectable): def _get_from_objects(self): return [self] - def group_parenthesized(self): + def _group_parenthesized(self): return False engine = property(lambda s: s.selectable.engine) @@ -808,13 +810,13 @@ class ColumnImpl(Selectable, CompareMixin): def copy_container(self): return self.column - def get_col_by_original(self, column): + def _get_col_by_original(self, column): if self.column.original is column: return self.column else: return None - def group_parenthesized(self): + def _group_parenthesized(self): return False def _get_from_objects(self): @@ -846,12 +848,9 @@ class TableImpl(Selectable): rowid_column = property(lambda s: s._rowid_column) - def get_from_text(self): - return self.table.name - engine = property(lambda s: s.table.engine) - def get_col_by_original(self, column): + def _get_col_by_original(self, column): try: col = self.columns[column.key] except KeyError: @@ -861,7 +860,7 @@ class TableImpl(Selectable): else: return None - def group_parenthesized(self): + def _group_parenthesized(self): return False def _process_from_dict(self, data, asfrom): @@ -1024,7 +1023,7 @@ class Select(Selectable, TailClauseMixin): else: co._make_proxy(self) - def get_col_by_original(self, column): + def _get_col_by_original(self, column): if self.use_labels: return self.columns.get(column.label,None) else: -- 2.47.2