Migrate to pyproject.toml for project configuration

[crazy4pi314]

Pre-Request Checklist

• I checked to make sure that this feature has not already been requested.

Issue Description

By newly accepted PEP guides for best practices, project configuration/parameters should be set in a pyproject.toml instead of requirements files, setup.py, and other conf files. Many other tools in the Python ecosystem already support getting configuration from these toml files (just another markdown sort of syntax). One really nice thing about this is that there is one file (not script) that you can look at for everything you need to configure the project. It allows for so many specifications like optional and dev dependencies, easy version numbering based on git tags, and so much more.

Proposed Solution

Move any tools/configuration to the pyproject.toml file we already have (black requires it for conf).

Tools confirmed to use:

• black
• pytest
• mypy

Tools that we use that don't default support pyproject.toml, but have shims to make it work:

• flake8
• sphinx
  • MyST by extension

Additional References

Blogs from Python core maintainers/community that are helpful in understanding the changes and how to migrate:

• https://snarky.ca/what-the-heck-is-pyproject-toml/
• http://ivory.idyll.org/blog/2021-transition-to-pyproject.toml-example.html
• https://discuss.python.org/t/where-to-get-started-with-pyproject-toml/4906

Examples of files in the wild:

• https://github.com/sphinx-toolbox/sphinx-pyproject/blob/master/pyproject.toml

[dbanty]

@crazy4pi314 will you be using Poetry to define dependencies as part of this? It’ll give you the separation between ranges on install and pinning for CI that you’re looking for in #839 and is by far the easiest way to manage dependencies in general (that I’ve found).

We use it over in pyQuil if you want to see an example of config, usage in CI, etc.

[crazy4pi314]

@crazy4pi314 will you be using Poetry to define dependencies as part of this?

Yeah, I think that would make the most sense. It is just too complicated to manage the different groups of requirements, lockfiles, and package metadata it seems without tools like Poetry :) Thanks for the example too!

[github-actions]

This issue had no activity for 2 months, and will be closed in one week unless there is new activity. Cheers!

[natestemen]

related: #857

[purva-thakre]

@natestemen Can we make this a priority for the coming milestone?

Based on how toqito is set up, I know poetry is a better and faster dependency resolver than pip. It would make issues like #2659 easier to understand.

[natestemen]

@bachase if Mitiq is going to switch to a new tool for dependency/env management, can you just say briefly why you like uv better than poetry to help us make an informed choice?

[bachase]

@bachase if Mitiq is going to switch to a new tool for dependency/env management, can you just say briefly why you like uv better than poetry to help us make an informed choice?

https://martynassubonis.substack.com/p/python-project-management-primer-a55 is a good summary that I agree with, although I primarily started out with the speed of uv which was way faster than poetry in resolving dependencies. It's worth deciding this sooner across all the unitary foundation libraries though ... should we start a discussion in this project on the pros/cons and get feedback from other contributors of other packages too?

I personally don't see many cons aside from the work of needing to migrate it, and that dependabot isn't working out of the box with uv yet (https://docs.astral.sh/uv/guides/integration/dependency-bots/#dependabot but seems to be coming soon)

[natestemen]

Thanks for the links Brad! These were helpful to learn a bit more and get some context.

It's worth deciding this sooner across all the unitary foundation libraries

Agreed, just for the sake of efficiency across projects. Since we already have multiple projects using poetry, I think we should just stick with that for now.

[bachase]

@purva-thakre do you have a reproducible example of slow dependency resolution? Or any anecdotal data?

@natestemen if that was a challenge, it could be worth a quick test with uv vs poetry to see the difference. I can't recall the specific case but when I first got excited about uv, it was when poetry was taking minutes to resolve dependencies and uv took a few seconds. That's huge!

As for the impact across UV projects, I think we could focus on the main python packages - mitiq, metriq and ucc. In which case it might not be so painful to migrate?
Cc @cosenal

[purva-thakre]

@bachase I can't find the logs for this right now but I noticed that pip was not doing a good job in toqito because there would be quite a few installation errors after using pip install -e..

pip would either get stuck resolving dependencies or install an incompatible version of some dependency. I ended up pushing for getting rid of the requirements.txt files in favor of dependency groups in the toml file.

Pinging @vprusso in case I have forgotten anything worth mentioning.

[bachase]

Just to add one quick anecdote

For a fresh clone of ucc and removing the poetry.lock, doing a poetry lock took about 12 seconds. Doing a uv lock took 0.5 seconds.