==============
single-version
==============
.. image:: https://madewithlove.now.sh/vn?heart=true&colorA=%23ffcd00&colorB=%23da251d
.. image:: https://badgen.net/pypi/v/single-version
:target: https://pypi.org/project/single-version
Utility to let you have a single source of version in your code base.
This utility targets modern Python projects which have layout generated by `Poetry`_, with a *pyproject.toml* file in place of *setup.py*. With this layout, the project initially has two places to maintain version string: one in *pyproject.toml* file and one in some *\*.py* file (normally *__init__.py*):
.. code-block:: toml
# pyproject.toml
[tool.poetry]
name = "your-package"
version = "0.1.0"
.. code-block:: python
# your_package/__init__.py
__version__ = "0.1.0"
This duplicity often leads to inconsistency when you, the author, forget to update both.
*single-version* was born to solve that headache circumstance. By convention, it chooses the *pyproject.toml* file as original source of version string. Your project's ``__version__`` variable then is computed from it. When your package is already deployed and installed to some system, the version string will be retrieved from that Python environment (the *pyproject.toml* is not included in distribution file).
Years ago, to retrieve version for an installed package, people often used `pkg_resources`_, which has well-known issue of causing slow import. Learning from that mistake, *single-version* use |importlib.metadata|_, which becomes standard from Python 3.8, instead.
Usage
-----
Add ``single_version`` as your project dependency:
.. code-block:: sh
poetry add single-version
Assume that your package source tree is like this::
.
├── awesome_name
│ └── __init__.py
├── pyproject.toml
├── README.rst
└── tests/
where the ``__version__`` variable is defined in `awesome_name/__init__.py` file. The file content can be like this:
.. code-block:: python
from pathlib import Path
from single_version import get_version
__version__ = get_version('awesome_name', Path(__file__).parent.parent)
API Reference
-------------
*def* **get_version** (package_name: *str*, looked_path: *Path*) -> *str*
- ``package_name``: Your package's name (same as in *pyproject.toml* file).
- ``looked_path`` (of ``pathlib.Path`` type): Folder where your project's *pyproject.toml* resides.
.. _Poetry: https://python-poetry.org/
.. _pkg_resources: https://setuptools.readthedocs.io/en/latest/pkg_resources.html
.. |importlib.metadata| replace:: ``importlib.metadata``
.. _importlib.metadata: https://docs.python.org/3.8/library/importlib.metadata.html
Raw data
{
"_id": null,
"home_page": "https://github.com/hongquan/single-version",
"name": "single-version",
"maintainer": "Nguy\u1ec5n H\u1ed3ng Qu\u00e2n",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "ng.hong.quan@gmail.com",
"keywords": "",
"author": "Nguy\u1ec5n H\u1ed3ng Qu\u00e2n",
"author_email": "ng.hong.quan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a6/59/108dcfe49cde1f7f976445ae0e8c66dc2cdc6114dcfaf664afa8d5702f10/single_version-1.6.0.tar.gz",
"platform": null,
"description": "==============\nsingle-version\n==============\n\n.. image:: https://madewithlove.now.sh/vn?heart=true&colorA=%23ffcd00&colorB=%23da251d\n.. image:: https://badgen.net/pypi/v/single-version\n :target: https://pypi.org/project/single-version\n\nUtility to let you have a single source of version in your code base.\n\nThis utility targets modern Python projects which have layout generated by `Poetry`_, with a *pyproject.toml* file in place of *setup.py*. With this layout, the project initially has two places to maintain version string: one in *pyproject.toml* file and one in some *\\*.py* file (normally *__init__.py*):\n\n.. code-block:: toml\n\n # pyproject.toml\n [tool.poetry]\n name = \"your-package\"\n version = \"0.1.0\"\n\n.. code-block:: python\n\n # your_package/__init__.py\n __version__ = \"0.1.0\"\n\nThis duplicity often leads to inconsistency when you, the author, forget to update both.\n\n*single-version* was born to solve that headache circumstance. By convention, it chooses the *pyproject.toml* file as original source of version string. Your project's ``__version__`` variable then is computed from it. When your package is already deployed and installed to some system, the version string will be retrieved from that Python environment (the *pyproject.toml* is not included in distribution file).\n\nYears ago, to retrieve version for an installed package, people often used `pkg_resources`_, which has well-known issue of causing slow import. Learning from that mistake, *single-version* use |importlib.metadata|_, which becomes standard from Python 3.8, instead.\n\n\nUsage\n-----\n\nAdd ``single_version`` as your project dependency:\n\n.. code-block:: sh\n\n poetry add single-version\n\n\nAssume that your package source tree is like this::\n\n .\n \u251c\u2500\u2500 awesome_name\n \u2502 \u2514\u2500\u2500 __init__.py\n \u251c\u2500\u2500 pyproject.toml\n \u251c\u2500\u2500 README.rst\n \u2514\u2500\u2500 tests/\n\nwhere the ``__version__`` variable is defined in `awesome_name/__init__.py` file. The file content can be like this:\n\n.. code-block:: python\n\n from pathlib import Path\n\n from single_version import get_version\n\n\n __version__ = get_version('awesome_name', Path(__file__).parent.parent)\n\n\nAPI Reference\n-------------\n\n\n*def* **get_version** (package_name: *str*, looked_path: *Path*) -> *str*\n\n- ``package_name``: Your package's name (same as in *pyproject.toml* file).\n\n- ``looked_path`` (of ``pathlib.Path`` type): Folder where your project's *pyproject.toml* resides.\n\n\n.. _Poetry: https://python-poetry.org/\n.. _pkg_resources: https://setuptools.readthedocs.io/en/latest/pkg_resources.html\n.. |importlib.metadata| replace:: ``importlib.metadata``\n.. _importlib.metadata: https://docs.python.org/3.8/library/importlib.metadata.html\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Small utility to define version string for Poetry-style Python project.",
"version": "1.6.0",
"project_urls": {
"Homepage": "https://github.com/hongquan/single-version",
"Repository": "https://github.com/hongquan/single-version.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "61b5ffbbc700075f6d07164dea524b81a495689d18a0f6dd44f07c8cdfeb9fb5",
"md5": "ad9018dfeca57375c8c4ed89e8e0cd5a",
"sha256": "67a2734e728b9554750e867b33591f3ad9509ccb851bb3047ced7bfe68429ecd"
},
"downloads": -1,
"filename": "single_version-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad9018dfeca57375c8c4ed89e8e0cd5a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 4223,
"upload_time": "2023-08-12T06:09:04",
"upload_time_iso_8601": "2023-08-12T06:09:04.533400Z",
"url": "https://files.pythonhosted.org/packages/61/b5/ffbbc700075f6d07164dea524b81a495689d18a0f6dd44f07c8cdfeb9fb5/single_version-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a659108dcfe49cde1f7f976445ae0e8c66dc2cdc6114dcfaf664afa8d5702f10",
"md5": "a35d20c4dd1c652c8bc70af8c58c8fdc",
"sha256": "3b1fb6e9bd2c88268948d9191c78b63ddd3c07554c1f07cd8a85aedf2486e4fc"
},
"downloads": -1,
"filename": "single_version-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "a35d20c4dd1c652c8bc70af8c58c8fdc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 3595,
"upload_time": "2023-08-12T06:09:05",
"upload_time_iso_8601": "2023-08-12T06:09:05.962540Z",
"url": "https://files.pythonhosted.org/packages/a6/59/108dcfe49cde1f7f976445ae0e8c66dc2cdc6114dcfaf664afa8d5702f10/single_version-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-12 06:09:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hongquan",
"github_project": "single-version",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "single-version"
}
JSON
