[docs] add Python client documentation #2461
Conversation
|
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
left a comment
There was a problem hiding this comment.
TY for the PR. Added some comments/questions. PTAL!
|
|
||
| # Create configuration | ||
| conf = Configuration() | ||
| conf.set_string("bootstrap.servers", "localhost:9123") |
There was a problem hiding this comment.
Add comment here to adjust according to where Fluss is running
website/docs/apis/python-client.md
Outdated
| To use the Fluss Python client, you need to install the `fluss-python` package. | ||
|
|
||
| ```bash | ||
| pip install fluss-python |
There was a problem hiding this comment.
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
| table = connection.get_table("my_db.my_table") | ||
| print(table.get_table_info()) |
There was a problem hiding this comment.
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?
| 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") |
There was a problem hiding this comment.
Can you confirm if these are currently honoured?
…sections ConfigOptionsDocGenerator
|
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!" |
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.