Specifying Your Project’s Version ¶

Setuptools can work well with most versioning schemes. Over the years,setuptools has tried to closely follow thePEP 440 scheme, but italso supports legacy versions. There are, however, afew special things to watch out for, in order to ensure that setuptools andother tools can always tell what version of your package is newer than anotherversion. Knowing these things will also help you correctly specify whatversions of other projects your project depends on.

A version consists of an alternating series of release numbers andpre-releaseorpost-release tags. Arelease number is a series of digits punctuated bydots, such as2.4 or0.5. Each series of digits is treatednumerically, so releases2.1 and2.1.0 are different ways to spell thesame release number, denoting the first subrelease of release 2. But2.10is thetenth subrelease of release 2, and so is a different and newer releasefrom2.1 or2.1.0. Leading zeros within a series of digits are alsoignored, so2.01 is the same as2.1, and different from2.0.1.

Following a release number, you can have either a pre-release or post-releasetag. Pre-release tags make a version be consideredolder than the versionthey are appended to. So, revision2.4 isnewer than release candidate2.4rc1, which in turn is newer than beta release2.4b1 oralpha release2.4a1. Postrelease tags makea version be considerednewer than the version they are appended to. So,revisions like2.4.post1 are newer than2.4, butolderthan2.4.1 (which has a higher release number).

In the case of legacy versions (for example,2.4pl1), they are consideredolder than non-legacy versions. Taking that in count, a revision2.4pl1isolder than2.4. Note that2.4pl1 is notPEP 440-compliant.

A pre-release tag is a series of letters that are alphabetically before“final”. Some examples of prerelease tags would includealpha,beta,a,c,dev, and so on. You do not have to place a dot or dashbefore the prerelease tag if it’s immediately after a number, but it’s okay todo so if you prefer. Thus,2.4c1 and2.4.c1 and2.4-c1 allrepresent release candidate 1 of version2.4, and are treated as identicalby setuptools. Note that onlya,b, andrc arePEP 440-compliantpre-release tags.

In addition, there are three special prerelease tags that are treated as ifthey wererc:c,pre, andpreview. So, version2.4c1,2.4pre1 and2.4preview1 are all the exact same version as2.4rc1, and are treated as identical by setuptools.

A post-release tag is the string.post, followed by a non-negative integervalue. Post-release tags are generally used to separate patch numbers, portnumbers, build numbers, revision numbers, or date stamps from the releasenumber. For example, the version2.4.post1263 might denote Subversionrevision 1263 of a post-release patch of version2.4. Or you might use2.4.post20051127 to denote a date-stamped post-release. Legacy post-releasetags could be either a series of letters that are alphabetically greater than orequal to “final”, or a dash (-) - for example2.4-r1263 or2.4-20051127.

Notice that after each legacy pre or post-release tag, you are free to placeanother release number, followed again by more pre- or post-release tags. Forexample,0.6a9.dev41475 could denote Subversion revision 41475 of thein-development version of the ninth alpha of release 0.6. Notice thatdevis a pre-release tag, so this version is alower version number than0.6a9, which would be the actual ninth alpha of release 0.6. But the41475 is a post-release tag, so this version isnewer than0.6a9.dev.

For the most part, setuptools’ interpretation of version numbers is intuitive,but here are a few tips that will keep you out of trouble in the corner cases:

Don’t stick adjoining pre-release tags together without a dot or numberbetween them. Version1.9adev is theadev prerelease of1.9,not a development pre-release of1.9a. Use.dev instead, as in1.9a.dev, or separate the prerelease tags with a number, as in1.9a0dev.1.9a.dev,1.9a0dev, and even1.9a0.dev0 areidentical versions from setuptools’ point of view, so you can use whateverscheme you prefer. Of these examples, only1.9a0.dev0 isPEP 440-compliant.

If you want to be certain that your chosen numbering scheme works the wayyou think it will, you can use thepkg_resources.parse_version() functionto compare different version numbers:

>>>frompkg_resourcesimportparse_version>>>parse_version("1.9.a.dev")==parse_version("1.9a0dev")True>>>parse_version("2.1-rc2")<parse_version("2.1")True>>>parse_version("0.6a9dev-r41475")<parse_version("0.6a9")True

