Follow the pattern used by OpenDAL

gistfile1.md

You are modernizing a Rust core library with a Python binding.

Goal

Use OpenDAL (cloned at /path/to/opendal) as a high-quality reference for project structure and Rust↔Python bridging. However, our repository already uses several toolchains; you must evaluate the current setup first, THEN decide which OpenDAL practices should be adopted or not. We only need Python bindings—ignore other languages.

Your responsibilities

1. Scan the current repository:

   • Identify existing Rust toolchains (cargo config, clippy, fmt, build workflow).
   • Identify existing Python toolchains (pyproject layout, test/lint tools, maturin/pyo3 setup).
   • Identify existing directory structure for Rust + Python.
   • Identify gaps or inconsistencies.

2. Study OpenDAL (structurally, not code-copying):

   • How Rust crates and modules are organized.
   • How py-opendal is structured (directory layout, maturin integration, CI/lint/test flows).
   • How they expose Rust APIs to Python cleanly.
   • What additional tools/configs OpenDAL uses that we currently lack.

3. Decide which OpenDAL practices should be referenced:

   • Only adopt parts that actually improve our current workflow.
   • Do NOT replace toolchains we already use correctly.
   • Keep the toolchain minimal and consistent.

4. Implement improvements:

   • Update directory layout if needed.
   • Improve Rust↔Python binding structure (pyo3/maturin or equivalent).
   • Add or refine configs (Cargo.toml, pyproject, clippy/fmt, Python tooling, test layout).
   • Update or add example usage and smoke tests.

5. Verify everything works:

   • For every change, run the required commands (build, install, test) until they pass without errors.
   • Fix any failures automatically.
   • Ensure Python can import the generated extension and run example code successfully.

6. Update documentation:

   • README.md: clear project intro, quickstart, Python usage, dev environment setup, how to build/test.
   • AGENTS.md: architecture summary, Rust core description, Python binding structure, toolchains used, contributor workflow.

Rules

• Only Python binding is needed—simplify where OpenDAL supports multiple languages.
• Do not over-engineer; adopt only practical improvements.
• No copying OpenDAL source—only borrow structure and engineering practice.
• After each step, run the necessary build/test commands until all pass.