Add best-effort uv install/use support (keep Poetry as canonical)

@hms5232

Follow-up discussion of #92

@hms5232 got your point 👌

@afunTW I don't think we can/should generate/update requirements.txt in CI pipeline. CI shouldn't make changes to the source repo, isn't it?
IIRC, the export command of Poetry can be used to generate requirements.txt. So, in practice, we can either ask developers to remember to run the command every time they update dependency, or just document the generation command in README.md for users who really want to use requirements.txt. 🤣
Not sure if there are other ways.

The pre-commit git hook might be another way. Call the Poetry export command every time they make new commits.
But it might require an existing working poetry installed in $PATH. Just not sure if this should be a hard requirement.

I think we only use Poetry in this project.

For example, Javascript/Node has three package manager at least, but project will not maintain package-lock.json, yarn.lock and pnpm-lock.yaml. They will choose one as their common tool.

Pip is good and has built-in in Python, but it can't control dependencies exactly (This is a disaster when you have many projects use different dependency version in same environment/computer).

@bluet

Understood and agree that CI shouldn't make changes. But I would like to separate into two topics here

Support multiple package manager or not?
Maintain the build-in requirements.txt or not?

Considering the discussion above and the phase of the project right now, supporting only one package manager is the consensus between @bluet, @hms5232, and me.

On the other hand, the built-in package manager always catches my eye on it. I believe the support of requirements.txt is the basic developer-friendly feature.

For example, Javascript/Node has three package manager at least, but project will not maintain package-lock.json, yarn.lock and pnpm-lock.yaml. They will choose one as their common tool.

Actually, the meaning of requirements.txt is like package.json rather than the lock file to me.

@bluet

Understood and agree that CI shouldn't make changes. But I would like to separate into two topics here
1. Support multiple package manager or not?

2. Maintain the build-in requirements.txt or not?
Considering the discussion above and the phase of the project right now, supporting only one package manager is the consensus between @bluet, @hms5232, and me.

On the other hand, the built-in package manager always catches my eye on it. I believe the support of requirements.txt is the basic developer-friendly feature.

For example, Javascript/Node has three package manager at least, but project will not maintain package-lock.json, yarn.lock and pnpm-lock.yaml. They will choose one as their common tool.

Actually, the meaning of requirements.txt is like package.json rather than the lock file to me.

This is one of downside of pip. The requirements.txt looks like:

urllib3==1.26.7
virtualenv==20.10.0
virtualenv-clone==0.5.4

That show the package name and version but not include/point out their dependency graph. So I think requirements.txt is between package.json and lock file. How about you?

The PEP 582 is still in draft, so we should consider that how to keep dependency fit those package but not effect other package in environment (or in reverse, the environment effect project dependencies).

In conclusion, Poetry or Pipenv is good to reach it. Nevertheless, Pipenv has some negative point so I no longer use it. It is my belief:

We should only support one package manager (current is Poetry).
We should maintain both pyproject.toml (PEP 621) and poetry.lock but not include requirements.txt.

By the way, if we want to migrate to PEP 582 in the future, I recommend pyflow or pdm.

So I think requirements.txt is between package.json and lock file. How about you?

Agree, package.json event composes some other functionality.

We should only support one package manager (current is Poetry).

I believe we are on the same page

We should maintain both pyproject.toml (PEP 621) and poetry.lock but not include requirements.txt

What I am only concerned about is the support on requirements.txt. But letting it out of our maintenance scope is fine for our first milestone. Considering the multiple Python supports, this is not a well fit for this project indeed as well.

So I think requirements.txt is between package.json and lock file. How about you?

Agree, package.json event composes some other functionality.

We should only support one package manager (current is Poetry).

I believe we are on the same page

We should maintain both pyproject.toml (PEP 621) and poetry.lock but not include requirements.txt

What I am only concerned about is the support on requirements.txt. But letting it out of our maintenance scope is fine for our first milestone. Considering the multiple Python supports, this is not a well fit for this project indeed as well.

Yes, Poetry has Python version check. And they released 1.2.0 recently. I will make a PR to upgrade CI setting after I use it for a while.

@hms5232

hi @hms5232 , still waiting for your PR hahaha

@hms5232

hi @hms5232 , still waiting for your PR hahaha

