This is an automated email from the ASF dual-hosted git repository.
mgreber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/kudu.git
The following commit(s) were added to refs/heads/master by this push:
new 6e3a51a31 KUDU-2345 Add developer docs for the python client
6e3a51a31 is described below
commit 6e3a51a31c7ca0c8937723e070149c8731bdc7a1
Author: Gabriella Lotz <[email protected]>
AuthorDate: Wed Aug 27 14:04:54 2025 +0200
KUDU-2345 Add developer docs for the python client
Add virtual environment setup recommendation. Add clear test running
examples for both all tests and single tests. Include directory
navigation notes for clarity and convert to standard Markdown
format for better readability.
Change-Id: I0cd38ecd5acf4a40c7f04d89c073d093ac5c83e0
Reviewed-on: http://gerrit.cloudera.org:8080/23352
Tested-by: Kudu Jenkins
Reviewed-by: Marton Greber <[email protected]>
Reviewed-by: Zoltan Chovan <[email protected]>
---
python/README.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 102 insertions(+), 3 deletions(-)
diff --git a/python/README.md b/python/README.md
index 15e871d9e..e7f3c3a79 100644
--- a/python/README.md
+++ b/python/README.md
@@ -1,11 +1,110 @@
-kudu-python: Python interface to the Apache Kudu C++ Client API
----------------------------------------------------------------
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License. -->
+
+# kudu-python: Python interface to the Apache Kudu C++ Client API
Using this package requires that you install the Kudu C++ client libraries and
headers. See https://kudu.apache.org for more.
-To install from PyPI, run
+## System Dependencies
+
+Before installing the Python client, you need to install OS-specific system
dependencies.
+
+The Kudu Python client requires several packages that vary by operating system
(Debian/Ubuntu, CentOS/RHEL, OpenSUSE/SLES). These include build tools like
`setuptools` and the Python development package.
+
+For automated installation of these dependencies, you can use the bootstrap
script:
https://github.com/apache/kudu/blob/master/docker/bootstrap-python-env.sh
+
+## Virtual Environment
+
+**Note: It is recommended to use a Python virtual environment to avoid
conflicts with system packages.**
+
+If you don't have virtualenv installed, you can learn more and install it from
[the official virtualenv
website](https://virtualenv.pypa.io/en/latest/index.html).
+
+## Setting up a Virtual Environment
+```bash
+# Create a virtual environment
+# You can use any Python version supported by kudu-python (check
https://pypi.org/project/kudu-python/)
+virtualenv venv -p 3.8
+
+# Activate the virtual environment
+source venv/bin/activate
+
+# To deactivate later:
+deactivate
```
+
+## Installing from PyPI
+
+```bash
pip install kudu-python
```
+
+## Installing from Source
+
+**Note: Make sure you are in the `kudu/python` directory where the
requirements files are located.**
+
+```bash
+cd /path/to/kudu/python # Navigate to the python directory if not already
there
+pip install -r requirements.txt
+python setup.py sdist
+pip install dist/kudu-python-*.tar.gz
+```
+
+## Building for Development
+
+### Setting up the KUDU_HOME Environment Variable
+
+Before building for development, you need to set the `KUDU_HOME` environment
variable to point to the root directory of your Kudu git repository:
+
+```bash
+export KUDU_HOME=/path/to/kudu
+```
+
+This variable is required by various scripts and tools in the project. Make
sure it's set in your environment before running any Kudu-related commands.
+
+
+**Note: Make sure you are in the `kudu/python` directory where the
requirements files are located.**
+
+```bash
+cd $KUDU_HOME/python # Navigate to the python directory if not already there
+pip install -r requirements.txt
+pip install -r requirements_dev.txt
+python setup.py build_ext --inplace
+```
+
+## Run All Tests
+
+```bash
+python setup.py test
+```
+
+## Run Single Test
+
+```bash
+python -m unittest kudu.tests.test_client.TestClient.test_list_tables
+```
+
+## Debugging A Test
+
+To debug a specific test using Python's built-in debugger (pdb):
+
+```bash
+python -m pdb -m unittest kudu.tests.test_client.TestClient.test_list_tables
+```
+
+This will start the debugger before running the test, allowing you to set
breakpoints and step through the code.
