diff options
Diffstat (limited to 'doc')
29 files changed, 72 insertions, 72 deletions
diff --git a/doc/build/changelog/changelog_04.rst b/doc/build/changelog/changelog_04.rst index 1bd49871c..f0bef1c3a 100644 --- a/doc/build/changelog/changelog_04.rst +++ b/doc/build/changelog/changelog_04.rst @@ -765,7 +765,7 @@ The case() function now also takes a dictionary as its whens parameter. It also interprets the "THEN" expressions as values by default, meaning case([(x==y, - "foo")]) will interpret "foo" as a bound value, not a SQL + "foo")]) will interpret "foo" as a bound value, not an SQL expression. use text(expr) for literal SQL expressions in this case. For the criterion itself, these may be literal strings only if the "value" keyword is present, otherwise @@ -2785,7 +2785,7 @@ :tickets: 818 removed __len__ from "dynamic" collection as it would require issuing - a SQL "count()" operation, thus forcing all list evaluations to issue + an SQL "count()" operation, thus forcing all list evaluations to issue redundant SQL .. change:: @@ -3182,7 +3182,7 @@ during an executemany()-style call. inline=True flag on any insert/update statement also forces the same behavior with a single execute(). result.postfetch_cols() is a collection of columns for which the previous - single insert or update statement contained a SQL-side default expression. + single insert or update statement contained an SQL-side default expression. .. change:: :tags: diff --git a/doc/build/changelog/changelog_05.rst b/doc/build/changelog/changelog_05.rst index 04ab11dca..fd6fbeaec 100644 --- a/doc/build/changelog/changelog_05.rst +++ b/doc/build/changelog/changelog_05.rst @@ -3519,7 +3519,7 @@ makes SQLA's SQLite date type compatible with datetimes that were saved directly using Pysqlite (which just calls str()). Note that this is incompatible with the existing microseconds - values in a SQLA 0.4 generated SQLite database file. + values in an SQLA 0.4 generated SQLite database file. To get the old behavior globally: diff --git a/doc/build/changelog/changelog_06.rst b/doc/build/changelog/changelog_06.rst index 927aae21d..e19aae0ba 100644 --- a/doc/build/changelog/changelog_06.rst +++ b/doc/build/changelog/changelog_06.rst @@ -426,7 +426,7 @@ :tags: orm :tickets: 1995 - Fixed bug where a column with a SQL or server side default + Fixed bug where a column with an SQL or server side default that was excluded from a mapping with include_properties or exclude_properties would result in UnmappedColumnError. @@ -3460,7 +3460,7 @@ The type/expression system now does a more complete job of determining the return type from an expression as well as the adaptation of the Python operator into - a SQL operator, based on the full left/right/operator + an SQL operator, based on the full left/right/operator of the given expression. In particular the date/time/interval system created for Postgresql EXTRACT in has now been generalized into diff --git a/doc/build/changelog/changelog_07.rst b/doc/build/changelog/changelog_07.rst index fa952f012..a775de5ad 100644 --- a/doc/build/changelog/changelog_07.rst +++ b/doc/build/changelog/changelog_07.rst @@ -526,7 +526,7 @@ :tickets: 2568 Adjusted a very old bugfix which attempted - to work around a SQLite issue that itself was + to work around an SQLite issue that itself was "fixed" as of sqlite 3.6.14, regarding quotes surrounding a table name when using the "foreign_key_list" pragma. The fix has been @@ -923,7 +923,7 @@ :tickets: 2467 Fixed bug whereby if cast() is used - on a SQL expression whose type is not supported + on an SQL expression whose type is not supported by cast() and therefore CAST isn't rendered by the dialect, the order of evaluation could change if the casted expression required that it be @@ -4265,7 +4265,7 @@ :tags: orm :tickets: 2018 - the aliased() function, if passed a SQL FromClause element + the aliased() function, if passed an SQL FromClause element (i.e. not a mapped class), will return element.alias() instead of raising an error on AliasedClass. @@ -4405,7 +4405,7 @@ :tags: orm :tickets: 1995 - Fixed bug where a column with a SQL or server side default + Fixed bug where a column with an SQL or server side default that was excluded from a mapping with include_properties or exclude_properties would result in UnmappedColumnError. (also in 0.6.7) diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst index 5d74af71c..7c694c8a6 100644 --- a/doc/build/changelog/changelog_08.rst +++ b/doc/build/changelog/changelog_08.rst @@ -2101,7 +2101,7 @@ It was the "aliasing" behavior of the latter use case that was getting in the way of the former use case. The method now - specifically considers a SQL expression like + specifically considers an SQL expression like :func:`.expression.select` or :func:`.expression.alias` separately from a mapped entity like a :func:`.aliased` construct. diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst index 3ac0ab0b4..e629eef23 100644 --- a/doc/build/changelog/changelog_09.rst +++ b/doc/build/changelog/changelog_09.rst @@ -771,7 +771,7 @@ :tickets: 3159 Fixed bug where Postgresql JSON type was not able to persist or - otherwise render a SQL NULL column value, rather than a JSON-encoded + otherwise render an SQL NULL column value, rather than a JSON-encoded ``'null'``. To support this case, changes are as follows: * The value :func:`.null` can now be specified, which will always @@ -875,7 +875,7 @@ :tickets: 3130 :versions: 1.0.0b1 - Fixed a SQLite join rewriting issue where a subquery that is embedded + Fixed an SQLite join rewriting issue where a subquery that is embedded as a scalar subquery such as within an IN would receive inappropriate substitutions from the enclosing query, if the same table were present inside the subquery as were in the enclosing query such as in a diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst index 07188b771..8c366e4b6 100644 --- a/doc/build/changelog/changelog_10.rst +++ b/doc/build/changelog/changelog_10.rst @@ -583,7 +583,7 @@ Fixed two issues regarding Sybase reflection, allowing tables without primary keys to be reflected as well as ensured that - a SQL statement involved in foreign key detection is pre-fetched up + an SQL statement involved in foreign key detection is pre-fetched up front to avoid driver issues upon nested queries. Fixes here courtesy Eugene Zapolsky; note that we cannot currently test Sybase to locally verify these changes. @@ -1142,8 +1142,8 @@ :tickets: 3402 Fixed regression within the flush process when an attribute were - set to a SQL expression for an UPDATE, and the SQL expression when - compared to the previous value of the attribute would produce a SQL + set to an SQL expression for an UPDATE, and the SQL expression when + compared to the previous value of the attribute would produce an SQL comparison other than ``==`` or ``!=``, the exception "Boolean value of this clause is not defined" would raise. The fix ensures that the unit of work will not interpret the SQL expression in this way. @@ -1329,7 +1329,7 @@ there's no data being referenced). In order to maintain the new feature of :ticket:`3282` while still - allowing a SQLite DROP operation to maintain ordering, we now + allowing an SQLite DROP operation to maintain ordering, we now do the sort with full FKs taken under consideration, and if we encounter an unresolvable cycle, only *then* do we forego attempting to sort the tables; we instead emit a warning and go with the unsorted list. @@ -1943,7 +1943,7 @@ :pullreq: github:150 The type of expression is reported when an object passed to a - SQL expression unit can't be interpreted as a SQL fragment; + SQL expression unit can't be interpreted as an SQL fragment; pull request courtesy Ryan P. Kelly. .. change:: diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst index fd153a925..d72b2e11d 100644 --- a/doc/build/changelog/migration_08.rst +++ b/doc/build/changelog/migration_08.rst @@ -734,7 +734,7 @@ functionality, except on the database side:: Column('data', LowerString) ) -Above, the ``LowerString`` type defines a SQL expression that will be emitted +Above, the ``LowerString`` type defines an SQL expression that will be emitted whenever the ``test_table.c.data`` column is rendered in the columns clause of a SELECT statement:: diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst index a4fbf117d..8064b242d 100644 --- a/doc/build/changelog/migration_10.rst +++ b/doc/build/changelog/migration_10.rst @@ -601,7 +601,7 @@ to not support this behavior; third party dialects may also need modification in order to take advantage of the new behavior. A dialect which currently uses the ``._limit`` or ``._offset`` attributes will continue to function for those cases where the limit/offset was specified as a simple integer value. -However, when a SQL expression is specified, these two attributes will +However, when an SQL expression is specified, these two attributes will instead raise a :class:`.CompileError` on access. A third-party dialect which wishes to support the new feature should now call upon the ``._limit_clause`` and ``._offset_clause`` attributes to receive the full SQL expression, rather @@ -634,7 +634,7 @@ does not support ALTER, in the case that during a DROP, the given tables have an unresolvable cycle; in this case a warning is emitted, and the tables are dropped with **no** ordering, which is usually fine on SQLite unless constraints are enabled. To resolve the warning and proceed with at least -a partial ordering on a SQLite database, particuarly one where constraints +a partial ordering on an SQLite database, particuarly one where constraints are enabled, re-apply "use_alter" flags to those :class:`.ForeignKey` and :class:`.ForeignKeyConstraint` objects which should be explicitly omitted from the sort. @@ -862,7 +862,7 @@ Column server defaults now render literal values The "literal binds" compiler flag is switched on when a :class:`.DefaultClause`, set up by :paramref:`.Column.server_default` -is present as a SQL expression to be compiled. This allows literals +is present as an SQL expression to be compiled. This allows literals embedded in SQL to render correctly, such as:: from sqlalchemy import Table, Column, MetaData, Text @@ -1841,7 +1841,7 @@ full SQL string to :meth:`.Connection.execute`, but that you can send strings with SQL expressions into many functions, such as :meth:`.Select.where`, :meth:`.Query.filter`, and :meth:`.Select.order_by`. -Note that by "SQL expressions" we mean a **full fragment of a SQL string**, +Note that by "SQL expressions" we mean a **full fragment of an SQL string**, such as:: # the argument sent to where() is a full SQL expression diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst index 6f0da3780..cb028cc6e 100644 --- a/doc/build/changelog/migration_11.rst +++ b/doc/build/changelog/migration_11.rst @@ -185,7 +185,7 @@ as :class:`.NullType` is used to refer to any expression of unknown type. Additionally, the treatment of a so-called "unhashable" type is slightly -different than its been in previous releases; internally we are using +different than it's been in previous releases; internally we are using the ``id()`` function to get a "hash value" from these structures, just as we would any ordinary mapped object. This replaces the previous approach which applied a counter to the object. @@ -212,11 +212,11 @@ string value:: >>> some_user = User() >>> q = s.query(User).filter(User.name == some_user) ... - sqlalchemy.exc.ArgumentError: Object <__main__.User object at 0x103167e90> is not legal as a SQL literal value + sqlalchemy.exc.ArgumentError: Object <__main__.User object at 0x103167e90> is not legal as an SQL literal value The exception is now immediate when the comparison is made between ``User.name == some_user``. Previously, a comparison like the above -would produce a SQL expression that would only fail once resolved +would produce an SQL expression that would only fail once resolved into a DBAPI execution call; the mapped ``User`` object would ultimately become a bound parameter that would be rejected by the DBAPI. @@ -1239,7 +1239,7 @@ this CHECK constraint can now be disabled using the new Large parameter and row values are now truncated in logging and exception displays ---------------------------------------------------------------------------------- -A large value present as a bound parameter for a SQL statement, as well as a +A large value present as a bound parameter for an SQL statement, as well as a large value present in a result row, will now be truncated during display within logging, exception reporting, as well as ``repr()`` of the row itself:: @@ -1364,7 +1364,7 @@ JSON "null" is inserted as expected with ORM operations, regardless of column de The :class:`.types.JSON` type and its descendant types :class:`.postgresql.JSON` and :class:`.mysql.JSON` have a flag :paramref:`.types.JSON.none_as_null` which when set to True indicates that the Python value ``None`` should translate -into a SQL NULL rather than a JSON NULL value. This flag defaults to False, +into an SQL NULL rather than a JSON NULL value. This flag defaults to False, which means that the column should *never* insert SQL NULL or fall back to a default unless the :func:`.null` constant were used. However, this would fail in the ORM under two circumstances; one is when the column also contained @@ -1415,7 +1415,7 @@ New JSON.NULL Constant Added To ensure that an application can always have full control at the value level of whether a :class:`.types.JSON`, :class:`.postgresql.JSON`, :class:`.mysql.JSON`, or :class:`.postgresql.JSONB` column -should receive a SQL NULL or JSON ``"null"`` value, the constant +should receive an SQL NULL or JSON ``"null"`` value, the constant :attr:`.types.JSON.NULL` has been added, which in conjunction with :func:`.null` can be used to determine fully between SQL NULL and JSON ``"null"``, regardless of what :paramref:`.types.JSON.none_as_null` is set @@ -1697,7 +1697,7 @@ Above, in the :paramref:`.relationship.primaryjoin` expression, we are using :func:`.type_coerce` to handle bound parameters passed via lazyloading as integers, since we already know these will come from our ``StringAsInt`` type which maintains the value as an integer in -Python. We are then using :func:`.cast` so that as a SQL expression, +Python. We are then using :func:`.cast` so that as an SQL expression, the VARCHAR "id" column will be CAST to an integer for a regular non- converted join as with :meth:`.Query.join` or :func:`.orm.joinedload`. That is, a joinedload of ``.pets`` looks like:: @@ -1839,7 +1839,7 @@ This includes: * The SQL type assigned to indexed access of an :class:`~.postgresql.ARRAY` takes into account the number of dimensions configured. An :class:`~.postgresql.ARRAY` with three - dimensions will return a SQL expression with a type of :class:`~.postgresql.ARRAY` of + dimensions will return an SQL expression with a type of :class:`~.postgresql.ARRAY` of one less dimension. Given a column with type ``ARRAY(Integer, dimensions=3)``, we can now perform this expression:: diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 709642ecf..adcbcf049 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -7,7 +7,7 @@ Working with Engines and Connections .. module:: sqlalchemy.engine This section details direct usage of the :class:`.Engine`, -:class:`.Connection`, and related objects. Its important to note that when +:class:`.Connection`, and related objects. It's important to note that when using the SQLAlchemy ORM, these objects are not generally accessed; instead, the :class:`.Session` object is used as the interface to the database. However, for applications that are built around direct usage of textual SQL @@ -295,7 +295,7 @@ Explicit, connectionless execution delivers the expression to the Implicit execution is also connectionless, and makes usage of the :meth:`~.Executable.execute` method on the expression itself. This method is provided as part of the -:class:`.Executable` class, which refers to a SQL statement that is sufficient +:class:`.Executable` class, which refers to an SQL statement that is sufficient for being invoked against the database. The method makes usage of the assumption that either an :class:`~sqlalchemy.engine.Engine` or diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst index a7287a360..ab1506834 100644 --- a/doc/build/core/defaults.rst +++ b/doc/build/core/defaults.rst @@ -321,7 +321,7 @@ use case, add the flag ``optional=True`` to the provides no other option for generating primary key identifiers. The :class:`~sqlalchemy.schema.Sequence` object also has the ability to be -executed standalone like a SQL expression, which has the effect of calling its +executed standalone like an SQL expression, which has the effect of calling its "next value" function:: seq = Sequence('some_sequence') diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index 17ec9416c..a6950c949 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -160,7 +160,7 @@ And for an absolute file path, the three slashes are followed by the absolute pa #Windows alternative using raw string engine = create_engine(r'sqlite:///C:\path\to\foo.db') -To use a SQLite ``:memory:`` database, specify an empty URL:: +To use an SQLite ``:memory:`` database, specify an empty URL:: engine = create_engine('sqlite://') diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index 0fd78abeb..fef3c9f2e 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -248,7 +248,7 @@ Executing The interesting part of an :class:`~sqlalchemy.sql.expression.Insert` is executing it. In this tutorial, we will generally focus on the most explicit -method of executing a SQL construct, and later touch upon some "shortcut" ways +method of executing an SQL construct, and later touch upon some "shortcut" ways to do it. The ``engine`` object we created is a repository for database connections capable of issuing SQL to the database. To acquire a connection, we use the ``connect()`` method:: @@ -552,7 +552,7 @@ some of its capabilities. We've seen how to equate two columns to each other: >>> print(users.c.id == addresses.c.user_id) users.id = addresses.user_id -If we use a literal value (a literal meaning, not a SQLAlchemy clause object), +If we use a literal value (a literal meaning, not an SQLAlchemy clause object), we get a bind parameter: .. sourcecode:: pycon+sql @@ -569,7 +569,7 @@ we did with the :class:`~sqlalchemy.sql.expression.Insert` object to see it: >>> (users.c.id == 7).compile().params {u'id_1': 7} -Most Python operators, as it turns out, produce a SQL expression here, like +Most Python operators, as it turns out, produce an SQL expression here, like equals, not equals, etc.: .. sourcecode:: pycon+sql diff --git a/doc/build/faq/connections.rst b/doc/build/faq/connections.rst index 658b4f785..01aeb2bea 100644 --- a/doc/build/faq/connections.rst +++ b/doc/build/faq/connections.rst @@ -94,10 +94,10 @@ a COMMIT as any connection is returned to the pool:: engine = create_engine('mssql://scott:tiger@mydsn', pool=QueuePool(reset_on_return='commit')) -I am using multiple connections with a SQLite database (typically to test transaction operation), and my test program is not working! +I am using multiple connections with an SQLite database (typically to test transaction operation), and my test program is not working! ---------------------------------------------------------------------------------------------------------------------------------------------------------- -If using a SQLite ``:memory:`` database, or a version of SQLAlchemy prior +If using an SQLite ``:memory:`` database, or a version of SQLAlchemy prior to version 0.7, the default connection pool is the :class:`.SingletonThreadPool`, which maintains exactly one SQLite connection per thread. So two connections in use in the same thread will actually be the same SQLite diff --git a/doc/build/faq/ormconfiguration.rst b/doc/build/faq/ormconfiguration.rst index 3a2ea29a6..03f8370de 100644 --- a/doc/build/faq/ormconfiguration.rst +++ b/doc/build/faq/ormconfiguration.rst @@ -244,7 +244,7 @@ all queries. The consequence of this is that any query that limits rows using ``LIMIT`` or ``OFFSET`` should **always** specify an ``ORDER BY``. Otherwise, it is not deterministic which rows will actually be returned. -When we use a SQLAlchemy method like :meth:`.Query.first`, we are in fact +When we use an SQLAlchemy method like :meth:`.Query.first`, we are in fact applying a ``LIMIT`` of one to the query, so without an explicit ordering it is not deterministic what row we actually get back. While we may not notice this for simple queries on databases that usually @@ -293,7 +293,7 @@ the two queries may not see the same results: ORDER BY anon_1.users_id Depending on database specifics, there is -a chance we may get the a result like the following for the two queries:: +a chance we may get a result like the following for the two queries:: -- query #1 +--------+ diff --git a/doc/build/faq/performance.rst b/doc/build/faq/performance.rst index 8413cb5a2..6ea0a0616 100644 --- a/doc/build/faq/performance.rst +++ b/doc/build/faq/performance.rst @@ -10,8 +10,8 @@ Performance .. _faq_how_to_profile: -How can I profile a SQLAlchemy powered application? ---------------------------------------------------- +How can I profile an SQLAlchemy powered application? +---------------------------------------------------- Looking for performance issues typically involves two stratgies. One is query profiling, and the other is code profiling. @@ -22,7 +22,7 @@ Query Profiling Sometimes just plain SQL logging (enabled via python's logging module or via the ``echo=True`` argument on :func:`.create_engine`) can give an idea how long things are taking. For example, if you log something -right after a SQL operation, you'd see something like this in your +right after an SQL operation, you'd see something like this in your log:: 17:37:48,325 INFO [sqlalchemy.engine.base.Engine.0x...048c] SELECT ... diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index 8a47db77a..f7818018a 100644 --- a/doc/build/faq/sessions.rst +++ b/doc/build/faq/sessions.rst @@ -171,7 +171,7 @@ But why isn't the one automatic call to ROLLBACK enough? Why must I ROLLBACK ag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is again a matter of the :class:`.Session` providing a consistent interface and -refusing to guess about what context its being used. For example, the +refusing to guess about what context it's being used in. For example, the :class:`.Session` supports "framing" above within multiple levels. Such as, suppose you had a decorator ``@with_session()``, which did this:: @@ -227,7 +227,7 @@ comes into play if you want to SAVEPOINT- you might call ``begin_nested()`` several times, and the ``commit()``/``rollback()`` calls each resolve the most recent ``begin_nested()``. The meaning of ``rollback()`` or ``commit()`` is dependent upon which enclosing block it is called, and you might have any -sequence of ``rollback()``/``commit()`` in any order, and its the level of nesting +sequence of ``rollback()``/``commit()`` in any order, and it's the level of nesting that determines their behavior. In both of the above cases, if ``flush()`` broke the nesting of transaction @@ -275,7 +275,7 @@ Query has no ``__len__()``, why not? The Python ``__len__()`` magic method applied to an object allows the ``len()`` builtin to be used to determine the length of the collection. It's intuitive -that a SQL query object would link ``__len__()`` to the :meth:`.Query.count` +that an SQL query object would link ``__len__()`` to the :meth:`.Query.count` method, which emits a `SELECT COUNT`. The reason this is not possible is because evaluating the query as a list would incur two SQL calls instead of one:: diff --git a/doc/build/faq/sqlexpressions.rst b/doc/build/faq/sqlexpressions.rst index c3504218b..0d1733c7e 100644 --- a/doc/build/faq/sqlexpressions.rst +++ b/doc/build/faq/sqlexpressions.rst @@ -11,7 +11,7 @@ SQL Expressions How do I render SQL expressions as strings, possibly with bound parameters inlined? ------------------------------------------------------------------------------------ -The "stringification" of a SQLAlchemy statement or Query in the vast majority +The "stringification" of an SQLAlchemy statement or Query in the vast majority of cases is as simple as:: print(str(statement)) diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 4fd9b0633..ac7d683e9 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -58,7 +58,7 @@ Glossary of :class:`.InstrumentedAttribute`, which are descriptors that provide the above mentioned ``__get__()``, ``__set__()`` and ``__delete__()`` methods. The :class:`.InstrumentedAttribute` - will generate a SQL expression when used at the class level:: + will generate an SQL expression when used at the class level:: >>> print MyClass.data == 5 data = :data_1 @@ -628,7 +628,7 @@ Glossary The relationship from ``department`` to ``employee`` is one to many, since many employee records can be associated with a - single department. A SQLAlchemy mapping might look like:: + single department. An SQLAlchemy mapping might look like:: class Department(Base): __tablename__ = 'department' @@ -679,7 +679,7 @@ Glossary The relationship from ``employee`` to ``department`` is many to one, since many employee records can be associated with a - single department. A SQLAlchemy mapping might look like:: + single department. An SQLAlchemy mapping might look like:: class Department(Base): __tablename__ = 'department' @@ -873,7 +873,7 @@ Glossary FOREIGN KEY project_id REFERENCES project(id) ) - A SQLAlchemy declarative mapping for the above might look like:: + An SQLAlchemy declarative mapping for the above might look like:: class Employee(Base): __tablename__ = 'employee' diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst index 83cee51da..4515067c8 100644 --- a/doc/build/orm/extensions/baked.rst +++ b/doc/build/orm/extensions/baked.rst @@ -10,7 +10,7 @@ Baked Queries construction and string-compilation steps. This means that for a particular :class:`~.query.Query` building scenario that is used more than once, all of the Python function invocation involved in building the query -from its initial construction up through generating a SQL string will only +from its initial construction up through generating an SQL string will only occur **once**, rather than for each time that query is built up and executed. The rationale for this system is to greatly reduce Python interpreter @@ -155,7 +155,7 @@ as being impacted by this particular form of overhead. .. topic:: Measure twice, cut once - For background on how to profile a SQLAlchemy application, please see + For background on how to profile an SQLAlchemy application, please see the section :ref:`faq_performance`. It is essential that performance measurement techniques are used when attempting to improve the performance of an application. diff --git a/doc/build/orm/extensions/declarative/relationships.rst b/doc/build/orm/extensions/declarative/relationships.rst index fb53c28bb..fc9dc114f 100644 --- a/doc/build/orm/extensions/declarative/relationships.rst +++ b/doc/build/orm/extensions/declarative/relationships.rst @@ -130,7 +130,7 @@ as well, passing the string name of the table as defined in the id = Column(Integer, primary_key=True) keywords = relationship("Keyword", secondary="keywords") -As with traditional mapping, its generally not a good idea to use +As with traditional mapping, it's generally not a good idea to use a :class:`.Table` as the "secondary" argument which is also mapped to a class, unless the :func:`.relationship` is declared with ``viewonly=True``. Otherwise, the unit-of-work system may attempt duplicate INSERT and diff --git a/doc/build/orm/loading_relationships.rst b/doc/build/orm/loading_relationships.rst index 3a0026bbe..aa993c359 100644 --- a/doc/build/orm/loading_relationships.rst +++ b/doc/build/orm/loading_relationships.rst @@ -15,7 +15,7 @@ Using Loader Strategies: Lazy Loading, Eager Loading By default, all inter-object relationships are **lazy loading**. The scalar or collection attribute associated with a :func:`~sqlalchemy.orm.relationship` contains a trigger which fires the first time the attribute is accessed. This -trigger, in all but one case, issues a SQL call at the point of access +trigger, in all but one case, issues an SQL call at the point of access in order to load the related object or objects: .. sourcecode:: python+sql diff --git a/doc/build/orm/mapped_attributes.rst b/doc/build/orm/mapped_attributes.rst index 2e7e9b3eb..260041ebc 100644 --- a/doc/build/orm/mapped_attributes.rst +++ b/doc/build/orm/mapped_attributes.rst @@ -156,7 +156,7 @@ usable with :class:`.Query`. To provide these, we instead use the self._email = email The ``.email`` attribute, in addition to providing getter/setter behavior when we have an -instance of ``EmailAddress``, also provides a SQL expression when used at the class level, +instance of ``EmailAddress``, also provides an SQL expression when used at the class level, that is, from the ``EmailAddress`` class directly: .. sourcecode:: python+sql @@ -210,7 +210,7 @@ logic:: @email.expression def email(cls): - """Produce a SQL expression that represents the value + """Produce an SQL expression that represents the value of the _email column, minus the last twelve characters.""" return func.substr(cls._email, 0, func.length(cls._email) - 12) @@ -218,7 +218,7 @@ logic:: Above, accessing the ``email`` property of an instance of ``EmailAddress`` will return the value of the ``_email`` attribute, removing or adding the hostname ``@example.com`` from the value. When we query against the ``email`` -attribute, a SQL function is rendered which produces the same effect: +attribute, an SQL function is rendered which produces the same effect: .. sourcecode:: python+sql diff --git a/doc/build/orm/mapped_sql_expr.rst b/doc/build/orm/mapped_sql_expr.rst index e091e33a6..63595440b 100644 --- a/doc/build/orm/mapped_sql_expr.rst +++ b/doc/build/orm/mapped_sql_expr.rst @@ -75,7 +75,7 @@ needs to be present inside the hybrid, using the ``if`` statement in Python and Using column_property --------------------- -The :func:`.orm.column_property` function can be used to map a SQL +The :func:`.orm.column_property` function can be used to map an SQL expression in a manner similar to a regularly mapped :class:`.Column`. With this technique, the attribute is loaded along with all other column-mapped attributes at load time. This is in some @@ -176,7 +176,7 @@ here with a classical mapping:: Using a plain descriptor ------------------------- -In cases where a SQL query more elaborate than what :func:`.orm.column_property` +In cases where an SQL query more elaborate than what :func:`.orm.column_property` or :class:`.hybrid_property` can provide must be emitted, a regular Python function accessed as an attribute can be used, assuming the expression only needs to be available on an already-loaded instance. The function @@ -204,5 +204,5 @@ which is then used to emit a query:: The plain descriptor approach is useful as a last resort, but is less performant in the usual case than both the hybrid and column property approaches, in that -it needs to emit a SQL query upon each access. +it needs to emit an SQL query upon each access. diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst index a30d486b5..f679c5c15 100644 --- a/doc/build/orm/persistence_techniques.rst +++ b/doc/build/orm/persistence_techniques.rst @@ -7,7 +7,7 @@ Additional Persistence Techniques Embedding SQL Insert/Update Expressions into a Flush ===================================================== -This feature allows the value of a database column to be set to a SQL +This feature allows the value of a database column to be set to an SQL expression instead of a literal value. It's especially useful for atomic updates, calling stored procedures, etc. All you do is assign an expression to an attribute:: @@ -18,7 +18,7 @@ an attribute:: someobject = session.query(SomeClass).get(5) - # set 'value' attribute to a SQL expression adding one + # set 'value' attribute to an SQL expression adding one someobject.value = some_table.c.value + 1 # issues "UPDATE some_table SET value=value+1" @@ -48,7 +48,7 @@ This is most easily accomplished using the # execute a string statement result = session.execute("select * from table where id=:id", {'id':7}) - # execute a SQL expression construct + # execute an SQL expression construct result = session.execute(select([mytable]).where(mytable.c.id==7)) The current :class:`~sqlalchemy.engine.Connection` held by the diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index 0f96ba50a..2fbb5082f 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -681,7 +681,7 @@ initiated by calling the :meth:`~.Session.begin` method. construct within the :class:`.Session` itself which may be maintaining zero or more actual database (DBAPI) transactions. An individual DBAPI connection begins participation in the "transaction" as it is first - used to execute a SQL statement, then remains present until the session-level + used to execute an SQL statement, then remains present until the session-level "transaction" is completed. See :ref:`unitofwork_transaction` for further detail. diff --git a/doc/build/orm/session_state_management.rst b/doc/build/orm/session_state_management.rst index 090bf7674..1a4a879c9 100644 --- a/doc/build/orm/session_state_management.rst +++ b/doc/build/orm/session_state_management.rst @@ -416,7 +416,7 @@ Refreshing / Expiring :term:`Expiring` means that the database-persisted data held inside a series of object attributes is erased, in such a way that when those attributes -are next accessed, a SQL query is emitted which will refresh that data from +are next accessed, an SQL query is emitted which will refresh that data from the database. When we talk about expiration of data we are usually talking about an object @@ -599,7 +599,7 @@ may have occurred. can't fully predict when the same SELECT statement, emitted a second time, will definitely return the data we already have, or will return new data. So as a best guess, it assumes that within the scope of a transaction, unless - it is known that a SQL expression has been emitted to modify a particular row, + it is known that an SQL expression has been emitted to modify a particular row, there's no need to refresh a row unless explicitly told to do so. The :meth:`.Session.expire` and :meth:`.Session.refresh` methods are used in diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 0a9fc7430..cd5536b7a 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -148,7 +148,7 @@ is described in detail at :ref:`declarative_mixins`. When our class is constructed, Declarative replaces all the :class:`.Column` objects with special Python accessors known as :term:`descriptors`; this is a process known as :term:`instrumentation`. The "instrumented" mapped class -will provide us with the means to refer to our table in a SQL context as well +will provide us with the means to refer to our table in an SQL context as well as to persist and load the values of columns from the database. Outside of what the mapping process does to our class, the class remains @@ -1429,7 +1429,7 @@ get rows back for those users who don't have any addresses, e.g.:: ON users.id=adr_count.user_id Using the :class:`~sqlalchemy.orm.query.Query`, we build a statement like this -from the inside out. The ``statement`` accessor returns a SQL expression +from the inside out. The ``statement`` accessor returns an SQL expression representing the statement generated by a particular :class:`~sqlalchemy.orm.query.Query` - this is an instance of a :func:`~.expression.select` construct, which are described in :ref:`sqlexpression_toplevel`:: @@ -1440,7 +1440,7 @@ construct, which are described in :ref:`sqlexpression_toplevel`:: ... group_by(Address.user_id).subquery() The ``func`` keyword generates SQL functions, and the ``subquery()`` method on -:class:`~sqlalchemy.orm.query.Query` produces a SQL expression construct +:class:`~sqlalchemy.orm.query.Query` produces an SQL expression construct representing a SELECT statement embedded within an alias (it's actually shorthand for ``query.statement.alias()``). |