Rename "py_cel.Cel" class to "py_cel.Env" for consistency

dmitriplotnikov · copybara-github · commit bc409f6aca04 · 2026-01-09T15:36:51.000-08:00
Documentation of CEL ubiquitously refers to this object as
"enviroment". The API should reflect this convention.

PiperOrigin-RevId: 853942563
diff --git a/BUILD b/BUILD
@@ -12,12 +12,12 @@ exports_files(["LICENSE"])
 pybind_extension(
     name = "py_cel",
     srcs = [
-        "py_cel.cc",
-        "py_cel.h",
         "py_cel_activation.cc",
         "py_cel_activation.h",
         "py_cel_arena.cc",
         "py_cel_arena.h",
+        "py_cel_env.cc",
+        "py_cel_env.h",
         "py_cel_env_internal.cc",
         "py_cel_env_internal.h",
         "py_cel_expression.cc",
diff --git a/conformance/conformance_test.py b/conformance/conformance_test.py
@@ -158,14 +158,14 @@ def _run_conformance_test(self, simple_test: simple_pb.SimpleTest):
         break
 
     self.descriptor_pool = descriptor_pool.Default()
-    self.cel = cel.Cel(
+    self.env = cel.NewEnv(
         self.descriptor_pool,
         variables=decls,
         extensions=extensions,
         container=simple_test.container,
     )
     try:
-      compiled_expr = self.cel.compile(
+      compiled_expr = self.env.compile(
           simple_test.expr, disable_check=simple_test.disable_check
       )
     except Exception as e:  # pylint: disable=broad-except
@@ -188,7 +188,7 @@ def _run_conformance_test(self, simple_test: simple_pb.SimpleTest):
     for key, value in simple_test.bindings.items():
       values[key] = self._convert_value(value.value)
 
-    act = self.cel.Activation(values)
+    act = self.env.Activation(values)
     try:
       res = compiled_expr.eval(act)
     except Exception as e:  # pylint: disable=broad-except
diff --git a/custom_ext/custom_ext_test.py b/custom_ext/custom_ext_test.py
@@ -40,16 +40,16 @@ def _compile_expr(
   ) -> cel.Expression:
     """Creates a CEL expression for the given extension and compiles the expression."""
     self.descriptor_pool = descriptor_pool.Default()
-    self.cel = cel.Cel(
+    self.env = cel.NewEnv(
         self.descriptor_pool,
         variables={},
         extensions=[ext()],
     )
-    return self.cel.compile(expression)
+    return self.env.compile(expression)
 
   def _create_activation(self, impl) -> cel.Activation:
     """Creates a CEL Activation with a late-bound translate function."""
-    return self.cel.Activation(
+    return self.env.Activation(
         {},
         functions=[
             cel.Function(
@@ -66,7 +66,7 @@ def test_basic_function(self, ext):
     compiled_expr = self._compile_expr(
         ext, "'Hello, world!'.translate('en', 'es')"
     )
-    act = self.cel.Activation({})
+    act = self.env.Activation({})
     res = compiled_expr.eval(act)
 
     self.assertEqual(res.value(), "¡Hola Mundo!")
@@ -85,7 +85,7 @@ def test_late_bound_function(self, ext):
   @parameterized.named_parameters(EXT_IMPLEMENTATIONS)
   def test_error_no_matching_overload(self, ext):
     compiled_expr = self._compile_expr(ext, "translate_late('Hello, world!')")
-    act = self.cel.Activation(
+    act = self.env.Activation(
         {},
         functions=[
             cel.Function(
diff --git a/py_cel_env.cc b/py_cel_env.cc
@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#include "py_cel.h"
+#include "py_cel_env.h"
 
 #include <Python.h>  // IWYU pragma: keep - Needed for PyObject
 
@@ -38,48 +38,47 @@ namespace cel_python {
 
 namespace py = ::pybind11;
 
-void PyCel::DefinePythonBindings(pybind11::module& m) {
-  py::class_<PyCel, std::shared_ptr<PyCel>> cel_class(m, "Cel");
-  cel_class
-      .def(py::init([](py::object descriptor_pool,
-                       std::optional<std::unordered_map<std::string, PyCelType>>
-                           variables,
-                       std::optional<std::vector<py::object>> extensions,
-                       const std::optional<std::string>& container) {
-             PyObject* pool_ptr = nullptr;
-             if (descriptor_pool.is_none()) {
-               // Replicates python's `descriptor_pool.Default()`
-               pool_ptr = py::module::import("google.protobuf.descriptor_pool")
-                              .attr("Default")()
-                              .ptr();
-             } else {
-               pool_ptr = descriptor_pool.ptr();
-             }
+void PyCelEnv::DefinePythonBindings(pybind11::module& m) {
+  py::class_<PyCelEnv, std::shared_ptr<PyCelEnv>> cel_class(m, "Env");
+  m.def(
+      "NewEnv",
+      [](py::object descriptor_pool,
+         std::optional<std::unordered_map<std::string, PyCelType>> variables,
+         std::optional<std::vector<py::object>> extensions,
+         const std::optional<std::string>& container) {
+        PyObject* pool_ptr = nullptr;
+        if (descriptor_pool.is_none()) {
+          // Replicates python's `descriptor_pool.Default()`
+          pool_ptr = py::module::import("google.protobuf.descriptor_pool")
+                         .attr("Default")()
+                         .ptr();
+        } else {
+          pool_ptr = descriptor_pool.ptr();
+        }
 
-             std::vector<PyObject*> ext_ptrs;
-             if (extensions) {
-               ext_ptrs.reserve(extensions->size());
-               for (const auto& ext : *extensions) {
-                 ext_ptrs.push_back(ext.ptr());
-               }
-             }
+        std::vector<PyObject*> ext_ptrs;
+        if (extensions) {
+          ext_ptrs.reserve(extensions->size());
+          for (const auto& ext : *extensions) {
+            ext_ptrs.push_back(ext.ptr());
+          }
+        }
 
-             return std::make_shared<PyCel>(
-                 pool_ptr,
-                 std::move(variables).value_or(
-                     std::unordered_map<std::string, PyCelType>{}),
-                 ext_ptrs, container.value_or(""));
-           }),
-           py::arg("descriptor_pool") = py::none(),
-           py::arg("variables") = py::none(),
-           py::arg("extensions") = py::none(),
-           py::arg("container") = py::none())
-      .def("compile", &PyCel::Compile, py::arg("expression"),
+        return PyCelEnv(pool_ptr,
+                        std::move(variables).value_or(
+                            std::unordered_map<std::string, PyCelType>{}),
+                        ext_ptrs, container.value_or(""));
+      },
+      py::arg("descriptor_pool") = py::none(),
+      py::arg("variables") = py::none(), py::arg("extensions") = py::none(),
+      py::arg("container") = py::none());
+  cel_class
+      .def("compile", &PyCelEnv::Compile, py::arg("expression"),
            py::arg("disable_check") = false)
-      .def("deserialize", &PyCel::Deserialize, py::arg("serialized"))
+      .def("deserialize", &PyCelEnv::Deserialize, py::arg("serialized"))
       .def(
           "Activation",
-          [](PyCel& self,
+          [](PyCelEnv& self,
              std::optional<std::unordered_map<std::string, py::object>> data,
              const std::optional<std::vector<std::shared_ptr<PyCelFunction>>>&
                  functions,
@@ -103,30 +102,31 @@ void PyCel::DefinePythonBindings(pybind11::module& m) {
           py::arg("arena") = nullptr);
 }
 
-PyCel::PyCel(PyObject* descriptor_pool,
-             std::unordered_map<std::string, PyCelType> variable_types,
-             const std::vector<PyObject*>& extensions, std::string container)
+PyCelEnv::PyCelEnv(PyObject* descriptor_pool,
+                   std::unordered_map<std::string, PyCelType> variable_types,
+                   const std::vector<PyObject*>& extensions,
+                   std::string container)
     : env_(std::make_unique<PyCelEnvInternal>(
           descriptor_pool, std::move(variable_types), extensions,
           std::move(container))) {
   ABSL_CHECK(PyGILState_Check());
 }
 
-PyCel::~PyCel() = default;
+PyCelEnv::~PyCelEnv() = default;
 
-std::shared_ptr<PyCelActivation> PyCel::NewActivation(
+std::shared_ptr<PyCelActivation> PyCelEnv::NewActivation(
     const std::unordered_map<std::string, PyObject*>& data,
     const std::vector<std::shared_ptr<PyCelFunction>>& functions,
     const std::shared_ptr<PyCelArena>& arena) {
   return std::make_shared<PyCelActivation>(env_, data, functions, arena);
 }
 
-absl::StatusOr<PyCelExpression> PyCel::Compile(const std::string& cel_expr,
-                                               bool disable_check) {
+absl::StatusOr<PyCelExpression> PyCelEnv::Compile(const std::string& cel_expr,
+                                                  bool disable_check) {
   return PyCelExpression::Compile(env_, cel_expr, disable_check);
 }
 
-absl::StatusOr<PyCelExpression> PyCel::Deserialize(
+absl::StatusOr<PyCelExpression> PyCelEnv::Deserialize(
     const std::string& serialized_expr) {
   return PyCelExpression::Deserialize(env_, serialized_expr);
 }
diff --git a/py_cel_env.h b/py_cel_env.h
@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#ifndef THIRD_PARTY_CEL_PYTHON_PY_CEL_H_
-#define THIRD_PARTY_CEL_PYTHON_PY_CEL_H_
+#ifndef THIRD_PARTY_CEL_PYTHON_PY_CEL_ENV_H_
+#define THIRD_PARTY_CEL_PYTHON_PY_CEL_ENV_H_
 
 #include <Python.h>  // IWYU pragma: keep - Needed for PyObject
 
@@ -41,21 +41,16 @@ class RuntimeOptions;
 // All classes and functions in this namespace are pybind11-wrapped.
 namespace cel_python {
 
-class PyCel;
-class PyCelEnv;
+class PyCelEnvInternal;
 class PyCelFunction;
 class PyMessageFactory;
 
 // CEL environment. Provides access to the CEL compiler.
-class PyCel {
+class PyCelEnv {
  public:
   static void DefinePythonBindings(pybind11::module& m);
 
-  explicit PyCel(PyObject* descriptor_pool = nullptr,
-                 std::unordered_map<std::string, PyCelType> variable_types = {},
-                 const std::vector<PyObject*>& extensions = {},
-                 std::string container = "");
-  ~PyCel();
+  ~PyCelEnv();
 
   absl::StatusOr<PyCelExpression> Compile(const std::string& cel_expr,
                                           bool disable_check = false);
@@ -69,9 +64,13 @@ class PyCel {
   std::shared_ptr<PyCelEnvInternal> GetEnv() { return env_; }
 
  private:
+  // Private constructor. Use `py_cel.NewEnv()` in python to obtain an instance.
+  PyCelEnv(PyObject* descriptor_pool,
+           std::unordered_map<std::string, PyCelType> variable_types,
+           const std::vector<PyObject*>& extensions, std::string container);
   std::shared_ptr<PyCelEnvInternal> env_;
 };
 
 }  // namespace cel_python
 
-#endif  // THIRD_PARTY_CEL_PYTHON_PY_CEL_H_
+#endif  // THIRD_PARTY_CEL_PYTHON_PY_CEL_ENV_H_
diff --git a/py_cel_module.cc b/py_cel_module.cc
@@ -12,9 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#include "py_cel.h"
 #include "py_cel_activation.h"
 #include "py_cel_arena.h"
+#include "py_cel_env.h"
 #include "py_cel_expression.h"
 #include "py_cel_function.h"
 #include "py_cel_function_decl.h"
@@ -40,7 +40,7 @@ PYBIND11_MODULE(py_cel, m) {
   PyCelFunctionDecl::DefinePythonBindings(m);
   PyCelPythonExtension::DefinePythonBindings(m);
   PyCelFunction::DefinePythonBindings(m);
-  PyCel::DefinePythonBindings(m);
+  PyCelEnv::DefinePythonBindings(m);
 }
 
 }  // namespace cel_python
diff --git a/py_cel_test.py b/py_cel_test.py
diff --git a/py_cel_value.cc b/py_cel_value.cc
