From: Mike Bayer Date: Sun, 30 Sep 2012 15:13:52 +0000 (-0400) Subject: - commit Priit Laes docstring fixes X-Git-Tag: rel_0_8_0b1~99 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=74461bab1967acb1da4a04a5ee0e1085fe64e83b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - commit Priit Laes docstring fixes - don't even talk about metadata.bind in declarative --- diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index c3989dc8a5..82319af27c 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -1169,8 +1169,8 @@ This behavior can be disabled using the ``cascade_backrefs`` flag:: So above, the assignment of ``i1.order = o1`` will append ``i1`` to the ``items`` collection of ``o1``, but will not add ``i1`` to the session. You can, of -course, :func:`~.Session.add` ``i1`` to the session at a later point. This option -may be helpful for situations where an object needs to be kept out of a +course, :meth:`~.Session.add` ``i1`` to the session at a later point. This +option may be helpful for situations where an object needs to be kept out of a session until it's construction is completed, but still needs to be given associations to objects which are already persistent in the target session. @@ -1344,9 +1344,8 @@ goes back into "autocommit" mode, until :meth:`.Session.begin` is called again:: session.rollback() raise -The :func:`.Session.begin` method also returns a -transactional token which is compatible with the Python 2.6 ``with`` -statement:: +The :meth:`.Session.begin` method also returns a transactional token which is +compatible with the Python 2.6 ``with`` statement:: Session = sessionmaker(bind=engine, autocommit=True) session = Session() diff --git a/lib/sqlalchemy/ext/declarative/__init__.py b/lib/sqlalchemy/ext/declarative/__init__.py index 4849a58dcc..b3cecf6b07 100644 --- a/lib/sqlalchemy/ext/declarative/__init__.py +++ b/lib/sqlalchemy/ext/declarative/__init__.py @@ -30,8 +30,7 @@ As a simple example:: Above, the :func:`declarative_base` callable returns a new base class from which all mapped classes should inherit. When the class definition is -completed, a new :class:`.Table` and -:func:`.mapper` will have been generated. +completed, a new :class:`.Table` and :func:`.mapper` will have been generated. The resulting table and mapper are accessible via ``__table__`` and ``__mapper__`` attributes on the @@ -60,13 +59,13 @@ just give the column a name. Below, column "some_table_id" is mapped to the Attributes may be added to the class after its construction, and they will be added to the underlying :class:`.Table` and -:func:`.mapper()` definitions as appropriate:: +:func:`.mapper` definitions as appropriate:: SomeClass.data = Column('data', Unicode) SomeClass.related = relationship(RelatedInfo) Classes which are constructed using declarative can interact freely -with classes that are mapped explicitly with :func:`mapper`. +with classes that are mapped explicitly with :func:`.mapper`. It is recommended, though not required, that all tables share the same underlying :class:`~sqlalchemy.schema.MetaData` object, @@ -86,16 +85,6 @@ CREATE statements for all tables:: engine = create_engine('sqlite://') Base.metadata.create_all(engine) -The usual techniques of associating :class:`.MetaData:` with :class:`.Engine` -apply, such as assigning to the ``bind`` attribute:: - - Base.metadata.bind = create_engine('sqlite://') - -To associate the engine with the :func:`declarative_base` at time -of construction, the ``bind`` argument is accepted:: - - Base = declarative_base(bind=create_engine('sqlite://')) - :func:`declarative_base` can also receive a pre-existing :class:`.MetaData` object, which allows a declarative setup to be associated with an already @@ -212,9 +201,9 @@ the :class:`.MetaData` object used by the declarative base:: id = Column(Integer, primary_key=True) keywords = relationship("Keyword", secondary=keywords) -Like other :func:`.relationship` arguments, a string is accepted as well, -passing the string name of the table as defined in the ``Base.metadata.tables`` -collection:: +Like other :func:`~sqlalchemy.orm.relationship` arguments, a string is accepted +as well, passing the string name of the table as defined in the +``Base.metadata.tables`` collection:: class Author(Base): __tablename__ = 'authors' @@ -223,7 +212,7 @@ collection:: As with traditional mapping, its generally not a good idea to use a :class:`.Table` as the "secondary" argument which is also mapped to -a class, unless the :class:`.relationship` is declared with ``viewonly=True``. +a class, unless the :func:`.relationship` is declared with ``viewonly=True``. Otherwise, the unit-of-work system may attempt duplicate INSERT and DELETE statements against the underlying table. @@ -865,7 +854,7 @@ Mixing in Relationships Relationships created by :func:`~sqlalchemy.orm.relationship` are provided with declarative mixin classes exclusively using the -:func:`.declared_attr` approach, eliminating any ambiguity +:class:`.declared_attr` approach, eliminating any ambiguity which could arise when copying a relationship and its possibly column-bound contents. Below is an example which combines a foreign key column and a relationship so that two classes ``Foo`` and ``Bar`` can both be configured to @@ -1109,7 +1098,7 @@ In the case of ``__table_args__`` or ``__mapper_args__`` specified with declarative mixins, you may want to combine some parameters from several mixins with those you wish to define on the class iteself. The -:func:`.declared_attr` decorator can be used +:class:`.declared_attr` decorator can be used here to create user-defined collation routines that pull from multiple collections:: @@ -1231,7 +1220,7 @@ Sessions Note that ``declarative`` does nothing special with sessions, and is only intended as an easier way to configure mappers and :class:`~sqlalchemy.schema.Table` objects. A typical application -setup using :func:`~sqlalchemy.orm.scoped_session` might look like:: +setup using :class:`~sqlalchemy.orm.scoped_session` might look like:: engine = create_engine('postgresql://scott:tiger@localhost/test') Session = scoped_session(sessionmaker(autocommit=False, diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py index e827bc5b88..3c4a0e5d86 100644 --- a/lib/sqlalchemy/orm/scoping.py +++ b/lib/sqlalchemy/orm/scoping.py @@ -49,8 +49,8 @@ class scoped_session(object): :param \**kw: Keyword arguments will be passed to the session factory callable, if an existing :class:`.Session` is not present. If the :class:`.Session` is present and - keyword arguments have been passed, :class:`.InvalidRequestError` - is raised. + keyword arguments have been passed, + :exc:`~sqlalchemy.exc.InvalidRequestError` is raised. """ if kw: diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 5e5cf2246a..9b0c31e6a9 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -442,7 +442,7 @@ class Session(_SessionClassMethods): query_cls=query.Query): """Construct a new Session. - See also the :func:`.sessionmaker` function which is used to + See also the :class:`.sessionmaker` function which is used to generate a :class:`.Session`-producing callable with a given set of arguments. @@ -640,13 +640,13 @@ class Session(_SessionClassMethods): """Flush pending changes and commit the current transaction. If no transaction is in progress, this method raises an - InvalidRequestError. + :exc:`~sqlalchemy.exc.InvalidRequestError`. By default, the :class:`.Session` also expires all database loaded state on all ORM-managed attributes after transaction commit. This so that subsequent operations load the most recent data from the database. This behavior can be disabled using - the ``expire_on_commit=False`` option to :func:`.sessionmaker` or + the ``expire_on_commit=False`` option to :class:`.sessionmaker` or the :class:`.Session` constructor. If a subtransaction is in effect (which occurs when begin() is called @@ -671,10 +671,11 @@ class Session(_SessionClassMethods): """Prepare the current transaction in progress for two phase commit. If no transaction is in progress, this method raises an - InvalidRequestError. + :exc:`~sqlalchemy.exc.InvalidRequestError`. Only root transactions of two phase sessions can be prepared. If the - current transaction is not such, an InvalidRequestError is raised. + current transaction is not such, an + :exc:`~sqlalchemy.exc.InvalidRequestError` is raised. """ if self.transaction is None: @@ -978,7 +979,7 @@ class Session(_SessionClassMethods): linked to the :class:`.MetaData` ultimately associated with the :class:`.Table` or other selectable to which the mapper is mapped. - 6. No bind can be found, :class:`.UnboundExecutionError` + 6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError` is raised. :param mapper: @@ -1599,7 +1600,7 @@ class Session(_SessionClassMethods): """Associate an object with this :class:`.Session` for related object loading. - Accesses of attributes mapped with :class:`.relationship` + Accesses of attributes mapped with :func:`.relationship` will attempt to load a value from the database using this :class:`.Session` as the source of connectivity. The values will be loaded based on foreign key values present on this