From: Mike Bayer Date: Sat, 21 Oct 2006 21:55:18 +0000 (+0000) Subject: docstrings X-Git-Tag: rel_0_3_0~16 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b78c493702cd01d3c027852e9d9493e612686009;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git docstrings --- diff --git a/doc/build/read_markdown.py b/doc/build/read_markdown.py index a427361ec1..a7f5090968 100644 --- a/doc/build/read_markdown.py +++ b/doc/build/read_markdown.py @@ -12,7 +12,10 @@ def dump_tree(elem, stream): if elem.tag.startswith('MYGHTY:'): dump_myghty_tag(elem, stream) else: - stream.write("<%s %s>" % (elem.tag, " ".join(["%s=%s" % (key, repr(val)) for key, val in elem.attrib.iteritems()]))) + if len(elem.attrib): + stream.write("<%s %s>" % (elem.tag, " ".join("%s=%s" % (key, repr(val)) for key, val in elem.attrib.iteritems()))) + else: + stream.write("<%s>" % elem.tag) if elem.text: stream.write(elem.text) for child in elem: diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index cea363116b..c18da2005b 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -34,70 +34,103 @@ def _relation_loader(mapper, secondary=None, primaryjoin=None, secondaryjoin=Non return properties.PropertyLoader(mapper, secondary, primaryjoin, secondaryjoin, lazy=lazy, **kwargs) def backref(name, **kwargs): + """create a BackRef object with explicit arguments, which are the same arguments one + can send to relation(). + + used with the "backref" keyword argument to relation() in place + of a string argument. """ return properties.BackRef(name, **kwargs) def deferred(*columns, **kwargs): """return a DeferredColumnProperty, which indicates this object attributes should only be loaded - from its corresponding table column when first accessed.""" + from its corresponding table column when first accessed. + + used with the 'properties' dictionary sent to mapper().""" return properties.ColumnProperty(deferred=True, *columns, **kwargs) def mapper(class_, table=None, *args, **params): - """return a new Mapper object.""" + """return a new Mapper object. + + See the Mapper class for a description of arguments.""" return Mapper(class_, table, *args, **params) def synonym(name, proxy=False): - """set up 'name' as a synonym to another MapperProperty.""" + """set up 'name' as a synonym to another MapperProperty. + + Used with the 'properties' dictionary sent to mapper().""" return properties.SynonymProperty(name, proxy=proxy) def clear_mappers(): - """remove all mappers that have been created thus far. when new mappers are - created, they will be assigned to their classes as their primary mapper.""" + """remove all mappers that have been created thus far. + + when new mappers are created, they will be assigned to their classes as their primary mapper.""" mapper_registry.clear() def clear_mapper(m): - """remove the given mapper from the storage of mappers. when a new mapper is - created for the previous mapper's class, it will be used as that classes' + """remove the given mapper from the storage of mappers. + + when a new mapper is created for the previous mapper's class, it will be used as that classes' new primary mapper.""" del mapper_registry[m.class_key] def eagerload(name): """return a MapperOption that will convert the property of the given name - into an eager load.""" + into an eager load. + + used with query.options().""" return strategies.EagerLazyOption(name, lazy=False) def lazyload(name): """return a MapperOption that will convert the property of the given name - into a lazy load""" + into a lazy load. + + used with query.options().""" return strategies.EagerLazyOption(name, lazy=True) def noload(name): """return a MapperOption that will convert the property of the given name - into a non-load.""" + into a non-load. + + used with query.options().""" return strategies.EagerLazyOption(name, lazy=None) def contains_eager(key, decorator=None): + """return a MapperOption that will indicate to the query that the given + attribute will be eagerly loaded without any row decoration, or using + a custom row decorator. + + used when feeding SQL result sets directly into + query.instances().""" return strategies.RowDecorateOption(key, decorator=decorator) def defer(name): - """returns a MapperOption that will convert the column property of the given - name into a deferred load. Used with mapper.options()""" + """return a MapperOption that will convert the column property of the given + name into a deferred load. + + used with query.options()""" return strategies.DeferredOption(name, defer=True) def undefer(name): - """returns a MapperOption that will convert the column property of the given - name into a non-deferred (regular column) load. Used with mapper.options.""" + """return a MapperOption that will convert the column property of the given + name into a non-deferred (regular column) load. + + used with query.options().""" return strategies.DeferredOption(name, defer=False) - - def cascade_mappers(*classes_or_mappers): - """given a list of classes and/or mappers, identifies the foreign key relationships + """attempt to create a series of relations() between mappers automatically, via + introspecting the foreign key relationships of the underlying tables. + + given a list of classes and/or mappers, identifies the foreign key relationships between the given mappers or corresponding class mappers, and creates relation() objects representing those relationships, including a backreference. Attempts to find the "secondary" table in a many-to-many relationship as well. The names of the relations will be a lowercase version of the related class. In the case of one-to-many or many-to-many, the name will be "pluralized", which currently is based on the English language (i.e. an 's' or - 'es' added to it).""" + 'es' added to it). + + NOTE: this method usually works poorly, and its usage is generally not advised. + """ table_to_mapper = {} for item in classes_or_mappers: if isinstance(item, Mapper): diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 87c276368e..ba3f019b07 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -1206,18 +1206,24 @@ class MapperExtension(object): Mapper functions. For each method in MapperExtension, a result of EXT_PASS indicates the functionality is not overridden.""" def get_session(self): - """called to retrieve a contextual Session instance with which to - register a new object. Note: this is not called if a session is - provided with the __init__ params (i.e. _sa_session)""" + """retrieve a contextual Session instance with which to register a new object. + + Note: this is not called if a session is provided with the __init__ params (i.e. _sa_session)""" return EXT_PASS def select_by(self, query, *args, **kwargs): - """overrides the select_by method of the Query object""" + """override the select_by method of the Query object. + + the return value of this method is used as the result of query.select_by() if the + value is anything other than EXT_PASS.""" return EXT_PASS def select(self, query, *args, **kwargs): - """overrides the select method of the Query object""" + """override the select method of the Query object. + + the return value of this method is used as the result of query.select() if the + value is anything other than EXT_PASS.""" return EXT_PASS def create_instance(self, mapper, selectcontext, row, class_): - """called when a new object instance is about to be created from a row. + """receieve a row when a new object instance is about to be created from that row. the method can choose to create the instance itself, or it can return None to indicate normal object creation should take place. @@ -1231,10 +1237,11 @@ class MapperExtension(object): """ return EXT_PASS def append_result(self, mapper, selectcontext, row, instance, identitykey, result, isnew): - """called when an object instance is being appended to a result list. + """receive an object instance before that instance is appended to a result list. - If this method returns EXT_PASS, it is assumed that the mapper should do the appending, else - if this method returns any other value or None, it is assumed that the append was handled by this method. + If this method returns EXT_PASS, result appending will proceed normally. + if this method returns any other value or None, result appending will not proceed for + this instance, giving this extension an opportunity to do the appending itself, if desired. mapper - the mapper doing the operation @@ -1254,37 +1261,42 @@ class MapperExtension(object): """ return EXT_PASS def populate_instance(self, mapper, selectcontext, row, instance, identitykey, isnew): - """called right before the mapper, after creating an instance from a row, passes the row - to its MapperProperty objects which are responsible for populating the object's attributes. - If this method returns EXT_PASS, it is assumed that the mapper should do the appending, else - if this method returns any other value or None, it is assumed that the append was handled by this method. + """receive a newly-created instance before that instance has its attributes populated. - Essentially, this method is used to have a different mapper populate the object: + The normal population of attributes is according to each + attribute's corresponding MapperProperty (which includes column-based attributes as well + as relationships to other classes). If this method returns EXT_PASS, instance population + will proceed normally. If any other value or None is returned, instance population + will not proceed, giving this extension an opportunity to populate the instance itself, + if desired.. + + A common usage of this method is to have population performed by an alternate mapper. This can + be acheived via the populate_instance() call on Mapper. def populate_instance(self, mapper, selectcontext, instance, row, identitykey, isnew): othermapper.populate_instance(selectcontext, instance, row, identitykey, isnew, frommapper=mapper) - return True + return None """ return EXT_PASS def before_insert(self, mapper, connection, instance): - """called before an object instance is INSERTed into its table. + """receive an object instance before that instance is INSERTed into its table. this is a good place to set up primary key values and such that arent handled otherwise.""" return EXT_PASS def before_update(self, mapper, connection, instance): - """called before an object instnace is UPDATED""" + """receive an object instance before that instance is UPDATEed.""" return EXT_PASS def after_update(self, mapper, connection, instance): - """called after an object instnace is UPDATED""" + """receive an object instance after that instance is UPDATEed.""" return EXT_PASS def after_insert(self, mapper, connection, instance): - """called after an object instance has been INSERTed""" + """receive an object instance after that instance is INSERTed.""" return EXT_PASS def before_delete(self, mapper, connection, instance): - """called before an object instance is DELETEed""" + """receive an object instance before that instance is DELETEed.""" return EXT_PASS def after_delete(self, mapper, connection, instance): - """called after an object instance is DELETEed""" + """receive an object instance after that instance is DELETEed.""" return EXT_PASS class _ExtensionCarrier(MapperExtension):