pip-tools is missing a lot of practical documentation

[Kache]

Coming from having experience with poetry and bundler from Ruby, I'm finding it frustrating to get started with pip-tools. As far as I can tell, the only docs available are:

• https://pip-tools.readthedocs.io/en/stable/

• https://github.com/jazzband/pip-tools/blob/main/README.rst

  A synopsis of my experience follows.

Environment Versions

1. OS Type: OSX
2. Python version: Python 3.11.1
3. pip version: pip 22.3.1
4. pip-tools version: pip-compile, version 6.12.1

Steps to replicate

I started out trying to use a pyproject.toml, as I heard pip-tools now supports it. I wasn't even able to get a minimal working project up and running:

[project]
name = "sandbox"
# dependencies = ["more-itertools"]

Which fails if the last line is uncommented, with no guidance as what to do:

❯ pip-compile -v --no-emit-index-url --resolver=backtracking pyproject.toml
Creating venv isolated environment...
Installing packages in isolated environment... (setuptools >= 40.8.0, wheel)
Getting build dependencies for wheel...
Backend subprocess exited when trying to invoke get_requires_for_build_wheel
Failed to parse /Users/REDACTED/sandbox/pyproject.toml

Adopting a pyproject.toml generated via poetry doesn't work either.

I was more successful with requirements.in, but have been unable to find mentions of or ways to do practical things like:

• separate prod, test, dev dependency constraints
• basic constraint operators, e.g.
  • poetry explaining things like ^: https://python-poetry.org/docs/dependency-specification/
  • bundler explaining things like ~>: https://bundler.io/guides/gemfile.html

Expected result

...

Actual result

...

[webknjaz]

Yes, send PRs.

[benjamin-kirkbride]

So uh.. what is the solution to the minimal example that doesn't work above?

[AndydeCleyre]

@benjamin-kirkbride It's not a valid pyproject.toml file, which pip-tools will not generate for you. I recommend flit for that task, but that's not the only option. If you check with validate-pyproject, it reports:

Invalid file: pyproject.toml
[ERROR] `project` must contain ['version'] properties

[nikhilweee]

I had no luck with validate-pyproject and unfortunately I had to spend a lot more time debugging the underlying issue. I have described my solution in https://github.com/jazzband/pip-tools/issues/1860 in case someone else gets the same error Failed to parse pyproject.toml

[aentwist]

I landed here because I wish the 'build backend failed to parse pyproject.toml' error message was better. Thanks for the linting recommendations.

separate prod, test, dev dependency constraints

https://github.com/jazzband/pip-tools/?tab=readme-ov-file#workflow-for-layered-requirements

basic constraint operators

There is no reason anyone should duplicate documentation. These should be PEP 508 (also found on the packaging site), and with a guide. Do I think their guide is good? Not really. But does that belong here? No.