feat: python runtime facade for interop

Signed-off-by: Sam Gammon <[email protected]>

Author: sgammon

elide/runtime/python/BUILD.bazel

@@ -5,6 +5,7 @@ load(
 )
 
 PYTHON_BUILTINS = [
+  "elide",
   "sqlite3",
 ]
 
@@ -13,6 +14,11 @@ py_runtime(
     deps = ["//elide/runtime/python/%s" % m for m in PYTHON_BUILTINS],
 )
 
+alias(
+    name = "python",
+    actual = ":dist",
+)
+
 ## -- Distribution -- ##
 
 runtime_dist(

elide/runtime/python/elide/BUILD.bazel

@@ -0,0 +1,12 @@
+load(
+    "//tools:defs.bzl",
+    "py_library",
+)
+package(
+    default_visibility = ["//visibility:public"],
+)
+
+py_library(
+  name = "elide",
+  srcs = ["__init__.py"],
+)

elide/runtime/python/elide/__init__.py

@@ -15,4 +15,71 @@
  Defines Elide-specific APIs.
 """
 
-hello = "hi"
+import polyglot
+
+# Registered polyglot bindings.
+registered_py_symbols = {}
+
+# Internal factory method for binding management.
+def __bind_factory(name = None):
+    def binder(obj):
+        symbol = name or obj.__name__
+        if symbol in registered_py_symbols:
+            raise ValueError(f"Symbol '{symbol}' already bound for polyglot access.")
+
+        # register the symbol
+        polyglot.export_value(
+            symbol,
+            obj
+        )
+        return obj
+    return binder
+
+def bind(obj):
+    """Binds a Python symbol within Elide's polyglot context; this exposes the symbol (at its regular name)
+       for cross-language interop.
+
+       This function is designed to be used as a parameterless decorator. For example:
+
+       ```python
+       from elide import bind
+
+       @bind
+       def my_function():
+           # do something
+           pass
+       ```
+
+       `bind` specifically exists to reuse a symbol's name as-defined in Python. To bind the symbol to a
+       different name, use `poly`.
+
+         :param obj: The Python object to bind for polyglot access.
+         :return: The bound object, which is also registered for polyglot access.
+       """
+
+    return __bind_factory()(obj)
+
+def poly(name = None):
+    """Binds a Python symbol within Elide's polyglot context; this exposes the symbol at its regular given
+       name, or at the name provided as a parameter, for cross-language interop.
+
+       This function is designed to be used as a parameterized decorator. For example:
+
+       ```python
+       from elide import poly
+
+       @poly("my_function")
+       def some_function():
+         # do something
+         pass
+       ```
+
+       `poly` must be called even if no name is provided. `bind` is also provided as a shorthand which needs
+       not be called, takes no parameters, and always uses the name of the symbol as defined in Python.
+
+         :param name: The name to bind the symbol to for polyglot access. If not provided, the symbol's name
+                        as defined in Python will be used.
+         :return: The bound object, which is also registered for polyglot access.
+       """
+
+    return __bind_factory(name)

elide/runtime/python/sqlite3/__init__.py

@@ -15,5 +15,3 @@
  Defines the Python-side SQLite3 API for use in Elide; roughly follows the standardized
  Python `sqlite3` module API.
 """
-
-hello = "hi"