feat: add a basic async python client starting point (#1014)

This changes `lancedb` from a "pure python" setuptools project to a
maturin project and adds a rust lancedb dependency.

The async python client is extremely minimal (only `connect` and
`Connection.table_names` are supported). The purpose of this PR is to
get the infrastructure in place for building out the rest of the async
client.

Although this is not technically a breaking change (no APIs are
changing) it is still a considerable change in the way the wheels are
built because they now include the native shared library.

python/src/connection.rs

@@ -0,0 +1,66 @@
+// Copyright 2024 Lance Developers.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::time::Duration;
+
+use lancedb::connection::Connection as LanceConnection;
+use pyo3::{pyclass, pyfunction, pymethods, PyAny, PyRef, PyResult, Python};
+use pyo3_asyncio::tokio::future_into_py;
+
+use crate::error::PythonErrorExt;
+
+#[pyclass]
+pub struct Connection {
+    inner: LanceConnection,
+}
+
+#[pymethods]
+impl Connection {
+    pub fn table_names(self_: PyRef<'_, Self>) -> PyResult<&PyAny> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            inner.table_names().await.infer_error()
+        })
+    }
+}
+
+#[pyfunction]
+pub fn connect(
+    py: Python,
+    uri: String,
+    api_key: Option<String>,
+    region: Option<String>,
+    host_override: Option<String>,
+    read_consistency_interval: Option<f64>,
+) -> PyResult<&PyAny> {
+    future_into_py(py, async move {
+        let mut builder = lancedb::connect(&uri);
+        if let Some(api_key) = api_key {
+            builder = builder.api_key(&api_key);
+        }
+        if let Some(region) = region {
+            builder = builder.region(&region);
+        }
+        if let Some(host_override) = host_override {
+            builder = builder.host_override(&host_override);
+        }
+        if let Some(read_consistency_interval) = read_consistency_interval {
+            let read_consistency_interval = Duration::from_secs_f64(read_consistency_interval);
+            builder = builder.read_consistency_interval(read_consistency_interval);
+        }
+        Ok(Connection {
+            inner: builder.execute().await.infer_error()?,
+        })
+    })
+}

python/src/error.rs

@@ -0,0 +1,61 @@
+// Copyright 2024 Lance Developers.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use pyo3::{
+    exceptions::{PyOSError, PyRuntimeError, PyValueError},
+    PyResult,
+};
+
+use lancedb::error::Error as LanceError;
+
+pub trait PythonErrorExt<T> {
+    /// Convert to a python error based on the Lance error type
+    fn infer_error(self) -> PyResult<T>;
+    /// Convert to OSError
+    fn os_error(self) -> PyResult<T>;
+    /// Convert to RuntimeError
+    fn runtime_error(self) -> PyResult<T>;
+    /// Convert to ValueError
+    fn value_error(self) -> PyResult<T>;
+}
+
+impl<T> PythonErrorExt<T> for std::result::Result<T, LanceError> {
+    fn infer_error(self) -> PyResult<T> {
+        match &self {
+            Ok(_) => Ok(self.unwrap()),
+            Err(err) => match err {
+                LanceError::InvalidTableName { .. } => self.value_error(),
+                LanceError::TableNotFound { .. } => self.value_error(),
+                LanceError::TableAlreadyExists { .. } => self.runtime_error(),
+                LanceError::CreateDir { .. } => self.os_error(),
+                LanceError::Store { .. } => self.runtime_error(),
+                LanceError::Lance { .. } => self.runtime_error(),
+                LanceError::Schema { .. } => self.value_error(),
+                LanceError::Runtime { .. } => self.runtime_error(),
+            },
+        }
+    }
+
+    fn os_error(self) -> PyResult<T> {
+        self.map_err(|err| PyOSError::new_err(err.to_string()))
+    }
+
+    fn runtime_error(self) -> PyResult<T> {
+        self.map_err(|err| PyRuntimeError::new_err(err.to_string()))
+    }
+
+    fn value_error(self) -> PyResult<T> {
+        self.map_err(|err| PyValueError::new_err(err.to_string()))
+    }
+}

python/src/lib.rs

@@ -0,0 +1,32 @@
+// Copyright 2024 Lance Developers.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use connection::{connect, Connection};
+use env_logger::Env;
+use pyo3::{pymodule, types::PyModule, wrap_pyfunction, PyResult, Python};
+
+pub mod connection;
+pub(crate) mod error;
+
+#[pymodule]
+pub fn _lancedb(_py: Python, m: &PyModule) -> PyResult<()> {
+    let env = Env::new()
+        .filter_or("LANCEDB_LOG", "warn")
+        .write_style("LANCEDB_LOG_STYLE");
+    env_logger::init_from_env(env);
+    m.add_class::<Connection>()?;
+    m.add_function(wrap_pyfunction!(connect, m)?)?;
+    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
+    Ok(())
+}