refactor(binding/python): Add multiple custom exception for each of error code in Rust Core

bindings/python/python/opendal/__init__.pyi

@@ -19,8 +19,6 @@ from typing import AsyncIterable, Iterable, Optional
 
 from opendal.layers import Layer
 
-class Error(Exception): ...
-
 class Operator:
     def __init__(self, scheme: str, **kwargs): ...
     def layer(self, layer: Layer): ...

bindings/python/python/opendal/exceptions.pyi

@@ -0,0 +1,86 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+class Error(Exception):
+    """Base class for exceptions in this module."""
+
+    pass
+
+class Unexpected(Error):
+    """Unexpected errors"""
+
+    pass
+
+class Unsupported(Error):
+    """Unsupported operation"""
+
+    pass
+
+class ConfigInvalid(Error):
+    """Config is invalid"""
+
+    pass
+
+class NotFound(Error):
+    """Not found"""
+
+    pass
+
+class PermissionDenied(Error):
+    """Permission denied"""
+
+    pass
+
+class IsADirectory(Error):
+    """Is a directory"""
+
+    pass
+
+class NotADirectory(Error):
+    """Not a directory"""
+
+    pass
+
+class AlreadyExists(Error):
+    """Already exists"""
+
+    pass
+
+class IsSameFile(Error):
+    """Is same file"""
+
+    pass
+
+class ConditionNotMatch(Error):
+    """Condition not match"""
+
+    pass
+
+class ContentTruncated(Error):
+    """Content truncated"""
+
+    pass
+
+class ContentIncomplete(Error):
+    """Content incomplete"""
+
+    pass
+
+class InvalidInput(Error):
+    """Invalid input"""
+
+    pass

bindings/python/src/errors.rs

@@ -0,0 +1,61 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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::create_exception;
+use pyo3::exceptions::PyException;
+
+use crate::*;
+
+create_exception!(opendal, Error, PyException, "OpenDAL Base Exception");
+create_exception!(opendal, UnexpectedError, Error, "Unexpected errors");
+create_exception!(opendal, UnsupportedError, Error, "Unsupported operation");
+create_exception!(opendal, ConfigInvalidError, Error, "Config is invalid");
+create_exception!(opendal, NotFoundError, Error, "Not found");
+create_exception!(opendal, PermissionDeniedError, Error, "Permission denied");
+create_exception!(opendal, IsADirectoryError, Error, "Is a directory");
+create_exception!(opendal, NotADirectoryError, Error, "Not a directory");
+create_exception!(opendal, AlreadyExistsError, Error, "Already exists");
+create_exception!(opendal, IsSameFileError, Error, "Is same file");
+create_exception!(
+    opendal,
+    ConditionNotMatchError,
+    Error,
+    "Condition not match"
+);
+create_exception!(opendal, ContentTruncatedError, Error, "Content truncated");
+create_exception!(opendal, ContentIncompleteError, Error, "Content incomplete");
+create_exception!(opendal, InvalidInputError, Error, "Invalid input");
+
+pub fn format_pyerr(err: ocore::Error) -> PyErr {
+    use ocore::ErrorKind::*;
+    match err.kind() {
+        Unexpected => UnexpectedError::new_err(err.to_string()),
+        Unsupported => UnsupportedError::new_err(err.to_string()),
+        ConfigInvalid => ConfigInvalidError::new_err(err.to_string()),
+        NotFound => NotFoundError::new_err(err.to_string()),
+        PermissionDenied => PermissionDeniedError::new_err(err.to_string()),
+        IsADirectory => IsADirectoryError::new_err(err.to_string()),
+        NotADirectory => NotADirectoryError::new_err(err.to_string()),
+        AlreadyExists => AlreadyExistsError::new_err(err.to_string()),
+        IsSameFile => IsSameFileError::new_err(err.to_string()),
+        ConditionNotMatch => ConditionNotMatchError::new_err(err.to_string()),
+        ContentTruncated => ContentTruncatedError::new_err(err.to_string()),
+        ContentIncomplete => ContentIncompleteError::new_err(err.to_string()),
+        InvalidInput => InvalidInputError::new_err(err.to_string()),
+        _ => UnexpectedError::new_err(err.to_string()),
+    }
+}

