[feat] Set up uv, ruff, and other settings for Python binding

[naivedogger]

Purpose

Linked issue: close #12

Brief change log

Tests

API and Format

Documentation

[Copilot]

Pull Request Overview

This PR sets up the foundation for Python bindings for Fluss using PyO3 and Maturin, including development tooling configuration and project structure.

Key changes:

• Configures Python project with pyproject.toml including dependencies, build system, and tooling settings
• Sets up development environment with uv, ruff, and mypy configurations
• Adds comprehensive README with development workflow and API documentation

Reviewed Changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.

File	Description
bindings/python/pyproject.toml	Defines Python project configuration, dependencies, and tooling settings
bindings/python/README.md	Provides development setup instructions and project documentation
bindings/python/Cargo.toml	Configures Rust crate for Python bindings with PyO3 dependencies
.licenserc.yaml	Excludes uv.lock from license header requirements

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[luoyuxia]

@naivedogger Thanks for the pr. Left some comments.

[luoyuxia]

why we need to add uv.lock, haven't seen any python binding project include it. I think we don't need to include it since cargo.lock is also ignored by us

[naivedogger]

Deleted.

[luoyuxia]

Have gone through other projects, we should use fluss

Suggested change

	name = "fluss_python"
	name = "fluss"

[naivedogger]

Sure

[luoyuxia]

why once_cell is needed? If needed, we can attach it in following pull requests.

[naivedogger]

Will introduce this later on

[luoyuxia]

tokio = { workspace = true }

[naivedogger]

fixed

[luoyuxia]

I'd like to suggestion arrow also use { workspace = true }

[luoyuxia]

See what delta did
https://github.com/delta-io/delta-rs/blob/main/python/Cargo.toml

[naivedogger]

Yes, this looks better.

[luoyuxia]

nit: Linux or macOs

[naivedogger]

fixed

[luoyuxia]

add a link for uv package manager?

[naivedogger]

fixed

[luoyuxia]

nit:

Apache Fluss™ Python Bindings

[naivedogger]

fixed

[luoyuxia]

add todo in here

[naivedogger]

fixed

[luoyuxia]

we shuld always put user-faced api into first. So, let's organize it as, assuming System Requirements is only for developer:

<!--
  ~ 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.
-->

# Apache Fluss™ Python Bindings

Python bindings for Fluss using PyO3 and Maturin.


## API Overview

### Basic Usage

### Core Classes

#### `Config`

Configuration for Fluss connection parameters

#### `FlussConnection`

Main interface for connecting to Fluss cluster

#### `FlussAdmin`

Administrative operations for managing tables (create, delete, etc.)

#### `FlussTable`

Represents a Fluss table, providing read and write operations

#### `TableWriter`

Used for writing data to tables, supports PyArrow and Pandas

#### `LogScanner`

Used for scanning table log data

### Release

```bash
# Build wheel
uv run maturin build --release

# Publish to PyPI
uv run maturin publish

Development

Requirements

• Python 3.9+
• Rust 1.70+
• uv package manager
• MacOS

⚠️ Before you start:
Please make sure you can successfully build and run the Fluss Rust client on your machine.
The Python bindings require a working Fluss Rust backend and compatible environment.

Install Dependencies-dev

cd bindings/python
uv sync --all-extras

Build Development Version

source .venv/bin/activate
uv run maturin develop

Build Release Version

uv run maturin build --release

Code Formatting and Linting

uv run ruff format python/
uv run ruff check python/

Type Checking

uv run mypy python/

Run Examples

uv run python example/example.py

Build API docs:

uv run pdoc fluss_python

Project Structure

bindings/python/
├── Cargo.toml              # Rust dependency configuration
├── pyproject.toml          # Python project configuration
├── README.md              # This file
├── src/                   # Rust source code
│   ├── lib.rs            # Main entry module
│   ├── config.rs         # Configuration related
│   ├── connection.rs     # Connection management
│   ├── admin.rs          # Admin operations
│   ├── table.rs          # Table operations
│   ├── types.rs          # Data types
│   └── error.rs          # Error handling
├── python/               # Python package source
│   └── fluss_python/
│       ├── __init__.py   # Python package entry
        ├── __init__.pyi  # Stub file
│       └── py.typed      # Type declarations
└── example/              # Example code
    └── example.py

License

Apache 2.0 License

[naivedogger]

This looks great!