A Poetry plugin for dynamically extracting the package version.

Overview

Poetry Version Plugin

Test Publish Coverage Package version

A Poetry plugin for dynamically extracting the package version.

It can read the version from a file __init__.py with:

# __init__.py

__version__ = "0.1.0"

Alternatively, it can read it from a git tag, set with a GitHub release or with:

$ git tag 0.1.0

🚨 Consider this in the alpha stage. Read the warning below.

When to use

This is useful mainly if you are building a package library for others to use and you want to set the version in a place different than pyproject.toml, but you still want to keep a single source of truth.

It won't be helpful in other use cases like managing local app environments with Poetry.

How to use

Make sure you have Poetry version 1.2.0a1 or above. Read below for instructions to install it if you haven't.

Install Poetry Version Plugin

Install this plugin to your Poetry:

$ poetry plugin add poetry-version-plugin

--> 100%

Set version in init file

Set your package version in your file __init__.py, for example:

from .main import do_awesome_stuff, AwesomeClass

__version__ = "0.2.3"

And then edit your pyproject.toml with a section containing:

[tool.poetry-version-plugin]
source = "init"

Next, build your project. It will show an output like:

$ poetry build
Using __init__.py file at my_awesome_package/__init__.py for dynamic version
Setting package dynamic version to __version__ variable from __init__.py: 0.1.9
Building my-awesome-package (0.1.9)
  - Building sdist
  - Built my-awesome-package-0.1.9.tar.gz
  - Building wheel
  - Built my-awesome-package-0.1.9-py3-none-any.whl

Set the version in a Git tag

Alternatively, to extract the version to use from a Git tag, add a section:

[tool.poetry-version-plugin]
source = "git-tag"

Then create a git tag, for example:

$ git tag 0.1.3

In this case, when building your project, it will show an output like:

$ poetry build
Git tag found, setting dynamic version to: 0.1.3
Building my-awesome-package (0.1.3)
  - Building sdist
  - Built my-awesome-package-0.1.3.tar.gz
  - Building wheel
  - Built my-awesome-package-0.1.3-py3-none-any.whl

Version in pyproject.toml

Currently (2021-05-24) Poetry requires a version configuration in the pyproject.toml, even if you use this plugin.

When using this plugin, that version config won't be used, but Poetry still requires it to be present in the pyproject.toml.

To make it more evident that you are not using that version you can set it to 0.

[tool.poetry]
name = "my-awesome-package"
version = "0"

That way, you will more easily notice if the plugin is not installed, as it will show that you are building a package with version 0 instead of the dynamic version set.

An example pyproject.toml

A short, minimal example pyproject.toml could look like:

"] readme = "README.md" [tool.poetry.dependencies] python = "^3.6" [build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api" [tool.poetry-version-plugin] source = "init" ">
[tool.poetry]
name = "my-awesome-package"
version = "0"
description = ""
authors = ["Rick Sanchez "]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.6"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.poetry-version-plugin]
source = "init"

Why

By default, Poetry expects you to set your package version in pyproject.toml. And that would work in most cases.

But imagine you want to expose the version of your package in a __version__ variable so that your users can do things like:

import my_awesome_package
print(my_awesome_package.__version__)

You could manually write the __version__ variable and handle the synchronization between it and the pyproject.toml yourself, which is very error-prone.

The current official way of doing it without duplicating the value is with importlib.metadata.

But that module is only available in Python 3.8 and above. So, for Python 3.7 and 3.6 you have to install a backport as a dependency of your package:

[tool.poetry.dependencies]
importlib-metadata = {version = "^1.0", python = "<3.8"}

