Warn against using requires/provides/obsoletes in setup.py

[techtonik]

BPO	1635217
Nosy	@vstinner, @tarekziade, @merwok

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/merwok'
closed_at = <Date 2019-07-29.11:26:25.785>
created_at = <Date 2007-01-14.15:09:04.000>
labels = ['easy', 'type-feature', 'library', 'docs']
title = 'Warn against using requires/provides/obsoletes in setup.py'
updated_at = <Date 2019-07-29.11:26:25.778>
user = 'https://bugs.python.org/techtonik'

bugs.python.org fields:

activity = <Date 2019-07-29.11:26:25.778>
actor = 'vstinner'
assignee = 'eric.araujo'
closed = True
closed_date = <Date 2019-07-29.11:26:25.785>
closer = 'vstinner'
components = ['Distutils', 'Documentation']
creation = <Date 2007-01-14.15:09:04.000>
creator = 'techtonik'
dependencies = []
files = []
hgrepos = []
issue_num = 1635217
keywords = ['easy']
message_count = 15.0
messages = ['31028', '31029', '31030', '107145', '112787', '160473', '160755', '160797', '160842', '160906', '160918', '160975', '161009', '161011', '348608']
nosy_count = 6.0
nosy_names = ['nnorwitz', 'vstinner', 'techtonik', 'tarek', 'eric.araujo', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue1635217'
versions = ['Python 2.7', 'Python 3.5']

[techtonik]

It would be nice to see example of setup() call on the page with "requires" keywords argument description http://docs.python.org/dist/node10.html

Like:
setup(...,
requires=["somepackage (>1.0, !=1.5)"],
provides=["mypkg (1.1)"]
)

There seems to be mistake in table with examples for "provides" keyword on the same page - it looks like:
mypkg (1.1

shouldn't this be mypkg (1.1)?

[nnorwitz]

Thanks for the report. I fixed the unbalanced paren. I'll leave this open in case someone is ambitious to add more doc.

Committed revision 53487. (2.5)
Committed revision 53488.

[nnorwitz]

Anatoly, if you could create the doc in plain text, we could add it.

[techtonik]

Neal, why a piece from bpo-1635217#msg31028 doesn't qualify as an example?

It seems that this issue may become obsolete with new packaging guide coming up.

[merwok]

This report is made obsolete by PEP-345. Be certain that distutils2 docs and tests will contain examples of Requires-Dist and Provides-Dist.

[techtonik]

I still need requires example - here. http://docs.python.org/distutils/setupscript.html#relationships-between-distributions-and-packages - after "Dependencies.." paragraph. =)

setup(...,
requires=["somepackage (>1.0, !=1.5)"],
provides=["mypkg (1.1)"]
)

[techtonik]

It doesn't seem that requires parameter is honored by pip. Should we document install_requires instead?

[merwok]

Sorry, I have to reject this again.

1. The distutils doc only gets bug fixes now. It is more useful to spend time on distutils2.

2. requires is unusable and unused, because it contains module names, not PyPI project names. Documenting it would cause more harm than good. Right now people use setuptools’ install_requires, which were the inspiration for the PEP-345 fields, which is implemented in distutils2.

[techtonik]

You've nailed it. I think it is important to know that requires is unused. Still this parameter is already present in documentation and causes a lot of trouble (at first I thought there is a bug with pip).

Can we still have proper comment explaining the situation with a pointer to install_requires without any reference to setuptools, so that the latest documentation could actually be useful?

[merwok]

It may be good to document that requires/provides/obsoletes are effectively unused.

It is not appropriate for stdlib doc to talk about install_requires, which is specific to setuptools, and it’s better to talk about the new standard fields from PEP-345 anyway.

[techtonik]

PEP-345 completely misses practical side. I need to specify dependencies for my package, so that people who checked out the source code could run pip install . in virtualenv and get everything fetched.

People reading the docs are more practical. What is the alternative if requires doesn't work and install_requires is not official?

[merwok]

Again, the stdlib docs do not document third-party projects. Use the pip doc if you use pip.

[techtonik]

I am trying to get what's the proposed standard for users right now? How are you going to define dependencies in distutils2?

[merwok]

Right now the standard (i.e. official) way is Requires, which is unusable; the de facto standard (but not blessed by any PEP) is setuptools’ install_requires. The new standard is documented in d2 docs and there will be examples (http://bugs.python.org/issue1635217#msg112787).

[vstinner]

This issue seems to be controversial. I suggest to open a discussion at te Packaging forum https://discuss.python.org/c/packaging rather than using the bug tracker. I close this issue.