# pypi-version
[](https://github.com/dmytrostriletskyi/pypi-version/releases)
[](https://pypi.python.org/pypi/pypi-version/)
[](https://travis-ci.com/dmytrostriletskyi/pypi-version)
[](https://codecov.io/gh/dmytrostriletskyi/pypi-version)
[](https://pepy.tech/project/pypi-version)
[](https://pypi.python.org/pypi/pypi-version/)
[](https://pypi.python.org/pypi/pypi-version/)
* [Getting started](#getting-started)
* [How to install](#how-to-install)
* [What is pypi-version](#what-is-pypi-version)
* [Motivation](#motivation)
* [Examples](#examples)
* [Usage](#usage)
* [Command line interface](#command-line-interface)
* [Configuration file](#configuration-file)
* [Continuous integration services](#continuous-integration-services)
* [Travis-CI](#travis-ci)
* [CircleCI](#circleci)
* [Contributing](#contributing)
* [References](#references)
* [Python package](#python-package)
* [Gitflow workflow](#gitflow-workflow)
* [Upload to PyPi](#upload-to-pypi)
* [Continuous integration services](#references-continuous-integration-services)
## Getting started
### How to install
Install the `pypi-version` with the following command using `pip3`:
```bash
$ pip3 install pypi-version
```
### What is pypi-version
``pypi-version`` checks if you haven't forgotten to bump the ``PyPi package version number`` before you merge a release
pull request.
It would be useful if you:
* develop [Python package](https://packaging.python.org/overview/),
* follow [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow),
* upload package to the [Python Package Index (PyPi)](https://pypi.org/),
* use the following continuous integration services: [Travis-CI](https://travis-ci.com), [CircleCI](https://circleci.com)
If you do not know these concepts, go ahead to the [references section](https://github.com/dmytrostriletskyi/pypi-version/tree/develop#references) first. After, start reading from the next section.
### Motivation
`Python packages` have version number such as `0.1.0` or `1.3.3`. `Python packages` commonly are uploaded to `PyPi`.
Sometimes after adding new functionality to your package you forget to increase the version number of the package.
So when you try to upload it, you get the error message `Package version number already in use`. It is okay if
you develop the package locally and alone, you just modify the version number and upload it again. But if you
develop the package using particular development flow such as `Gitflow workflow` and continuous integration
services — then you should create separated pull request to bump the version, the resources and time you will spend
on it are increasing in few times. The cost of the mistake is high.
So if you integrate the `pypi-version` to your continuous integration service by checking the version using simple command line tool, it will `never` allow your pull request to be merged if you forget to increase the version.
### Examples
There is the test repository of the ``Python package`` that has integrated `pypi-version` — [test-pypi-version-travis-ci](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci). It uses `Travis CI` as continuous integration service.
It contains:
* `develop` and `master` branches,
* `master` branch contains file [setup.py where version is 0.1.0](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci/blob/master/setup.py#L7),
* according to the version number in the `master` branch (release branch), package is [uploaded to the PyPi with version 0.1.0](https://pypi.org/project/test-pypi-version-travis-ci/),
* there is a [pull request from develop branch to master branch](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci/pull/1) — it is a release pull request that intend increasing of the version number,
* but in the changes [version number in setup.py isn't increased](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci/pull/1/files#diff-2eeaed663bd0d25b7e608891384b7298R8),
* that's because [pull request's continuous integration checking](https://travis-ci.com/dmytrostriletskyi/test-pypi-version-travis-ci/builds/107324550) is failed — there is `pypi-version` checking integrated.
* as configured, there are an [installing of the pypi-version and checking the version by using it](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci/blob/master/.travis.yml),
* as the result, `pypi-version` [checks](https://travis-ci.com/dmytrostriletskyi/test-pypi-version-travis-ci/jobs/190875378#L482) if release pull request's (from `develop` to `master`) changes contain an increasing the ``package version number`` before it will be merged. In the example that is described above there is no increasing the version —
`pypi-version check` is failed. If one of the declared checking in the configuration file is failed — it means pull request continuous integration checking is failed and pull request does not allowed to be merged with wrong version number.
## Usage
### Command line interface
To check if you haven't forgotten to bump the ``PyPi package version number`` before you merge a release
pull request:
```bash
$ pypi-version check
```
To fetch the version of the `pypi-version` package:
```bash
$ pypi-version --version
pypi-version, version 0.1.0
```
To fetch all available package commands, use the following command:
```bash
$ pypi-version --help
Usage: pypi-version [OPTIONS] COMMAND [ARGS]...
Command line interface for PyPi version checking.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
check Check if you haven't forgotten to bump the PyPi package version.
```
### Configuration file
`pypi-version` requires a configuration file called `.pypi-version.yml` to be located in the root of the project:
```
package
|
- ...
- source
- README.md
- setup.py
- .pypi-version.yml
...
```
The configuration file should contains:
* the section with your `PyPi package name` that is the same with the name in the `setup.py`:
```yml
package:
name: test-pypi-version-travis-ci
```
* name of the continuous integration service you use. Available options are: `travis`.
```yml
ci:
name: travis
```
* `development` and `release` branch names. In the configurations which are illustrated below means
`package version number` will be checked only when you do a pull request from `develop` to `master`.
```yml
branches:
development: develop
release: master
```
The full example of the configuration file is:
```yml
package:
name: pypi-version
ci:
name: travis
branches:
development: develop
release: master
```
### Continuous integration services
#### Travis-CI
The example of the configuration file which install and use `pypi-version`:
```yml
language: python
python:
- "3.6"
install:
- pip install pypi-version
script:
- pypi-version check
```
The example of the failed build (version hasn't been bumped):
#### CircleCI
The example of the configuration file which install and use `pypi-version`:
```yml
version: 2
jobs:
build:
docker:
- image: circleci/python:3.6.4
steps:
- checkout
- run:
name: Install pypi-version package
command: sudo pip3 install pypi-version
- run:
name: Check if PyPi should be bumped
command: sudo -H -E pypi-version check
```
The example of the failed build (version hasn't been bumped):
## Contributing
Clone the project and install requirements:
```bash
$ git clone git@github.com:dmytrostriletskyi/pypi-version.git && cd pypi-version
$ pip3 install -r requirements.txt
$ pip3 install -r requirements-dev.txt
$ pip3 install -r requirements-tests.txt
```
When you will make changes, ensure your code pass [the checkers](https://github.com/dmytrostriletskyi/pypi-version/blob/develop/.travis.yml#L15) and is covered by tests using [pytest](https://docs.pytest.org/en/latest).
If you are new for the contribution, please read:
* Read about pull requests — https://help.github.com/en/articles/about-pull-requests
* Read how to provide pull request — https://help.github.com/en/articles/creating-a-pull-request-from-a-fork
* Also the useful article about how to contribute — https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/
## References
### Python package
`Python package` is redistributed and reused couple of the `Python` scripts. They exist to solve the typical problems. So if
you have common problem in your project — instead of writing own code and spend a time for it, use the package that already have required functionality. The examples of `Python packages` you should know are [requests](https://github.com/kennethreitz/requests) and [Django](https://github.com/django/django).
### Gitflow workflow
Instead of a single `master` branch, this workflow uses two branches to record the history of the project. The `master` branch stores the official release history, and the `develop` branch serves as an integration branch for features.
<img src="https://wac-cdn.atlassian.com/dam/jcr:a9cea7b7-23c3-41a7-a4e0-affa053d9ea7/04%20(1).svg?cdnVersion=le" width="700" height="300">
So when you complete the feature, you open the pull request from `feature` branch to the `develop` branch. When you complete the bunch of features, you open the pull request from `develop` branch to `master` branch which are going to merge this bunch of features that means you do new release.
According to the changes that contains new features, you should increase your version number (e.g. from `1.0.0` to `1.1.0`) in the file called `setup.py` in the same pull request.
### Upload to PyPi
When your features with increased version number have been merged to the `master` branch, you are going to upload your source code to the `Python Package Index`.
Being in the root of you project,
```
package
|
- ...
- source
- README.md
- setup.py
...
```
you do the following command:
```
$ python3 setup.py sdist
$ twine upload dist/*
```
And if you haven't forgotten to bump the ``PyPi package version number``, the upload is successful.
<img src="https://habrastorage.org/webt/55/pk/jn/55pkjnoezzvidqcyordvtyyhgw0.png" width="700" height="300">
<h3 id="references-continuous-integration-services">Continuous integration services</h3>
Continuous integration services are useful when you want add some robotic checking for your pull request changes.
For instance, you can run checking code style with [flake8](https://github.com/PyCQA/flake8) and run tests with [pytest](https://github.com/pytest-dev/pytest) to check your changes does not break existing functionality on the few version
of `Python`. The configuration file example for `Travis CI` is presented below.
```yml
language: python
python:
- "3.4"
- "3.5"
- "3.6"
- "3.7-dev"
install:
- pip install -r requirements-dev.txt
- pip install -r requirements-tests.txt
script:
- cat requirements-tests.txt requirements-dev.txt | safety check --stdin
- radon cc accessify -nb --total-average
- isort -rc accessify --diff && isort -rc tests --diff
- flake8 accessify
- coverage run -m pytest -vv tests
after_success:
- coverage report -m && coverage xml
- bash <(curl -s https://codecov.io/bash)
```
Each pull request the checking report will be presented. By clicking on the `details` you will see full report.
Raw data
{
"_id": null,
"home_page": "https://github.com/dmytrostriletskyi/pypi-version",
"name": "pypi-version",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Dmytro Striletskyi",
"author_email": "dmytro.striletskyi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b0/76/7095c3ade72b5a46190e1242d09197a50c2594d963538ea4fc60f84e406e/pypi-version-0.2.0.tar.gz",
"platform": "",
"description": "# pypi-version\n\n[](https://github.com/dmytrostriletskyi/pypi-version/releases)\n[](https://pypi.python.org/pypi/pypi-version/)\n[](https://travis-ci.com/dmytrostriletskyi/pypi-version)\n[](https://codecov.io/gh/dmytrostriletskyi/pypi-version)\n\n[](https://pepy.tech/project/pypi-version)\n[](https://pypi.python.org/pypi/pypi-version/)\n[](https://pypi.python.org/pypi/pypi-version/)\n\n * [Getting started](#getting-started)\n * [How to install](#how-to-install)\n * [What is pypi-version](#what-is-pypi-version)\n * [Motivation](#motivation)\n * [Examples](#examples)\n * [Usage](#usage)\n * [Command line interface](#command-line-interface)\n * [Configuration file](#configuration-file)\n * [Continuous integration services](#continuous-integration-services)\n * [Travis-CI](#travis-ci)\n * [CircleCI](#circleci)\n * [Contributing](#contributing)\n * [References](#references)\n * [Python package](#python-package)\n * [Gitflow workflow](#gitflow-workflow)\n * [Upload to PyPi](#upload-to-pypi)\n * [Continuous integration services](#references-continuous-integration-services)\n\n## Getting started\n\n### How to install\n\nInstall the `pypi-version` with the following command using `pip3`:\n\n```bash\n$ pip3 install pypi-version\n```\n\n### What is pypi-version\n\n``pypi-version`` checks if you haven't forgotten to bump the ``PyPi package version number`` before you merge a release \npull request. \n\nIt would be useful if you:\n\n* develop [Python package](https://packaging.python.org/overview/),\n* follow [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow),\n* upload package to the [Python Package Index (PyPi)](https://pypi.org/),\n* use the following continuous integration services: [Travis-CI](https://travis-ci.com), [CircleCI](https://circleci.com)\n\nIf you do not know these concepts, go ahead to the [references section](https://github.com/dmytrostriletskyi/pypi-version/tree/develop#references) first. After, start reading from the next section.\n\n### Motivation\n\n`Python packages` have version number such as `0.1.0` or `1.3.3`. `Python packages` commonly are uploaded to `PyPi`.\nSometimes after adding new functionality to your package you forget to increase the version number of the package. \nSo when you try to upload it, you get the error message `Package version number already in use`. It is okay if \nyou develop the package locally and alone, you just modify the version number and upload it again. But if you \ndevelop the package using particular development flow such as `Gitflow workflow` and continuous integration \nservices \u2014 then you should create separated pull request to bump the version, the resources and time you will spend \non it are increasing in few times. The cost of the mistake is high.\n\nSo if you integrate the `pypi-version` to your continuous integration service by checking the version using simple command line tool, it will `never` allow your pull request to be merged if you forget to increase the version.\n\n### Examples\n\nThere is the test repository of the ``Python package`` that has integrated `pypi-version` \u2014 [test-pypi-version-travis-ci](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci). It uses `Travis CI` as continuous integration service.\n\nIt contains:\n\n* `develop` and `master` branches,\n* `master` branch contains file [setup.py where version is 0.1.0](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci/blob/master/setup.py#L7),\n\n\n\n* according to the version number in the `master` branch (release branch), package is [uploaded to the PyPi with version 0.1.0](https://pypi.org/project/test-pypi-version-travis-ci/),\n\n\n\n* there is a [pull request from develop branch to master branch](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci/pull/1) \u2014 it is a release pull request that intend increasing of the version number,\n\n\n\n* but in the changes [version number in setup.py isn't increased](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci/pull/1/files#diff-2eeaed663bd0d25b7e608891384b7298R8),\n\n\n\n* that's because [pull request's continuous integration checking](https://travis-ci.com/dmytrostriletskyi/test-pypi-version-travis-ci/builds/107324550) is failed \u2014 there is `pypi-version` checking integrated.\n\n\n\n* as configured, there are an [installing of the pypi-version and checking the version by using it](https://github.com/dmytrostriletskyi/test-pypi-version-travis-ci/blob/master/.travis.yml),\n\n\n\n* as the result, `pypi-version` [checks](https://travis-ci.com/dmytrostriletskyi/test-pypi-version-travis-ci/jobs/190875378#L482) if release pull request's (from `develop` to `master`) changes contain an increasing the ``package version number`` before it will be merged. In the example that is described above there is no increasing the version \u2014 \n`pypi-version check` is failed. If one of the declared checking in the configuration file is failed \u2014 it means pull request continuous integration checking is failed and pull request does not allowed to be merged with wrong version number.\n\n\n\n## Usage\n\n### Command line interface\n\nTo check if you haven't forgotten to bump the ``PyPi package version number`` before you merge a release \npull request:\n\n```bash\n$ pypi-version check\n```\n\nTo fetch the version of the `pypi-version` package:\n\n```bash\n$ pypi-version --version\npypi-version, version 0.1.0\n```\n\nTo fetch all available package commands, use the following command:\n\n```bash\n$ pypi-version --help\nUsage: pypi-version [OPTIONS] COMMAND [ARGS]...\n\n Command line interface for PyPi version checking.\n\nOptions:\n --version Show the version and exit.\n --help Show this message and exit.\n\nCommands:\n check Check if you haven't forgotten to bump the PyPi package version.\n```\n\n### Configuration file\n\n`pypi-version` requires a configuration file called `.pypi-version.yml` to be located in the root of the project:\n\n```\npackage\n |\n - ...\n - source\n - README.md\n - setup.py\n - .pypi-version.yml\n ...\n```\n\nThe configuration file should contains:\n\n* the section with your `PyPi package name` that is the same with the name in the `setup.py`:\n\n```yml\npackage:\n name: test-pypi-version-travis-ci\n```\n\n* name of the continuous integration service you use. Available options are: `travis`.\n\n```yml\nci:\n name: travis\n```\n\n* `development` and `release` branch names. In the configurations which are illustrated below means \n`package version number` will be checked only when you do a pull request from `develop` to `master`.\n\n```yml\nbranches:\n development: develop\n release: master\n```\n\nThe full example of the configuration file is:\n\n```yml\npackage:\n name: pypi-version\n\nci:\n name: travis\n\nbranches:\n development: develop\n release: master\n```\n\n### Continuous integration services\n\n#### Travis-CI\n\nThe example of the configuration file which install and use `pypi-version`:\n\n```yml\nlanguage: python\n\npython:\n - \"3.6\"\n\ninstall:\n - pip install pypi-version\n\nscript:\n - pypi-version check\n```\n\nThe example of the failed build (version hasn't been bumped):\n\n\n\n#### CircleCI\n\nThe example of the configuration file which install and use `pypi-version`:\n\n```yml\nversion: 2\njobs:\n build:\n docker:\n - image: circleci/python:3.6.4\n steps:\n - checkout\n - run:\n name: Install pypi-version package\n command: sudo pip3 install pypi-version\n - run:\n name: Check if PyPi should be bumped\n command: sudo -H -E pypi-version check\n```\n\nThe example of the failed build (version hasn't been bumped):\n\n\n\n## Contributing\n\nClone the project and install requirements:\n\n```bash\n$ git clone git@github.com:dmytrostriletskyi/pypi-version.git && cd pypi-version\n$ pip3 install -r requirements.txt\n$ pip3 install -r requirements-dev.txt\n$ pip3 install -r requirements-tests.txt\n```\n\nWhen you will make changes, ensure your code pass [the checkers](https://github.com/dmytrostriletskyi/pypi-version/blob/develop/.travis.yml#L15) and is covered by tests using [pytest](https://docs.pytest.org/en/latest).\n\nIf you are new for the contribution, please read:\n\n* Read about pull requests \u2014 https://help.github.com/en/articles/about-pull-requests\n* Read how to provide pull request \u2014 https://help.github.com/en/articles/creating-a-pull-request-from-a-fork\n* Also the useful article about how to contribute \u2014 https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/\n\n## References\n\n### Python package\n\n`Python package` is redistributed and reused couple of the `Python` scripts. They exist to solve the typical problems. So if\nyou have common problem in your project \u2014 instead of writing own code and spend a time for it, use the package that already have required functionality. The examples of `Python packages` you should know are [requests](https://github.com/kennethreitz/requests) and [Django](https://github.com/django/django). \n\n### Gitflow workflow\n\nInstead of a single `master` branch, this workflow uses two branches to record the history of the project. The `master` branch stores the official release history, and the `develop` branch serves as an integration branch for features.\n\n<img src=\"https://wac-cdn.atlassian.com/dam/jcr:a9cea7b7-23c3-41a7-a4e0-affa053d9ea7/04%20(1).svg?cdnVersion=le\" width=\"700\" height=\"300\">\n\nSo when you complete the feature, you open the pull request from `feature` branch to the `develop` branch. When you complete the bunch of features, you open the pull request from `develop` branch to `master` branch which are going to merge this bunch of features that means you do new release. \n\n\n\nAccording to the changes that contains new features, you should increase your version number (e.g. from `1.0.0` to `1.1.0`) in the file called `setup.py` in the same pull request. \n\n\n\n### Upload to PyPi\n\nWhen your features with increased version number have been merged to the `master` branch, you are going to upload your source code to the `Python Package Index`. \n\nBeing in the root of you project,\n\n```\npackage\n |\n - ...\n - source\n - README.md\n - setup.py\n ...\n```\n\nyou do the following command:\n\n```\n$ python3 setup.py sdist\n$ twine upload dist/*\n```\n\nAnd if you haven't forgotten to bump the ``PyPi package version number``, the upload is successful. \n\n<img src=\"https://habrastorage.org/webt/55/pk/jn/55pkjnoezzvidqcyordvtyyhgw0.png\" width=\"700\" height=\"300\">\n\n<h3 id=\"references-continuous-integration-services\">Continuous integration services</h3>\n\nContinuous integration services are useful when you want add some robotic checking for your pull request changes. \nFor instance, you can run checking code style with [flake8](https://github.com/PyCQA/flake8) and run tests with [pytest](https://github.com/pytest-dev/pytest) to check your changes does not break existing functionality on the few version \nof `Python`. The configuration file example for `Travis CI` is presented below.\n\n```yml\nlanguage: python\n\npython:\n - \"3.4\"\n - \"3.5\"\n - \"3.6\"\n - \"3.7-dev\"\n\ninstall:\n - pip install -r requirements-dev.txt\n - pip install -r requirements-tests.txt\n\nscript:\n - cat requirements-tests.txt requirements-dev.txt | safety check --stdin\n - radon cc accessify -nb --total-average\n - isort -rc accessify --diff && isort -rc tests --diff\n - flake8 accessify\n - coverage run -m pytest -vv tests\n\nafter_success:\n - coverage report -m && coverage xml\n - bash <(curl -s https://codecov.io/bash)\n```\n\nEach pull request the checking report will be presented. By clicking on the `details` you will see full report.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Check if you haven't forgotten to bump the PyPi package version number before you merge a release pull request.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/dmytrostriletskyi/pypi-version"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b0767095c3ade72b5a46190e1242d09197a50c2594d963538ea4fc60f84e406e",
"md5": "321d28067326b7a810c596726bab6bee",
"sha256": "5f2f8eef2d695b8954f1d998d12c90a1abf5498dd7d79eada829bf690ca11d6c"
},
"downloads": -1,
"filename": "pypi-version-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "321d28067326b7a810c596726bab6bee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13601,
"upload_time": "2019-04-30T16:14:48",
"upload_time_iso_8601": "2019-04-30T16:14:48.454778Z",
"url": "https://files.pythonhosted.org/packages/b0/76/7095c3ade72b5a46190e1242d09197a50c2594d963538ea4fc60f84e406e/pypi-version-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-04-30 16:14:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dmytrostriletskyi",
"github_project": "pypi-version",
"github_not_found": true,
"lcname": "pypi-version"
}
JSON
