From 30e4b186f2f9ec00eb9b9fbab4463894a730f57f Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 22 Sep 2010 23:48:17 -0400 Subject: [PATCH] doc edits --- doc/build/core/expression_api.rst | 2 ++ doc/build/core/tutorial.rst | 10 ++++++---- doc/build/orm/mapper_config.rst | 4 ++-- doc/build/orm/relationships.rst | 2 ++ doc/build/orm/tutorial.rst | 6 ++++-- lib/sqlalchemy/orm/query.py | 13 ++++++++----- lib/sqlalchemy/orm/session.py | 9 +++++---- lib/sqlalchemy/sql/expression.py | 23 +++++++++++++---------- 8 files changed, 42 insertions(+), 27 deletions(-) diff --git a/doc/build/core/expression_api.rst b/doc/build/core/expression_api.rst index c01f84c2cb..c39701a596 100644 --- a/doc/build/core/expression_api.rst +++ b/doc/build/core/expression_api.rst @@ -1,3 +1,5 @@ +.. _expression_api_toplevel: + SQL Statements and Expressions ============================== diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index 23190a143c..bf39201981 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -1187,12 +1187,14 @@ Finally, a delete. Easy enough: Further Reference ================== -API docs: :mod:`sqlalchemy.sql.expression` +Expression Language Reference: :ref:`expression_api_toplevel` -Table Metadata Reference: :ref:`metadata_toplevel` +Database Metadata Reference: :ref:`metadata_toplevel` -Engine/Connection/Execution Reference: :ref:`engines_toplevel` +Engine Reference: :ref:`engines_toplevel` -SQL Types: :ref:`types` +Connection Reference: :ref:`connections_toplevel` + +Types Reference: :ref:`types_toplevel` diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst index 574646ca77..15377436fa 100644 --- a/doc/build/orm/mapper_config.rst +++ b/doc/build/orm/mapper_config.rst @@ -1,7 +1,7 @@ -.. _mapper_config_toplevel: - .. module:: sqlalchemy.orm +.. _mapper_config_toplevel: + Mapper Configuration ==================== diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst index 3428473288..f9337a5f63 100644 --- a/doc/build/orm/relationships.rst +++ b/doc/build/orm/relationships.rst @@ -1,5 +1,7 @@ .. module:: sqlalchemy.orm +.. _relationship_config_toplevel: + Relationship Configuration ========================== diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 6f38a35c90..1ac212961d 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -1436,6 +1436,8 @@ Further Reference Query Reference: :ref:`query_api_toplevel` -Further information on mapping setups are in :ref:`datamapping_toplevel`. +Mapper Reference: :ref:`mapper_config_toplevel` -Further information on working with Sessions: :ref:`session_toplevel`. +Relationship Reference: :ref:`relationship_config_toplevel` + +Session Reference: :ref:`session_toplevel`. diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index cba3e7619c..2d3f61da7e 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -498,7 +498,12 @@ class Query(object): @property def whereclause(self): - """The WHERE criterion for this Query.""" + """A readonly attribute which returns the current WHERE criterion for this Query. + + This returned value is a SQL expression construct, or ``None`` if no + criterion has been established. + + """ return self._criterion @_generative() @@ -2028,8 +2033,7 @@ class Query(object): Also, the ``before_delete()`` and ``after_delete()`` :class:`~sqlalchemy.orm.interfaces.MapperExtension` methods are not called from this method. For a delete hook here, use the - ``after_bulk_delete()`` - :class:`~sqlalchemy.orm.interfaces.MapperExtension` method. + :meth:`.SessionExtension.after_bulk_delete()` event hook. """ #TODO: lots of duplication and ifs - probably needs to be @@ -2154,8 +2158,7 @@ class Query(object): Also, the ``before_update()`` and ``after_update()`` :class:`~sqlalchemy.orm.interfaces.MapperExtension` methods are not called from this method. For an update hook here, use the - ``after_bulk_update()`` - :class:`~sqlalchemy.orm.interfaces.SessionExtension` method. + :meth:`.SessionExtension.after_bulk_update()` event hook. """ diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index d97ef87e76..95d29812e5 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -106,13 +106,13 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False, The full resolution is described in the ``get_bind()`` method of ``Session``. Usage looks like:: - sess = Session(binds={ + Session = sessionmaker(binds={ SomeMappedClass: create_engine('postgresql://engine1'), somemapper: create_engine('postgresql://engine2'), some_table: create_engine('postgresql://engine3'), }) - Also see the ``bind_mapper()`` and ``bind_table()`` methods. + Also see the :meth:`.Session.bind_mapper` and :meth:`.Session.bind_table` methods. :param \class_: Specify an alternate class other than ``sqlalchemy.orm.session.Session`` which should be used by the returned @@ -143,8 +143,9 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False, as returned by the ``query()`` method. Defaults to :class:`~sqlalchemy.orm.query.Query`. - :param twophase: When ``True``, all transactions will be started using - :mod:`~sqlalchemy.engine_TwoPhaseTransaction`. During a ``commit()``, + :param twophase: When ``True``, all transactions will be started as + a "two phase" transaction, i.e. using the "two phase" semantics + of the database in use along with an XID. During a ``commit()``, after ``flush()`` has been issued for all attached databases, the ``prepare()`` method on each database's ``TwoPhaseTransaction`` will be called. This allows each database to roll back the entire diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py index 5df3b87943..ed561bbeb2 100644 --- a/lib/sqlalchemy/sql/expression.py +++ b/lib/sqlalchemy/sql/expression.py @@ -3924,16 +3924,21 @@ class Select(_SelectBaseMixin, FromClause): return self._get_display_froms() @_generative - def with_hint(self, selectable, text, dialect_name=None): + def with_hint(self, selectable, text, dialect_name='*'): """Add an indexing hint for the given selectable to this :class:`Select`. - The text of the hint is written specific to a specific backend, and - typically uses Python string substitution syntax to render the name - of the table or alias, such as for Oracle:: + The text of the hint is rendered in the appropriate + location for the database backend in use, relative + to the given :class:`.Table` or :class:`.Alias` passed as the + *selectable* argument. The dialect implementation + typically uses Python string substitution syntax + with the token ``%(name)s`` to render the name of + the table or alias. E.g. when using Oracle, the + following:: - select([mytable]).with_hint(mytable, "+ index(%(name)s - ix_mytable)") + select([mytable]).\\ + with_hint(mytable, "+ index(%(name)s ix_mytable)") Would render SQL as:: @@ -3943,13 +3948,11 @@ class Select(_SelectBaseMixin, FromClause): hint to a particular backend. Such as, to add hints for both Oracle and Sybase simultaneously:: - select([mytable]).\ - with_hint(mytable, "+ index(%(name)s ix_mytable)", 'oracle').\ + select([mytable]).\\ + with_hint(mytable, "+ index(%(name)s ix_mytable)", 'oracle').\\ with_hint(mytable, "WITH INDEX ix_mytable", 'sybase') """ - if not dialect_name: - dialect_name = '*' self._hints = self._hints.union({(selectable, dialect_name):text}) @property -- 2.47.2