chore(python-binding): documentation and PyPI metadata (#18711)

* Improve Python binding documentation and PyPI metadata

- Enhanced README.md with comprehensive API reference tables organized by functionality
- Added clear examples progression from local tables to cloud storage
- Updated pyproject.toml description to highlight multi-modal data warehouse for AI era
- Added readme field to ensure PyPI displays full documentation
- Improved messaging around structured data, JSON, and vector embeddings support

* Fix YAML formatting issues

- Remove trailing spaces in bindings.python.yml and build_bindings_python action
- Fix yamllint errors for Python binding CI files

Author: BohuTANG

src/bendpy/README.md

@@ -1,42 +1,91 @@
 # Databend Python Binding
 
-Official Python binding for [Databend](https://databend.com) - The AI-Native Data Warehouse.
+Official Python binding for [Databend](https://databend.com) - The multi-modal data warehouse built for the AI era.
 
-Databend is the open-source alternative to Snowflake with near 100% SQL compatibility and native AI capabilities. Built in Rust with MPP architecture and S3-native storage, Databend unifies structured tables, JSON documents, and vector embeddings in a single platform.
+Databend unifies structured data, JSON documents, and vector embeddings in a single platform with near 100% Snowflake compatibility. Built in Rust with MPP architecture and S3-native storage for cloud-scale analytics.
 
 ## Installation
 
 ```bash
 pip install databend
 ```
 
+To test, run:
+```python
+python3 -c "import databend; ctx = databend.SessionContext(); ctx.sql('SELECT version() AS version').show()"
+```
+
+## API Reference
+
+### Core Operations
+| Method | Description |
+|--------|-------------|
+| `SessionContext()` | Create a new session context |
+| `sql(query)` | Execute SQL query, returns DataFrame |
+
+### File Registration
+| Method | Description |
+|--------|-------------|
+| `register_parquet(name, path, pattern=None, connection=None)` | Register Parquet files as table |
+| `register_csv(name, path, pattern=None, connection=None)` | Register CSV files as table |
+| `register_ndjson(name, path, pattern=None, connection=None)` | Register NDJSON files as table |
+| `register_tsv(name, path, pattern=None, connection=None)` | Register TSV files as table |
+
+### Cloud Storage Connections
+| Method | Description |
+|--------|-------------|
+| `create_s3_connection(name, key, secret, endpoint=None, region=None)` | Create S3 connection |
+| `create_azblob_connection(name, url, account, key)` | Create Azure Blob connection |
+| `create_gcs_connection(name, url, credential)` | Create Google Cloud connection |
+| `list_connections()` | List all connections |
+| `describe_connection(name)` | Show connection details |
+| `drop_connection(name)` | Remove connection |
+
+### Stage Management
+| Method | Description |
+|--------|-------------|
+| `create_stage(name, url, connection)` | Create external stage |
+| `show_stages()` | List all stages |
+| `list_stages(stage_name)` | List files in stage |
+| `describe_stage(name)` | Show stage details |
+| `drop_stage(name)` | Remove stage |
+
+### DataFrame Operations
+| Method | Description |
+|--------|-------------|
+| `collect()` | Execute and collect results |
+| `show(num=20)` | Display results in console |
+| `to_pandas()` | Convert to pandas DataFrame |
+| `to_polars()` | Convert to polars DataFrame |
+| `to_arrow_table()` | Convert to PyArrow Table |
+
 ## Examples
 
-### Local Files
+### Local Tables
 
 ```python
 import databend
 ctx = databend.SessionContext()
 
-# Query local Parquet files
-ctx.register_parquet("orders", "/path/to/orders/")
-ctx.register_parquet("customers", "/path/to/customers/")
-df = ctx.sql("SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id").to_pandas()
+# Create and query in-memory tables
+ctx.sql("CREATE TABLE users (id INT, name STRING, age INT)").collect()
+ctx.sql("INSERT INTO users VALUES (1, 'Alice', 25), (2, 'Bob', 30)").collect()
+df = ctx.sql("SELECT * FROM users WHERE age > 25").to_pandas()
 ```
 
-### Local Tables
+### Working with Local Files
 
 ```python
 import databend
 ctx = databend.SessionContext()
 
-# Create and query local tables
-ctx.sql("CREATE TABLE users (id INT, name STRING, age INT)").collect()
-ctx.sql("INSERT INTO users VALUES (1, 'Alice', 25), (2, 'Bob', 30)").collect()
-df = ctx.sql("SELECT * FROM users WHERE age > 25").to_pandas()
+# Query local Parquet files
+ctx.register_parquet("orders", "/path/to/orders/")
+ctx.register_parquet("customers", "/path/to/customers/")
+df = ctx.sql("SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id").to_pandas()
 ```
 
-### S3 Remote Files
+### Cloud Storage - S3 Files
 
 ```python
 import databend
@@ -49,14 +98,14 @@ ctx.register_parquet("trips", "s3://bucket/trips/", connection="s3")
 df = ctx.sql("SELECT COUNT(*) FROM trips").to_pandas()
 ```
 
-### Remote Tables
+### Cloud Storage - S3 Tables
 
 ```python
 import databend
 import os
 ctx = databend.SessionContext()
 
-# Create S3 connection and table
+# Create S3 connection and persistent table
 ctx.create_s3_connection("s3", os.getenv("AWS_ACCESS_KEY_ID"), os.getenv("AWS_SECRET_ACCESS_KEY"))
 ctx.sql("CREATE TABLE s3_table (id INT, name STRING) 's3://bucket/table/' CONNECTION=(CONNECTION_NAME='s3')").collect()
 df = ctx.sql("SELECT * FROM s3_table").to_pandas()

src/bendpy/pyproject.toml

@@ -7,7 +7,8 @@ build-backend = "maturin"
 version = "0.1.0"
 name = "databend"
 requires-python = ">=3.10"
-description = "Official Python binding for Databend - The AI-Native Data Warehouse. Open-source alternative to Snowflake with near 100% SQL compatibility, native AI capabilities, and unified support for structured, semi-structured, and vector data."
+description = "The multi-modal data warehouse built for the AI era. Unified analytics for structured data, JSON, and vector embeddings with near 100% Snowflake compatibility."
+readme = "README.md"
 license = {text = "Apache-2.0"}
 authors = [{name = "Databend Labs", email = "hi@databend.com"}]
 maintainers = [{name = "Databend Community", email = "hi@databend.com"}]