From 4ea0032ff890fb5ab0838e42b8b66ffbd521f4df Mon Sep 17 00:00:00 2001 From: Michael J Ward Date: Sat, 7 Sep 2024 06:07:27 -0500 Subject: [PATCH] add section to the contributor guide on separating python and rust code (#860) --- docs/source/contributor-guide/introduction.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/source/contributor-guide/introduction.rst b/docs/source/contributor-guide/introduction.rst index 6de2b87bc..4457a898f 100644 --- a/docs/source/contributor-guide/introduction.rst +++ b/docs/source/contributor-guide/introduction.rst @@ -71,6 +71,17 @@ Our pre-commit hooks can be installed by running :code:`pre-commit install`, whi The pre-commit hooks can also be run adhoc without installing them by simply running :code:`pre-commit run --all-files` +Guidelines for Separating Python and Rust Code +---------------------------------------------- + +Version 40 of ``datafusion-python`` introduced ``python`` wrappers around the ``pyo3`` generated code to vastly improve the user experience. (See the `blog post `_ and `pull request `_ for more details.) + +Mostly, the ``python`` code is limited to pure wrappers with type hints and good docstrings, but there are a few reasons for when the code does more: + +1. Trivial aliases like :py:func:`~datafusion.functions.array_append` and :py:func:`~datafusion.functions.list_append`. +2. Simple type conversion, like from a ``path`` to a ``string`` of the path or from ``number`` to ``lit(number)``. +3. The additional code makes an API **much** more pythonic, like we do for :py:func:`~datafusion.functions.named_struct` (see `source code `_). + Update Dependencies -------------------