From cebb673af18dfa245176fba7328a2fcfcd401bee Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 28 Mar 2007 00:23:39 +0000 Subject: [PATCH] some more docstring patches for [ticket:214] --- lib/sqlalchemy/orm/session.py | 88 +++++++++++++++++++++++------------ lib/sqlalchemy/orm/util.py | 14 ++++-- lib/sqlalchemy/sql.py | 24 ++++++---- 3 files changed, 81 insertions(+), 45 deletions(-) diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 51d850d3c1..86d61c7c9e 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -271,74 +271,100 @@ class Session(object): if e is None: raise exceptions.InvalidRequestError("Could not locate any Engine bound to mapper '%s'" % str(mapper)) return e + def query(self, mapper_or_class, entity_name=None, **kwargs): - """return a new Query object corresponding to this Session and the mapper, or the classes' primary mapper.""" + """Return a new Query object corresponding to this Session and + the mapper, or the classes' primary mapper. + """ + if isinstance(mapper_or_class, type): return query.Query(_class_mapper(mapper_or_class, entity_name=entity_name), self, **kwargs) else: return query.Query(mapper_or_class, self, **kwargs) + def _sql(self): class SQLProxy(object): def __getattr__(self, key): def call(*args, **kwargs): kwargs[engine] = self.engine return getattr(sql, key)(*args, **kwargs) - + sql = property(_sql) - + def flush(self, objects=None): - """flush all the object modifications present in this session to the database. - - 'objects' is a list or tuple of objects specifically to be flushed; if None, all - new and modified objects are flushed.""" + """Flush all the object modifications present in this session + to the database. + + `objects` is a list or tuple of objects specifically to be + flushed; if None, all new and modified objects are flushed. + """ + self.uow.flush(self, objects) def get(self, class_, ident, **kwargs): - """return an instance of the object based on the given identifier, or None if not found. - - The ident argument is a scalar or tuple of primary key column values in the order of the - table def's primary key columns. - - the entity_name keyword argument may also be specified which further qualifies the underlying - Mapper used to perform the query.""" + """Return an instance of the object based on the given + identifier, or None if not found. + + The `ident` argument is a scalar or tuple of primary key + column values in the order of the table def's primary key + columns. + + The `entity_name` keyword argument may also be specified which + further qualifies the underlying Mapper used to perform the + query. + """ + entity_name = kwargs.get('entity_name', None) return self.query(class_, entity_name=entity_name).get(ident) - + def load(self, class_, ident, **kwargs): - """return an instance of the object based on the given identifier. - - If not found, raises an exception. The method will *remove all pending changes* to the object - already existing in the Session. The ident argument is a scalar or tuple of - primary key columns in the order of the table def's primary key columns. - - the entity_name keyword argument may also be specified which further qualifies the underlying - Mapper used to perform the query.""" + """Return an instance of the object based on the given + identifier. + + If not found, raises an exception. The method will **remove + all pending changes** to the object already existing in the + Session. The `ident` argument is a scalar or tuple of primary + key columns in the order of the table def's primary key + columns. + + The `entity_name` keyword argument may also be specified which + further qualifies the underlying Mapper used to perform the + query. + """ + entity_name = kwargs.get('entity_name', None) return self.query(class_, entity_name=entity_name).load(ident) def refresh(self, obj): - """reload the attributes for the given object from the database, clear any changes made.""" + """Reload the attributes for the given object from the + database, clear any changes made. + """ + self._validate_persistent(obj) if self.query(obj.__class__)._get(obj._instance_key, reload=True) is None: raise exceptions.InvalidRequestError("Could not refresh instance '%s'" % repr(obj)) def expire(self, obj): - """mark the given object as expired. - - this will add an instrumentation to all mapped attributes on the instance such that when - an attribute is next accessed, the session will reload all attributes on the instance - from the database. + """Mark the given object as expired. + + This will add an instrumentation to all mapped attributes on + the instance such that when an attribute is next accessed, the + session will reload all attributes on the instance from the + database. """ + for c in [obj] + list(_object_mapper(obj).cascade_iterator('refresh-expire', obj)): self._expire_impl(c) - + def _expire_impl(self, obj): self._validate_persistent(obj) + def exp(): if self.query(obj.__class__)._get(obj._instance_key, reload=True) is None: raise exceptions.InvalidRequestError("Could not refresh instance '%s'" % repr(obj)) + attribute_manager.trigger_history(obj, exp) - + def is_expired(self, obj, unexpire=False): """Return True if the given object has been marked as expired.""" diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index d1ae9f7968..cb62eab530 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -19,20 +19,24 @@ class CascadeOptions(object): self.merge = "merge" in values or "all" in values self.expunge = "expunge" in values or "all" in values self.refresh_expire = "refresh-expire" in values or "all" in values - + for x in values: if x not in all_cascades: raise exceptions.ArgumentError("Invalid cascade option '%s'" % x) - + def __contains__(self, item): return getattr(self, item.replace("-", "_"), False) + def __repr__(self): return "CascadeOptions(arg=%s)" % repr(",".join([x for x in ['delete', 'save_update', 'merge', 'expunge', 'delete_orphan', 'refresh-expire'] if getattr(self, x, False) is True])) def polymorphic_union(table_map, typecolname, aliasname='p_union'): - """create a UNION statement used by a polymorphic mapper. - - See the SQLAlchemy advanced mapping docs for an example of how this is used.""" + """Create a ``UNION`` statement used by a polymorphic mapper. + + See the SQLAlchemy advanced mapping docs for an example of how + this is used. + """ + colnames = util.Set() colnamemaps = {} types = {} diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py index 74f085cb1a..849dfe1d12 100644 --- a/lib/sqlalchemy/sql.py +++ b/lib/sqlalchemy/sql.py @@ -421,6 +421,7 @@ class _FunctionGateway(object): if name[-1] == '_': name = name[0:-1] return getattr(_FunctionGenerator(), name) + func = _FunctionGateway() def _compound_clause(keyword, *clauses): @@ -435,7 +436,6 @@ def _is_literal(element): def is_column(col): return isinstance(col, ColumnElement) - class AbstractDialect(object): """Represent the behavior of a particular database. @@ -678,7 +678,6 @@ class Compiled(ClauseVisitor): return self.execute(*multiparams, **params).scalar() - class ClauseElement(object): """Base class for elements of a programmatically constructed SQL expression. @@ -769,7 +768,9 @@ class ClauseElement(object): else: return None - engine = property(lambda s: s._find_engine(), doc="Attempts to locate a Engine within this ClauseElement structure, or returns None if none found.") + engine = property(lambda s: s._find_engine(), + doc="""Attempts to locate a Engine within this ClauseElement + structure, or returns None if none found.""") def execute(self, *multiparams, **params): """Compile and execute this ``ClauseElement``.""" @@ -1663,9 +1664,10 @@ class _Exists(_BooleanExpression): kwargs['correlate'] = True s = select(*args, **kwargs) _BooleanExpression.__init__(self, _TextClause("EXISTS"), s, None) + def _hide_froms(self): return self._get_from_objects() - + class Join(FromClause): def __init__(self, left, right, onclause=None, isouter = False): self.left = left._selectable() @@ -2156,7 +2158,11 @@ class Select(_SelectBaseMixin, FromClause): well as the ability to execute itself and return a result set. """ - def __init__(self, columns=None, whereclause = None, from_obj = [], order_by = None, group_by=None, having=None, use_labels = False, distinct=False, for_update=False, engine=None, limit=None, offset=None, scalar=False, correlate=True): + def __init__(self, columns=None, whereclause=None, from_obj=[], + order_by=None, group_by=None, having=None, + use_labels=False, distinct=False, for_update=False, + engine=None, limit=None, offset=None, scalar=False, + correlate=True): _SelectBaseMixin.__init__(self) self.__froms = util.OrderedSet() self.__hide_froms = util.Set([self]) @@ -2192,7 +2198,6 @@ class Select(_SelectBaseMixin, FromClause): self.__correlator = Select._CorrelatedVisitor(self, False) self.__wherecorrelator = Select._CorrelatedVisitor(self, True) - if columns is not None: for c in columns: self.append_column(c) @@ -2207,7 +2212,6 @@ class Select(_SelectBaseMixin, FromClause): for f in from_obj: self.append_from(f) - # whereclauses must be appended after the columns/FROM, since it affects # the correlation of subqueries. see test/sql/select.py SelectTest.testwheresubquery if whereclause is not None: @@ -2232,9 +2236,11 @@ class Select(_SelectBaseMixin, FromClause): for s in cs.selects: s.parens = False - def visit_column(self, c):pass + def visit_column(self, c): + pass - def visit_table(self, c):pass + def visit_table(self, c): + pass def visit_select(self, select): if select is self.select: -- 2.47.2