bindings/python/src/lib.rs

@@ -37,6 +37,8 @@ mod file;
 pub use file::*;
 mod utils;
 pub use utils::*;
+mod errors;
+pub use errors::*;
 
 /// OpenDAL Python binding
 ///
@@ -82,7 +84,6 @@ fn _opendal(py: Python, m: &PyModule) -> PyResult<()> {
     m.add_class::<Metadata>()?;
     m.add_class::<PresignedRequest>()?;
     m.add_class::<Capability>()?;
-    m.add("Error", py.get_type::<Error>())?;
 
     // Layer module
     let layers_module = PyModule::new(py, "layers")?;
@@ -93,5 +94,24 @@ fn _opendal(py: Python, m: &PyModule) -> PyResult<()> {
         .getattr("modules")?
         .set_item("opendal.layers", layers_module)?;
 
+    let exception_module = PyModule::new(py, "exceptions")?;
+    exception_module.add("Error", py.get_type::<Error>())?;
+    exception_module.add("Unexpected", py.get_type::<UnexpectedError>())?;
+    exception_module.add("Unsupported", py.get_type::<UnsupportedError>())?;
+    exception_module.add("ConfigInvalid", py.get_type::<ConfigInvalidError>())?;
+    exception_module.add("NotFound", py.get_type::<NotFoundError>())?;
+    exception_module.add("PermissionDenied", py.get_type::<PermissionDeniedError>())?;
+    exception_module.add("IsADirectory", py.get_type::<IsADirectoryError>())?;
+    exception_module.add("NotADirectory", py.get_type::<NotADirectoryError>())?;
+    exception_module.add("AlreadyExists", py.get_type::<AlreadyExistsError>())?;
+    exception_module.add("IsSameFile", py.get_type::<IsSameFileError>())?;
+    exception_module.add("ConditionNotMatch", py.get_type::<ConditionNotMatchError>())?;
+    exception_module.add("ContentTruncated", py.get_type::<ContentTruncatedError>())?;
+    exception_module.add("ContentIncomplete", py.get_type::<ContentIncompleteError>())?;
+    exception_module.add("InvalidInput", py.get_type::<InvalidInputError>())?;
+    m.add_submodule(exception_module)?;
+    py.import("sys")?
+        .getattr("modules")?
+        .set_item("opendal.exceptions", exception_module)?;
     Ok(())
 }

bindings/python/src/operator.rs

@@ -86,7 +86,7 @@ impl Operator {
             let w = this.writer(&path).map_err(format_pyerr)?;
             Ok(File::new_writer(w))
         } else {
-            Err(Error::new_err(format!(
+            Err(UnsupportedError::new_err(format!(
                 "OpenDAL doesn't support mode: {mode}"
             )))
         }
@@ -245,7 +245,7 @@ impl AsyncOperator {
                 let w = this.writer(&path).await.map_err(format_pyerr)?;
                 Ok(AsyncFile::new_writer(w))
             } else {
-                Err(Error::new_err(format!(
+                Err(UnsupportedError::new_err(format!(
                     "OpenDAL doesn't support mode: {mode}"
                 )))
             }
@@ -547,9 +547,11 @@ impl PresignedRequest {
         let mut headers = HashMap::new();
         for (k, v) in self.0.header().iter() {
             let k = k.as_str();
-            let v = v.to_str().map_err(|err| Error::new_err(err.to_string()))?;
+            let v = v
+                .to_str()
+                .map_err(|err| UnexpectedError::new_err(err.to_string()))?;
             if headers.insert(k, v).is_some() {
-                return Err(Error::new_err("duplicate header"));
+                return Err(UnexpectedError::new_err("duplicate header"));
             }
         }
         Ok(headers)

bindings/python/src/utils.rs

@@ -17,20 +17,10 @@
 
 use std::os::raw::c_int;
 
-use pyo3::create_exception;
-use pyo3::exceptions::PyException;
-use pyo3::exceptions::PyFileExistsError;
-use pyo3::exceptions::PyFileNotFoundError;
-use pyo3::exceptions::PyNotImplementedError;
-use pyo3::exceptions::PyPermissionError;
 use pyo3::ffi;
 use pyo3::prelude::*;
 use pyo3::AsPyPointer;
 
-use crate::*;
-
-create_exception!(opendal, Error, PyException, "OpenDAL related errors");
-
 /// A bytes-like object that implements buffer protocol.
 #[pyclass(module = "opendal")]
 pub struct Buffer {
@@ -83,14 +73,3 @@ impl Buffer {
         Ok(())
     }
 }
-
-pub fn format_pyerr(err: ocore::Error) -> PyErr {
-    use ocore::ErrorKind::*;
-    match err.kind() {
-        NotFound => PyFileNotFoundError::new_err(err.to_string()),
-        AlreadyExists => PyFileExistsError::new_err(err.to_string()),
-        PermissionDenied => PyPermissionError::new_err(err.to_string()),
-        Unsupported => PyNotImplementedError::new_err(err.to_string()),
-        _ => Error::new_err(err.to_string()),
-    }
-}

bindings/python/tests/test_async_copy.py

@@ -16,10 +16,10 @@
 # under the License.
 
 import os
-from random import randint
 from uuid import uuid4
 
 import pytest
+from opendal.exceptions import IsADirectory, IsSameFile, NotFound
 
 
 @pytest.mark.asyncio
@@ -42,7 +42,7 @@ async def test_async_copy(service_name, operator, async_operator):
 async def test_async_copy_non_exist(service_name, operator, async_operator):
     source_path = f"random_file_{str(uuid4())}"
     target_path = f"random_file_{str(uuid4())}"
-    with pytest.raises(Exception) as e_info:
+    with pytest.raises(NotFound) :
         await async_operator.copy(source_path, target_path)
 
 
@@ -52,7 +52,7 @@ async def test_async_copy_source_directory(service_name, operator, async_operato
     source_path = f"random_file_{str(uuid4())}/"
     await async_operator.create_dir(source_path)
     target_path = f"random_file_{str(uuid4())}"
-    with pytest.raises(Exception) as e_info:
+    with pytest.raises(IsADirectory) :
         await async_operator.copy(source_path, target_path)
 
 
@@ -64,7 +64,7 @@ async def test_async_copy_target_directory(service_name, operator, async_operato
     await async_operator.write(source_path, content)
     target_path = f"random_file_{str(uuid4())}/"
     await async_operator.create_dir(target_path)
-    with pytest.raises(Exception) as e_info:
+    with pytest.raises(IsADirectory) :
         await async_operator.copy(source_path, target_path)
     await async_operator.delete(source_path)
     await async_operator.delete(target_path)
@@ -76,7 +76,7 @@ async def test_async_copy_self(service_name, operator, async_operator):
     source_path = f"random_file_{str(uuid4())}"
     content = os.urandom(1024)
     await async_operator.write(source_path, content)
-    with pytest.raises(Exception) as e_info:
+    with pytest.raises(IsSameFile) :
         await async_operator.copy(source_path, source_path)
     await async_operator.delete(source_path)
 

bindings/python/tests/test_async_delete.py

@@ -16,10 +16,10 @@
 # under the License.
 
 import os
-from random import randint
 from uuid import uuid4
 
 import pytest
+from opendal.exceptions import NotFound
 
 
 @pytest.mark.asyncio
@@ -43,6 +43,6 @@ async def test_async_remove_all(service_name, operator, async_operator):
     await async_operator.remove_all(f"{parent}/x/")
     for path in excepted:
         if not path.endswith("/"):
-            with pytest.raises(FileNotFoundError) as e_info:
+            with pytest.raises(NotFound) :
                 await async_operator.read(f"{parent}/{path}")
     await async_operator.remove_all(f"{parent}/")