How to specify Python requirements by allowing prereleases?

Question

I am having some kind of confusion regarding the right way of declaring requirements of Python packages.

New builds that are not officially released yes do have pre-release names like 0.2.3.dev20160513165655.

pip is really smart to install pre-releases when we add --pre option and when we are building the develop branch we do use it. Master branch does not use it.

I discovered that if I put foobar>=0.2.3 in a requirements file the development version will not be picked even if I specified the --pre parameter.

The pip documentation is not helping here too much because is missing to point anything about pre-releases.

I used the approach of putting foobar>0.2.2 which in conjunction with --pre would install the pre-release.

Still even this if a bit flawed because if we release a hotfix like 0.2.2.1 it may have picked it.

So, what's the best approach to deal with this?

Side note: It would be highly desired not to have to patch the requirement file when we do make a release (a pull request from develop to master). Please remember that develop branch is always using --pre and the master doesn't.

Answer 1

For anyone else coming across this question, the answer is in the same documentation:

If a Requirement specifier includes a pre-release or development version (e.g. >=0.0.dev0) then pip will allow pre-release and development versions for that requirement. This does not include the != flag.

Hence, specifying >=0.2.3.dev0 or similar should pick the "newest" prerelease.

Note that if you already have 0.2.3 released, it will always sort "newer" than prereleases such as 0.2.3.dev20160513165655. PEP 440 says the following:

The developmental release segment consists of the string .dev, followed by a non-negative integer value. Developmental releases are ordered by their numerical component, immediately before the corresponding release (and before any pre-releases with the same release segment), and following any previous release (including any post-releases).

It also says:

... publishing developmental releases of pre-releases to general purpose public index servers is strongly discouraged, as it makes the version identifier difficult to parse for human readers. If such a release needs to be published, it is substantially clearer to instead create a new pre-release by incrementing the numeric component.

Developmental releases of post-releases are also strongly discouraged ...

So ideally you would not use a datestamp, but something like dev1, dev2, dev3. I think the PEP is actually saying you should use 0.2.3.dev1, 0.2.4.dev1, 0.2.5.dev1, but either is equally readable. It really depends on how many builds you are producing.

In your case, if 0.2.3 is already released, all the subsequent development releases need to be 0.2.4.dev20160513165655 so that pip will see it as newer.