add a note to contains_eager re: propcomparator.and_

Change-Id: I5555db3a0e94a92a15759f64b6298c4b2800d183
References: https://github.com/sqlalchemy/sqlalchemy/discussions/9898#discussioncomment-6404539

diff --git a/doc/build/orm/queryguide/relationships.rst b/doc/build/orm/queryguide/relationships.rst
index 7642c70a1a6c52adb8a27164d722aa1bf646085f..30c8b1906fc9c2230d5b57877fac1166ba3d99fc 100644 (file)
--- a/doc/build/orm/queryguide/relationships.rst
+++ b/doc/build/orm/queryguide/relationships.rst
@@ -1132,6 +1132,17 @@ that we can opt to **modify** what values the collection is intended to store,
 by writing our SQL to load a subset of elements for collections or
 scalar attributes.
 
+.. tip::  SQLAlchemy now has a **much simpler way to do this**, by allowing
+   WHERE criteria to be added directly to loader options such as
+   :func:`_orm.joinedload`
+   and :func:`_orm.selectinload` using :meth:`.PropComparator.and_`.  See
+   the section :ref:`loader_option_criteria` for examples.
+
+   The techniques described here still apply if the related collection is
+   to be queried using SQL criteria or modifiers more complex than a simple
+   WHERE clause.
+
+
 As an example, we can load a ``User`` object and eagerly load only particular
 addresses into its ``.addresses`` collection by filtering the joined data,
 routing it using :func:`_orm.contains_eager`, also using
@@ -1173,6 +1184,11 @@ in fact associated with the collection.
    assuming default session settings, or the :meth:`.Session.expire_all`
    or :meth:`.Session.expire` methods are used.
 
+.. seealso::
+
+    :ref:`loader_option_criteria` - modern API allowing WHERE criteria directly
+    within any relationship loader option
+
 
 Relationship Loader API
 -----------------------

diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py
index 0315737d660a2cd3f7e4663eadfd9ba752f8aff9..5cf5ec7b4b7df72078eb975534388d24d8888fa6 100644 (file)
--- a/lib/sqlalchemy/engine/url.py
+++ b/lib/sqlalchemy/engine/url.py
@@ -836,6 +836,12 @@ def make_url(name_or_url: Union[str, URL]) -> URL:
 
     if isinstance(name_or_url, str):
         return _parse_url(name_or_url)
+    elif not isinstance(name_or_url, URL) and not hasattr(
+        name_or_url, "_sqla_is_testing_if_this_is_a_mock_object"
+    ):
+        raise exc.ArgumentError(
+            f"Expected string or URL object, got {name_or_url!r}"
+        )
     else:
         return name_or_url