Creating multiple constructors & shorter bindings (similar to pybind11)

[phil-zxx]

Say I have the following C++ Date class. Using pybind11 I can easily wrap it to be used in Python:

/* date.hpp */
#include <string>

class Date
{
public:
    int year, month, day;
    
    Date(int year, int month, int day);
    Date(const std::string& yyyymmdd);

    Date add_days(int N) const;  // Returns new date with N days added
    bool is_weekend() const;     // Returns true if date is Sat or Sun
};

/* date_bindings.cpp */
#include <pybind11/pybind11.h>
#include <date.hpp>

namespace py = pybind11;

PYBIND11_MODULE(date_py, m) {
    py::class_<Date>(m, "Date")
        .def(py::init<int, int, int>(),      py::arg("year"), py::arg("month"), py::arg("day"))
        .def(py::init<const std::string&>(), py::arg("yyyymmdd"))
        .def("add_days",        &Date::add_days, py::arg("N"))
        .def("is_weekend",      &Date::is_weekend)
        .def_readwrite("year",  &Date::year)
        .def_readwrite("month", &Date::month)
        .def_readwrite("day",   &Date::day);
}

That's 15 lines of code for my bindings using pybind11.

Now, I want to do the same in Rust. So I implemented my Date class and then used PyO3 to wrap it:

/* date.rs */

#[derive(Debug)]
pub struct Date {
    pub year: u16,
    pub month: u8,
    pub day: u8
}

impl Date {
    pub fn from_ymd(year: u16, month: u8, day: u8) -> Date {
        // ...
    }

    pub fn from_str(s: &str) -> Date {
        // ...
    }

    pub const fn add_days(&self, N: u8) -> Self {
        // ...
    }
    pub const fn is_weekend(&self) -> bool {
        // ...
    }
}

/* date_bindings.rs */

use pyo3::prelude::*;
use my_library::Date;

#[pyclass(name = "Date")]
struct DatePy {
    inner: Date
}

#[pymethods]
impl DatePy {
    #[new]
    fn new(year: u16, month: u8, day: u8) -> Self {
        DatePy{inner: Date::from_ymd(year, month, day)}
    }
    fn add_days(&self, N: u8) -> PyResult<Self> {
        Ok(DatePy{inner: self._date.add_days(N)})
    }
    fn is_weekend(&self) -> PyResult<bool> {
        Ok(self.inner.is_weekend())
    }
    #[getter]
    fn get_year(&self) -> PyResult<u16> {
        Ok(self.inner.year)
    }
    #[getter]
    fn get_month(&self) -> PyResult<u8> {
        Ok(self.inner.month)
    }
    #[getter]
    fn get_day(&self) -> PyResult<u8> {
        Ok(self.inner.day)
    }
    #[setter]
    fn set_year(&mut self, year: u16) -> PyResult<()> {
        self.inner.year = year;
        Ok(())
    }
    #[setter]
    fn set_month(&mut self, month: u8) -> PyResult<()> {
        self.inner.month = month;
        Ok(())
    }
    #[setter]
    fn set_day(&mut self, day: u8) -> PyResult<()> {
        self.inner.day = day;
        Ok(())
    }
}

#[pymodule]
fn date_py(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<DatePy>()?;
    Ok(())
}

I've noticed that the PyO3 bindings contain a lot of boilerplate, and hence they are much longer compared to pybind11:

• 15 lines with pybind11
• 54 lines with PyO3

Questions:

1. Am I using PyO3 correctly? Are there ways to shorten the code to achieve a similar level of "conciseness" as is the case for pybind11?
2. Is there is a way to create PyO3 bindings without the DatePy helper struct? Again, ideally similar to pybind where I don't need to manually create any helper structs.
3. How can I add two (or more) constructors such as #[new] fn new(year: u16, month: u8, day: u8) and #[new] fn new(yyyymmdd: &str) similar to pybind11? RIght now, I am only able to expose 1 constructor with PyO3.

---

Question originates from Correct & concise way to use PyO3 Bindings (similar to pybind11), where a commenter suggested to raise an issue on the PyO3 GitHub.

[birkenfeld]

In principle, you don't need a helper struct. You can just expose Date as-is as a pyclass. That gets rid of most of the boilerplate, at the cost of "infecting" possibly pure Rust library code with Python-specific annotations - but that's the way PyO3 is, currently. It would look roughly like this (haven't checked for correctness):

#[derive(Debug)]
#[pyclass]
pub struct Date {
    #[pyo3(get, set)]
    pub year: u16,
    #[pyo3(get, set)]
    pub month: u8,
    #[pyo3(get, set)]
    pub day: u8
}

#[pymethods]
impl Date {
    #[new]
    pub fn from_ymd(year: u16, month: u8, day: u8) -> Date {
        // ...
    }

    pub const fn add_days(&self, N: u8) -> Self {
        // ...
    }
    pub const fn is_weekend(&self) -> bool {
        // ...
    }
}

// methods not exposed to Python
impl Date {
    pub fn from_str(s: &str) -> Date {
        // ...
    }
}

All the methods in pymethods can still be called from Rust, too. In this case, the PyO3 specific code is quite minimal because all the involved argument types can be Rust native, and PyO3 converts them automatically. Of course, in the case of taking/returning Python native types you'll have some code in pymethods that's only binding related.

As for question 3, there is no such thing as multiple constructors in Python either, so pybind11 probably creates a wrapper in the background calling constructors based on types received. You can mimic that by taking *args, **kwds (or something more restricted that still fits all possible constructors) and typechecking.

[phil-zxx]

Thanks @birkenfeld for your comments!

Regarding

at the cost of "infecting" possibly pure Rust library code with Python-specific annotations

So if i want to keep my rust library clean, i will have to create helper structs such as DatePy? There is no way to tell PyO3 to "just expose" an existing rust class (which is how pybind does it)? I ask, because I've been working with C++ & pybind for years, and having to "infect" pure rust code to expose a class to Python is therefore counter-intuitive to me. So I want to make sure I didn't miss anything.

---

Regarding

You can mimic [multiple constructors] by taking *args, **kwds

In case, this could help someone else in the future, I tried the following, which works for me:

#[pymethods]
impl DatePy {
    #[new]
    #[pyo3(signature = (*py_args))]
    fn new(py_args: &Bound<'_, PyTuple>) -> PyResult<Self> {
        if py_args.len() == 3 && py_args.iter().all(|item| { item.is_instance_of::<PyLong>() }) {
            let year: u16 = py_args.get_item(0)?.extract()?;
            let month: u8 = py_args.get_item(1)?.extract()?;
            let day: u8   = py_args.get_item(2)?.extract()?;
            Ok(Date::from_ymd(year, month, day).into())
        } else if py_args.len() == 1 && py_args.get_item(0)?.is_instance_of::<PyString>() {
            Ok(Date::from_str(py_args.get_item(0)?.extract()?).into())
        } else {
            Err(PyValueError::new_err(format!("Expected the following signatures: (year: int, month: int, day: int) or (yyyymmdd: str), but have {:?}", py_args)))
        }
    }
}

Any advice on how I could improve this new function, would be appreciated.