From: aplatkouski <5857672+aplatkouski@users.noreply.github.com>
Date: Thu, 4 Jun 2020 20:51:15 +0000 (+0300)
Subject: Fix typos in documentation - Using the Session
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d682383d1511c23c35311895d222849b0f91133f;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Fix typos in documentation - Using the Session

Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com>
---

diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst
index f0cb23d42d..b6902262c1 100644
--- a/doc/build/glossary.rst
+++ b/doc/build/glossary.rst
@@ -412,7 +412,7 @@ Glossary
 
         .. seealso::
 
-        	:ref:`pooling_toplevel`
+            :ref:`pooling_toplevel`
 
     DBAPI
         DBAPI is shorthand for the phrase "Python Database API
diff --git a/doc/build/orm/extensions/declarative/api.rst b/doc/build/orm/extensions/declarative/api.rst
index 9998965c40..be97604d3b 100644
--- a/doc/build/orm/extensions/declarative/api.rst
+++ b/doc/build/orm/extensions/declarative/api.rst
@@ -103,7 +103,7 @@ Above, classes which inherit from ``DefaultBase`` will use one
 created perhaps within distinct databases::
 
     DefaultBase.metadata.create_all(some_engine)
-    OtherBase.metadata_create_all(some_other_engine)
+    OtherBase.metadata.create_all(some_other_engine)
 
 
 ``__table_cls__``
diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst
index 27c8c382f4..fde22a8807 100644
--- a/doc/build/orm/persistence_techniques.rst
+++ b/doc/build/orm/persistence_techniques.rst
@@ -104,8 +104,9 @@ bound to a single :class:`~sqlalchemy.engine.Engine` or
 :class:`~sqlalchemy.orm.session.Session` which is bound either to multiple
 engines, or none at all (i.e. relies upon bound metadata), both
 :meth:`~.Session.execute` and
-:meth:`~.Session.connection` accept a ``mapper`` keyword
-argument, which is passed a mapped class or
+:meth:`~.Session.connection` accept a dictionary of bind arguments
+:paramref:`~.Session.execute.bind_arguments` which may include "mapper"
+which is passed a mapped class or
 :class:`~sqlalchemy.orm.mapper.Mapper` instance, which is used to locate the
 proper context for the desired engine::
 
@@ -113,9 +114,9 @@ proper context for the desired engine::
     session = Session()
 
     # need to specify mapper or class when executing
-    result = session.execute("select * from table where id=:id", {'id':7}, mapper=MyMappedClass)
+    result = session.execute("select * from table where id=:id", {'id':7}, bind_arguments={'mapper': MyMappedClass})
 
-    result = session.execute(select([mytable], mytable.c.id==7), mapper=MyMappedClass)
+    result = session.execute(select([mytable], mytable.c.id==7), bind_arguments={'mapper': MyMappedClass})
 
     connection = session.connection(MyMappedClass)
 
@@ -249,7 +250,7 @@ at :paramref:`_schema.Column.autoincrement`.
 
 For server-generating columns that are not primary key columns or that are not
 simple autoincrementing integer columns, the ORM requires that these columns
-are marked with an appropriate server_default directive that allows the ORM to
+are marked with an appropriate ``server_default`` directive that allows the ORM to
 retrieve this value.   Not all methods are supported on all backends, however,
 so care must be taken to use the appropriate method. The two questions to be
 answered are, 1. is this column part of the primary key or not, and 2. does the
diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst
index bf57ac6862..df157c17c9 100644
--- a/doc/build/orm/session_basics.rst
+++ b/doc/build/orm/session_basics.rst
@@ -522,10 +522,10 @@ Adding New or Existing Items
 ----------------------------
 
 :meth:`~.Session.add` is used to place instances in the
-session. For *transient* (i.e. brand new) instances, this will have the effect
+session. For :term:`transient` (i.e. brand new) instances, this will have the effect
 of an INSERT taking place for those instances upon the next flush. For
-instances which are *persistent* (i.e. were loaded by this session), they are
-already present and do not need to be added. Instances which are *detached*
+instances which are :term:`persistent` (i.e. were loaded by this session), they are
+already present and do not need to be added. Instances which are :term:`detached`
 (i.e. have been removed from a session) may be re-associated with a session
 using this method::
 
@@ -632,7 +632,7 @@ illustrated in the example below::
         # ...
 
         addresses = relationship(
-            "Address", cascade="all, delete, delete-orphan")
+            "Address", cascade="all, delete-orphan")
 
     # ...
 
