From 4b1c8ccc4f46ba9f76bb3a095e3da0b3f6bb2f7b Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sat, 30 Nov 2013 17:31:00 -0500 Subject: [PATCH] - the pronoun removal commit. there was only one instance of a standalone gendered pronoun with a gender-neutral subject, but also have replaced all occurences of "his/her", "his or her", etc. The docs have always strived to account for both genders in any non-specific singular pronoun, however recent controversy in the community suggests that a zero-gendered-pronoun policy is probably best going forward. Conflicts: doc/build/changelog/migration_08.rst doc/build/orm/session.rst examples/nested_sets/nested_sets.py Conflicts: doc/build/changelog/changelog_02.rst doc/build/orm/session.rst doc/build/orm/tutorial.rst examples/beaker_caching/advanced.py --- CHANGES_PRE_05 | 2 +- doc/build/orm/tutorial.rst | 53 +++++++++++++++-------------- examples/beaker_caching/advanced.py | 12 +++---- examples/nested_sets/nested_sets.py | 7 ++-- test/orm/test_assorted_eager.py | 4 +-- 5 files changed, 41 insertions(+), 37 deletions(-) diff --git a/CHANGES_PRE_05 b/CHANGES_PRE_05 index 6291375d62..e28dbfbff9 100644 --- a/CHANGES_PRE_05 +++ b/CHANGES_PRE_05 @@ -3497,7 +3497,7 @@ count() [ticket:287] turned on for individual table, schema, and column identifiers when used in all queries/creates/drops. Enabled via "quote=True" in Table or Column, as well as "quote_schema=True" in Table. Thanks to -Aaron Spike for his excellent efforts. +Aaron Spike for the excellent efforts. - assignmapper was setting is_primary=True, causing all sorts of mayhem by not raising an error when redundant mappers were set up, fixed - added allow_null_pks option to Mapper, allows rows where some diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 4b8e535948..94cccff328 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -90,7 +90,7 @@ Next, we can issue CREATE TABLE statements derived from our table metadata, by c () COMMIT -.. note:: +.. note:: Users familiar with the syntax of CREATE TABLE may notice that the VARCHAR columns were generated without a length; on SQLite and Postgresql, @@ -195,7 +195,7 @@ A large number of applications don't require this degree of separation, and for those SQLAlchemy offers an alternate "shorthand" configurational style called :mod:`~.sqlalchemy.ext.declarative`. For many applications, this is the only style of configuration needed. -Our above example using this style is as follows:: +Our above example using this style is as follows:: >>> from sqlalchemy.ext.declarative import declarative_base @@ -220,11 +220,11 @@ Above, the :func:`~sqlalchemy.ext.declarative.declarative_base` function defines we name ``Base``, from which all of our ORM-enabled classes will derive. Note that we define :class:`~sqlalchemy.schema.Column` objects with no "name" field, since it's inferred from the given -attribute name. +attribute name. The underlying :class:`~sqlalchemy.schema.Table` object created by our :func:`~sqlalchemy.ext.declarative.declarative_base` version of ``User`` is accessible via the -``__table__`` attribute:: +``__table__`` attribute:: >>> users_table = User.__table__ @@ -345,7 +345,7 @@ We can add more ``User`` objects at once using ... User('mary', 'Mary Contrary', 'xxg527'), ... User('fred', 'Fred Flinstone', 'blah')]) -Also, Ed has already decided his password isn't too secure, so lets change it: +Also, we've decided the password for Ed isn't too secure, so lets change it: .. sourcecode:: python+sql @@ -986,9 +986,10 @@ in memory, without using any SQL: >>> jack.addresses[1].user -Let's add and commit ``Jack Bean`` to the database. ``jack`` as well as the -two ``Address`` members in his ``addresses`` collection are both added to the -session at once, using a process known as **cascading**: +Let's add and commit ``Jack Bean`` to the database. ``jack`` as well +as the two ``Address`` members in the corresponding ``addresses`` +collection are both added to the session at once, using a process +known as **cascading**: .. sourcecode:: python+sql @@ -1009,7 +1010,7 @@ Querying for Jack, we get just Jack back. No SQL is yet issued for Jack's addre {sql}>>> jack = session.query(User).\ ... filter_by(name='jack').one() #doctest: +NORMALIZE_WHITESPACE BEGIN (implicit) - SELECT users.id AS users_id, users.name AS users_name, + SELECT users.id AS users_id, users.name AS users_name, users.fullname AS users_fullname, users.password AS users_password FROM users WHERE users.name = ? @@ -1023,7 +1024,7 @@ Let's look at the ``addresses`` collection. Watch the SQL: .. sourcecode:: python+sql {sql}>>> jack.addresses #doctest: +NORMALIZE_WHITESPACE - SELECT addresses.id AS addresses_id, addresses.email_address AS + SELECT addresses.id AS addresses_id, addresses.email_address AS addresses_email_address, addresses.user_id AS addresses_user_id FROM addresses WHERE ? = addresses.user_id ORDER BY addresses.id @@ -1068,17 +1069,17 @@ See :ref:`loading_toplevel` for information on :func:`~sqlalchemy.orm.subqueryload`. We'll also see another way to "eagerly" load in the next section. -.. note:: +.. note:: The join created by :func:`.joinedload` is anonymously aliased such that it **does not affect the query results**. An :meth:`.Query.order_by` or :meth:`.Query.filter` call **cannot** reference these aliased - tables - so-called "user space" joins are constructed using + tables - so-called "user space" joins are constructed using :meth:`.Query.join`. The rationale for this is that :func:`.joinedload` is only applied in order to affect how related objects or collections are loaded as an optimizing detail - it can be added or removed with no impact - on actual results. See the section :ref:`zen_of_eager_loading` for - a detailed description of how this is used, including how to use a single + on actual results. See the section :ref:`zen_of_eager_loading` for + a detailed description of how this is used, including how to use a single explicit JOIN for filtering/ordering and eager loading simultaneously. .. _ormtutorial_joins: @@ -1129,7 +1130,7 @@ Or we can make a real JOIN construct; the most common way is to use Note that when :meth:`~sqlalchemy.orm.query.Query.join` is called with an explicit target as well as an ON clause, we use a tuple as the argument. This is so that multiple joins can be chained together, as in:: session.query(Foo).join( - Foo.bars, + Foo.bars, (Bat, bar.bats), (Widget, Bat.widget_id==Widget.id) ) @@ -1179,9 +1180,9 @@ additional queries and without the "automatic" join embedded by the ... options(contains_eager(Address.user)): #doctest: +NORMALIZE_WHITESPACE ... print address, address.user SELECT users.id AS users_id, users.name AS users_name, users.fullname AS users_fullname, - users.password AS users_password, addresses.id AS addresses_id, - addresses.email_address AS addresses_email_address, addresses.user_id AS addresses_user_id - FROM addresses JOIN users ON users.id = addresses.user_id + users.password AS users_password, addresses.id AS addresses_id, + addresses.email_address AS addresses_email_address, addresses.user_id AS addresses_user_id + FROM addresses JOIN users ON users.id = addresses.user_id WHERE users.name = ? ('jack',) {stop} @@ -1453,7 +1454,7 @@ relationships to mappings at any point in time, in this case the existing relationship needs to be removed, so we need to tear down the mappings completely and start again. -.. note:: +.. note:: Tearing down mappers with :func:`~.orm.clear_mappers` is not a typical operation, and normal applications do not need to use this function. It is @@ -1485,9 +1486,10 @@ their parent: >>> mapper(Address, addresses_table) # doctest: +ELLIPSIS -Now when we load Jack (below using :meth:`~.Query.get`, which loads by primary key), -removing an address from his ``addresses`` collection will result in that -``Address`` being deleted: +Now when we load the user ``jack`` (below using :meth:`~.Query.get`, +which loads by primary key), removing an address from the +corresponding ``addresses`` collection will result in that ``Address`` +being deleted: .. sourcecode:: python+sql @@ -1520,7 +1522,8 @@ removing an address from his ``addresses`` collection will result in that ('jack@google.com', 'j25@yahoo.com') {stop}1 -Deleting Jack will delete both Jack and his remaining ``Address``: +Deleting Jack will delete both Jack and the remaining ``Address`` associated +with the user: .. sourcecode:: python+sql @@ -1711,8 +1714,8 @@ keyword string 'firstpost'": ('firstpost',) {stop}[BlogPost("Wendy's Blog Post", 'This is a test', )] -If we want to look up just Wendy's posts, we can tell the query to narrow down -to her as a parent: +If we want to look up posts owned by the user ``wendy``, we can tell +the query to narrow down to that ``User`` object as a parent: .. sourcecode:: python+sql diff --git a/examples/beaker_caching/advanced.py b/examples/beaker_caching/advanced.py index c16e02f33a..5597a230a4 100644 --- a/examples/beaker_caching/advanced.py +++ b/examples/beaker_caching/advanced.py @@ -1,6 +1,6 @@ """advanced.py -Illustrate usage of Query combined with the FromCache option, +Illustrate usage of Query combined with the FromCache option, including front-end loading, cache invalidation, namespace techniques and collection caching. @@ -17,13 +17,13 @@ def load_name_range(start, end, invalidate=False): start/end are integers, range is then "person " - "person ". - The cache option we set up is called "name_range", indicating + The cache option we set up is called "name_range", indicating a range of names for the Person class. The `Person.addresses` collections are also cached. Its basically another level of tuning here, as that particular cache option - can be transparently replaced with joinedload(Person.addresses). - The effect is that each Person and his/her Address collection + can be transparently replaced with joinedload(Person.addresses). + The effect is that each Person and their Address collection is cached either together or separately, affecting the kind of SQL that emits for unloaded Person objects as well as the distribution of data within the cache. @@ -63,13 +63,13 @@ print ", ".join([p.name for p in load_name_range(2, 12)]) print "\ntwenty five through forty, invalidate first:\n" print ", ".join([p.name for p in load_name_range(25, 40, True)]) -# illustrate the address loading from either cache/already +# illustrate the address loading from either cache/already # on the Person print "\n\nPeople plus addresses, two through twelve, addresses possibly from cache" for p in load_name_range(2, 12): print p.format_full() -# illustrate the address loading from either cache/already +# illustrate the address loading from either cache/already # on the Person print "\n\nPeople plus addresses, two through twelve, addresses from cache" for p in load_name_range(2, 12): diff --git a/examples/nested_sets/nested_sets.py b/examples/nested_sets/nested_sets.py index 55d734d4ed..21f2acf396 100644 --- a/examples/nested_sets/nested_sets.py +++ b/examples/nested_sets/nested_sets.py @@ -83,14 +83,15 @@ session.commit() print session.query(Employee).all() -# 1. Find an employee and all his/her supervisors, no matter how deep the tree. +# 1. Find an employee and all their supervisors, no matter how deep the tree. ealias = aliased(Employee) print session.query(Employee).\ filter(ealias.left.between(Employee.left, Employee.right)).\ filter(ealias.emp=='Eddie').all() -#2. Find the employee and all his/her subordinates. (This query has a nice symmetry with the first query.) -print session.query(Employee).\ +#2. Find the employee and all their subordinates. +# (This query has a nice symmetry with the first query.) +print(session.query(Employee).\ filter(Employee.left.between(ealias.left, ealias.right)).\ filter(ealias.emp=='Chuck').all() diff --git a/test/orm/test_assorted_eager.py b/test/orm/test_assorted_eager.py index 5ea996c3b2..f90827ae6f 100644 --- a/test/orm/test_assorted_eager.py +++ b/test/orm/test_assorted_eager.py @@ -101,8 +101,8 @@ class EagerTest(_base.MappedTest): def test_noorm(self): """test the control case""" # I want to display a list of tests owned by owner 1 - # if someoption is false or he hasn't specified it yet (null) - # but not if he set it to true (example someoption is for hiding) + # if someoption is false or they haven't specified it yet (null) + # but not if they set it to true (example someoption is for hiding) # desired output for owner 1 # test_id, cat_name -- 2.47.3