Pip: Incorrect documentation on requirements.txt format

[wwuck]

While attempting to fix an issue in pip-tools, it was discovered that the documentation for the requirements.txt format conflicts with the actual behaviour of pip when it parses a requirements.txt file.

The documentation for requirements.txt format mentions Comments are stripped before line continuations are processed. but the pip code appears to do the opposite, processing the line continuations before it strips the comments.

Which one is correct?

[wwuck]

Does this have any effect on the new pip resolver @pradyunsg ?

[pradyunsg]

Nope. The resolver kicks in after the processing of all potential input sources (including requirements.txt).

[wwuck]

So is there an official consensus on which one is correct @pradyunsg @chrahunt ?

[pradyunsg]

So much of requirements.txt is implementation defined that I'm inclined to say we should update the documentation to match what the behaviour is, instead of touching the behavior.

[gutsytechster]

Would it mean stating within the docs that Comments are stripped after line continuations are processed.? Or do you feel some other wording could be used?

[AndydeCleyre]

Just in case it's missed, all that's needed IMO is #7780.

[atugushev]

I made an experiment (#8094) and swapped the lines to see what happens. Two tests test_comments_and_joins_case1 and test_comments_and_joins_case3 are failed, see the tests:

https://github.com/pypa/pip/blob/a531a15376ae8ee9670c1ab15262876a96624b97/tests/unit/test_req_file.py#L76-L100

Since this case:

package1 \
   # a comment
package2

is pretty legit and well tested, thus we may assume that there is a bug in documentation rather than in code.