Python API typing, lint, config/makefile

[alexander-beedie]

I realise this is a relatively enormous-looking PR; however, I promise it is a LOT less involved than it may initially look! 🤣 (And there are zero logical/functional changes).

Summary

I made a few smaller PRs to add Polars support to Kùzu recently, and working with (and testing) the Python module had a little friction, so I thought I'd reduce it.

Specifically:

• The PythonAPI surface is now fully typed¹ (function signatures, return types, etc). This should lead to an improved developer experience in real-world usage (IDE autocomplete & hinting, integration with other projects that already implement static type checking, etc).
• The entire Python API now passes both ruff check² and mypy³ linting rules.
• Consistent formatting was applied, via ruff format⁴ (this is likely worth integrating into CI and/or pre-commit, but I haven't done that). The existing formatting actually changed very little, so this change mostly just ensures consistent string quoting and max line-length. I set line-length at a level that would result in minimal change.
• Switched out all usage of os.path for pathlib.Path.
• Created a Makefile in tools/python_api that can:
  • Setup a clean Python .venv for testing/validating changes.
  • Download/resolve requirements for that venv (using uv)⁵.
  • Trigger a make python build from the existing root Makefile.
  • Run the Python unit tests.
  • Output its own "help".

Being able to quickly get up and running in a virtual environment and trigger builds/tests is now a lot smoother, and all the configuration for mypy & ruff is centralised in the new/added pyproject.toml file (which is based on what we use for Polars, with Kùzu-specific customisation).

Examples

• Find out what the Makefile can do:

  

• Install/update the venv requirements:

  

• Check lint and apply formatting:

  

• Run unit tests:

  

...and so on 👌

CLA

(In case this is a "per-PR" requirement?)
I have read and agree to the terms under CLA.md

Footnotes

1. https://peps.python.org/pep-0484/ ↩

2. https://astral.sh/ruff ↩

3. https://mypy-lang.org/ ↩

4. https://docs.astral.sh/ruff/formatter/ ↩

5. https://astral.sh/blog/uv ↩

[alexander-beedie]

FYI: I've also seen how to enormously speed up the Python unit tests, but I'll leave that for a follow up PR. Didn't want to mix functional changes with lint/formatting/config...

[mewim]

@alexander-beedie
Nice PR. Thanks for your contribution.