A few weeks ago I found a bug at 1.2.1 and report to poetry, they has fixed it at main branch, but still not release in new version. I'm waiting for this, lol.

Poetry 1.2 have many features and some of them are incompatible with 1.1. I am on the road to learn how to apply them. 🚀

@hms5232

@hms5232 ok cool, sounds great

@hms5232

@hms5232 ok cool, sounds great

Update~ I trace the bug reported issue and notice that Poetry seems that plant to release the fixed at version 1.3. Should we wait for 1.3 or just upgrade pipeline to 1.2 first?

@hms5232

@hms5232 If 1.3 might take a while to release, maybe we should go for 1.2 first.

@hms5232

@hms5232 If 1.3 might take a while to release, maybe we should go for 1.2 first.

I'm not sure release schedule whether is delay. The 1.3 marked "Past due by about 1 month" 😄 but 99% completed.

I plan to make a update to go to Poetry 1.2 next week if 1.3 can not release this week. 💪

Sounds great

Surprise! 1.3 has released this morning 🎉 . I'm using this version. If everything okay, I will send a PR to bump Poetry version in action pipeline.

@hms5232

Are we ready to be Poetry-only? @hms5232 @afunTW @vincentinttsh @ziloka

ref:

might also need to update README too if we do.

@hms5232

Are we ready to be Poetry-only? @hms5232 @afunTW @vincentinttsh @ziloka

As here saying, delete the requirements/, there will no other requirements.txt file exists. Therefore, I vote yes.

might also need to update README too if we do.

Maybe add a develop chapter in README or a CONTRIBUTING.md?

@hms5232

@hms5232 go! go! power rangers!

Seems that we have everything settled and can close the issue?

uv as a candidate alongside Poetry — analysis (May 2026)

Astral's uv has matured enough since this thread started in 2023 that it's worth re-evaluating. Concrete dimensions, with this project's actual config in mind:

Speed (the headline win)

Poetry 2.x cold resolve: ~30-60 s on this lockfile size.
uv lock cold: ~1-3 s. 10-30× faster. Compounds heavily in CI matrix runs (Py 3.10 / 3.11 / 3.12 / 3.13 / 3.14 — 5 cells × 30 s saved each = 2.5 min/run).

Compatibility

Build backend already poetry-core in [build-system] — uv is happy with any PEP 517 backend, no change needed there.
The catch: project metadata is in [tool.poetry] (Poetry-specific). uv natively reads PEP 621 [project]. For full uv sync support, project deps need to migrate to [project] + [dependency-groups]. Both formats can coexist during transition.

Migration plan (parallel, low-risk)

Phase 1 (additive, zero risk): Add a PEP 621 [project] section with the same deps mirrored from [tool.poetry.dependencies]. Both Poetry and uv can install at this point.
Phase 2 (lockfile parity check): uv lock → diff resolved versions vs poetry.lock. uv's resolver is stricter; may surface real version conflicts that Poetry hid. Investigate any drift.
Phase 3 (CI speedup): Add uv sync + uv run pytest workflow alongside the existing Poetry one. Run both for 1-2 release cycles to confirm parity.
Phase 4 (deprecation): Once confidence high, remove Poetry-specific config; document uv as primary.

Gotchas

py-to-exe.yml workflow uses Poetry — needs migration too.
Contributor docs (README "Setup" section) need updating; recommend keeping pip install -e . as the always-works fallback for users who don't want either tool.
pyproject.toml deps with caret constraints (^3.12.0) — both Poetry and uv interpret these; no change needed.
The [tool.poetry.dev-dependencies] legacy section needs migration to [tool.poetry.group.dev.dependencies] (Poetry-side) or to PEP 621 [dependency-groups] (uv-native). Doing both is cleanest.

Recommended approach for proxybroker2

Phase 1 + 3 are the high-value-low-risk wins (CI speedup with both tools functional). Phase 4 (Poetry removal) can wait until after 2.0.0 stable lands. This avoids gating on a tooling migration during the active 2.0.0b cycle.

If maintainers agree, I'm happy to open a focused PR for Phase 1 + 2.

