Skip to content

Commit 32427ad

Browse files
CaselITzzzeek
authored andcommitted
The noload loader option is now deprecated.
Fixes: #11045 Change-Id: If77517926eda71f92cd92b2d22a69a5ee172274e
1 parent 1f704fb commit 32427ad

16 files changed

Lines changed: 450 additions & 389 deletions
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. change::
2+
:tags: orm
3+
:tickets: 11045
4+
5+
The :func:`_orm.noload` relationship loader option and related
6+
``lazy='noload'`` setting is deprecated and will be removed in a future
7+
release. This option was originally intended for custom loader patterns
8+
that are no longer applicable in modern SQLAlchemy.

‎lib/sqlalchemy/orm/_orm_constructors.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1426,11 +1426,6 @@ class that will be synchronized with this one. It is usually
14261426
issues a JOIN to the immediate parent object, specifying primary
14271427
key identifiers using an IN clause.
14281428
1429-
* ``noload`` - no loading should occur at any time. The related
1430-
collection will remain empty. The ``noload`` strategy is not
1431-
recommended for general use. For a general use "never load"
1432-
approach, see :ref:`write_only_relationship`
1433-
14341429
* ``raise`` - lazy loading is disallowed; accessing
14351430
the attribute, if its value were not already loaded via eager
14361431
loading, will raise an :exc:`~sqlalchemy.exc.InvalidRequestError`.
@@ -1493,6 +1488,13 @@ class that will be synchronized with this one. It is usually
14931488
:ref:`write_only_relationship` - more generally useful approach
14941489
for large collections that should not fully load into memory
14951490
1491+
* ``noload`` - no loading should occur at any time. The related
1492+
collection will remain empty.
1493+
1494+
.. deprecated:: 2.1 The ``noload`` loader strategy is deprecated and
1495+
will be removed in a future release. This option produces incorrect
1496+
results by returning ``None`` for related items.
1497+
14961498
* True - a synonym for 'select'
14971499
14981500
* False - a synonym for 'joined'

‎lib/sqlalchemy/orm/strategies.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -638,6 +638,13 @@ class _NoLoader(_AbstractRelationshipLoader):
638638

639639
__slots__ = ()
640640

641+
@util.deprecated(
642+
"2.1",
643+
"The ``noload`` loader strategy is deprecated and will be removed "
644+
"in a future release. This option "
645+
"produces incorrect results by returning ``None`` for related "
646+
"items.",
647+
)
641648
def init_class_attribute(self, mapper):
642649
self.is_class_level = True
643650

‎lib/sqlalchemy/orm/strategy_options.py‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -478,24 +478,23 @@ def immediateload(
478478
)
479479
return loader
480480

