From: Mike Bayer Date: Mon, 25 Jun 2007 03:47:29 +0000 (+0000) Subject: docstring cleanup, removal of some ORM cruft X-Git-Tag: rel_0_4_6~178 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4cc6c4f4fca2236124ba0f426da534bd59cab4e2;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git docstring cleanup, removal of some ORM cruft --- diff --git a/doc/build/read_markdown.py b/doc/build/read_markdown.py index 35df7a5ce7..acd23915ee 100644 --- a/doc/build/read_markdown.py +++ b/doc/build/read_markdown.py @@ -1,10 +1,12 @@ """loads Markdown files, converts each one to HTML and parses the HTML into an ElementTree structure. The collection of ElementTrees are further parsed to generate a table of contents structure, and are - manipulated to replace various markdown-generated HTML with specific Myghty tags before being written - to Myghty templates, which then re-access the table of contents structure at runtime. + manipulated to replace various markdown-generated HTML with specific Mako tags before being written + to Mako templates, which then re-access the table of contents structure at runtime. Much thanks to Alexey Shamrin, who came up with the original idea and did all the heavy Markdown/Elementtree -lifting for this module.""" +lifting for this module. +""" + import sys, re, os from toc import TOCElement diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py index 0255a922d2..29695fb1f4 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -207,22 +207,29 @@ class MapperProperty(object): """ def setup(self, querycontext, **kwargs): - """Called when a statement is being constructed.""" + """Called by Query for the purposes of constructing a SQL statement. + + Each MapperProperty associated with the target mapper processes the + statement referenced by the query context, adding columns and/or + criterion as appropriate. + """ pass def create_row_processor(self, selectcontext, mapper, row): - """return a tuple of a row processing and an instance post-processing function. + """return a 2-tuple consiting of a row processing function and an instance post-processing function. Input arguments are the query.SelectionContext and the *first* applicable row of a result set obtained within query.Query.instances(), called - the first time mapper.populate_instance() is invoked for a particular - result, and only once per result. - - By looking at the columns present within the row, MapperProperty - returns two callables which will be used to process all rows and instances. + only the first time a particular mapper.populate_instance() is invoked for the + overal result. + + The settings contained within the SelectionContext as well as the columns present + in the row (which will be the same columns present in all rows) are used to determine + the behavior of the returned callables. The callables will then be used to process + all rows and to post-process all instances, respectively. - callables are of the following form: + callables are of the following form:: def execute(instance, row, **flags): # process incoming instance and given row. @@ -239,15 +246,22 @@ class MapperProperty(object): return (execute, post_execute) - either tuple value can also be None in which case no function is called. + either tuple value can also be ``None`` in which case no function is called. """ + raise NotImplementedError() def cascade_iterator(self, type, object, recursive=None, halt_on=None): + """return an iterator of objects which are child objects of the given object, + as attached to the attribute corresponding to this MapperProperty.""" + return [] def cascade_callable(self, type, object, callable_, recursive=None, halt_on=None): + """run the given callable across all objects which are child objects of + the given object, as attached to the attribute corresponding to this MapperProperty.""" + return [] def get_criterion(self, query, key, value): @@ -267,9 +281,6 @@ class MapperProperty(object): def set_parent(self, parent): self.parent = parent - def get_sub_mapper(self): - raise NotImplementedError() - def init(self, key, parent): """Called after all mappers are compiled to assemble relationships between mappers, establish instrumented class @@ -280,7 +291,11 @@ class MapperProperty(object): self.do_init() def do_init(self): - """Template method for subclasses.""" + """Perform subclass-specific initialization steps. + + This is a *template* method called by the + ``MapperProperty`` object's init() method.""" + pass def register_dependencies(self, *args, **kwargs): @@ -324,9 +339,9 @@ class StrategizedProperty(MapperProperty): """A MapperProperty which uses selectable strategies to affect loading behavior. - There is a single default strategy selected, and alternate - strategies can be selected at selection time through the usage of - ``StrategizedOption`` objects. + There is a single default strategy selected by default. Alternate + strategies can be selected at Query time through the usage of + ``StrategizedOption`` objects via the Query.options() method. """ def _get_context_strategy(self, context): @@ -405,9 +420,6 @@ class SynonymProperty(MapperProperty): def setup(self, querycontext, **kwargs): pass - def get_sub_mapper(self): - return self.parent.props[self.name].get_sub_mapper() - def create_row_processor(self, selectcontext, mapper, row): return (None, None) @@ -527,4 +539,5 @@ class LoaderStrategy(object): StrategizedProperty delegates its create_row_processor method directly to this method. """ + raise NotImplementedError() diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py index 79fa101d25..78830b7409 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -40,9 +40,6 @@ class ColumnProperty(StrategizedProperty): else: return strategies.ColumnLoader(self) - def get_sub_mapper(self): - return None - def getattr(self, object): return getattr(object, self.key) @@ -61,8 +58,6 @@ class ColumnProperty(StrategizedProperty): ColumnProperty.logger = logging.class_logger(ColumnProperty) mapper.ColumnProperty = ColumnProperty - - class PropertyLoader(StrategizedProperty): """Describes an object property that holds a single item or list @@ -116,9 +111,6 @@ class PropertyLoader(StrategizedProperty): private = property(lambda s:s.cascade.delete_orphan) - def get_sub_mapper(self): - return self.mapper - def create_strategy(self): if self.lazy: return strategies.LazyLoader(self) diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 0fb8939c93..5a2e04c7b5 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -717,7 +717,7 @@ class Query(object): def count(self, whereclause=None, params=None, **kwargs): """Apply this query's criterion to a SELECT COUNT statement. - the whereclause, params and **kwargs arguments are deprecated. use filter() + the whereclause, params and \**kwargs arguments are deprecated. use filter() and other generative methods to establish modifiers. """ @@ -878,7 +878,7 @@ class Query(object): return self.filter(self._legacy_join_by(args, kwargs, start=self._joinpoint)) def count_by(self, *args, **params): - """DEPRECATED. use query.filter_by(**params).count()""" + """DEPRECATED. use query.filter_by(\**params).count()""" return self.count(self.join_by(*args, **params)) @@ -911,7 +911,7 @@ class Query(object): def get_by(self, *args, **params): - """DEPRECATED. use query.filter(*args).filter_by(**params).first()""" + """DEPRECATED. use query.filter_by(\**params).first()""" ret = self._extension.get_by(self, *args, **params) if ret is not mapper.EXT_PASS: @@ -920,7 +920,7 @@ class Query(object): return self._legacy_filter_by(*args, **params).first() def select_by(self, *args, **params): - """DEPRECATED. use use query.filter(*args).filter_by(**params).all().""" + """DEPRECATED. use use query.filter_by(\**params).all().""" ret = self._extension.select_by(self, *args, **params) if ret is not mapper.EXT_PASS: @@ -1060,12 +1060,12 @@ class Query(object): return [keys, p] def selectfirst_by(self, *args, **params): - """DEPRECATED. Use query.filter(*args).filter_by(**kwargs).first()""" + """DEPRECATED. Use query.filter_by(\**kwargs).first()""" return self._legacy_filter_by(*args, **params).first() def selectone_by(self, *args, **params): - """DEPRECATED. Use query.filter(*args).filter_by(**kwargs).one()""" + """DEPRECATED. Use query.filter_by(\**kwargs).one()""" return self._legacy_filter_by(*args, **params).one() diff --git a/lib/sqlalchemy/orm/strategies.py b/lib/sqlalchemy/orm/strategies.py index b4a66a6dc3..9d78c0e7cc 100644 --- a/lib/sqlalchemy/orm/strategies.py +++ b/lib/sqlalchemy/orm/strategies.py @@ -242,7 +242,6 @@ class LazyLoader(AbstractRelationLoader): if self.use_get: self.logger.info(str(self.parent_property) + " will use query.get() to optimize instance loads") - def init_class_attribute(self): self._register_attribute(self.parent.class_, callable_=lambda i: self.setup_loader(i)) @@ -319,7 +318,6 @@ class LazyLoader(AbstractRelationLoader): return lazyload - def create_row_processor(self, selectcontext, mapper, row): if not self.is_default or len(selectcontext.options): def execute(instance, row, isnew, **flags): @@ -543,12 +541,6 @@ class EagerLoader(AbstractRelationLoader): EagerRowAdapter.map = map return EagerRowAdapter - def _decorate_row(self, row): - # adapts a row at row iteration time to transparently - # convert plain columns into the aliased columns that were actually - # added to the column clause of the SELECT. - return self._row_decorator(row) - def init_class_attribute(self): self.parent_property._get_strategy(LazyLoader).init_class_attribute() @@ -650,7 +642,6 @@ class EagerLoader(AbstractRelationLoader): self.logger.debug("could not locate identity key from row '%s'; missing column '%s'" % (repr(decorated_row), str(k))) return None - def create_row_processor(self, selectcontext, mapper, row): row_decorator = self._create_row_decorator(selectcontext, row) if row_decorator is not None: @@ -723,8 +714,12 @@ class EagerLazyOption(StrategizedOption): EagerLazyOption.logger = logging.class_logger(EagerLazyOption) - - +# TODO: enable FetchMode option. currently +# this class does nothing. will require Query +# to swich between using its "polymorphic" selectable +# and its regular selectable in order to make decisions +# (therefore might require that FetchModeOperation is performed +# only as the first operation on a Query.) class FetchModeOption(PropertyOption): def __init__(self, key, type): super(FetchModeOption, self).__init__(key) @@ -755,4 +750,3 @@ class RowDecorateOption(PropertyOption): RowDecorateOption.logger = logging.class_logger(RowDecorateOption) - diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py index a7b88d158f..65874fbb43 100644 --- a/lib/sqlalchemy/sql.py +++ b/lib/sqlalchemy/sql.py @@ -950,8 +950,12 @@ class ClauseElement(object): __metaclass__ = _FigureVisitName def _clone(self): - # shallow copy. mutator operations always create - # clones of container objects. + """create a shallow copy of this ClauseElement. + + This method may be used by a generative API. + Its also used as part of the "deep" copy afforded + by a traversal that combines the copy_internals() + method.""" c = self.__class__.__new__(self.__class__) c.__dict__ = self.__dict__.copy() return c