Once you’ve decided on a version numbering scheme for your project, you canhave setuptools automatically tag your in-development releases with variouspre- or post-release tags. See the following section for more details.

Tagging and “Daily Build” or “Snapshot” Releases¶

Warning

Please note that runningpythonsetup.py... directly is no longerconsidered a good practice and that in the future the commandsegg_infoandrotate will be deprecated.

As a result, the instructions and information presented in this sectionshould be consideredtransitional while setuptools don’t provide amechanism for tagging releases.

Meanwhile, if you can also consider usingsetuptools-scm to achievesimilar objectives.

When a set of related projects are under development, it may be important totrack finer-grained version increments than you would normally use for e.g.“stable” releases. While stable releases might be measured in dotted numberswith alpha/beta/etc. status codes, development versions of a project oftenneed to be tracked by revision or build number or even build date. This isespecially true when projects in development need to refer to one another, andtherefore may literally need an up-to-the-minute version of something!

To support these scenarios,setuptools allows you to “tag” your source andegg distributions by adding one or more of the following to the project’s“official” version identifier:

A manually-specified pre-release tag, such as “build” or “dev”, or amanually-specified post-release tag, such as a build or revision number(--tag-build=STRING,-bSTRING)
An 8-character representation of the build date (--tag-date,-d), asa postrelease tag

You can add these tags by addingegg_info and the desired options tothe command line ahead of thesdist orbdist commands that you wantto generate a daily build or snapshot for. See the section below on theegg_info command for more details.

(Also, before you release your project, be sure to see the section onSpecifying Your Project’s Version for more information about how pre- andpost-release tags affect how version numbers are interpreted. This isimportant in order to make sure that dependency processing tools will knowwhich versions of your project are newer than others).

Finally, if you are creating builds frequently, and either building them in adownloadable location or are copying them to a distribution server, you shouldprobably also check out therotate command, which lets you automaticallydelete all but the N most-recently-modified distributions matching a globpattern. So, you can use a command line like:

setup.pyegg_info-rbDEVbdist_eggrotate-m.egg-k3

to build an egg whose version info includes “DEV-rNNNN” (where NNNN is themost recent Subversion revision that affected the source tree), and thendelete any egg files from the distribution directory except for the threethat were built most recently.

If you have to manage automated builds for multiple packages, each withdifferent tagging and rotation policies, you may also want to check out thealias command, which would let each package define an alias likedailythat would perform the necessary tag, build, and rotate commands. Then, asimpler script or cron job could just runsetup.pydaily in each projectdirectory. (And, you could also define sitewide or per-user default versionsof thedaily alias, so that projects that didn’t define their own woulduse the appropriate defaults.)

Making “Official” (Non-Snapshot) Releases¶

When you make an official release, creating source or binary distributions,you will need to override the tag settings fromsetup.cfg, so that youdon’t end up registering versions likefoobar-0.7a1.dev-r34832. This iseasy to do if you are developing on the trunk and using tags or branches foryour releases - just make the change tosetup.cfg after branching ortagging the release, so the trunk will still produce development snapshots.

Alternately, if you are not branching for releases, you can override thedefault version options on the command line, using something like:

setup.pyegg_info-Db""sdistbdist_egg

The first part of this command (egg_info-Db"") will override theconfigured tag information, before creating source and binary eggs. Thus, thesecommands will use the plain version from yoursetup.py, without adding thebuild designation string.

Of course, if you will be doing this a lot, you may wish to create a personalalias for this operation, e.g.:

setup.pyalias-ureleaseegg_info-Db""

You can then use it like this:

setup.pyreleasesdistbdist_egg

Or of course you can create more elaborate aliases that do all of the above.See the sections below on theegg_info andalias commands for more ideas.

On this page

Specifying Your Project’s Version
- Tagging and “Daily Build” or “Snapshot” Releases
- Making “Official” (Non-Snapshot) Releases

Movatterモバイル変換

Specifying Your Project’s Version¶

Tagging and “Daily Build” or “Snapshot” Releases¶

Making “Official” (Non-Snapshot) Releases¶

Specifying Your Project’s Version ¶