This is an automated email from the ASF dual-hosted git repository.
numinnex pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iggy.git
The following commit(s) were added to refs/heads/master by this push:
new 039a91ca9 refactor(python): readme improvements (#3825)
039a91ca9 is described below
commit 039a91ca9f91460098bc831c8d39293ae3516ec8
Author: Daniil Novikov <[email protected]>
AuthorDate: Fri Aug 7 16:00:49 2026 +0200
refactor(python): readme improvements (#3825)
Which issue does this PR address?
Closes #3750
The documentation provided in Python SDK does not provide a golden path
for development workflow. The absence of golden path adds the cognitive
load on most devs, especially the new ones.
README for Python SDK now provides a clear instruction on how to build
and test it and gives basic advice on troubleshooting for precommit and
prepush hooks. The new path is tested by hand and has fixed a number of
unwanted side effects described in the linked issue.
---
foreign/python/README.md | 119 +++++++++++++++++++++++++++++++++++++++--------
1 file changed, 100 insertions(+), 19 deletions(-)
diff --git a/foreign/python/README.md b/foreign/python/README.md
index f01754f6d..99a9b0ed6 100644
--- a/foreign/python/README.md
+++ b/foreign/python/README.md
@@ -23,7 +23,7 @@ Apache Iggy is the persistent message streaming platform
written in Rust, suppor
### Basic Installation
```bash
-# Using uv
+# Using uv in an existing project
uv add apache-iggy
# Using pip
@@ -32,31 +32,112 @@ source .venv/bin/activate
pip install apache-iggy
```
-### Supported Python Versions
+### Prerequisites
+
+Every installation below compiles the Rust extension, so you'll need:
- Python 3.10+
+- Rust toolchain: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs |
sh`
+- `uv`: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+- All checks tooling from
[CONTRIBUTING.md](https://github.com/apache/iggy/blob/master/CONTRIBUTING.md).
+- Docker
### Local Development
-```bash
-# Start server for testing using docker
-docker compose -f docker-compose.test.yml up --build
+**IMPORTANT: All commands are supposed to be ran from `foreign/python` unless
it's specified to run in repository's root folder.**
-# Or use cargo
-cargo run --bin iggy-server -- --with-default-root-credentials --fresh
+1. Build a project for development
-# Using uv:
-uv sync --all-extras
-uv run maturin develop
-uv run pytest tests/ -v # Run tests (requires iggy-server running)
+ With `uv`:
-# Using pip:
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -e ".[all]"
-maturin develop
-pytest tests/ -v # Run tests (requires iggy-server running)
-```
+ ```bash
+ # Create a venv
+ uv venv
+
+ # Sync the environment without updating it
+ uv sync --frozen --all-extras --no-install-project
+
+ # Build the project -- this builds the rust extension into the venv (debug
profile) - re-run after any rust change
+ uv run --no-sync maturin develop
+ ```
+
+ With `pip`:
+
+ ```bash
+ # Create a venv
+ python3 -m venv .venv
+
+ # Activate the venv
+ source .venv/bin/activate
+
+ # Install the dependencies
+ pip install -e ".[all]"
+
+ # Build the project -- this builds the rust extension into the venv (debug
profile) - re-run after any rust change
+ maturin develop
+ ```
+
+2. Run the server to be able to run the tests (this blocks the terminal - run
steps 3-5 in a separate one). `--fresh` deletes `local_data/` on every run -
drop it if you have existing data you want to keep.
+
+ ```bash
+ # run from the repository's root directory
+ cargo run --bin iggy-server -- --with-default-root-credentials --fresh
+ ```
+
+3. Run the tests
+
+ `uv`:
+
+ ```bash
+ uv run --no-sync pytest tests/ -v
+ ```
+
+ `pip`:
+
+ ```bash
+ pytest tests/ -v # make sure iggy-server is running and the venv is
activated
+ ```
+
+4. To update the stubs, only after changing the pyo3 API surface (nothing in
CI checks stub freshness, so unconditional regen just invites `.pyi` churn), use
+
+ ```bash
+ # run from foreign/python
+ cargo run --bin stub_gen
+ # TODO: Known bug: running this from a subdirectory of `foreign/python`
corrupts the tracked stub, see
https://github.com/apache/iggy/pull/3825/changes/BASE..773a27971b4ddb7b44773ded395ed23afb1de4c9#r3727691619
+ ```
+
+5. Before committing, test the pre-commit and pre-push hooks. `prek` only
inspects staged content, so stage your work first:
+
+ ```bash
+ git add -A
+ prek run # runs pre-commit hooks
+ prek run --hook-stage pre-push
+ # if a hook modifies files, re-run `git add -A` and `prek run`.
+ ```
+
+ These are some of the essential commands prek is running, so it's
recommended to run them manually before
+running prek / committing / pushing. This list is not exhaustive and other
hook failures are possible.
+
+ ```bash
+ uv run --no-sync ruff format .
+ ```
+
+ ```bash
+ uv run --no-sync ruff check --fix .
+ ```
+
+ ```bash
+ cargo fmt --manifest-path Cargo.toml
+ ```
+
+ ```bash
+ cargo clippy --manifest-path Cargo.toml --all-targets --all-features -- -D
warnings
+ ```
+
+ ```bash
+ # run from the repository's root directory
+ ./scripts/ci/markdownlint.sh --fix foreign/python/README.md # read the diff
after applying this, sometimes it gives unwanted results, e.g. messing up
enumerations
+ ```
## Examples
@@ -64,7 +145,7 @@ Refer to the
[examples/python/](https://github.com/apache/iggy/tree/master/examp
## Contributing
-See
[CONTRIBUTING.md](https://github.com/apache/iggy/blob/master/foreign/python/CONTRIBUTING.md)
for development setup and guidelines.
+See
[CONTRIBUTING.md](https://github.com/apache/iggy/blob/master/CONTRIBUTING.md)
for contribution guidelines.
## License