But then, when they release each new version of the backport (currently 4.0.1), you have to update it (or not). And your users would have to manually handle conflicts with any other packages that also depend on importlib-metadata which could be multiple, as many packages could be doing the same trick (I've dealt with that).

The other option is not to pin any version range of your importlib-metadata in your pyproject.toml and hope for the best.

And then your __init__.py would have to include code using it, like:

# I don't want this extra complexity 😔
# And it doesn't work in Docker 🐋
try:
    import importlib.metadata as importlib_metadata
except ModuleNotFoundError:
    import importlib_metadata

__version__ = importlib_metadata.version(__name__)

But that code is extra complexity and logic needed in your code, in each of your packages.

🚨 Additionally, this only works when your package is installed in a Python environment. It won't work if, for example, you simply put your code in a container, which is common for web apps and distributed systems.

How this plugin solves it

With this plugin, your package doesn't depend on importlib-metadata, so your users won't need to handle conflicts or extra dependencies.

Instead, your build system (Poetry) is what needs to have this plugin installed.

That avoids the extra code complexity on your side, dependency conflicts for your users, and support for other use cases like code copied directly inside a container.

Version from Git tag

Alternatively, this plugin can also extract the version from a Git tag.

So, you could only create each version in a Git tag (for example, a GitHub release) instead of writing it in code.

And then build the package on Continuous Integration (e.g. GitHub Actions). And this plugin would get the version of the package from that Git tag.

Install Poetry 1.2.0a1

For this plugin to work, you need Poetry version 1.2.0a1 or above.

Poetry 1.2.0a1 was released recently.

There's a high chance you already have installed Poetry 1.1.x.

The first step is to uninstall it:

$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -O
--> 100%

$ python get-poetry.py --uninstall
--> 100%

And then install the new Poetry with the new installer:

$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -O
--> 100%

$ python install-poetry.py --preview
--> 100%

🔍 Notice that the new installer file is named install-poetry.py instead of get-poetry.py. Also, notice that, currently, you need to set --preview for it to install the alpha version 1.2.0a1.

You can check that it worked with:

$ poetry --version
Poetry (version 1.2.0a1)

Support for version in init file

When using a __version__ variable in your __init__.py you can have more logic in that file, import modules, and do more things above and below the declaration of that variable.

But the value has to be a literal string, like:

___version___ = "0.2.0"

...instead of calling a function or something similar.

And the variable has to be at the top-level, so it can't be inside an if statement or similar.

This is all fine and supported in your __init__.py:

# __init__.py

# This is all valid 👍✅

from .main import do_awesome_stuff, AwesomeClass

awesome = AwesomeClass()

# Some comment explaining why this is commented out
# __version__ = "1.0.0"

__version__ = "0.2.3"

if __name__ == "__main__":
    awesome.run()

This example is all valid and supported, and it includes:

  • Imports
  • Other objects and variables
  • Comments
  • The same string __version__ inside a comment
  • If blocks around

But this is not supported:

# 🚨 Not supported

if 2 == 2:
    __version__ = "0.1.0

And this is not supported:

# 🚨 Not supported

def get_version():
    return "0.2.0"

__version__ = get_version()

How the plugin works

Poetry runs the plugin when building a package, and it sets the version right before creating the "package distributable" (e.g., the wheel).

How the version variable works

If you have a package (a single package) declared in the packages config in your pyproject.toml, the plugin will use that package's __init__.py to find the __version__ variable.

If you don't have any packages config, the plugin will assume that you have a single package named as your project, but in the module version (changing - for _). So, if your package is my-awesome-project, the plugin will use the file at my_awesome_project/__init__.py to find the __version__ variable.

This file structure is the default if you create a new project with the command poetry new, so it should work as expected.

The way the plugin works internally is by parsing the __init__.py file. Reading the Python's "Abstract Syntax Tree" using the ast standard module and extracting the literal value of the string. So, it doesn't execute the code in __init__.py, it only reads it as Python code.

The plugin doesn't try to import and execute that __init__.py file because that could require extra computation, external dependencies, etc. And it doesn't try to extract the __version__ with regular expressions, as that would be prone to errors if, for example, there was some other __version__ somewhere in the code, in a comment or inside a string.

Warning

🚨 Consider this in the alpha stage. Poetry 1.2.0a1 with support for plugins was released on 2021-05-21. I started writing this plugin 3 days later, on 2021-05-24.

Things might break in Poetry or in this plugin. So, please try it and test it very carefully before fully adopting it for delicate systems.

The way it works might change, and the specific configuration might change.

Also, if you don't find the following sections intuitive:

[tool.poetry-version-plugin]
source = "init"

and

[tool.poetry-version-plugin]
source = "git-tag"

let me know what alternative configuration would make more sense and be more intuitive to you.

👍 The good news is, assuming you are building packages to then upload them to PyPI for your users to download and use them, the worst that could happen if something broke is that you wouldn't be able to build a new version until something is fixed or changed. But your users shouldn't be affected in any way.

Release Notes

Latest Changes

  • ✏️ Fix typos and rewording in README.md. PR #8 by @Gl0deanR.

0.1.3

License

This project is licensed under the terms of the MIT license.

Comments
  • Update the version resource when using poetry version

    Update the version resource when using poetry version

    Hi! Thanks for the plugin. It can solve real inconsistencies when using poetry for packages. I think you should consider adding support for altering the version using the poetry version minor/patch/major. I don't mind sending a PR if you see this suggestion fitting.

    answered 
    opened by aviramha 2
  • This plugin is no longer available today!

    This plugin is no longer available today!

    The github actions that were working fine until yesterday are no longer available.

    I get the following error when loading this plugin.

    Run poetry plugin add poetry-version-plugin
    Using version ^0.1.3 for poetry-version-plugin
    Updating dependencies
    Resolving dependencies...
    
      AttributeError
    
      can't set attribute
    
      at ~/.local/share/pypoetry/venv/lib/python3.9/site-packages/poetry/packages/dependency_package.py:38 in __setattr__
           34│     def __setattr__(self, key: str, value: Any) -> None:
           35│         if key in {"_dependency", "_package"}:
           36│             return super().__setattr__(key, value)
           37│ 
        →  38│         setattr(self._package, key, value)
           39│ 
           40│     def __str__(self) -> str:
           41│         return str(self._package)
           42│ 
    Error: Process completed with exit code 1.
    

    We have confirmed that this error also occurs in the following minimal case dockerfile.

    FROM python:3.6
    
    RUN apt-get update
    RUN apt-get install curl -y
    
    RUN curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -O
    
    RUN python install-poetry.py --preview --version 1.2.0a1
    ENV PATH /root/.local/bin:$PATH
    RUN poetry --version
    RUN poetry plugin add poetry-version-plugin
    

    This means that this plugin can no longer be installed. Do you know the cause?

    opened by Uno-Takashi 1
  • Modify plugin for 1.2.0rc2

    Modify plugin for 1.2.0rc2

    The goal of this PR is to resolve issues documented in #27 and compatibility issues mentioned in #25.

    This PR resolves:

    • a bad method reference to module_name in [email protected]_name which is now only available via [email protected]_name
    • invalid method exception encountered on set_version as it was recently removed and rewritten to handle hashing under poetry.core's ProjectPackage._set_version(version, pretty_version)

    Additionally, this PR updates some dependencies to allow pytest to execute under Python 3.10.

    Tests are passing with the provided changes.

    Fixes #27 and #25

    investigate 
    opened by mbeacom 2
  • Plugin fails under Poetry 1.2.0rc2

    Plugin fails under Poetry 1.2.0rc2

    This plugin currently fails using the latest RC of Poetry (1.2.0rc2). There have been numerous changes to the Poetry core (to include movement and removal of some methods).

    If you attempt to run poetry commands following installation of this plugin under rc2, you will encounter a module_name not found in [email protected]_name (as it is no longer available here, but rather: [email protected]_name Additionally, set_version was removed in a previous release (documented here): https://github.com/python-poetry/poetry/issues/6223

    This required the addition of ProjectPackage._set_version as discussed here: https://github.com/python-poetry/website/pull/70#issuecomment-1229139312

    opened by mbeacom 0
  • plugin does not work anymore with latest poetry 1.2.0b2

    plugin does not work anymore with latest poetry 1.2.0b2

    Hi !

    I get this error now:

    AttributeError
      'ProjectPackage' object has no attribute 'set_version'
      at ~/.local/share/pypoetry/venv/lib/python3.10/site-packages/poetry_version_plugin/plugin.py:98 in activate
           94│                 io.write_line(
           95│                     "poetry-version-plugin: Git tag found, setting "
           96│                     f"dynamic version to: {tag}"
           97│                 )
        →  98│                 poetry.package.set_version(tag)
           99│                 return
    

    Certainly related to this update in poetry:

    https://github.com/python-poetry/poetry/pull/5486

    opened by ThomasChiroux 1
  • Can it also tell me the git ref?

    Can it also tell me the git ref?

    Hi. Thanks for poetry-version-plugin, I've found it really easy to use. Now I can do:

    $ mycliapp --version
    mycliapp 1.2.3dev4
    

    Sometimes I forget to add a tag, and an untagged version ends up in a co-worker's hands. When this happens it's hard to be sure which version they actually have. I'd like to be able to do this instead:

    $ mycliapp --version
    mycliapp 1.2.3dev4 
    88f9aaf02cbdc6a2a5972c07b167e78314ad153b
    

    Where 88f...3b is the current git ref (not the ref of the tag, which might be i the past). Is this information available?

    opened by MatrixManAtYrService 0
  • Add pipx installation option

    Add pipx installation option

    Hi, this is the first plugin I tried to install into poetry and I noticed there is a different approach when poetry is installed with pipx.

    https://python-poetry.org/docs/master/plugins/#with-pipx-inject

    opened by 1oglop1 0
Releases(0.1.3)
Owner
Sebastián Ramírez
Creator of FastAPI and Typer. Dev at @explosion. APIs, Deep Learning/ML, full-stack distributed systems, SQL/NoSQL, Python, Docker, JS, TypeScript, etc
Sebastián Ramírez
A PyPI mirror client according to PEP 381 http://www.python.org/dev/peps/pep-0381/

This is a PyPI mirror client according to PEP 381 + PEP 503 http://www.python.org/dev/peps/pep-0381/. bandersnatch =4.0 supports Linux, MacOSX + Wind

Python Packaging Authority 345 Dec 28, 2022
local pypi server (custom packages and auto-mirroring of pypi)

localshop A PyPI server which automatically proxies and mirrors PyPI packages based upon packages requested. It has support for multiple indexes and t

Michael van Tellingen 383 Sep 23, 2022
Template repo for a GCP-hosted REST API with automatic API versioning and custom domain mapping

Python + Poetry REST API with FastAPI, hosted on GCP This template will get you ready to deploy a FastAPI app in Google Cloud with automatic API versi

Kevin Duff 10 Dec 25, 2022
A PyPI mirror client according to PEP 381 http://www.python.org/dev/peps/pep-0381/

This is a PyPI mirror client according to PEP 381 + PEP 503 http://www.python.org/dev/peps/pep-0381/. bandersnatch =4.0 supports Linux, MacOSX + Wind

Python Packaging Authority 345 Dec 28, 2022
An installation and dependency system for Python

Pyflow Simple is better than complex - The Zen of Python Pyflow streamlines working with Python projects and files. It's an easy-to-use CLI app with a

David O'Connor 1.2k Dec 23, 2022
:package: :fire: Python project management. Manage packages: convert between formats, lock, install, resolve, isolate, test, build graph, show outdated, audit. Manage venvs, build package, bump version.

THE PROJECT IS ARCHIVED Forks: https://github.com/orsinium/forks DepHell -- project management for Python. Why it is better than all other tools: Form

DepHell 1.7k Dec 30, 2022
A Poetry plugin for dynamically extracting the package version.

Poetry Version Plugin A Poetry plugin for dynamically extracting the package version. It can read the version from a file __init__.py with: # __init__

Sebastián Ramírez 264 Dec 22, 2022
OS-agnostic, system-level binary package manager and ecosystem

Conda is a cross-platform, language-agnostic binary package manager. It is the package manager used by Anaconda installations, but it may be used for

Conda 5.1k Jan 07, 2023
Workon - A simple project manager for conda, windows 10 and vscode

WORK ON A simple project manager for conda, windows 10 and vscode Installation p

Jesus Alan Hernandez Galvan 1 Jan 16, 2022
Simple Library Management made with Python

Installation pip install mysql-connector-python NOTE: You must make a database (library) & and table (books, student) to hold all data. Languange and

SonLyte 10 Oct 21, 2021
OS-agnostic, system-level binary package manager and ecosystem

Conda is a cross-platform, language-agnostic binary package manager. It is the package manager used by Anaconda installations, but it may be used for

Conda 5.1k Dec 30, 2022
Python PyPi staging server and packaging, testing, release tool

devpi: PyPI server and packaging/testing/release tool This repository contains three packages comprising the core devpi system on the server and clien

629 Jan 01, 2023
Install All Basic Termux Packages To Your Phone

~All-Packages~ The Easiest Way To Install All Termux Packages 🤗 Tool By ⒹⓈ᭄ʜʏᴅʀᴀ✘๛ˢᴸ 👇 Contact Me On 👇 AVAILABLE ON : Termux TESTED ON : Term

ⒹⓈ ʜʏͥᴅᷧʀᷟᴀ✘๛ˢᴸ 7 Nov 12, 2022
The Fast Cross-Platform Package Manager

The Fast Cross-Platform Package Manager part of mamba-org Package Manager mamba Package Server quetz Package Builder boa mamba Mamba is a reimplementa

Mamba 4k Dec 30, 2022
Conan - The open-source C/C++ package manager

Conan Decentralized, open-source (MIT), C/C++ package manager. Homepage: https://conan.io/ Github: https://github.com/conan-io/conan Docs: https://doc

Conan.io 6.5k Jan 05, 2023
The Python Package Index

Warehouse Warehouse is the software that powers PyPI. See our development roadmap, documentation, and architectural overview. Getting Started You can

Python Packaging Authority 3.1k Jan 01, 2023
The Python package installer

pip - The Python Package Installer pip is the package installer for Python. You can use pip to install packages from the Python Package Index and othe

Python Packaging Authority 8.4k Dec 30, 2022
A software manager for easy development and distribution of Python code

Piper A software manager for easy development and distribution of Python code. The main features that Piper adds to Python are: Support for large-scal

13 Nov 22, 2022
A tool to upgrade dependencies to the latest versions

pip-check-updates A tool to upgrade dependencies to the latest versions, inspired by npm-check-updates Install From PyPi pip install pip-check-updates

Zeheng Li 12 Jan 06, 2023
Dotpkg - Package manager for your dotfiles

Dotpkg A package manager for your dotfiles. Usage First make sure to have Python

FW 4 Mar 18, 2022