Demonstrate python_requires usage

[ncraike]

It would be useful if the sample setup.py demonstrated how to use python_requires to describe the versions of Python your project supports.

I understand python_requires is a new feature of Pip, but I didn't realise it existed: I actually assumed that Pip used the Programming Lange :: Python classifiers to determine the Python versions supported, and published a "Python3-only" package which was still installable on Python 2 as a result.

It'd be useful if the sample demonstrated python_requires, and clarified that the classifiers are recommendations only (for humans to read), while python_requires is actually checked by Pip before installing.

[pfmoore]

I'd be very cautious how we present this (if we do). It's very important not to encourage over-specifying here, or we'll end up with well-meaning project authors listing the versions they support (e.g., 2.7, 3.5 and 3.6), and as a result locking users out from testing their package with newer versions of Python, or even using untested combinations (which they might need to do, accepting that it's at their own risk).

I don't have much of a problem with requires_python >= 3 but anything more restrictive should be used with care (even requires_python = 3 runs a risk if & when Python 4 gets released!).

[ncraike]

I understand that concern.

Considering the goal of sampleproject is to demo packaging tools to new Python developers and get them shipping their code, I think many if not most will be packaging young projects where requires_python >= 3 is appropriate. A single codebase installable on both Python 2 and 3 is not an an easy task and not a beginner's problem.

My biggest concern though is that the current sample setup.py seems to present a solution to packaging a Python-3-only project with the sample usage of "classifiers"… but is not actually a solution at all.

I think a sample usage of requires_python would go a long way to clarifying which options solve which problems. But it'd definitely make sense if the example was commented out by default, and if there was plenty of supporting comments explaining why, eg requires_python >= 3 may be what they need, but requires_python = 3.3 is likely a bad idea.

[pfmoore]

That's a fair comment. The current project, though, does take pains to be an example of how to write a 2/3 compatible project, for better or worse (tox.ini includes 2.7, setup.py includes 2.7 in the classifiers, etc).

A comment block in setup.py including example usage of requires_python could be useful, but that block should probably note the other things that need to change, too. And that might make it too clumsy.

Maybe this is something that should be explained in the Packaging User Guide, rather than trying to cram everything into comments in here.

[ncraike]

The current project, though, does take pains to be an example of how to write a 2/3 compatible project, for better or worse (tox.ini includes 2.7, setup.py includes 2.7 in the classifiers, etc).

Ah, right. If that's the current standard you're aiming for, I completely get you not wanting to abandon that and assume Python3-only.

Maybe this is something that should be explained in the Packaging User Guide, rather than trying to cram everything into comments in here.

That's a decent point. I'm worried that the absence of requires_python altogether makes the classifiers look like they control the same Pip install behaviour. New developers won't read into other options in the Packaging User Guide if they think they've already found the option they need.

Of course we can't ensure that 100% of developers read the relevant docs when they need to. But I think the current state increases the risk they'll make the same mistake I did.

[marcelm]

To anyone who stumbles upon this issue trying to figure out how to use python_requires (and whether requires_ or python_ comes first), here is how it should look in setup.py for a Python-3-only project:

setup(
    ...
    python_requires='>=3',
    ...
)

[pradyunsg]

Perhaps we can add a commented line for python_requires?

[xavfernandez]

With Python 2 support ending in less than a year, I think defaulting to python_requires='>=3' would make sense. (And with Python 3.4 support ending in less than 3 months, we might even push it to python_requires='>=3.5')

[pfmoore]

+1 on making 3.5+ the norm:

setup(
    ...
    # Remove or modify this line if you want to support Python versions older than 3.5
    python_requires='>=3.5',
    ...
)```

[f18m]

+1 for this issue... I just released my Python3-only package on pypi just tagging it with the classifier "Programming Language :: Python :: 3" and a lot of users complained that it didn't work after installing it with "pip" instead of "pip3"... I'm going to add the python_requires='>=3', line to setup.py, but having that in the example would have saved me a lot of time! Thanks.