From b0ce2fef316fa762b090b8a61f8d36dd8ff4ca2a Mon Sep 17 00:00:00 2001 From: jepegit Date: Thu, 16 Jul 2026 20:36:10 +0200 Subject: [PATCH] docs: align README with uv workflow and Python 3.11+ floor (#19) Co-authored-by: Cursor --- .../03-solved-issues/issue19_original.md | 16 ++++++ .issueflows/03-solved-issues/issue19_plan.md | 41 +++++++++++++++ .../03-solved-issues/issue19_status.md | 15 ++++++ .../code-review-packaging-and-ops.md | 8 +-- .../04-designs-and-guides/this-project.md | 2 +- README.md | 52 ++++++++----------- 6 files changed, 99 insertions(+), 35 deletions(-) create mode 100644 .issueflows/03-solved-issues/issue19_original.md create mode 100644 .issueflows/03-solved-issues/issue19_plan.md create mode 100644 .issueflows/03-solved-issues/issue19_status.md diff --git a/.issueflows/03-solved-issues/issue19_original.md b/.issueflows/03-solved-issues/issue19_original.md new file mode 100644 index 0000000..30e7219 --- /dev/null +++ b/.issueflows/03-solved-issues/issue19_original.md @@ -0,0 +1,16 @@ +# Issue #19: Align README with uv and the actual Python version floor + +Source: https://github.com/ife-bat/oeleo/issues/19 + +## Original issue text + +## Summary +README still mixes `pip` / `python -m build` guidance and says Python 3.8 is no longer required for ≥0.6, while `pyproject.toml` still has `requires-python = \">=3.8,<3.13\"`. Day-to-day toolchain is **uv**. + +**Finding ID:** DOC-01 +**Size:** yolo-fit +**Design doc:** `.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md` and `this-project.md` + +## Acceptance +- [ ] README install/dev/test commands match `uv` workflow +- [ ] Python version story matches `pyproject.toml` (raise floor or fix the README claim) diff --git a/.issueflows/03-solved-issues/issue19_plan.md b/.issueflows/03-solved-issues/issue19_plan.md new file mode 100644 index 0000000..26536c0 --- /dev/null +++ b/.issueflows/03-solved-issues/issue19_plan.md @@ -0,0 +1,41 @@ +# Issue #19 plan + +## Goal + +Align README install/dev/test/build guidance with the project's **uv** workflow and the current `requires-python` floor (`>=3.11,<3.13`). + +## Constraints + +- Docs-only; do not change `pyproject.toml` unless the README claim still disagrees (floor already raised in #11). +- Keep a clear PyPI end-user install path (`pip install oeleo` is fine for consumers). +- Match day-to-day commands in `.issueflows/04-designs-and-guides/this-project.md`. +- Update DOC-01 note in `code-review-packaging-and-ops.md` so agents do not re-open closed drift. + +### Prior art + +- `this-project.md` — canonical `uv sync` / `uv run pytest -m "not ssh"` commands. +- `code-review-packaging-and-ops.md` DOC-01 — source finding for this issue. +- Issue #11 — already raised `requires-python` to `>=3.11,<3.13`; README Dev bullets already reflect that. + +## Approach + +1. Expand **Development** with `uv sync` / `uv sync --all-extras`, version bump via `uv version --bump`, and tests matching CI (`not ssh` default). +2. Replace `python -m build` / `python -m twine …` with `uv build` / `uv publish`. +3. Leave consumer `pip install oeleo` under Install; optionally note from-source/dev uses uv. +4. Confirm Python version wording matches `pyproject.toml` (no floor change needed). +5. Mark DOC-01 addressed in the packaging design doc. + +## Files to touch + +| File | Change | +|------|--------| +| `README.md` | uv-first dev/test/build/publish; Python floor consistency | +| `.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md` | DOC-01 resolved note | + +## Test strategy + +`uv run pytest -m "not ssh"` (docs-only; regression check). + +## Open questions + +None — yolo auto-confirm. diff --git a/.issueflows/03-solved-issues/issue19_status.md b/.issueflows/03-solved-issues/issue19_status.md new file mode 100644 index 0000000..71ec117 --- /dev/null +++ b/.issueflows/03-solved-issues/issue19_status.md @@ -0,0 +1,15 @@ +# Issue #19 status + +- [x] Done + +## What's done + +- README Development: `uv sync`, tests, format, `uv version --bump`, `uv build` / `uv publish`. +- Consumer install kept as `pip install oeleo`; pointed clone/dev at Development. +- Confirmed Python floor wording matches `pyproject.toml` (`>=3.11,<3.13`; raised in #11). +- DOC-01 marked resolved in `code-review-packaging-and-ops.md`; `this-project.md` publish note updated. +- Unit tests: `uv run pytest -m "not ssh"` green. + +## Remaining work + +None. diff --git a/.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md b/.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md index 7d4e45e..268c7ee 100644 --- a/.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md +++ b/.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md @@ -15,10 +15,12 @@ See [`code-review-overview.md`](code-review-overview.md) for the index. ### DOC-01 — Docs/toolchain drift -- README still shows `pip install oeleo` and `python -m build` / twine; day-to-day is **uv**. -- README: “Python 3.8 support is no longer required” for ≥0.6, but `requires-python = ">=3.8,<3.13"` remains. +**Resolved in #19** (floor raised earlier in #11): README Development uses `uv sync` / `uv run` / `uv build` / `uv publish`, and states `requires-python = ">=3.11,<3.13"`. Consumer install remains `pip install oeleo` from PyPI. + +Still open / related: + - `requirements.txt` at repo root is tiny/legacy relative to `uv.lock`. -- Agents should follow **`uv`** + `pyproject.toml` over README anecdotes when they conflict; fix docs in a dedicated issue. +- Prefer **`uv`** + `pyproject.toml` if any remaining doc anecdotes disagree. ## Windows app / PyInstaller diff --git a/.issueflows/04-designs-and-guides/this-project.md b/.issueflows/04-designs-and-guides/this-project.md index ab571dc..80ce05b 100644 --- a/.issueflows/04-designs-and-guides/this-project.md +++ b/.issueflows/04-designs-and-guides/this-project.md @@ -48,7 +48,7 @@ Config is via **environment variables** / `.env` (see `.env_example` and README) - **Static version (uv):** `[project] version` lives in `pyproject.toml` (currently `0.7.0`). - Bump with `uv version --bump ` before the release commit when closing a release-oriented issue. -- Publish historically via build + twine (README); keep PyPI tokens out of the repo. +- Publish with `uv build` / `uv publish` (see README); keep PyPI tokens out of the repo. ## Entry points diff --git a/README.md b/README.md index 7676a37..57425bf 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,14 @@ Python package / app that can be used for transferring files from an instrument- ### Install +From PyPI (end users): + ```bash -$ pip install oeleo +pip install oeleo ``` + +From a clone (development), use **uv** — see [Development](#development). + ### Run 1. Create an `oeleo` worker instance. @@ -276,44 +281,29 @@ for name in ("paramiko", "fabric", "invoke"): ## Development -- Developed using `uv` on `python 3.11+`. -- Requires Python `>=3.11,<3.13` (see `pyproject.toml`). - -### Some useful commands - -#### Update version - -```bash -# update version in pyproject.toml, e.g. from 0.5.3 to 0.6.0 -``` -## Testing - -Unit tests: +Day-to-day toolchain is **uv** (`uv.lock` is committed). Requires Python `>=3.11,<3.13` (see `pyproject.toml`); develop on **3.11+** (CI uses 3.12). ```bash -uv run pytest -``` +# Sync the project environment (add --all-extras when you need pystray) +uv sync +uv sync --all-extras -SSH integration tests (requires a local SSH server): +# Unit tests (default / CI path) +uv run pytest -m "not ssh" -```bash +# SSH integration tests (needs a local SSH server — see tests/README.md) uv run pytest -m ssh -``` -See `tests/README.md` for Docker setup, environment variables, and helper scripts. +# Format (black + isort; not enforced in CI) +uv run black oeleo tests app +uv run isort oeleo tests app -#### Build +# Bump version in pyproject.toml (e.g. 0.7.0 → 0.7.1) +uv version --bump patch -```bash -python -m build -``` - -#### Publish - -If you are using 2-factor authentication, you need to create a token on pypi.org and run: - -```bash -python -m twine upload -u __token__ -p dist/* +# Build and publish +uv build +uv publish # uses PyPI token from the environment / keyring ``` ### Next