You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

133 lines
5.5 KiB

4 years ago
  1. Metadata-Version: 2.0
  2. Name: incremental
  3. Version: 17.5.0
  4. Summary: UNKNOWN
  5. Home-page: https://github.com/twisted/incremental
  6. Author: Amber Brown
  7. Author-email: hawkowl@twistedmatrix.com
  8. License: MIT
  9. Platform: UNKNOWN
  10. Classifier: Intended Audience :: Developers
  11. Classifier: License :: OSI Approved :: MIT License
  12. Classifier: Programming Language :: Python :: 2
  13. Classifier: Programming Language :: Python :: 2.6
  14. Classifier: Programming Language :: Python :: 2.7
  15. Classifier: Programming Language :: Python :: 3
  16. Classifier: Programming Language :: Python :: 3.3
  17. Classifier: Programming Language :: Python :: 3.4
  18. Classifier: Programming Language :: Python :: 3.5
  19. Classifier: Programming Language :: Python :: 3.6
  20. Provides-Extra: scripts
  21. Requires-Dist: click (>=6.0); extra == 'scripts'
  22. Requires-Dist: twisted (>=16.4.0); extra == 'scripts'
  23. Incremental
  24. ===========
  25. |travis|
  26. |pypi|
  27. |coverage|
  28. Incremental is a small library that versions your Python projects.
  29. API documentation can be found `here <https://hawkowl.github.io/incremental/docs/>`_.
  30. Quick Start
  31. -----------
  32. Add this to your ``setup.py``\ 's ``setup()`` call, removing any other versioning arguments:
  33. .. code::
  34. setup(
  35. use_incremental=True,
  36. setup_requires=['incremental'],
  37. install_requires=['incremental'], # along with any other install dependencies
  38. ...
  39. }
  40. Then run ``python -m incremental.update <projectname> --create`` (you will need ``click`` installed from PyPI).
  41. It will create a file in your package named ``_version.py`` and look like this:
  42. .. code::
  43. from incremental import Version
  44. __version__ = Version("widgetbox", 17, 1, 0)
  45. __all__ = ["__version__"]
  46. Then, so users of your project can find your version, in your root package's ``__init__.py`` add:
  47. .. code::
  48. from ._version import __version__
  49. Subsequent installations of your project will then use Incremental for versioning.
  50. Incremental Versions
  51. --------------------
  52. ``incremental.Version`` is a class that represents a version of a given project.
  53. It is made up of the following elements (which are given during instantiation):
  54. - ``package`` (required), the name of the package this ``Version`` represents.
  55. - ``major``, ``minor``, ``micro`` (all required), the X.Y.Z of your project's ``Version``.
  56. - ``release_candidate`` (optional), set to 0 or higher to mark this ``Version`` being of a release candidate (also sometimes called a "prerelease").
  57. - ``dev`` (optional), set to 0 or higher to mark this ``Version`` as a development release.
  58. You can extract a PEP-440 compatible version string by using the following methods:
  59. - ``.local()``, which returns a ``str`` containing the full version plus any Git or SVN information, if available. An example output would be ``"17.1.1rc1+r123"`` or ``"3.7.0+rb2e812003b5d5fcf08efd1dffed6afa98d44ac8c"``.
  60. - ``.public()``, which returns a ``str`` containing the full version, without any Git or SVN information. This is the version you should provide to users, or publicly use. An example output would be ``"13.2.0"``, ``"17.1.2dev1"``, or ``"18.8.0rc2"``.
  61. Calling ``repr()`` with a ``Version`` will give a Python-source-code representation of it, and calling ``str()`` with a ``Version`` will provide a string similar to ``'[Incremental, version 16.10.1]'``.
  62. Updating
  63. --------
  64. Incremental includes a tool to automate updating your Incremental-using project's version called ``incremental.update``.
  65. It updates the ``_version.py`` file and automatically updates some uses of Incremental versions from an indeterminate version to the current one.
  66. It requires ``click`` from PyPI.
  67. ``python -m incremental.update <projectname>`` will perform updates on that package.
  68. The commands that can be given after that will determine what the next version is.
  69. - ``--newversion=<version>``, to set the project version to a fully-specified version (like 1.2.3, or 17.1.0dev1).
  70. - ``--rc``, to set the project version to ``<year-2000>.<month>.0rc1`` if the current version is not a release candidate, or bump the release candidate number by 1 if it is.
  71. - ``--dev``, to set the project development release number to 0 if it is not a development release, or bump the development release number by 1 if it is.
  72. - ``--patch``, to increment the patch number of the release. This will also reset the release candidate number, pass ``--rc`` at the same time to increment the patch number and make it a release candidate.
  73. If you give no arguments, it will strip the release candidate number, making it a "full release".
  74. Incremental supports "indeterminate" versions, as a stand-in for the next "full" version. This can be used when the version which will be displayed to the end-user is unknown (for example "introduced in" or "deprecated in"). Incremental supports the following indeterminate versions:
  75. - ``Version("<projectname>", "NEXT", 0, 0)``
  76. - ``<projectname> NEXT``
  77. When you run ``python -m incremental.update <projectname> --rc``, these will be updated to real versions (assuming the target final version is 17.1.0):
  78. - ``Version("<projectname>", 17, 1, 0, release_candidate=1)``
  79. - ``<projectname> 17.1.0rc1``
  80. Once the final version is made, it will become:
  81. - ``Version("<projectname>", 17, 1, 0)``
  82. - ``<projectname> 17.1.0``
  83. .. |coverage| image:: https://codecov.io/github/hawkowl/incremental/coverage.svg?branch=master
  84. .. _coverage: https://codecov.io/github/hawkowl/incremental
  85. .. |travis| image:: https://travis-ci.org/hawkowl/incremental.svg?branch=master
  86. .. _travis: http://travis-ci.org/hawkowl/incremental
  87. .. |pypi| image:: http://img.shields.io/pypi/v/incremental.svg
  88. .. _pypi: https://pypi.python.org/pypi/incremental