[docs] add Python client documentation by Prajwal-banakar · Pull Request #2461 · apache/fluss

Prajwal-banakar · 2026-01-23T17:33:18Z

Purpose

Linked issue: close #2447

The purpose of this change is to add comprehensive documentation for the Fluss Python Client. This ensures that Python users have a dedicated guide that mirrors the structure of the existing Java Client documentation while highlighting Python-specific features like PyArrow and Pandas integration.

Brief change log

This pull request introduces the following changes:

New Documentation File: Created website/docs/apis/python-client.md which includes sections for Installation, Initialization, Admin API, and Table API.

Code Examples: Added asynchronous Python code snippets demonstrating how to connect to a cluster, manage databases/tables, and perform high-performance data writing and scanning.

Ecosystem Integration: Documented the native support for PyArrow Tables and Pandas DataFrames, providing users with idiomatic ways to handle data in Python.

Sidebar Alignment: Set the sidebar_position to 2 to ensure the Python Client appears immediately after the Java Client in the API documentation hierarchy.

Build Consistency: Updated website/package-lock.json to reflect the environment-specific dependency tree used during local verification of the documentation site.

Tests

Manual Verification: The documentation was built and verified locally using the Docusaurus development server (npm run start).
Visual Check: Confirmed that all code blocks render correctly, syntax highlighting is active, and the sidebar navigation is correctly ordered.
Before

After changes

API and Format

This change does not affect any existing public Java APIs or storage formats; it is strictly a documentation addition for the Python Client.

Documentation

This PR introduces a new documentation page for the Fluss Python Client.

Prajwal-banakar · 2026-01-24T05:16:36Z

Hi @polyzos , the build failed due to a NotLeaderOrFollowerException in FlussTableITCase, which seems unrelated to my documentation changes. Could you please review this PR and trigger a re-run?

leekeiabstraction

TY for the PR. Added some comments/questions. PTAL!

leekeiabstraction · 2026-01-24T09:51:04Z

website/docs/apis/python-client.md

+
+# Create configuration
+conf = Configuration()
+conf.set_string("bootstrap.servers", "localhost:9123")


Add comment here to adjust according to where Fluss is running

leekeiabstraction · 2026-01-24T09:52:44Z

website/docs/apis/python-client.md

+To use the Fluss Python client, you need to install the `fluss-python` package.
+
+```bash
+pip install fluss-python


I'm not a frequent python user, but is fluss-python available publicly?

https://pypi.org/search/?q=fluss-python

python-workspace % pip install fluss-python ERROR: Could not find a version that satisfies the requirement fluss-python (from versions: none) ERROR: No matching distribution found for fluss-python

leekeiabstraction · 2026-01-24T10:00:07Z

website/docs/apis/python-client.md

+table = connection.get_table("my_db.my_table")
+print(table.get_table_info())


While this follows the Java API flow, should we consider a flow that does not cause error as user follow it? If the server is a fresh one, would an Error occur here?

leekeiabstraction · 2026-01-24T10:06:32Z

website/docs/apis/python-client.md

+conf.set_string("client.security.protocol", "sasl")
+conf.set_string("client.security.sasl.mechanism", "PLAIN")
+conf.set_string("client.security.sasl.username", "alice")
+conf.set_string("client.security.sasl.password", "alice-secret")


Can you confirm if these are currently honoured?

Prajwal-banakar · 2026-01-24T15:42:30Z

Hi @leekeiabstraction, I have addressed all your feedback:

Updated the Installation section to point to the bindings/python directory in the fluss-rust repository.

Reordered the documentation so the Admin API (resource creation) comes before the Table API (usage) to ensure a smooth flow for fresh clusters.

Added the requested code comments to the initialization examples.

Verified the SASL configuration keys against the standard client setup.

PTAL when you have a chance. Thanks!"

leekeiabstraction

Thank you Prajwal for the update. Left further comments. PTAL!

leekeiabstraction · 2026-01-31T11:13:07Z

website/docs/apis/python-client.md

@@ -0,0 +1,213 @@
+---
+title: "Python Client"
+sidebar_position: 2


Sidebar position 2 clashes with current position for Client Support Matrix. Update Client Support Matrix's to be larger.

leekeiabstraction · 2026-01-31T11:17:43Z

website/docs/apis/python-client.md

+* **Table API**: For reading from and writing to Fluss tables.
+
+## Installation
+The Fluss Python client is provided as bindings within the Rust client repository. To install it from source:


This might change soon if we decide to release artefacts for 0.1.0.

nit: The Fluss Python client is currently...

leekeiabstraction · 2026-01-31T11:25:30Z

website/docs/apis/python-client.md

+The `Connection` object is the entry point for interacting with Fluss. It is created using `Connection.create()` and requires a configuration dictionary.
+
+```python
+from fluss.client import Connection


