# [lexid][repo_ref]
`lexid` is a micro library to increment lexically ordered numerical ids.
Throughout the sequence of ids, this expression will always be true, whether you are dealing with integers or strings:
older_id < newer_id
The left most character/digit is only used to maintain lexical order, so that the position in the sequence is maintained in the remaining digits.
Such ids can be useful as build or version numbers, which are often displayed by tooling which does not understand their correct ordering.
Project/Repo:
[![MIT License][license_img]][license_ref]
[![Supported Python Versions][pyversions_img]][pyversions_ref]
[![CalVer 2021.1006][version_img]][version_ref]
[![PyPI Version][pypi_img]][pypi_ref]
[![PyPI Downloads][downloads_img]][downloads_ref]
Code Quality/CI:
[![GitHub CI Status][github_build_img]][github_build_ref]
[![GitLab CI Status][gitlab_build_img]][gitlab_build_ref]
[![Type Checked with mypy][mypy_img]][mypy_ref]
[![Code Coverage][codecov_img]][codecov_ref]
[![Code Style: sjfmt][style_img]][style_ref]
| Name | role | since | until |
|----------------------------------|-------------------|------------------|-------|
| Manuel Barkhau (mbarkhau@gmail.com) | author/maintainer | 2020-09 | - |
## Usage
```
$ pip install lexid
$ lexid_incr 1001
1002
$ lexid_incr 1999
22000
$ lexid_incr 1
22
$ lexid_incr 1 -n 100
22
..
28
29
330
331
...
398
399
4400
4401
...
```
In Python.
```
>>> import lexid
>>> lexid.incr("1")
'22'
>>> lexid.incr("0001")
'0002'
>>> lexid.incr("0999")
'11000'
```
To avoid possible zero truncation issues (e.g. with "0001" -> "1") and to reduce rollovers, start at a higher number:
```
>>> lexid.incr("1001")
'1002'
>>> lexid.incr("1002")
'1003'
>>> lexid.incr("1999")
'22000'
```
## Lexical Ids
The key thing to look at is how padding may eventually be exhausted.
In order to preserve lexical ordering, build numbers are incremented
in a special way. Examples will perhaps illustrate more clearly.
```python
"0001"
"0002"
"0003"
...
"0999"
"11000"
"11001"
...
"19998"
"19999"
"220000"
"220001"
```
What is happening here is that the left-most digit is incremented
early/preemptively. Whenever the left-most digit would change, the padding
of the id is expanded through a multiplication by 11.
```python
>>> prev_id = "0999"
>>> num_digits = len(prev_id)
>>> num_digits
4
>>> prev_int = int(prev_id, 10)
>>> prev_int
999
>>> maybe_next_int = prev_int + 1
>>> maybe_next_int
1000
>>> maybe_next_id = f"{maybe_next_int:0{num_digits}}"
>>> maybe_next_id
"1000"
>>> is_padding_ok = prev_id[0] == maybe_next_id[0]
>>> is_padding_ok
False
>>> if is_padding_ok:
... # normal case
... next_id = maybe_next_id
... else:
... # extra padding needed
... next_int = maybe_next_int * 11
... next_id = str(next_int)
>>> next_id
"11000"
```
This behaviour ensures that the following semantic is always preserved:
`new_version > old_version`. This will be true, regardless of padding
expansion. To illustrate the issue this solves, consider what would happen
if we did not expand the padding and instead just incremented numerically.
```python
"0001"
"0002"
"0003"
...
"0999"
"1000"
...
"9999"
"10000"
```
Here we eventually run into a build number where the lexical ordering is
not preserved, since `"10000" > "9999" == False` (because the string `"1"`
is lexically smaller than `"9"`). With large enough padding this may be a
non issue, but it's better to not have to think about it.
Just as an example of why lexical ordering is a nice property to have,
there are lots of software which read git tags, but which have no logic to
parse version strings. This software can nonetheless order the version tags
correctly using commonly used lexical ordering. At the most basic
level it can allow you to use the UNIX `sort` command, for example to parse
VCS tags.
```shell
$ printf "v0.9.0\nv0.10.0\nv0.11.0\n" | sort
v0.10.0
v0.11.0
v0.9.0
$ printf "v0.9.0\nv0.10.0\nv0.11.0\n" | sort -n
v0.10.0
v0.11.0
v0.9.0
$ lexid_incr 0997 -n 5 | sort
0998
0999
11000
11001
11002
```
This sorting even works correctly in JavaScript!
```
> var versions = ["11002", "11001", "11000", "0999", "0998"];
> versions.sort();
["0998", "0999", "11000", "11001", "11002"]
```
[repo_ref]: https://github.com/mbarkhau/lexid
[github_build_img]: https://github.com/mbarkhau/lexid/workflows/CI/badge.svg
[github_build_ref]: https://github.com/mbarkhau/lexid/actions?query=workflow%3ACI
[gitlab_build_img]: https://gitlab.com/mbarkhau/lexid/badges/master/pipeline.svg
[gitlab_build_ref]: https://gitlab.com/mbarkhau/lexid/pipelines
[codecov_img]: https://gitlab.com/mbarkhau/lexid/badges/master/coverage.svg
[codecov_ref]: https://mbarkhau.gitlab.io/lexid/cov
[license_img]: https://img.shields.io/badge/License-MIT-blue.svg
[license_ref]: https://github.com/mbarkhau/lexid/blob/master/LICENSE
[mypy_img]: https://img.shields.io/badge/mypy-checked-green.svg
[mypy_ref]: https://mbarkhau.gitlab.io/lexid/mypycov
[style_img]: https://img.shields.io/badge/code%20style-%20sjfmt-f71.svg
[style_ref]: https://gitlab.com/mbarkhau/straitjacket/
[pypi_img]: https://img.shields.io/badge/PyPI-wheels-green.svg
[pypi_ref]: https://pypi.org/project/lexid/#files
[downloads_img]: https://pepy.tech/badge/lexid/month
[downloads_ref]: https://pepy.tech/project/lexid
[version_img]: https://img.shields.io/static/v1.svg?label=CalVer&message=2021.1006&color=blue
[version_ref]: https://pypi.org/project/pycalver/
[pyversions_img]: https://img.shields.io/pypi/pyversions/lexid.svg
[pyversions_ref]: https://pypi.python.org/pypi/lexid
# Changelog for https://github.com/mbarkhau/lexid
## 2021.1006
- Minor packaging updates
## 2020.1005
- Initial release (extracted from pycalver)
Raw data
{
"_id": null,
"home_page": "https://github.com/mbarkhau/lexid",
"name": "lexid",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7",
"maintainer_email": "",
"keywords": "lexical build number",
"author": "Manuel Barkhau",
"author_email": "mbarkhau@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/60/0b/28a3f9abc75abbf1fa996eb2dd77e1e33a5d1aac62566e3f60a8ec8b8a22/lexid-2021.1006.tar.gz",
"platform": "",
"description": "# [lexid][repo_ref]\n\n`lexid` is a micro library to increment lexically ordered numerical ids.\n\nThroughout the sequence of ids, this expression will always be true, whether you are dealing with integers or strings:\n\n older_id < newer_id\n\nThe left most character/digit is only used to maintain lexical order, so that the position in the sequence is maintained in the remaining digits.\n\nSuch ids can be useful as build or version numbers, which are often displayed by tooling which does not understand their correct ordering.\n\nProject/Repo:\n\n[![MIT License][license_img]][license_ref]\n[![Supported Python Versions][pyversions_img]][pyversions_ref]\n[![CalVer 2021.1006][version_img]][version_ref]\n[![PyPI Version][pypi_img]][pypi_ref]\n[![PyPI Downloads][downloads_img]][downloads_ref]\n\nCode Quality/CI:\n\n[![GitHub CI Status][github_build_img]][github_build_ref]\n[![GitLab CI Status][gitlab_build_img]][gitlab_build_ref]\n[![Type Checked with mypy][mypy_img]][mypy_ref]\n[![Code Coverage][codecov_img]][codecov_ref]\n[![Code Style: sjfmt][style_img]][style_ref]\n\n\n| Name | role | since | until |\n|----------------------------------|-------------------|------------------|-------|\n| Manuel Barkhau (mbarkhau@gmail.com) | author/maintainer | 2020-09 | - |\n\n\n## Usage\n\n```\n$ pip install lexid\n$ lexid_incr 1001\n1002\n$ lexid_incr 1999\n22000\n$ lexid_incr 1\n22\n$ lexid_incr 1 -n 100\n22\n..\n28\n29\n330\n331\n...\n398\n399\n4400\n4401\n...\n```\n\nIn Python.\n\n```\n>>> import lexid\n>>> lexid.incr(\"1\")\n'22'\n>>> lexid.incr(\"0001\")\n'0002'\n>>> lexid.incr(\"0999\")\n'11000'\n```\n\nTo avoid possible zero truncation issues (e.g. with \"0001\" -> \"1\") and to reduce rollovers, start at a higher number:\n\n```\n>>> lexid.incr(\"1001\")\n'1002'\n>>> lexid.incr(\"1002\")\n'1003'\n>>> lexid.incr(\"1999\")\n'22000'\n```\n\n\n## Lexical Ids\n\nThe key thing to look at is how padding may eventually be exhausted.\nIn order to preserve lexical ordering, build numbers are incremented\nin a special way. Examples will perhaps illustrate more clearly.\n\n```python\n\"0001\"\n\"0002\"\n\"0003\"\n...\n\"0999\"\n\"11000\"\n\"11001\"\n...\n\"19998\"\n\"19999\"\n\"220000\"\n\"220001\"\n```\n\nWhat is happening here is that the left-most digit is incremented\nearly/preemptively. Whenever the left-most digit would change, the padding\nof the id is expanded through a multiplication by 11.\n\n```python\n>>> prev_id = \"0999\"\n>>> num_digits = len(prev_id)\n>>> num_digits\n4\n>>> prev_int = int(prev_id, 10)\n>>> prev_int\n999\n>>> maybe_next_int = prev_int + 1\n>>> maybe_next_int\n1000\n>>> maybe_next_id = f\"{maybe_next_int:0{num_digits}}\"\n>>> maybe_next_id\n\"1000\"\n>>> is_padding_ok = prev_id[0] == maybe_next_id[0]\n>>> is_padding_ok\nFalse\n>>> if is_padding_ok:\n... # normal case\n... next_id = maybe_next_id\n... else:\n... # extra padding needed\n... next_int = maybe_next_int * 11\n... next_id = str(next_int)\n>>> next_id\n\"11000\"\n```\n\nThis behaviour ensures that the following semantic is always preserved:\n`new_version > old_version`. This will be true, regardless of padding\nexpansion. To illustrate the issue this solves, consider what would happen\nif we did not expand the padding and instead just incremented numerically.\n\n```python\n\"0001\"\n\"0002\"\n\"0003\"\n...\n\"0999\"\n\"1000\"\n...\n\"9999\"\n\"10000\"\n```\n\nHere we eventually run into a build number where the lexical ordering is\nnot preserved, since `\"10000\" > \"9999\" == False` (because the string `\"1\"`\nis lexically smaller than `\"9\"`). With large enough padding this may be a\nnon issue, but it's better to not have to think about it.\n\nJust as an example of why lexical ordering is a nice property to have,\nthere are lots of software which read git tags, but which have no logic to\nparse version strings. This software can nonetheless order the version tags\ncorrectly using commonly used lexical ordering. At the most basic\nlevel it can allow you to use the UNIX `sort` command, for example to parse\nVCS tags.\n\n\n```shell\n$ printf \"v0.9.0\\nv0.10.0\\nv0.11.0\\n\" | sort\nv0.10.0\nv0.11.0\nv0.9.0\n\n$ printf \"v0.9.0\\nv0.10.0\\nv0.11.0\\n\" | sort -n\nv0.10.0\nv0.11.0\nv0.9.0\n\n$ lexid_incr 0997 -n 5 | sort\n0998\n0999\n11000\n11001\n11002\n```\n\nThis sorting even works correctly in JavaScript!\n\n```\n> var versions = [\"11002\", \"11001\", \"11000\", \"0999\", \"0998\"];\n> versions.sort();\n[\"0998\", \"0999\", \"11000\", \"11001\", \"11002\"]\n```\n\n[repo_ref]: https://github.com/mbarkhau/lexid\n\n[github_build_img]: https://github.com/mbarkhau/lexid/workflows/CI/badge.svg\n[github_build_ref]: https://github.com/mbarkhau/lexid/actions?query=workflow%3ACI\n\n[gitlab_build_img]: https://gitlab.com/mbarkhau/lexid/badges/master/pipeline.svg\n[gitlab_build_ref]: https://gitlab.com/mbarkhau/lexid/pipelines\n\n[codecov_img]: https://gitlab.com/mbarkhau/lexid/badges/master/coverage.svg\n[codecov_ref]: https://mbarkhau.gitlab.io/lexid/cov\n\n[license_img]: https://img.shields.io/badge/License-MIT-blue.svg\n[license_ref]: https://github.com/mbarkhau/lexid/blob/master/LICENSE\n\n[mypy_img]: https://img.shields.io/badge/mypy-checked-green.svg\n[mypy_ref]: https://mbarkhau.gitlab.io/lexid/mypycov\n\n[style_img]: https://img.shields.io/badge/code%20style-%20sjfmt-f71.svg\n[style_ref]: https://gitlab.com/mbarkhau/straitjacket/\n\n[pypi_img]: https://img.shields.io/badge/PyPI-wheels-green.svg\n[pypi_ref]: https://pypi.org/project/lexid/#files\n\n[downloads_img]: https://pepy.tech/badge/lexid/month\n[downloads_ref]: https://pepy.tech/project/lexid\n\n[version_img]: https://img.shields.io/static/v1.svg?label=CalVer&message=2021.1006&color=blue\n[version_ref]: https://pypi.org/project/pycalver/\n\n[pyversions_img]: https://img.shields.io/pypi/pyversions/lexid.svg\n[pyversions_ref]: https://pypi.python.org/pypi/lexid\n\n\n\n# Changelog for https://github.com/mbarkhau/lexid\n\n## 2021.1006\n\n - Minor packaging updates\n\n\n## 2020.1005\n\n - Initial release (extracted from pycalver)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Variable width build numbers with lexical ordering.",
"version": "2021.1006",
"project_urls": {
"Homepage": "https://github.com/mbarkhau/lexid"
},
"split_keywords": [
"lexical",
"build",
"number"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cfe335764404a4b7e2021be1f88f42264c2e92e0c4720273559a62461ce64a47",
"md5": "d66956a88288bdd6c7b694f968ebe587",
"sha256": "5526bb5606fd74c7add23320da5f02805bddd7c77916f2dc1943e6bada8605ed"
},
"downloads": -1,
"filename": "lexid-2021.1006-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d66956a88288bdd6c7b694f968ebe587",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7",
"size": 7587,
"upload_time": "2021-04-02T20:18:33",
"upload_time_iso_8601": "2021-04-02T20:18:33.129300Z",
"url": "https://files.pythonhosted.org/packages/cf/e3/35764404a4b7e2021be1f88f42264c2e92e0c4720273559a62461ce64a47/lexid-2021.1006-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "600b28a3f9abc75abbf1fa996eb2dd77e1e33a5d1aac62566e3f60a8ec8b8a22",
"md5": "acaceb7ce84ee319b69ae06d8e561172",
"sha256": "509a3a4cc926d3dbf22b203b18a4c66c25e6473fb7c0e0d30374533ac28bafe5"
},
"downloads": -1,
"filename": "lexid-2021.1006.tar.gz",
"has_sig": false,
"md5_digest": "acaceb7ce84ee319b69ae06d8e561172",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7",
"size": 11525,
"upload_time": "2021-04-02T20:18:34",
"upload_time_iso_8601": "2021-04-02T20:18:34.668177Z",
"url": "https://files.pythonhosted.org/packages/60/0b/28a3f9abc75abbf1fa996eb2dd77e1e33a5d1aac62566e3f60a8ec8b8a22/lexid-2021.1006.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-04-02 20:18:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mbarkhau",
"github_project": "lexid",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lexid"
}
JSON