@@ -654,7 +654,7 @@ that this related object is not to shared with any other parent simultaneously::
         # ...
 
         preference = relationship(
-            "Preference", cascade="all, delete, delete-orphan",
+            "Preference", cascade="all, delete-orphan",
             single_parent=True)
 
 
diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index 8ea8af4a27..13763f6bc1 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -992,7 +992,7 @@ To use an entirely string-based statement, a :func:`_expression.text` construct
 representing a complete statement can be passed to
 :meth:`~sqlalchemy.orm.query.Query.from_statement()`.   Without further
 specification, the ORM will match columns in the ORM mapping to the result
-returned by the SQL statement based on column name::
+returned by the SQL statement based on column name:
 
 .. sourcecode:: python+sql
 
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 5ad8bcf2f2..eefac2520c 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -1308,7 +1308,7 @@ class Session(_SessionClassMethods):
         resolved through any of the optional keyword arguments.   This
         ultimately makes usage of the :meth:`.get_bind` method for resolution.
 
-        :param bind_arguments: dictionary of bind arguments.  may include
+        :param bind_arguments: dictionary of bind arguments. May include
          "mapper", "bind", "clause", other custom arguments that are passed
          to :meth:`.Session.get_bind`.
 
@@ -1449,8 +1449,8 @@ class Session(_SessionClassMethods):
 
         The :meth:`.Session.execute` method does *not* invoke autoflush.
 
-        The :class:`_engine.CursorResult` returned by the :meth:`.Session.
-        execute`
+        The :class:`_engine.CursorResult` returned by the
+        :meth:`.Session.execute`
         method is returned with the "close_with_result" flag set to true;
         the significance of this flag is that if this :class:`.Session` is
         autocommitting and does not have a transaction-dedicated
@@ -1463,7 +1463,7 @@ class Session(_SessionClassMethods):
         :class:`.Session` is configured with autocommit=True and no
         transaction has been started.
 
-        :param clause:
+        :param statement:
             An executable statement (i.e. an :class:`.Executable` expression
             such as :func:`_expression.select`) or string SQL statement
             to be executed.
@@ -1476,7 +1476,7 @@ class Session(_SessionClassMethods):
             must correspond to parameter names present in the statement.
 
         :param bind_arguments: dictionary of additional arguments to determine
-         the bind.  may include "mapper", "bind", or other custom arguments.
+         the bind.  May include "mapper", "bind", or other custom arguments.
          Contents of this dictionary are passed to the
          :meth:`.Session.get_bind` method.
 
@@ -1749,15 +1749,15 @@ class Session(_SessionClassMethods):
 
         The order of resolution is:
 
-        1. if mapper given and session.binds is present,
+        1. if mapper given and :paramref:`.Session.binds` is present,
            locate a bind based first on the mapper in use, then
            on the mapped class in use, then on any base classes that are
            present in the ``__mro__`` of the mapped class, from more specific
            superclasses to more general.
-        2. if clause given and session.binds is present,
+        2. if clause given and ``Session.binds`` is present,
            locate a bind based on :class:`_schema.Table` objects
-           found in the given clause present in session.binds.
-        3. if session.bind is present, return that.
+           found in the given clause present in ``Session.binds``.
+        3. if ``Session.binds`` is present, return that.
         4. if clause given, attempt to return a bind
            linked to the :class:`_schema.MetaData` ultimately
            associated with the clause.
@@ -2751,7 +2751,7 @@ class Session(_SessionClassMethods):
 
         .. seealso::
 
-            ``load_on_pending`` at :func:`_orm.relationship` - this flag
+            :paramref:`_orm.relationship.load_on_pending` - this flag
             allows per-relationship loading of many-to-ones on items that
             are pending.
 
diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index f7a97bfe5e..8726935f84 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -312,9 +312,8 @@ def identity_key(*args, **kwargs):
 
       E.g.::
 
-        >>> row = engine.execute(\
-            text("select * from table where a=1 and b=2")\
-            ).first()
+        >>> row = engine.execute(
+        ...     text("select * from table where a=1 and b=2")).first()
         >>> identity_key(MyClass, row=row)
         (<class '__main__.MyClass'>, (1, 2), None)
 
diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index 50b2a935a7..22aac9010e 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -685,8 +685,8 @@ class ValuesBase(UpdateBase):
         added to any existing RETURNING clause, provided that
         :meth:`.UpdateBase.returning` is not used simultaneously.  The column
         values will then be available on the result using the
-        :attr:`_engine.CursorResult.returned_defaults` accessor as a dictionary
-        ,
+        :attr:`_engine.CursorResult.returned_defaults` accessor as
+        a dictionary,
         referring to values keyed to the :class:`_schema.Column`
         object as well as
         its ``.key``.