481+
@util.deprecated(
482+
"2.1",
483+
"The :func:`_orm.noload` option is deprecated and will be removed "
484+
"in a future release. This option "
485+
"produces incorrect results by returning ``None`` for related "
486+
"items.",
487+
)
481488
def noload(self, attr: _AttrType) -> Self:
482489
"""Indicate that the given relationship attribute should remain
483490
unloaded.
484491
485492
The relationship attribute will return ``None`` when accessed without
486493
producing any loading effect.
487494
488-
This function is part of the :class:`_orm.Load` interface and supports
489-
both method-chained and standalone operation.
490-
491495
:func:`_orm.noload` applies to :func:`_orm.relationship` attributes
492496
only.
493497
494-
.. legacy:: The :func:`_orm.noload` option is **legacy**. As it
495-
forces collections to be empty, which invariably leads to
496-
non-intuitive and difficult to predict results. There are no
497-
legitimate uses for this option in modern SQLAlchemy.
498-
499498
.. seealso::
500499
501500
:ref:`loading_toplevel`

‎lib/sqlalchemy/testing/assertions.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,12 @@ def expect_deprecated(*messages, **kw):
8989
)
9090

9191

92+
def expect_noload_deprecation():
93+
return expect_deprecated(
94+
r"The (?:``noload`` loader strategy|noload\(\) option) is deprecated."
95+
)
96+
97+
9298
def expect_deprecated_20(*messages, **kw):
9399
return _expect_warnings_sqla_only(
94100
sa_exc.Base20DeprecationWarning, messages, **kw

‎lib/sqlalchemy/util/langhelpers.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1846,6 +1846,10 @@ def _warnings_warn(
18461846
category: Optional[Type[Warning]] = None,
18471847
stacklevel: int = 2,
18481848
) -> None:
1849+
1850+
if category is None and isinstance(message, Warning):
1851+
category = type(message)
1852+
18491853
# adjust the given stacklevel to be outside of SQLAlchemy
18501854
try:
18511855
frame = sys._getframe(stacklevel)

‎test/orm/inheritance/test_assorted_poly.py‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
from sqlalchemy.testing import eq_
4242
from sqlalchemy.testing import expect_warnings
4343
from sqlalchemy.testing import fixtures
44+
from sqlalchemy.testing.assertions import expect_noload_deprecation
4445
from sqlalchemy.testing.entities import ComparableEntity
4546
from sqlalchemy.testing.fixtures import fixture_session
4647
from sqlalchemy.testing.provision import normalize_sequence
@@ -2355,7 +2356,8 @@ class Common(Base):
23552356
def test_poly_query_on_correlate(self):
23562357
Common, Superclass = self._fixture(False)
23572358

2358-
poly = with_polymorphic(Superclass, "*")
2359+
with expect_noload_deprecation():
2360+
poly = with_polymorphic(Superclass, "*")
23592361

23602362
s = fixture_session()
23612363
q = (
@@ -2384,7 +2386,8 @@ def test_poly_query_on_correlate(self):
23842386
def test_poly_query_on_correlate_except(self):
23852387
Common, Superclass = self._fixture(True)
23862388

2387-
poly = with_polymorphic(Superclass, "*")
2389+
with expect_noload_deprecation():
2390+
poly = with_polymorphic(Superclass, "*")
23882391

23892392
s = fixture_session()
23902393
q = (

‎test/orm/test_ac_relationships.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
from sqlalchemy.testing import eq_
1818
from sqlalchemy.testing import expect_warnings
1919
from sqlalchemy.testing import fixtures
20+
from sqlalchemy.testing.assertions import expect_noload_deprecation
2021
from sqlalchemy.testing.assertions import expect_raises_message
2122
from sqlalchemy.testing.assertsql import CompiledSQL
2223
from sqlalchemy.testing.entities import ComparableEntity
@@ -142,7 +143,8 @@ def go():
142143
for b in a1.partitioned_bs:
143144
eq_(b.cs, [])
144145

145-
self.assert_sql_count(testing.db, go, 2)
146+
with expect_noload_deprecation():
147+
self.assert_sql_count(testing.db, go, 2)
146148

147149
@testing.combinations("ac_attribute", "ac_attr_w_of_type")
148150
def test_selectinload_w_joinedload_after(self, calling_style):

‎test/orm/test_default_strategies.py‎

Lines changed: 4 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
from test.orm import _fixtures
1919

2020

21-
class DefaultStrategyOptionsTest(_fixtures.FixtureTest):
21+
class DefaultStrategyOptionsTestFixtures(_fixtures.FixtureTest):
2222
def _assert_fully_loaded(self, users):
2323
# verify everything loaded, with no additional sql needed
2424
def go():
@@ -193,6 +193,9 @@ def _upgrade_fixture(self):
193193

194194
return fixture_session()
195195

196+
197+
class DefaultStrategyOptionsTest(DefaultStrategyOptionsTestFixtures):
198+
196199
def test_downgrade_baseline(self):
197200
"""Mapper strategy defaults load as expected
198201
(compare to rest of DefaultStrategyOptionsTest downgrade tests)."""
@@ -368,67 +371,6 @@ def go():
368371
# lastly, make sure they actually loaded properly
369372
eq_(users, self.static.user_all_result)
370373

371-
def test_noload_with_joinedload(self):
372-
"""Mapper load strategy defaults can be downgraded with
373-
noload('*') option, while explicit joinedload() option
374-
is still honored"""
375-
sess = self._downgrade_fixture()
376-
users = []
377-
378-
# test noload('*') shuts off 'orders' subquery, only 1 sql
379-
def go():
380-
users[:] = (
381-
sess.query(self.classes.User)
382-
.options(sa.orm.noload("*"))
383-
.options(joinedload(self.classes.User.addresses))
384-
.order_by(self.classes.User.id)
385-
.all()
386-
)
387-
388-
self.assert_sql_count(testing.db, go, 1)
389-
390-
# verify all the addresses were joined loaded (no more sql)
391-
self._assert_addresses_loaded(users)
392-
393-
# User.orders should have loaded "noload" (meaning [])
394-
def go():
395-
for u in users:
396-
assert u.orders == []
397-
398-
self.assert_sql_count(testing.db, go, 0)
399-
400-
def test_noload_with_subqueryload(self):
401-
"""Mapper load strategy defaults can be downgraded with
402-
noload('*') option, while explicit subqueryload() option
403-
is still honored"""
404-
sess = self._downgrade_fixture()
405-
users = []
406-
407-
# test noload('*') option combined with subqueryload()
408-
# shuts off 'addresses' load AND orders.items load: 2 sql expected
409-
def go():
410-
users[:] = (
411-
sess.query(self.classes.User)
412-
.options(sa.orm.noload("*"))
413-
.options(subqueryload(self.classes.User.orders))
414-
.order_by(self.classes.User.id)
415-
.all()
416-
)
417-
418-
self.assert_sql_count(testing.db, go, 2)
419-
420-
def go():
421-
# Verify orders have already been loaded: 0 sql
422-
for u, static in zip(users, self.static.user_all_result):
423-
assert len(u.orders) == len(static.orders)
424-
# Verify noload('*') prevented orders.items load
425-
# and set 'items' to []
426-
for u in users:
427-
for o in u.orders:
428-
assert o.items == []
429-
430-
self.assert_sql_count(testing.db, go, 0)
431-
432374
def test_joined(self):
433375
"""Mapper load strategy defaults can be upgraded with
434376
joinedload('*') option."""
@@ -654,99 +596,6 @@ def go():
654596
self._assert_fully_loaded(users)
655597

656598

657-
class NoLoadTest(_fixtures.FixtureTest):
658-
run_inserts = "once"
659-
run_deletes = None
660-
661-
def test_o2m_noload(self):
662-
Address, addresses, users, User = (
663-
self.classes.Address,
664-
self.tables.addresses,
665-
self.tables.users,
666-
self.classes.User,
667-
)
668-
669-
m = self.mapper_registry.map_imperatively(
670-
User,
671-
users,
672-
properties=dict(
673-
addresses=relationship(
674-
self.mapper_registry.map_imperatively(Address, addresses),
675-
lazy="noload",
676-
)
677-
),
678-
)
679-
q = fixture_session().query(m)
680-
result = [None]
681-
682-
def go():
683-
x = q.filter(User.id == 7).all()
684-
x[0].addresses
685-
result[0] = x
686-
687-
self.assert_sql_count(testing.db, go, 1)
688-
689-
self.assert_result(
690-
result[0], User, {"id": 7, "addresses": (Address, [])}
691-
)
692-
693-
def test_upgrade_o2m_noload_lazyload_option(self):
694-
Address, addresses, users, User = (
695-
self.classes.Address,
696-
self.tables.addresses,
697-
self.tables.users,
698-
self.classes.User,
699-
)
700-
701-
m = self.mapper_registry.map_imperatively(
702-
User,
703-
users,
704-
properties=dict(
705-
addresses=relationship(
706-
self.mapper_registry.map_imperatively(Address, addresses),
707-
lazy="noload",
708-
)
709-
),
710-
)
711-
q = fixture_session().query(m).options(sa.orm.lazyload(User.addresses))
712-
result = [None]
713-
714-
def go():
715-
x = q.filter(User.id == 7).all()
716-
x[0].addresses
717-
result[0] = x
718-
719-
self.sql_count_(2, go)
720-
721-
self.assert_result(
722-
result[0], User, {"id": 7, "addresses": (Address, [{"id": 1}])}
723-
)
724-
725-
def test_m2o_noload_option(self):
726-
Address, addresses, users, User = (
727-
self.classes.Address,
728-
self.tables.addresses,
729-
self.tables.users,
730-
self.classes.User,
731-
)
732-
self.mapper_registry.map_imperatively(
733-
Address, addresses, properties={"user": relationship(User)}
734-
)
735-
self.mapper_registry.map_imperatively(User, users)
736-
s = fixture_session()
737-
a1 = (
738-
s.query(Address)
739-
.filter_by(id=1)
740-
.options(sa.orm.noload(Address.user))
741-
.first()
742-
)
743-
744-
def go():
745-
eq_(a1.user, None)
746-
747-
self.sql_count_(0, go)
748-
749-
750599
class Issue11292Test(fixtures.DeclarativeMappedTest):
751600
@classmethod
752601
def setup_classes(cls):

0 commit comments

Comments
 (0)