Not a Python expert, but I run into the following error when importing the client package in python interpreter. (I'm on Mac). Am I missing something?

keithlee@--- python % pip install . Processing /Users/keithlee/IdeaProjects/f/fluss-rust/bindings/python Installing build dependencies ... done Getting requirements to build wheel ... done Preparing metadata (pyproject.toml) ... done Collecting pandas>=2.3.1 (from fluss==0.1.0) Downloading pandas-3.0.0-cp314-cp314-macosx_11_0_arm64.whl.metadata (79 kB) Collecting pyarrow>=10.0.0 (from fluss==0.1.0) Downloading pyarrow-23.0.0-cp314-cp314-macosx_12_0_arm64.whl.metadata (3.0 kB) Collecting numpy>=2.3.3 (from pandas>=2.3.1->fluss==0.1.0) Downloading numpy-2.4.1-cp314-cp314-macosx_14_0_arm64.whl.metadata (6.6 kB) Collecting python-dateutil>=2.8.2 (from pandas>=2.3.1->fluss==0.1.0) Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl.metadata (8.4 kB) Collecting six>=1.5 (from python-dateutil>=2.8.2->pandas>=2.3.1->fluss==0.1.0) Downloading six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB) Downloading pandas-3.0.0-cp314-cp314-macosx_11_0_arm64.whl (9.9 MB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 9.9/9.9 MB 29.6 MB/s 0:00:00 Downloading numpy-2.4.1-cp314-cp314-macosx_14_0_arm64.whl (5.2 MB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.2/5.2 MB 45.2 MB/s 0:00:00 Downloading pyarrow-23.0.0-cp314-cp314-macosx_12_0_arm64.whl (34.2 MB) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 34.2/34.2 MB 54.9 MB/s 0:00:00 Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB) Downloading six-1.17.0-py2.py3-none-any.whl (11 kB) Building wheels for collected packages: fluss Building wheel for fluss (pyproject.toml) ... done Created wheel for fluss: filename=fluss-0.1.0-cp314-cp314-macosx_11_0_arm64.whl size=4188845 sha256=bd436c60504f8b6e3e90775706d3f70227814149c080e85a836f5ff4387a11a8 Stored in directory: /private/var/folders/47/2p97sbt51xgdsqym52gn7cj80000gn/T/pip-ephem-wheel-cache-wg1s_vkk/wheels/d9/8f/5e/70d4bdfc4b18344a136d84aaa1fbc6c805c6b9ae074c3169c6 Successfully built fluss Installing collected packages: six, pyarrow, numpy, python-dateutil, pandas, fluss Successfully installed fluss-0.1.0 numpy-2.4.1 pandas-3.0.0 pyarrow-23.0.0 python-dateutil-2.9.0.post0 six-1.17.0 [notice] A new release of pip is available: 25.3 -> 26.0 [notice] To update, run: pip install --upgrade pip keithlee@--- python % python Python 3.14.2 (main, Dec 17 2025, 20:54:49) [Clang 21.1.4 ] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> from fluss.client import Connection Traceback (most recent call last): File "<python-input-0>", line 1, in <module> from fluss.client import Connection File "/Users/keithlee/IdeaProjects/f/fluss-rust/bindings/python/fluss/__init__.py", line 18, in <module> from ._fluss import * ModuleNotFoundError: No module named 'fluss._fluss'

Prajwal-banakar · 2026-01-31T15:23:33Z

Hi @leekeiabstraction I've updated the sidebar position to 3 and adjusted the installation text as suggested. I also added a note block explaining the ModuleNotFoundError. It happens because running the interpreter inside the bindings/python directory makes Python prioritize the local folder over the installed binary. Moving out of the directory fixes it. PTAL!

leekeiabstraction · 2026-02-09T23:10:26Z

Thank you Prajwal for updating the PR!

There has been newer changes on the python API side, can you update accordingly?

Reference: apache/fluss-rust#291

Note that your PR's current structure should be left as is, but also provide a link to the more comprehensive doc on rust client repo

Prajwal-banakar · 2026-02-10T05:14:47Z

Hi @leekeiabstraction , I have completed a full sync of the Python Client documentation with the recently merged changes in apache/fluss-rust#291 Looking forward to your feedback!

leekeiabstraction

Thank you @Prajwal-banakar for working on this. I'm thinking that we should do the following:

Move the content of this PR to fluss-rust
Change this pr to point to fluss-rust website.

This approach will ensure that rust/cpp/python docs stay near to client source and is discoverable from main site.

Prajwal-banakar · 2026-03-09T06:13:59Z

Hi @leekeiabstraction, I've slimmed down this PR to a lightweight intro page that links to https://clients.fluss.apache.org/user-guide/python/installation for the full reference. The link is currently broken since the fluss-rust site hasn't been deployed yet, but it will resolve once the site goes live. The detailed content is already present in the fluss-rust repo so no separate PR is needed from my side. PTAL!

…sections ConfigOptionsDocGenerator

leekeiabstraction · 2026-03-22T20:25:54Z

TY for the PR Prajwal, I've re-ordered the sections, added more links on the page and removed package-lock.json.

Prajwal-banakar · 2026-03-23T08:22:38Z

Thank you for the improvements and merging both PRs! I noticed the C++ Client page is also missing. can i work on it following the same pattern?

leekeiabstraction reviewed Jan 24, 2026

View reviewed changes

leekeiabstraction reviewed Jan 31, 2026

View reviewed changes

luoyuxia force-pushed the main branch from 0e2d71f to 74ee888 Compare February 6, 2026 12:32

Prajwal-banakar requested a review from leekeiabstraction February 7, 2026 04:46

leekeiabstraction reviewed Mar 8, 2026

View reviewed changes

Prajwal-banakar requested a review from leekeiabstraction March 9, 2026 06:16

Prajwal-banakar mentioned this pull request Mar 20, 2026

[docs] Add Rust client documentation #2462

Merged

Prajwal-banakar and others added 7 commits March 22, 2026 20:18

add Python client documentation

40ed5c1

address reviewer comments by fixing installation path and reordering …

eb22000

…sections ConfigOptionsDocGenerator

address feedback and add note on python installation path

63d9baf

align python client with fluss-rust apache#291 and address feedback

803cfc6

pointing to fluss-rust website.

6bb06f6

Remove package-lock.json, add more links

164cbea

Reorder client API sections

8042f23

leekeiabstraction force-pushed the docs-python-client branch from f03334e to 8042f23 Compare March 22, 2026 20:21

leekeiabstraction approved these changes Mar 22, 2026

View reviewed changes

leekeiabstraction merged commit c59c0f1 into apache:main Mar 22, 2026
2 checks passed

Prajwal-banakar deleted the docs-python-client branch March 23, 2026 08:04

leekeiabstraction mentioned this pull request Mar 23, 2026

[Docs] Add documentation for C++ Client #2448

Closed

2 tasks

Prajwal-banakar mentioned this pull request Mar 24, 2026

[docs] Add C++ client documentation #2923

Merged

		table = connection.get_table("my_db.my_table")
		print(table.get_table_info())

Conversation

Prajwal-banakar commented Jan 23, 2026

Purpose

Brief change log

Tests

API and Format

Documentation

Uh oh!

Prajwal-banakar commented Jan 24, 2026

Uh oh!

leekeiabstraction left a comment

Choose a reason for hiding this comment

Uh oh!

leekeiabstraction Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

leekeiabstraction Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

leekeiabstraction Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

leekeiabstraction Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

Prajwal-banakar commented Jan 24, 2026

Uh oh!

leekeiabstraction left a comment

Choose a reason for hiding this comment

Uh oh!

leekeiabstraction Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

leekeiabstraction Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

leekeiabstraction Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Prajwal-banakar commented Jan 31, 2026

Uh oh!

leekeiabstraction commented Feb 9, 2026

Uh oh!

Prajwal-banakar commented Feb 10, 2026

Uh oh!

leekeiabstraction left a comment

Choose a reason for hiding this comment

Uh oh!

Prajwal-banakar commented Mar 9, 2026

Uh oh!

leekeiabstraction commented Mar 22, 2026

Uh oh!

Uh oh!

Prajwal-banakar commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants