refactor(bindings/python): use declarative pymodule syntax

bindings/python/src/lib.rs

@@ -43,72 +43,120 @@ use pyo3_stub_gen::{define_stub_info_gatherer, derive::*};
 pub use services::*;
 
 #[pymodule(gil_used = false)]
-fn _opendal(py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
-    // Add version
-    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
-
-    // Operator module
-    add_pymodule!(py, m, "operator", [Operator, AsyncOperator])?;
-
-    // File module
-    add_pymodule!(py, m, "file", [File, AsyncFile])?;
-
-    // Capability module
-    add_pymodule!(py, m, "capability", [Capability])?;
-
-    // Services module
-    add_pymodule!(py, m, "services", [PyScheme])?;
-
-    // Layers module
-    add_pymodule!(
-        py,
-        m,
-        "layers",
-        [
-            Layer,
-            CapabilityOverrideLayer,
-            RetryLayer,
-            ConcurrentLimitLayer,
-            MimeGuessLayer
-        ]
-    )?;
-
-    // Types module
-    add_pymodule!(
-        py,
-        m,
-        "types",
-        [Entry, EntryMode, Metadata, PresignedRequest]
-    )?;
-
-    m.add_class::<WriteOptions>()?;
-    m.add_class::<ReadOptions>()?;
-    m.add_class::<ListOptions>()?;
-    m.add_class::<StatOptions>()?;
-    m.add_class::<DeleteOptions>()?;
-
-    // Exceptions module
-    add_pyexceptions!(
-        py,
-        m,
-        "exceptions",
-        [
-            Error,
-            Unexpected,
-            Unsupported,
-            ConfigInvalid,
-            NotFound,
-            PermissionDenied,
-            IsADirectory,
-            NotADirectory,
-            AlreadyExists,
-            IsSameFile,
-            ConditionNotMatch,
-            RateLimited,
-            RangeNotSatisfied,
-        ]
-    )?;
-    Ok(())
+mod _opendal {
+    use pyo3::prelude::*;
+
+    #[pymodule]
+    mod operator {
+        #[pymodule_export]
+        use crate::{AsyncOperator, Operator};
+
+        #[pymodule_init]
+        fn init(m: &pyo3::Bound<'_, pyo3::types::PyModule>) -> pyo3::PyResult<()> {
+            crate::register_in_sys(m, "operator")
+        }
+    }
+
+    #[pymodule]
+    mod file {
+        #[pymodule_export]
+        use crate::{AsyncFile, File};
+
+        #[pymodule_init]
+        fn init(m: &pyo3::Bound<'_, pyo3::types::PyModule>) -> pyo3::PyResult<()> {
+            crate::register_in_sys(m, "file")
+        }
+    }
+
+    #[pymodule]
+    mod capability {
+        #[pymodule_export]
+        use crate::Capability;
+
+        #[pymodule_init]
+        fn init(m: &pyo3::Bound<'_, pyo3::types::PyModule>) -> pyo3::PyResult<()> {
+            crate::register_in_sys(m, "capability")
+        }
+    }
+
+    #[pymodule]
+    mod services {
+        #[pymodule_export]
+        use crate::PyScheme;
+
+        #[pymodule_init]
+        fn init(m: &pyo3::Bound<'_, pyo3::types::PyModule>) -> pyo3::PyResult<()> {
+            crate::register_in_sys(m, "services")
+        }
+    }
+
+    #[pymodule]
+    mod layers {
+        #[pymodule_export]
+        use crate::{
+            CapabilityOverrideLayer, ConcurrentLimitLayer, Layer, MimeGuessLayer, RetryLayer,
+        };
+
+        #[pymodule_init]
+        fn init(m: &pyo3::Bound<'_, pyo3::types::PyModule>) -> pyo3::PyResult<()> {
+            crate::register_in_sys(m, "layers")
+        }
+    }
+
+    #[pymodule]
+    mod types {
+        #[pymodule_export]
+        use crate::{Entry, EntryMode, Metadata, PresignedRequest};
+
+        #[pymodule_init]
+        fn init(m: &pyo3::Bound<'_, pyo3::types::PyModule>) -> pyo3::PyResult<()> {
+            crate::register_in_sys(m, "types")
+        }
+    }
+
+    // Exceptions are `PyErr` subtypes, not `#[pyclass]`es, so they are added
+    // procedurally rather than via `#[pymodule_export]`.
+    #[pymodule]
+    mod exceptions {
+        #[pymodule_init]
+        fn init(m: &pyo3::Bound<'_, pyo3::types::PyModule>) -> pyo3::PyResult<()> {
+            use pyo3::prelude::*;
+
+            use crate::{
+                AlreadyExists, ConditionNotMatch, ConfigInvalid, Error, IsADirectory, IsSameFile,
+                NotADirectory, NotFound, PermissionDenied, RangeNotSatisfied, RateLimited,
+                Unexpected, Unsupported, add_exceptions,
+            };
+
+            add_exceptions!(
+                m,
+                [
+                    Error,
+                    Unexpected,
+                    Unsupported,
+                    ConfigInvalid,
+                    NotFound,
+                    PermissionDenied,
+                    IsADirectory,
+                    NotADirectory,
+                    AlreadyExists,
+                    IsSameFile,
+                    ConditionNotMatch,
+                    RateLimited,
+                    RangeNotSatisfied,
+                ]
+            )?;
+            crate::register_in_sys(m, "exceptions")
+        }
+    }
+
+    // Option types live directly on the top-level `opendal` module.
+    #[pymodule_export]
+    use crate::{DeleteOptions, ListOptions, ReadOptions, StatOptions, WriteOptions};
+
+    #[pymodule_export]
+    #[allow(non_upper_case_globals)]
+    pub const __version__: &str = env!("CARGO_PKG_VERSION");
 }
 
 define_stub_info_gatherer!(stub_info);

bindings/python/src/utils.rs

@@ -77,44 +77,30 @@ impl Buffer {
     }
 }
 
