rename EvaluatorCompiler to _EvaluatorCompiler

This is a private class, mark as such as some users
may have used this class directly in end-user code.

Change-Id: I2657eff1f9f11b59c0483922ac67d6420a082906
References: #9299

diff --git a/doc/build/changelog/unreleased_20/eval_is_private.rst b/doc/build/changelog/unreleased_20/eval_is_private.rst
new file mode 100644 (file)
index 0000000..0ad43de
--- /dev/null
+++ b/doc/build/changelog/unreleased_20/eval_is_private.rst
@@ -0,0 +1,7 @@
+.. change::
+    :tags: bug, orm
+
+    Marked the internal ``EvaluatorCompiler`` module as private to the ORM, and
+    renamed it to ``_EvaluatorCompiler``. For users that may have been relying
+    upon this, the name ``EvaluatorCompiler`` is still present, however this
+    use is not supported and will be removed in a future release.

diff --git a/lib/sqlalchemy/orm/bulk_persistence.py b/lib/sqlalchemy/orm/bulk_persistence.py
index 924c4cbc8e7b742f5749e60f9a0b0d3fcae308bb..1b3cce47ab11f16e96b37cdd28720716a3dd3ea9 100644 (file)
--- a/lib/sqlalchemy/orm/bulk_persistence.py
+++ b/lib/sqlalchemy/orm/bulk_persistence.py
@@ -871,7 +871,7 @@ class BulkUDCompileState(ORMDMLState):
         mapper = update_options._subject_mapper
         target_cls = mapper.class_
 
-        evaluator_compiler = evaluator.EvaluatorCompiler(target_cls)
+        evaluator_compiler = evaluator._EvaluatorCompiler(target_cls)
         crit = ()
         if statement._where_criteria:
             crit += statement._where_criteria
@@ -1686,7 +1686,7 @@ class BulkORMUpdate(BulkUDCompileState, UpdateDMLState):
         """
         mapper = update_options._subject_mapper
         target_cls = mapper.class_
-        evaluator_compiler = evaluator.EvaluatorCompiler(target_cls)
+        evaluator_compiler = evaluator._EvaluatorCompiler(target_cls)
         resolved_values = cls._get_resolved_values(mapper, statement)
         resolved_keys_as_propnames = cls._resolved_keys_as_propnames(
             mapper, resolved_values

diff --git a/lib/sqlalchemy/orm/evaluator.py b/lib/sqlalchemy/orm/evaluator.py
index dbc5d18eb2f2bd6d5f96d4c3eb27c82036cb12f3..f3796f03d1ed5da7dace5151baeddcad22f40b02 100644 (file)
--- a/lib/sqlalchemy/orm/evaluator.py
+++ b/lib/sqlalchemy/orm/evaluator.py
@@ -6,9 +6,21 @@
 # the MIT License: https://www.opensource.org/licenses/mit-license.php
 # mypy: ignore-errors
 
+"""Evaluation functions used **INTERNALLY** by ORM DML use cases.
+
+
+This module is **private, for internal use by SQLAlchemy**.
+
+.. versionchanged:: 2.0.4 renamed ``EvaluatorCompiler`` to
+   ``_EvaluatorCompiler``.
+
+"""
+
 
 from __future__ import annotations
 
+from typing import Type
+
 from . import exc as orm_exc
 from .base import LoaderCallableStatus
 from .base import PassiveFlag
@@ -18,6 +30,7 @@ from ..sql import and_
 from ..sql import operators
 from ..sql.sqltypes import Integer
 from ..sql.sqltypes import Numeric
+from ..util import warn_deprecated
 
 
 class UnevaluatableError(exc.InvalidRequestError):
@@ -44,7 +57,7 @@ _NO_OBJECT = _NoObject()
 _EXPIRED_OBJECT = _ExpiredObject()
 
 
-class EvaluatorCompiler:
+class _EvaluatorCompiler:
     def __init__(self, target_cls=None):
         self.target_cls = target_cls
 
@@ -340,3 +353,16 @@ class EvaluatorCompiler:
         else:
             val = clause.value
         return lambda obj: val
+
+
+def __getattr__(name: str) -> Type[_EvaluatorCompiler]:
+    if name == "EvaluatorCompiler":
+        warn_deprecated(
+            "Direct use of 'EvaluatorCompiler' is not supported, and this "
+            "name will be removed in a future release.  "
+            "'_EvaluatorCompiler' is for internal use only",
+            "2.0",
+        )
+        return _EvaluatorCompiler
+    else:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

diff --git a/test/orm/dml/test_evaluator.py b/test/orm/dml/test_evaluator.py
index 0a5674740d6a52fcfa27950fab480fc180f953c9..81da16914b769fb1db20b1489cb8c96ed7a6a591 100644 (file)
--- a/test/orm/dml/test_evaluator.py
+++ b/test/orm/dml/test_evaluator.py
@@ -25,7 +25,7 @@ from sqlalchemy.testing.fixtures import fixture_session
 from sqlalchemy.testing.schema import Column
 from sqlalchemy.testing.schema import Table
 
-compiler = evaluator.EvaluatorCompiler()
+compiler = evaluator._EvaluatorCompiler()
 
 
 def eval_eq(clause, testcases=None):
@@ -119,7 +119,7 @@ class EvaluateTest(fixtures.MappedTest):
 
         User = self.classes.User
 
-        compiler = evaluator.EvaluatorCompiler(User)
+        compiler = evaluator._EvaluatorCompiler(User)
 
         with expect_raises_message(
             evaluator.UnevaluatableError,
@@ -130,7 +130,7 @@ class EvaluateTest(fixtures.MappedTest):
     def test_raise_on_unannotated_unmatched_column(self):
         User = self.classes.User
 
-        compiler = evaluator.EvaluatorCompiler(User)
+        compiler = evaluator._EvaluatorCompiler(User)
 
         assert_raises_message(
             evaluator.UnevaluatableError,

diff --git a/test/orm/test_deprecations.py b/test/orm/test_deprecations.py
index 91d733877b6f732f94a0af10b80e7e3380fced58..a23bb7a24dd3382e35ab421bbaa40ab26b33a732 100644 (file)
--- a/test/orm/test_deprecations.py
+++ b/test/orm/test_deprecations.py
@@ -384,6 +384,20 @@ class SynonymTest(QueryTest, AssertsCompiledSQL):
         cls.mapper_registry.map_imperatively(Keyword, keywords)
 
 
+class MiscDeprecationsTest(fixtures.TestBase):
+    def test_evaluator_is_private(self):
+        with expect_deprecated(
+            "Direct use of 'EvaluatorCompiler' is not supported, and this "
+            "name will be removed in a future release.  "
+            "'_EvaluatorCompiler' is for internal use only"
+        ):
+            from sqlalchemy.orm.evaluator import EvaluatorCompiler
+
+        from sqlalchemy.orm.evaluator import _EvaluatorCompiler
+
+        is_(EvaluatorCompiler, _EvaluatorCompiler)
+
+
 class DeprecatedQueryTest(_fixtures.FixtureTest, AssertsCompiledSQL):
     __dialect__ = "default"