feat(pyo3-object_store): Configurable warning on PyExternalObjectStore creation (#550)

Author: kylebarron

pyo3-object_store/Cargo.toml

@@ -13,6 +13,10 @@ rust-version = "1.75"
 # Include the Python type hints as part of the cargo distribution
 include = ["src", "type-hints", "README.md", "LICENSE"]
 
+[features]
+default = ["external-store-warning"]
+external-store-warning = []
+
 [dependencies]
 async-trait = "0.1.85"
 bytes = "1"

pyo3-object_store/README.md

@@ -8,26 +8,26 @@ This provides Python builder classes so that Python users can easily create [`Ar
 
 1. Register the builders.
 
-   ```rs
-   #[pymodule]
-   fn python_module(py: Python, m: &Bound<PyModule>) -> PyResult<()> {
-       pyo3_object_store::register_store_module(py, m, "python_module", "store")?;
-       pyo3_object_store::register_exceptions_module(py, m, "python_module", "exceptions")?;
-   }
-   ```
+    ```rs
+    #[pymodule]
+    fn python_module(py: Python, m: &Bound<PyModule>) -> PyResult<()> {
+        pyo3_object_store::register_store_module(py, m, "python_module", "store")?;
+        pyo3_object_store::register_exceptions_module(py, m, "python_module", "exceptions")?;
+    }
+    ```
 
    This exports the underlying Python classes from your own Rust-Python library.
 
    Refer to [`register_store_module`] and [`register_exceptions_module`] for more information.
 
 2. Accept [`PyObjectStore`] as a parameter in your function exported to Python. Its [`into_dyn`][PyObjectStore::into_dyn] method (or `Into` impl) gives you an [`Arc<dyn ObjectStore>`][object_store::ObjectStore].
 
-   ```rs
-   #[pyfunction]
-   pub fn use_object_store(store: PyObjectStore) {
-       let store: Arc<dyn ObjectStore> = store.into_dyn();
-   }
-   ```
+    ```rs
+    #[pyfunction]
+    pub fn use_object_store(store: PyObjectStore) {
+        let store: Arc<dyn ObjectStore> = store.into_dyn();
+    }
+    ```
 
    You can also accept [`AnyObjectStore`] as a parameter, which wraps [`PyObjectStore`] and [`PyExternalObjectStore`]. This allows you to seamlessly recreate `ObjectStore` instances that users pass in from other Python libraries (like [`obstore`][obstore]) that themselves export `pyo3-object_store` builders.
 
@@ -39,6 +39,10 @@ The [`obstore`][obstore] Python library gives a full real-world example of using
 
 [obstore]: https://developmentseed.org/obstore/latest/
 
+## Feature flags
+
+- `external-store-warning` (enabled by default): Emit a user warning when constructing a `PyExternalObjectStore` (or `AnyObjectStore::PyExternalObjectStore`), to inform users that there may be performance implications due to lack of connection pooling across separately-compiled Python libraries. Disable this feature if you don't want the warning.
+
 ## ABI stability
 
 It's [not currently possible](https://github.com/PyO3/pyo3/issues/1444) to share a `#[pyclass]` across multiple Python libraries, except in special cases where the underlying data has a stable ABI.

pyo3-object_store/src/store.rs

@@ -206,15 +206,17 @@ impl<'py> FromPyObject<'py> for PyExternalObjectStore {
     fn extract_bound(ob: &Bound<'py, PyAny>) -> PyResult<Self> {
         match ob.extract() {
             Ok(inner) => {
-                let py = ob.py();
+                #[cfg(feature = "external-store-warning")]
+                {
+                    let py = ob.py();
 
-                let warnings_mod = py.import(intern!(py, "warnings"))?;
-                let warning = PyRuntimeWarning::new_err(
+                    let warnings_mod = py.import(intern!(py, "warnings"))?;
+                    let warning = PyRuntimeWarning::new_err(
                     "Successfully reconstructed a store defined in another Python module. Connection pooling will not be shared across store instances.",
                 );
-                let args = PyTuple::new(py, vec![warning])?;
-                warnings_mod.call_method1(intern!(py, "warn"), args)?;
-
+                    let args = PyTuple::new(py, vec![warning])?;
+                    warnings_mod.call_method1(intern!(py, "warn"), args)?;
+                }
                 Ok(Self(inner))
             }
             Err(err) => Err(err),