-/// Macro to create and register a PyO3 submodule with multiple classes.
-///
-/// Example:
-/// ```rust
-/// add_pymodule!(py, m, "services", [PyScheme, PyOtherClass]);
-/// ```
-#[macro_export]
-macro_rules! add_pymodule {
-    ($py:expr, $parent:expr, $name:expr, [$($cls:ty),* $(,)?]) => {{
-        let sub_module = pyo3::types::PyModule::new($py, $name)?;
-        $(
-            sub_module.add_class::<$cls>()?;
-        )*
-        $parent.add_submodule(&sub_module)?;
-        $py.import("sys")?
-            .getattr("modules")?
-            .set_item(format!("opendal.{}", $name), &sub_module)?;
-        Ok::<_, pyo3::PyErr>(())
-    }};
+/// Register a submodule in `sys.modules` as `opendal.{name}` and set its
+/// `__name__` to match, so dotted imports resolve and the module reports its
+/// qualified name rather than PyO3's default `_opendal.{name}`.
+pub fn register_in_sys(module: &Bound<'_, PyModule>, name: &str) -> PyResult<()> {
+    let qualified_name = format!("opendal.{name}");
+    module.setattr("__name__", &qualified_name)?;
+    module
+        .py()
+        .import("sys")?
+        .getattr("modules")?
+        .set_item(qualified_name, module)?;
+    Ok(())
 }
 
-/// Macro to create and register a PyO3 submodule containing exception types.
+/// Add exception types to a module by their Rust identifier.
 ///
-/// Example:
-/// ```rust
-/// add_pyexceptions!(py, m, "exceptions", [Error, Unexpected]);
-/// ```
+/// `create_exception!` types are `PyErr` subtypes, not `#[pyclass]`es, so they
+/// cannot be listed with `#[pymodule_export]`.
 #[macro_export]
-macro_rules! add_pyexceptions {
-    ($py:expr, $parent:expr, $name:expr, [$($exc:ty),* $(,)?]) => {{
-        let sub_module = pyo3::types::PyModule::new($py, $name)?;
+macro_rules! add_exceptions {
+    ($module:expr, [$($exc:ty),* $(,)?]) => {{
         $(
-            sub_module.add(stringify!($exc), $py.get_type::<$exc>())?;
+            $module.add(stringify!($exc), $module.py().get_type::<$exc>())?;
         )*
-        $parent.add_submodule(&sub_module)?;
-        $py.import("sys")?
-            .getattr("modules")?
-            .set_item(format!("opendal.{}", $name), &sub_module)?;
         Ok::<_, pyo3::PyErr>(())
     }};
 }