fix(security): bump vulnerable deps + add uv install/use compatibility (

Decision (2026-05-20): hybrid — Poetry primary, uv supported

After deep evaluation in PR #230 and discussion, decided to stay on Poetry as primary rather than do a full migration. Adding best-effort uv support for install/use.

Why not full migration

Snyk's GH App doesn't yet support uv.lock (snyk-python-plugin#251 open). Real-world experiments in PR chore: dependency refresh and compatibility/docs alignment (aiodns 4.x, tests, CI) #230 found:
- [project] with no [tool.poetry.dependencies] → snyk preview parses it but flags errors inconsistently
- [project] + [tool.poetry.dependencies] coexisting → snyk reports "pyproject.toml error Failed to detect issues"
- Only [tool.poetry.dependencies] (legacy) → snyk works natively
Dual-lockfile approach (uv.lock + poetry.lock) creates drift risk with auto-security-patching bots (Dependabot, Snyk auto-fix PRs may patch one but not the other). Pre-commit regeneration helps for human contributors but doesn't run on bot PRs.
Other famous uv adopters (Pydantic, FastAPI, httpx) don't use snyk — they rely on CodeQL + Dependabot + their own tooling. Snyk parity for uv is a real gap.
Maintainer has many repos; the migration's per-repo burden + ecosystem friction outweighs the speed gain today.

What's supported as of PR #230

Poetry (canonical): poetry install, poetry.lock is the authoritative lockfile, CI tests against it, snyk scans it natively.
pip: pip install git+https://github.com/bluet/proxybroker2.git@<tag> (always worked).
uv (best-effort):
- uv pip install git+https://github.com/bluet/proxybroker2.git@<tag> — works because poetry-core synthesizes PEP 621 metadata at build time
- uv add "proxybroker2 @ git+..." — works for uv-managed projects
- uv sync in a source checkout — works, produces a transient uv.lock (gitignored to avoid drift with poetry.lock)
- Caveat: uv-managed dev contributors may resolve different versions than CI tests against (poetry.lock is the canonical resolution).

Note on PyPI

Do not install from PyPI. Both proxybroker and proxybroker2 names are squatted there (see #186 and pypi/support#10315). Install only from this repository via git+https.

Revisit triggers

Reopen the full migration question when ANY of these happen:

snyk-python-plugin#251 ships uv.lock support in the GH App (not just CLI preview)
Snyk officially deprecates Poetry support
Build/CI cost of Poetry becomes painful enough that the migration's speed gain dominates the per-repo migration cost

Closing this issue as resolved with PR #230.

chore: dependency refresh and compatibility/docs alignment (aiodns 4.…

Navigation Menu

Repository navigation

Add best-effort uv install/use support (keep Poetry as canonical) #105

uv as a candidate alongside Poetry — analysis (May 2026)

Speed (the headline win)

Compatibility

Migration plan (parallel, low-risk)

Gotchas

Recommended approach for proxybroker2

Decision (2026-05-20): hybrid — Poetry primary, uv supported

Why not full migration

What's supported as of PR #230

Note on PyPI

Revisit triggers

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Add best-effort uv install/use support (keep Poetry as canonical) #105

Description

Activity

bluet commented on Aug 31, 2022

hms5232 commented on Sep 1, 2022

afunTW commented on Sep 1, 2022

hms5232 commented on Sep 1, 2022

afunTW commented on Sep 2, 2022

hms5232 commented on Sep 2, 2022

bluet commented on Nov 4, 2022

hms5232 commented on Nov 4, 2022

bluet commented on Nov 4, 2022

hms5232 commented on Nov 28, 2022

bluet commented on Nov 29, 2022

hms5232 commented on Nov 30, 2022

bluet commented on Nov 30, 2022

hms5232 commented on Dec 10, 2022

bluet commented on Feb 12, 2023

bluet commented on Feb 12, 2023

hms5232 commented on Feb 13, 2023

bluet commented on Feb 25, 2023

bluet commented on Feb 25, 2023

bluet commented on May 9, 2026

uv as a candidate alongside Poetry — analysis (May 2026)

Speed (the headline win)

Compatibility

Migration plan (parallel, low-risk)

Gotchas

Recommended approach for proxybroker2

bluet commented on May 20, 2026

Decision (2026-05-20): hybrid — Poetry primary, uv supported

Why not full migration

What's supported as of PR #230

Note on PyPI

Revisit triggers

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions